​

Updating

​

Before you update

• Know how you installed: npm (global) vs from source (git clone).
• Know how your Gateway is running: foreground terminal vs supervised service (launchd/systemd).
• Snapshot your tailoring:
  • Config: ~/.clawdbot/clawdbot.json
  • Credentials: ~/.clawdbot/credentials/
  • Workspace: ~/clawd

​

Update (npm install)

npm i -g clawdbot@latest

pnpm add -g clawdbot@latest

clawdbot doctor
clawdbot daemon restart
clawdbot health

• If your Gateway runs as a service, clawdbot daemon restart is preferred over killing PIDs.
• If you’re pinned to a specific version, see “Rollback / pinning” below.

​

Update (Control UI / RPC)

1. Runs a git update (clean rebase) or package manager update.
2. Writes a restart sentinel with a structured report (stdout/stderr tail).
3. Restarts the gateway and pings the last active session with the report.

​

Update (from source)

git pull
pnpm install
pnpm build
pnpm ui:install
pnpm ui:build
pnpm clawdbot doctor
pnpm clawdbot health

• pnpm build matters when you run the packaged clawdbot binary (dist/entry.js) or use Node to run dist/.
• If you run directly from TypeScript (pnpm clawdbot ... / bun run clawdbot ...), a rebuild is usually unnecessary, but config migrations still apply → run doctor.

​

Always run: clawdbot doctor

• Migrate deprecated config keys / legacy config file locations.
• Audit DM policies and warn on risky “open” settings.
• Check Gateway health and can offer to restart.
• Detect and migrate older gateway services (launchd/systemd; legacy schtasks) to current Clawdbot services.
• On Linux, ensure systemd user lingering (so the Gateway survives logout).

​

Start / stop / restart the Gateway

clawdbot daemon status
clawdbot daemon stop
clawdbot daemon restart
clawdbot gateway --port 18789
clawdbot logs --follow

• macOS launchd (app-bundled LaunchAgent): launchctl kickstart -k gui/$UID/com.clawdbot.gateway
• Linux systemd user service: systemctl --user restart clawdbot-gateway.service
• Windows (WSL2): systemctl --user restart clawdbot-gateway.service
  • launchctl/systemctl only work if the service is installed; otherwise run clawdbot daemon install.

​

Rollback / pinning (when something breaks)

​

Pin (npm)

npm i -g [email protected]

clawdbot doctor
clawdbot daemon restart

​

Pin (source) by date

git fetch origin
git checkout "$(git rev-list -n 1 --before=\"2026-01-01\" origin/main)"

pnpm install
pnpm build
clawdbot daemon restart

git checkout main
git pull

​

If you’re stuck

• Run clawdbot doctor again and read the output carefully (it often tells you the fix).
• Check: Troubleshooting
• Ask in Discord: https://discord.gg/clawd