mirror of
https://github.com/openclaw/openclaw.git
synced 2026-05-08 07:30:43 +00:00
181 lines
5.4 KiB
Markdown
181 lines
5.4 KiB
Markdown
---
|
|
summary: "Updating OpenClaw safely (global install or source), plus rollback strategy"
|
|
read_when:
|
|
- Updating OpenClaw
|
|
- Something breaks after an update
|
|
title: "Updating"
|
|
---
|
|
|
|
Keep OpenClaw up to date.
|
|
|
|
## Recommended: `openclaw update`
|
|
|
|
The fastest way to update. It detects your install type (npm or git), fetches the latest version, runs `openclaw doctor`, and restarts the gateway.
|
|
|
|
```bash
|
|
openclaw update
|
|
```
|
|
|
|
To switch channels or target a specific version:
|
|
|
|
```bash
|
|
openclaw update --channel beta
|
|
openclaw update --tag main
|
|
openclaw update --dry-run # preview without applying
|
|
```
|
|
|
|
`--channel beta` prefers beta, but the runtime falls back to stable/latest when
|
|
the beta tag is missing or older than the latest stable release. Use `--tag beta`
|
|
if you want the raw npm beta dist-tag for a one-off package update.
|
|
|
|
See [Development channels](/install/development-channels) for channel semantics.
|
|
|
|
## Alternative: re-run the installer
|
|
|
|
```bash
|
|
curl -fsSL https://openclaw.ai/install.sh | bash
|
|
```
|
|
|
|
Add `--no-onboard` to skip onboarding. For source installs, pass `--install-method git --no-onboard`.
|
|
|
|
## Alternative: manual npm, pnpm, or bun
|
|
|
|
```bash
|
|
npm i -g openclaw@latest
|
|
```
|
|
|
|
```bash
|
|
pnpm add -g openclaw@latest
|
|
```
|
|
|
|
```bash
|
|
bun add -g openclaw@latest
|
|
```
|
|
|
|
### Global npm installs and runtime dependencies
|
|
|
|
OpenClaw treats packaged global installs as read-only at runtime, even when the
|
|
global package directory is writable by the current user. Bundled plugin runtime
|
|
dependencies are staged into a writable runtime directory instead of mutating the
|
|
package tree. This keeps `openclaw update` from racing with a running gateway or
|
|
local agent that is repairing plugin dependencies during the same install.
|
|
|
|
Some Linux npm setups install global packages under root-owned directories such
|
|
as `/usr/lib/node_modules/openclaw`. OpenClaw supports that layout through the
|
|
same external staging path.
|
|
|
|
For hardened systemd units, set a writable stage directory that is included in
|
|
`ReadWritePaths`:
|
|
|
|
```ini
|
|
Environment=OPENCLAW_PLUGIN_STAGE_DIR=/var/lib/openclaw/plugin-runtime-deps
|
|
ReadWritePaths=/var/lib/openclaw /home/openclaw/.openclaw /tmp
|
|
```
|
|
|
|
If `OPENCLAW_PLUGIN_STAGE_DIR` is not set, OpenClaw uses `$STATE_DIRECTORY` when
|
|
systemd provides it, then falls back to `~/.openclaw/plugin-runtime-deps`.
|
|
The repair step treats that stage as an OpenClaw-owned local package root and
|
|
ignores user npm prefix/global settings, so global-install npm config does not
|
|
redirect bundled plugin dependencies into `~/node_modules` or the global package
|
|
tree.
|
|
|
|
### Bundled plugin runtime dependencies
|
|
|
|
Packaged installs keep bundled plugin runtime dependencies out of the read-only
|
|
package tree. On startup and during `openclaw doctor --fix`, OpenClaw repairs
|
|
runtime dependencies only for bundled plugins that are active in config, active
|
|
through legacy channel config, or enabled by their bundled manifest default.
|
|
|
|
Explicit disablement wins. A disabled plugin or channel does not get its
|
|
runtime dependencies repaired just because it exists in the package. External
|
|
plugins and custom load paths still use `openclaw plugins install` or
|
|
`openclaw plugins update`.
|
|
|
|
## Auto-updater
|
|
|
|
The auto-updater is off by default. Enable it in `~/.openclaw/openclaw.json`:
|
|
|
|
```json5
|
|
{
|
|
update: {
|
|
channel: "stable",
|
|
auto: {
|
|
enabled: true,
|
|
stableDelayHours: 6,
|
|
stableJitterHours: 12,
|
|
betaCheckIntervalHours: 1,
|
|
},
|
|
},
|
|
}
|
|
```
|
|
|
|
| Channel | Behavior |
|
|
| -------- | ------------------------------------------------------------------------------------------------------------- |
|
|
| `stable` | Waits `stableDelayHours`, then applies with deterministic jitter across `stableJitterHours` (spread rollout). |
|
|
| `beta` | Checks every `betaCheckIntervalHours` (default: hourly) and applies immediately. |
|
|
| `dev` | No automatic apply. Use `openclaw update` manually. |
|
|
|
|
The gateway also logs an update hint on startup (disable with `update.checkOnStart: false`).
|
|
|
|
## After updating
|
|
|
|
<Steps>
|
|
|
|
### Run doctor
|
|
|
|
```bash
|
|
openclaw doctor
|
|
```
|
|
|
|
Migrates config, audits DM policies, and checks gateway health. Details: [Doctor](/gateway/doctor)
|
|
|
|
### Restart the gateway
|
|
|
|
```bash
|
|
openclaw gateway restart
|
|
```
|
|
|
|
### Verify
|
|
|
|
```bash
|
|
openclaw health
|
|
```
|
|
|
|
</Steps>
|
|
|
|
## Rollback
|
|
|
|
### Pin a version (npm)
|
|
|
|
```bash
|
|
npm i -g openclaw@<version>
|
|
openclaw doctor
|
|
openclaw gateway restart
|
|
```
|
|
|
|
Tip: `npm view openclaw version` shows the current published version.
|
|
|
|
### Pin a commit (source)
|
|
|
|
```bash
|
|
git fetch origin
|
|
git checkout "$(git rev-list -n 1 --before=\"2026-01-01\" origin/main)"
|
|
pnpm install && pnpm build
|
|
openclaw gateway restart
|
|
```
|
|
|
|
To return to latest: `git checkout main && git pull`.
|
|
|
|
## If you are stuck
|
|
|
|
- Run `openclaw doctor` again and read the output carefully.
|
|
- For `openclaw update --channel dev` on source checkouts, the updater auto-bootstraps `pnpm` when needed. If you see a pnpm/corepack bootstrap error, install `pnpm` manually (or re-enable `corepack`) and rerun the update.
|
|
- Check: [Troubleshooting](/gateway/troubleshooting)
|
|
- Ask in Discord: [https://discord.gg/clawd](https://discord.gg/clawd)
|
|
|
|
## Related
|
|
|
|
- [Install Overview](/install) — all installation methods
|
|
- [Doctor](/gateway/doctor) — health checks after updates
|
|
- [Migrating](/install/migrating) — major version migration guides
|