{
  "title": "Updating",
  "content": "OpenClaw is moving fast (pre “1.0”). Treat updates like shipping infra: update → run checks → restart (or use `openclaw update`, which restarts) → verify.\n\n## Recommended: re-run the website installer (upgrade in place)\n\nThe **preferred** update path is to re-run the installer from the website. It\ndetects existing installs, upgrades in place, and runs `openclaw doctor` when\nneeded.\n\n* Add `--no-onboard` if you don’t want the onboarding wizard to run again.\n* For **source installs**, use:\n  \n  The installer will `git pull --rebase` **only** if the repo is clean.\n* For **global installs**, the script uses `npm install -g openclaw@latest` under the hood.\n* Legacy note: `clawdbot` remains available as a compatibility shim.\n\n* Know how you installed: **global** (npm/pnpm) vs **from source** (git clone).\n* Know how your Gateway is running: **foreground terminal** vs **supervised service** (launchd/systemd).\n* Snapshot your tailoring:\n  * Config: `~/.openclaw/openclaw.json`\n  * Credentials: `~/.openclaw/credentials/`\n  * Workspace: `~/.openclaw/workspace`\n\n## Update (global install)\n\nGlobal install (pick one):\n\nWe do **not** recommend Bun for the Gateway runtime (WhatsApp/Telegram bugs).\n\nTo switch update channels (git + npm installs):\n\nUse `--tag <dist-tag|version>` for a one-off install tag/version.\n\nSee [Development channels](/install/development-channels) for channel semantics and release notes.\n\nNote: on npm installs, the gateway logs an update hint on startup (checks the current channel tag). Disable via `update.checkOnStart: false`.\n\n* If your Gateway runs as a service, `openclaw gateway restart` is preferred over killing PIDs.\n* If you’re pinned to a specific version, see “Rollback / pinning” below.\n\n## Update (`openclaw update`)\n\nFor **source installs** (git checkout), prefer:\n\nIt runs a safe-ish update flow:\n\n* Requires a clean worktree.\n* Switches to the selected channel (tag or branch).\n* Fetches + rebases against the configured upstream (dev channel).\n* Installs deps, builds, builds the Control UI, and runs `openclaw doctor`.\n* Restarts the gateway by default (use `--no-restart` to skip).\n\nIf you installed via **npm/pnpm** (no git metadata), `openclaw update` will try to update via your package manager. If it can’t detect the install, use “Update (global install)” instead.\n\n## Update (Control UI / RPC)\n\nThe Control UI has **Update & Restart** (RPC: `update.run`). It:\n\n1. Runs the same source-update flow as `openclaw update` (git checkout only).\n2. Writes a restart sentinel with a structured report (stdout/stderr tail).\n3. Restarts the gateway and pings the last active session with the report.\n\nIf the rebase fails, the gateway aborts and restarts without applying the update.\n\n## Update (from source)\n\nFrom the repo checkout:\n\nManual (equivalent-ish):\n\n* `pnpm build` matters when you run the packaged `openclaw` binary ([`openclaw.mjs`](https://github.com/openclaw/openclaw/blob/main/openclaw.mjs)) or use Node to run `dist/`.\n* If you run from a repo checkout without a global install, use `pnpm openclaw ...` for CLI commands.\n* If you run directly from TypeScript (`pnpm openclaw ...`), a rebuild is usually unnecessary, but **config migrations still apply** → run doctor.\n* Switching between global and git installs is easy: install the other flavor, then run `openclaw doctor` so the gateway service entrypoint is rewritten to the current install.\n\n## Always Run: `openclaw doctor`\n\nDoctor is the “safe update” command. It’s intentionally boring: repair + migrate + warn.\n\nNote: if you’re on a **source install** (git checkout), `openclaw doctor` will offer to run `openclaw update` first.\n\nTypical things it does:\n\n* Migrate deprecated config keys / legacy config file locations.\n* Audit DM policies and warn on risky “open” settings.\n* Check Gateway health and can offer to restart.\n* Detect and migrate older gateway services (launchd/systemd; legacy schtasks) to current OpenClaw services.\n* On Linux, ensure systemd user lingering (so the Gateway survives logout).\n\nDetails: [Doctor](/gateway/doctor)\n\n## Start / stop / restart the Gateway\n\nCLI (works regardless of OS):\n\nIf you’re supervised:\n\n* macOS launchd (app-bundled LaunchAgent): `launchctl kickstart -k gui/$UID/bot.molt.gateway` (use `bot.molt.<profile>`; legacy `com.openclaw.*` still works)\n* Linux systemd user service: `systemctl --user restart openclaw-gateway[-<profile>].service`\n* Windows (WSL2): `systemctl --user restart openclaw-gateway[-<profile>].service`\n  * `launchctl`/`systemctl` only work if the service is installed; otherwise run `openclaw gateway install`.\n\nRunbook + exact service labels: [Gateway runbook](/gateway)\n\n## Rollback / pinning (when something breaks)\n\n### Pin (global install)\n\nInstall a known-good version (replace `<version>` with the last working one):\n\nTip: to see the current published version, run `npm view openclaw version`.\n\nThen restart + re-run doctor:\n\n### Pin (source) by date\n\nPick a commit from a date (example: “state of main as of 2026-01-01”):\n\nThen reinstall deps + restart:\n\nIf you want to go back to latest later:\n\n* Run `openclaw doctor` again and read the output carefully (it often tells you the fix).\n* Check: [Troubleshooting](/gateway/troubleshooting)\n* Ask in Discord: [https://discord.gg/clawd](https://discord.gg/clawd)",
  "code_samples": [
    {
      "code": "Notes:\n\n* Add `--no-onboard` if you don’t want the onboarding wizard to run again.\n* For **source installs**, use:",
      "language": "unknown"
    },
    {
      "code": "The installer will `git pull --rebase` **only** if the repo is clean.\n* For **global installs**, the script uses `npm install -g openclaw@latest` under the hood.\n* Legacy note: `clawdbot` remains available as a compatibility shim.\n\n## Before you update\n\n* Know how you installed: **global** (npm/pnpm) vs **from source** (git clone).\n* Know how your Gateway is running: **foreground terminal** vs **supervised service** (launchd/systemd).\n* Snapshot your tailoring:\n  * Config: `~/.openclaw/openclaw.json`\n  * Credentials: `~/.openclaw/credentials/`\n  * Workspace: `~/.openclaw/workspace`\n\n## Update (global install)\n\nGlobal install (pick one):",
      "language": "unknown"
    },
    {
      "code": "",
      "language": "unknown"
    },
    {
      "code": "We do **not** recommend Bun for the Gateway runtime (WhatsApp/Telegram bugs).\n\nTo switch update channels (git + npm installs):",
      "language": "unknown"
    },
    {
      "code": "Use `--tag <dist-tag|version>` for a one-off install tag/version.\n\nSee [Development channels](/install/development-channels) for channel semantics and release notes.\n\nNote: on npm installs, the gateway logs an update hint on startup (checks the current channel tag). Disable via `update.checkOnStart: false`.\n\nThen:",
      "language": "unknown"
    },
    {
      "code": "Notes:\n\n* If your Gateway runs as a service, `openclaw gateway restart` is preferred over killing PIDs.\n* If you’re pinned to a specific version, see “Rollback / pinning” below.\n\n## Update (`openclaw update`)\n\nFor **source installs** (git checkout), prefer:",
      "language": "unknown"
    },
    {
      "code": "It runs a safe-ish update flow:\n\n* Requires a clean worktree.\n* Switches to the selected channel (tag or branch).\n* Fetches + rebases against the configured upstream (dev channel).\n* Installs deps, builds, builds the Control UI, and runs `openclaw doctor`.\n* Restarts the gateway by default (use `--no-restart` to skip).\n\nIf you installed via **npm/pnpm** (no git metadata), `openclaw update` will try to update via your package manager. If it can’t detect the install, use “Update (global install)” instead.\n\n## Update (Control UI / RPC)\n\nThe Control UI has **Update & Restart** (RPC: `update.run`). It:\n\n1. Runs the same source-update flow as `openclaw update` (git checkout only).\n2. Writes a restart sentinel with a structured report (stdout/stderr tail).\n3. Restarts the gateway and pings the last active session with the report.\n\nIf the rebase fails, the gateway aborts and restarts without applying the update.\n\n## Update (from source)\n\nFrom the repo checkout:\n\nPreferred:",
      "language": "unknown"
    },
    {
      "code": "Manual (equivalent-ish):",
      "language": "unknown"
    },
    {
      "code": "Notes:\n\n* `pnpm build` matters when you run the packaged `openclaw` binary ([`openclaw.mjs`](https://github.com/openclaw/openclaw/blob/main/openclaw.mjs)) or use Node to run `dist/`.\n* If you run from a repo checkout without a global install, use `pnpm openclaw ...` for CLI commands.\n* If you run directly from TypeScript (`pnpm openclaw ...`), a rebuild is usually unnecessary, but **config migrations still apply** → run doctor.\n* Switching between global and git installs is easy: install the other flavor, then run `openclaw doctor` so the gateway service entrypoint is rewritten to the current install.\n\n## Always Run: `openclaw doctor`\n\nDoctor is the “safe update” command. It’s intentionally boring: repair + migrate + warn.\n\nNote: if you’re on a **source install** (git checkout), `openclaw doctor` will offer to run `openclaw update` first.\n\nTypical things it does:\n\n* Migrate deprecated config keys / legacy config file locations.\n* Audit DM policies and warn on risky “open” settings.\n* Check Gateway health and can offer to restart.\n* Detect and migrate older gateway services (launchd/systemd; legacy schtasks) to current OpenClaw services.\n* On Linux, ensure systemd user lingering (so the Gateway survives logout).\n\nDetails: [Doctor](/gateway/doctor)\n\n## Start / stop / restart the Gateway\n\nCLI (works regardless of OS):",
      "language": "unknown"
    },
    {
      "code": "If you’re supervised:\n\n* macOS launchd (app-bundled LaunchAgent): `launchctl kickstart -k gui/$UID/bot.molt.gateway` (use `bot.molt.<profile>`; legacy `com.openclaw.*` still works)\n* Linux systemd user service: `systemctl --user restart openclaw-gateway[-<profile>].service`\n* Windows (WSL2): `systemctl --user restart openclaw-gateway[-<profile>].service`\n  * `launchctl`/`systemctl` only work if the service is installed; otherwise run `openclaw gateway install`.\n\nRunbook + exact service labels: [Gateway runbook](/gateway)\n\n## Rollback / pinning (when something breaks)\n\n### Pin (global install)\n\nInstall a known-good version (replace `<version>` with the last working one):",
      "language": "unknown"
    },
    {
      "code": "",
      "language": "unknown"
    },
    {
      "code": "Tip: to see the current published version, run `npm view openclaw version`.\n\nThen restart + re-run doctor:",
      "language": "unknown"
    },
    {
      "code": "### Pin (source) by date\n\nPick a commit from a date (example: “state of main as of 2026-01-01”):",
      "language": "unknown"
    },
    {
      "code": "Then reinstall deps + restart:",
      "language": "unknown"
    },
    {
      "code": "If you want to go back to latest later:",
      "language": "unknown"
    }
  ],
  "headings": [
    {
      "level": "h2",
      "text": "Recommended: re-run the website installer (upgrade in place)",
      "id": "recommended:-re-run-the-website-installer-(upgrade-in-place)"
    },
    {
      "level": "h2",
      "text": "Before you update",
      "id": "before-you-update"
    },
    {
      "level": "h2",
      "text": "Update (global install)",
      "id": "update-(global-install)"
    },
    {
      "level": "h2",
      "text": "Update (`openclaw update`)",
      "id": "update-(`openclaw-update`)"
    },
    {
      "level": "h2",
      "text": "Update (Control UI / RPC)",
      "id": "update-(control-ui-/-rpc)"
    },
    {
      "level": "h2",
      "text": "Update (from source)",
      "id": "update-(from-source)"
    },
    {
      "level": "h2",
      "text": "Always Run: `openclaw doctor`",
      "id": "always-run:-`openclaw-doctor`"
    },
    {
      "level": "h2",
      "text": "Start / stop / restart the Gateway",
      "id": "start-/-stop-/-restart-the-gateway"
    },
    {
      "level": "h2",
      "text": "Rollback / pinning (when something breaks)",
      "id": "rollback-/-pinning-(when-something-breaks)"
    },
    {
      "level": "h3",
      "text": "Pin (global install)",
      "id": "pin-(global-install)"
    },
    {
      "level": "h3",
      "text": "Pin (source) by date",
      "id": "pin-(source)-by-date"
    },
    {
      "level": "h2",
      "text": "If you’re stuck",
      "id": "if-you’re-stuck"
    }
  ],
  "url": "llms-txt#updating",
  "links": []
}