# OpenClaw Upgrade Runbook (Existing Install)

Use this when OpenClaw is already installed and you want to upgrade in place.

## Recommended command

```bash
cd /Volumes/Data/openclaw-setups/openclaw-setup-max
bash ./scripts/update_openclaw.sh
```

## What `update_openclaw.sh` does

- Backs up:
  - `~/.openclaw/openclaw.json`
  - `~/.openclaw/agents/main/sessions/sessions.json`
- Stops local model guard LaunchAgents and gateway before update
- Runs `openclaw doctor --fix --non-interactive`
- Runs `openclaw update` with timeout protection
- Falls back to `npm install -g openclaw@...` if updater hangs/fails
- Prints timestamped step logs for restart/update traceability
- Starts gateway and installs service if missing
- If `~/.openclaw` is symlinked to `/Volumes/...`, patches gateway LaunchAgent logs to:
  - `/tmp/openclaw-gateway.launchd.log`
  - `/tmp/openclaw-gateway.launchd.err.log`
- Reinstalls schedule + budget guard LaunchAgents
- Kickstarts both guards immediately so profile/budget logic is applied now
- Prints gateway + model/guard status summary

## Useful options

```bash
# switch update channel
bash ./scripts/update_openclaw.sh --channel beta

# one-off version/tag
bash ./scripts/update_openclaw.sh --tag 2026.2.24

# increase built-in update timeout (seconds)
UPDATE_MAX_SECONDS=900 bash ./scripts/update_openclaw.sh

# capture a timestamped run log file
bash ./scripts/update_openclaw.sh 2>&1 | tee "/tmp/openclaw-update-$(date +%Y%m%d-%H%M%S).log"
```

## Verify after upgrade

```bash
openclaw --version
openclaw gateway status
openclaw gateway health --json
bash ./scripts/model_profile_switch.sh status
launchctl print gui/$(id -u)/ai.openclaw.local.model-schedule-guard | rg 'last exit code|state'
launchctl print gui/$(id -u)/ai.openclaw.local.model-budget-guard | rg 'last exit code|state'
ls -lT /tmp/openclaw-gateway.launchd.log /tmp/openclaw-gateway.launchd.err.log
```

## If gateway is loaded but not running

```bash
cd /Volumes/Data/openclaw-setups/openclaw-setup-max
bash ./scripts/update_openclaw.sh
```

If still failing, see:
- `docs/operations/troubleshooting.md`