Updating OpenClaw Version on a VPS inside a Docker and Mac Node
Guide me step-by-step. One command at a time. Confirm each output before moving on. Always include a rollback step before any destructive change.
OpenClaw Upgrade Runbook (VPS Docker + Mac Node)
0) Current setup (so the new helper has context)
* Gateway runs on a VPS in Docker.
* The running container image is locally built (e.g. openclaw:local-uv), not an official registry tag.
* Inside the container, the CLI is available as: /app/openclaw.mjs
* Repo checkout exists at: /app (has dist/, node_modules/, docs/)
* Gateway config is stored at: /home/node/.openclaw/openclaw.json (backups exist as openclaw.json.bak)
* Mac node is paired/connected via an SSH tunnel.
* Browser automation for JS/login sites should use the browser tool routed to the Mac node (profile openclaw), not system.run.
* Relevant config changes made recently (verify before upgrading):
* tools.exec.ask = off
* gateway.nodes.browser.mode = auto (so browser routes to Mac node automatically)
* gateway.bind = loopback (gateway only listens on 127.0.0.1 on the VPS)
* Mac node connectivity depends on a persistent SSH tunnel / port-forward (likely via a macOS LaunchAgent) so the Mac can reach the loopback-only gateway.
* Tailscale may exist, but it’s not the primary transport while loopback+SSH tunnel is in use.
1) Goal
Upgrade OpenClaw to the latest stable safely, with:
* predictable downtime
* a rollback plan
* no surprises with node compatibility (Mac node stays working)
2) Preflight checklist (gather facts)
Collect these outputs and paste them into the upgrade chat: On VPS host:
* Which image is running:
* docker inspect --format '{{.Config.Image}}' openclaw-openclaw-gateway-1
*
* Inside the gateway container:
* Current OpenClaw version:
* docker exec -it openclaw-openclaw-gateway-1 sh -lc '/app/openclaw.mjs --version'
* Current config deltas that matter:
*
* docker exec -it openclaw-openclaw-gateway-1 sh -lc '/app/openclaw.mjs config get tools.exec.ask'
* docker exec -it openclaw-openclaw-gateway-1 sh -lc '/app/openclaw.mjs config get gateway.nodes.browser.mode'
* Confirm node is connected:
* docker exec -it openclaw-openclaw-gateway-1 sh -lc '/app/openclaw.mjs nodes status'
* On the Mac node (if possible):
* Node version and how it’s installed (menubar app vs headless node host).
* 3) Backup plan (must-do before changes) VPS gateway backups:
* Backup config and workspace data (at minimum):
* /home/node/.openclaw/openclaw.json
* /home/node/.openclaw/workspace/ (if you care about workspace state)
* Record the current Docker image ID so you can roll back:
* docker image ls | head (or docker images | grep openclaw)
* Mac node backups:
* ~/.openclaw/exec-approvals.json
* ~/.openclaw/node.json (if present)
*
* 4) Choose your upgrade strategy You have two paths:
* A) Stay on local-build Docker image (what you have now)
* Update the source in /app (or wherever you build from)
* Rebuild openclaw:local-uv
* Restart containers
* Pros: keeps your custom build “shape” (uv/extra packages/etc)
* Cons: you must rebuild each upgrade
* B) Switch to official tagged image (later, optional)
* Use ghcr.io/openclaw/openclaw:latest or :<version>
* Requires updating compose / env to stop building locally
* Pros: easier upgrades (pull tags)
* Cons: you may lose custom extras unless you build a derived image
1/2
OpenClaw Upgrade Runbook (VPS Docker + Mac Node)
0) Current setup (so the new helper has context)
* Gateway runs on a VPS in Docker.
* The running container image is locally built (e.g. openclaw:local-uv), not an official registry tag.
* Inside the container, the CLI is available as: /app/openclaw.mjs
* Repo checkout exists at: /app (has dist/, node_modules/, docs/)
* Gateway config is stored at: /home/node/.openclaw/openclaw.json (backups exist as openclaw.json.bak)
* Mac node is paired/connected via an SSH tunnel.
* Browser automation for JS/login sites should use the browser tool routed to the Mac node (profile openclaw), not system.run.
* Relevant config changes made recently (verify before upgrading):
* tools.exec.ask = off
* gateway.nodes.browser.mode = auto (so browser routes to Mac node automatically)
* gateway.bind = loopback (gateway only listens on 127.0.0.1 on the VPS)
* Mac node connectivity depends on a persistent SSH tunnel / port-forward (likely via a macOS LaunchAgent) so the Mac can reach the loopback-only gateway.
* Tailscale may exist, but it’s not the primary transport while loopback+SSH tunnel is in use.
1) Goal
Upgrade OpenClaw to the latest stable safely, with:
* predictable downtime
* a rollback plan
* no surprises with node compatibility (Mac node stays working)
2) Preflight checklist (gather facts)
Collect these outputs and paste them into the upgrade chat: On VPS host:
* Which image is running:
* docker inspect --format '{{.Config.Image}}' openclaw-openclaw-gateway-1
*
* Inside the gateway container:
* Current OpenClaw version:
* docker exec -it openclaw-openclaw-gateway-1 sh -lc '/app/openclaw.mjs --version'
* Current config deltas that matter:
*
* docker exec -it openclaw-openclaw-gateway-1 sh -lc '/app/openclaw.mjs config get tools.exec.ask'
* docker exec -it openclaw-openclaw-gateway-1 sh -lc '/app/openclaw.mjs config get gateway.nodes.browser.mode'
* Confirm node is connected:
* docker exec -it openclaw-openclaw-gateway-1 sh -lc '/app/openclaw.mjs nodes status'
* On the Mac node (if possible):
* Node version and how it’s installed (menubar app vs headless node host).
* 3) Backup plan (must-do before changes) VPS gateway backups:
* Backup config and workspace data (at minimum):
* /home/node/.openclaw/openclaw.json
* /home/node/.openclaw/workspace/ (if you care about workspace state)
* Record the current Docker image ID so you can roll back:
* docker image ls | head (or docker images | grep openclaw)
* Mac node backups:
* ~/.openclaw/exec-approvals.json
* ~/.openclaw/node.json (if present)
*
* 4) Choose your upgrade strategy You have two paths:
* A) Stay on local-build Docker image (what you have now)
* Update the source in /app (or wherever you build from)
* Rebuild openclaw:local-uv
* Restart containers
* Pros: keeps your custom build “shape” (uv/extra packages/etc)
* Cons: you must rebuild each upgrade
* B) Switch to official tagged image (later, optional)
* Use ghcr.io/openclaw/openclaw:latest or :<version>
* Requires updating compose / env to stop building locally
* Pros: easier upgrades (pull tags)
* Cons: you may lose custom extras unless you build a derived image
1/2
The AI that actually does things. Emails, calendar, home automation - all from your favorite chat app. New shell, ready to help. The lobster way.
134,827Members
Resources
Was this page helpful?
