clawd/docs/update-plan.md

Update Plan: Claude Code & OpenClaw

Created: 2026-02-04

Principles

1. Never update blind — check what changed before applying
2. Always be able to rollback — save current version before updating
3. Verify after update — gateway must start and respond before declaring success
4. Don't update during active work — schedule for low-activity windows
5. James owns this — no manual intervention from Johan unless something breaks badly

Schedule

When: Daily at 5:30 AM ET (during Johan's second sleep block)

• Low-activity window, no active conversations
• If update fails, James has time to rollback before Johan wakes (~9-10 AM)

Frequency: Check daily, apply only when new versions exist.

Update Process (automated script)

Step 1: Check for updates (no changes yet)

- Read current versions (openclaw --version, claude --version)
- Check npm registry for latest versions
- If both current → exit (nothing to do)
- Log what's available

Step 2: Snapshot current state

- Record current versions to rollback file
- Backup gateway config (~/.openclaw/openclaw.json)
- Verify gateway is healthy BEFORE updating (curl health endpoint)

Step 3: Update OpenClaw (if new version)

- npm i -g openclaw@latest
- Run: openclaw doctor (migrations, config fixes)
- Restart gateway: systemctl --user restart openclaw-gateway
- Wait 10 seconds
- Health check: openclaw health / curl gateway
- If FAIL → rollback immediately (npm i -g openclaw@<old_version>)

Step 4: Update Claude Code (if new version)

- npm i -g @anthropic-ai/claude-code@latest
- Verify: claude --version
- (No restart needed — Claude Code is invoked per-session)

Step 5: Report

- Log results to memory/update-log.md
- Update dashboard status API
- If anything failed: create task for Johan

Rollback

- npm i -g openclaw@<previous_version>
- openclaw doctor
- systemctl --user restart openclaw-gateway
- Verify health

What the script does NOT do

• Update during active conversations
• Update if the gateway is unhealthy to begin with
• Continue if OpenClaw update fails (stops, rollback, alert)
• Update both at once if OpenClaw fails (Claude Code update skipped)

Files

• Script: ~/clawd/scripts/safe-update.sh
• Rollback file: ~/clawd/data/update-rollback.json
• Update log: ~/clawd/memory/update-log.md
• Cron: 5:30 AM ET daily

Open Questions for Johan

1. Auto-apply or approve? Script can either apply automatically at 5:30 AM, or just notify and wait for approval. Recommendation: auto-apply with rollback.
2. Channel: Stay on stable or use beta? Currently on stable (default).
3. Hold on major version bumps? e.g., if OpenClaw goes from 2026.2.x to 2026.3.x, pause and ask first?