Updating - OpenClaw OpenClawDocs Search...K 🇺🇸English🇺🇸 English🇨🇳 简体中文🇨🇳 繁體中文🇯🇵 日本語🇪🇸 Español🇧🇷 Português (BR)🇰🇷 한국어🇩🇪 Deutsch🇫🇷 Français🇮🇳 हिन्दी🇸🇦 العربية🇮🇹 Italiano🇻🇳 Tiếng Việt🇳🇱 Nederlands🇹🇷 Türkçe🇺🇦 Українська🇮🇩 Bahasa Indonesia🇵🇱 Polski🇷🇺 Русский🇮🇷 فارسی🇹🇭 ไทย🇺🇸English✓🇨🇳简体中文✓🇨🇳繁體中文✓🇯🇵日本語✓🇪🇸Español✓🇧🇷Português (BR)✓🇰🇷한국어✓🇩🇪Deutsch✓🇫🇷Français✓🇮🇳हिन्दी✓🇸🇦العربية✓🇮🇹Italiano✓🇻🇳Tiếng Việt✓🇳🇱Nederlands✓🇹🇷Türkçe✓🇺🇦Українська✓🇮🇩Bahasa Indonesia✓🇵🇱Polski✓🇷🇺Русский✓🇮🇷فارسی✓🇹🇭ไทย✓ Get startedInstallChannelsAgentsCapabilitiesClawHubModelsPlatformsGateway & OpsReferenceRelease & CIHelp Browse docs SectionInstallGet startedInstallChannelsAgentsCapabilitiesClawHubModelsPlatformsGateway & OpsReferenceRelease & CIHelp In this section Install overview InstallInstaller internalsNode.js Maintenance BackupsUpdatingUpdate troubleshootingMigrating Migration guideMigrating from ClaudeMigrating from Hermes UninstallRelease channels Containers AnsibleBunDockerNixPodman Hosting AzureCloudflare ContainersDaytonaDigitalOceanDocker VM runtimeexe.devFly.ioGCPHetznerHostingerKubernetesLinux servermacOS VMsNorthflankOracle CloudRailwayRaspberry PiRenderUpstash Box Advanced setup SetupOpenClaw agent runtime workflow Install/Maintenance/UpdatingCopy pageCopy pageCopy page as Markdown for LLMsView as MarkdownView this page as plain text↗Open in ChatGPTAsk questions about this page↗Open in ClaudeAsk questions about this page↗ Maintenance Updating InstallMaintenance Keep OpenClaw up to date. For Docker, Podman, and Kubernetes image replacements, see Upgrading container images. The gateway runs startup-safe upgrade work before readiness and exits if mounted state needs manual repair. Before a significant update, create a verified backup. Automatic config copies and migration recovery originals are not a full-state backup. Recommended: openclaw update Detects your install type (npm, pnpm, Bun, or git), fetches the latest version, runs openclaw doctor, and restarts a managed Gateway service. bashCopy code openclaw update Switch channels or target a specific version: bashCopy code openclaw update --channel betaopenclaw update --channel extended-stableopenclaw update --channel devopenclaw update --dry-run # preview without applying openclaw update has no --verbose flag (the installer does). For diagnostics use --dry-run to preview planned actions, --json for structured results, or openclaw update status --json to inspect channel and availability state. --channel beta prefers the beta npm dist-tag, but falls back to stable/latest when the beta tag is missing or its version is older than the latest stable release. Use --tag beta for a one-off package update pinned to the raw npm beta dist-tag instead. A saved update.channel remains the channel for future updates, automatic checks, and update status. For example, a one-off beta package on a saved stable channel keeps checking stable afterward. Use --channel beta to subscribe to beta updates. Plugins still follow the installed core version where required for compatibility. --channel extended-stable is package-only, and installation remains foreground-only. OpenClaw reads the public npm extended-stable selector, verifies the selected exact package, and installs that exact version. Missing or inconsistent registry data fails closed; it never falls back to latest. If the selected version is older than the installed version, the normal downgrade confirmation still applies. The CLI persists the channel after a successful core update; a direct npm install -g openclaw@extended-stable --allow-scripts=openclaw does not update update.channel, but a final extended-stable package version still checks only the verified extended-stable selector for update availability. That direct command is for npm 12 or npm 11.16+. On npm 11.15 and earlier, omit --allow-scripts=openclaw. After the core swap, eligible official npm plugins with bare/default or latest intent converge to that exact core version. Exact pins and explicit non-latest tags, third-party plugins, and non-npm sources remain unchanged. Version-bound runtime plugins converge to the base release cohort when the core is a correction release (for example, YYYY.M.P-2 uses plugin YYYY.M.P). Catalog installs created by current OpenClaw versions retain that default intent. Older records that contain only an exact version remain pinned because OpenClaw cannot safely distinguish an old automatic pin from a user pin; run openclaw plugins update @openclaw/name once on the extended-stable channel to opt that plugin back into exact-core tracking. --channel dev gives a persistent moving GitHub main checkout. Package installs reject the --tag main shorthand because the workspace checkout is not a self-contained package artifact. Use openclaw update --channel dev to switch to the supported checkout and build flow. Other explicit package specs keep their package-manager behavior. After a beta core update, eligible official npm plugins follow the exact installed beta version, including one-off --tag updates from a stable installation. For managed plugins, a missing beta release is a warning, not a failure: the core update can still succeed while a plugin falls back to its recorded default/latest release. See Release channels for channel semantics. Retire update recovery data Once you have verified the update and your conversations, preview retained migration originals: bashCopy code openclaw update cleanup --dry-run Use the same profile and state/config overrides as the update, and check the state directory printed in the report. The metadata-only preview can run while the Gateway is active. To apply, stop that Gateway yourself, wait for other SQLite maintenance to finish, then run openclaw update cleanup. Cleanup never stops or restarts the Gateway. Confirmation defaults to No; automation must explicitly pass --yes, including when using --json. Cleanup permanently gives up rollback to eligible originals, including repaired branches and old provider metadata. Current SQLite history, operator backups, and protected or unknown artifacts remain. It is not a substitute for a pre-update backup. See Update cleanup for eligibility, JSON output, and resuming interrupted deletion. Switch between npm and git installs Installer-driven switches verify the replacement before the working owner is retired. Source wrappers are published atomically; same-path npm shim transitions use an identity-checked backup that is restored on failure, so a failed candidate leaves the previous command runnable. The openclaw update command prints its final success result only after post-core convergence and requested restart health checks succeed. If a CLI update fails after installing a usable replacement, recovery uses the newly installed CLI to restart the Gateway it stopped, preserving the managed service definition. A rejected staged candidate leaves the original package intact, and recovery restarts that usable installation. A failed staged swap can also recover when the updater verifies that the original package and every changed launcher were restored. Incomplete rollback keeps the Gateway stopped and retains available backups for repair. After the live package has been modified, a blocking lifecycle, verification, or Doctor failure also leaves the Gateway stopped because the replacement is not known to be runnable. Repair the reported failure, rerun openclaw update, and check openclaw gateway status --deep. If an older target does not support preserving the service definition, automatic recovery stops and reports the error; inspect the service before restarting it manually. Use channels to change the install type. The updater keeps your state, config, credentials, and workspace in ~/.openclaw; it only changes which OpenClaw code install the CLI and gateway use. bashCopy code # npm package install -> editable git checkoutopenclaw update --channel dev # git checkout -> npm package installopenclaw update --channel stable Preview the install-mode switch first: bashCopy code openclaw update --channel dev --dry-runopenclaw update --channel stable --dry-run dev ensures a git checkout, builds it, and installs the global CLI from that checkout. The stable, extended-stable, and beta channels use package installs. Extended-stable is rejected on a git checkout without mutating or converting it. If the gateway is already installed, openclaw update refreshes the service metadata and restarts it unless you pass --no-restart. Dev updates build the complete runtime, including plugins and the Control UI, without generating TypeScript declarations. Preflight still validates the candidate, and the final checkout is rebuilt after checkout or rebase. Ordinary pnpm build and package builds continue to generate declarations. For package installs with a managed Gateway service, openclaw update targets the package root used by that service. If the shell openclaw command comes from a different install, the updater prints both roots and the managed service's Node path, and checks that Node version against the target release's engines.node requirement before replacing the package. Source-checkout servers (reference script) Teams running a gateway directly from a git checkout on a server can update it with scripts/update-gateway.sh from inside that checkout. It is the reference for a source-server update: it fails closed on all tracked local changes, including build outputs, fast-forwards main (or rebases a local server branch onto origin/main), installs dependencies with a frozen lockfile, builds clean, and restarts the gateway only after the build succeeds. This reference script requires Corepack and creates temporary shims without global activation before fetching. After fetching, it freezes the target commit and checks that its exact pnpm pin can run through those shims in a private probe workspace. The probe contains only package-manager metadata, not the target's dependencies, hooks, or configuration. Missing or invalid metadata, provisioning failure, or a version mismatch stops before checkout update or restart; repair the target pin or install a compatible Corepack, then retry. The same fetched commit is used for fast-forward or rebase. This is a fetched-target toolchain preflight, not a complete preflight of a rebased local branch or its build, and the script does not roll back later install or build failures. Local branch overrides remain in effect: install and build resolve the resulting checkout's pin, which may differ from the probed target pin. Operators must verify those overrides and maintain a recovery path. The same shim directory leads nested commands' PATH, and child workspace and lockfile roots follow each operation's directory. Bootstrap, install, or build failure prevents restart. The hosted installers also support npm-owned temporary provisioning when Corepack is unavailable; this server script deliberately requires Corepack. Warning A running older updater or server script keeps its old bootstrap code even if it checks out files containing this repair. If that older entry point invokes ambient pnpm, the operator must select a target-compatible pnpm launcher before the first update across the pin change. Validate that launcher against both the intended target and the known-good rollback ref before starting the update. Updating target files alone does not repair an older running binary. Generated output roots such as dist, dist-runtime, and package-local dist directories must be real directories. Bui…