OpenClaw Updates

SKILL.md

---
name: clawdbot-updates
description: Manage Clawdbot updates with version comparison, changelog review, risk assessment, config backup, rollback capability, and multi-gateway sync. Use when the user requests to check for updates, update Clawdbot, review what's new, assess update risks, backup/restore configuration, rollback an update, or sync updates across multiple gateways (ada-gateway, Pi, etc.).
---

# Clawdbot Updates Management

Enhanced update management for Clawdbot with safety controls, version tracking, and rollback capability.

## Quick Start

**Check for updates:**
```bash
scripts/check-updates.sh
```

**Update with backup:**
```bash
scripts/backup-config.sh
scripts/apply-update.sh
```

**Rollback if needed:**
```bash
scripts/rollback.sh
```

## Decision Tree

```
User requests update
├─ Step 1: Check current vs latest
│  └─ Run check-updates.sh
│     ├─ Already latest → Inform user, done
│     └─ Update available → Continue to Step 2
│
├─ Step 2: Show what's new
│  └─ Display:
│     ├─ Version comparison (current → latest)
│     ├─ Changelog/release notes
│     └─ Breaking changes warnings
│     └─ Ask: Proceed? → No → Done
│
├─ Step 3: Backup current state
│  └─ Run backup-config.sh
│     ├─ Backs up config.yaml
│     ├─ Records current version
│     ├─ Creates timestamped backup
│     └─ On failure → Abort update
│
├─ Step 4: Apply update
│  └─ Run apply-update.sh
│     ├─ Pulls latest code
│     ├─ Installs dependencies
│     ├─ Validates config
│     ├─ Restarts gateway
│     └─ On failure → Offer rollback
│
└─ Step 5: Verify
   └─ Check gateway status
      ├─ Success → Cleanup old backups
      └─ Failure → Run rollback.sh
```

## Scripts

### check-updates.sh

Compares current vs latest version without making changes.

**Output:**
- Current version
- Latest available version
- Changelog summary
- Breaking changes flag

**Exit codes:**
- 0: Update available
- 1: Already latest
- 2: Error checking

### backup-config.sh

Creates timestamped backup before updates.

**What's backed up:**
- config.yaml
- Current git commit hash
- Package.json dependencies
- Timestamp and version metadata

**Backup location:** `~/.clawdbot-backups/YYYY-MM-DD-HHMMSS/`

**Exit codes:**
- 0: Backup successful
- 1: Backup failed

### apply-update.sh

Applies the update with validation.

**Process:**
1. Verify backup exists
2. Git pull latest changes
3. npm install dependencies
4. Validate config.yaml
5. Restart gateway via `gateway` tool

**Exit codes:**
- 0: Update successful
- 1: Update failed (safe to rollback)

### rollback.sh

Restores from most recent backup.

**Process:**
1. Find latest backup
2. Restore config.yaml
3. Git checkout previous commit
4. Restore dependencies
5. Restart gateway

**Exit codes:**
- 0: Rollback successful
- 1: Rollback failed (manual intervention needed)

## Multi-Gateway Sync

When managing multiple gateways (ada-gateway, Pi, etc.):

1. **Test on one gateway first** (typically ada-gateway)
2. **Verify stability** for 24 hours
3. **Sync to other gateways** using the same scripts via nodes_run or SSH

**Example sync to Pi:**
```bash
# After successful update on ada-gateway
nodes run --node pi --command "cd ~/clawdbot && ./skills/clawdbot-updates/scripts/apply-update.sh"
```

## Mac Node Update

The Mac (MascotM3) runs two Clawdbot components that need separate updates:

### 1. CLI + Browser Relay

```bash
# SSH to Mac and update
ssh henrymascot@100.86.150.96 "export PATH=\"/opt/homebrew/bin:\$PATH\" && npm update -g clawdbot"
```

### 2. Chrome Extension (after CLI update)

```bash
# Reinstall extension files
ssh henrymascot@100.86.150.96 "export PATH=\"/opt/homebrew/bin:\$PATH\" && clawdbot browser extension install"
```

Then manually in Chrome:
- Go to `chrome://extensions`
- Find "Clawdbot Browser Relay"
- Click **Reload**

### 3. Restart Browser Serve (if running)

```bash
# Kill and restart browser serve
ssh henrymascot@100.86.150.96 "pkill -f 'clawdbot browser serve'; export PATH=\"/opt/homebrew/bin:\$PATH\" && nohup clawdbot browser serve --bind 127.0.0.1 --port 18791 > ~/.clawdbot-browser-serve.log 2>&1 &"
```

### 4. Mac App (Node capabilities)

The native Mac app (`com.clawdbot.mac.debug`) updates separately - check for new releases or auto-update if supported.

### Full Mac Update Command

```bash
# One-liner for CLI + extension + browser serve restart
ssh henrymascot@100.86.150.96 "export PATH=\"/opt/homebrew/bin:\$PATH\" && npm update -g clawdbot && clawdbot browser extension install && pkill -f 'clawdbot browser serve' || true && nohup clawdbot browser serve --bind 127.0.0.1 --port 18791 > ~/.clawdbot-browser-serve.log 2>&1 &"
```

**Note:** After running this, manually reload the extension in Chrome (`chrome://extensions` → Reload).

## Risk Assessment

Before updating, evaluate:

**Low risk:**
- Patch version bump (1.2.3 → 1.2.4)
- Bug fixes only
- No config changes

**Medium risk:**
- Minor version bump (1.2.0 → 1.3.0)
- New features added
- Optional config additions

**High risk:**
- Major version bump (1.0.0 → 2.0.0)
- Breaking changes noted
- Config format changes
- Deprecations

**Always backup before medium/high risk updates.**

## Config Validation

After update, verify:
- Config schema matches new version
- All required fields present
- Deprecated fields migrated
- Gateway restarts successfully

Use `gateway action=config.schema` to check schema compatibility.

## Troubleshooting

**Gateway won't restart:**
1. Check logs: `journalctl -u clawdbot -n 50`
2. Validate config: `gateway action=config.get`
3. Rollback if needed: `scripts/rollback.sh`

**Update fails mid-process:**
1. Don't panic - backup exists
2. Run rollback.sh
3. Check logs for root cause
4. Report issue before retrying

**Rollback fails:**
1. Backup still exists at `~/.clawdbot-backups/`
2. Manually restore config: `cp backup/config.yaml ~/clawdbot/config.yaml`
3. Manually restore code: `git reset --hard <commit-hash>`
4. Restart: `gateway action=restart`

## Best Practices

1. **Always backup before updating** - Automated in scripts
2. **Read changelog first** - Check for breaking changes
3. **Test on non-production first** - Use ada-gateway before Pi
4. **Update during low-usage times** - Avoid peak hours
5. **Keep multiple backups** - Don't delete immediately
6. **Monitor after update** - Watch for 24 hours
7. **Document issues** - Help improve future updates

## Maintenance

**Cleanup old backups:**
```bash
# Keep last 5 backups, delete older
ls -t ~/.clawdbot-backups/ | tail -n +6 | xargs -I {} rm -rf ~/.clawdbot-backups/{}
```

**Check backup space:**
```bash
du -sh ~/.clawdbot-backups/
```