更新

OpenClaw 迭代很快（还处于 “1.0” 之前）。把更新当作上线基础设施：更新 → 跑检查 → 重启（或使用会自动重启的 openclaw update）→ 验证。

推荐：重新运行官网安装器（原地升级）

首选更新方式是重新运行官网安装器。它会检测已有安装、原地升级，并在需要时运行 openclaw doctor。

curl -fsSL https://openclaw.ai/install.sh | bash

备注：

• 如果你不想再次运行 onboarding wizard，加 --no-onboard。
• 对源码安装，使用：

  curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git --no-onboard

  安装器只会在仓库干净时执行 git pull --rebase。
• 对全局安装，脚本底层会执行 npm install -g openclaw@latest。
• Legacy：openclaw 仍会作为兼容性 shim 保持可用。

更新前

• 确认你的安装方式：全局（npm/pnpm）还是源码（git clone）。
• 确认 Gateway 的运行方式：前台终端还是受监督的 service（launchd/systemd）。
• 备份/快照你的定制：
  • Config：~/.openclaw/openclaw.json
  • Credentials：~/.openclaw/credentials/
  • Workspace：~/.openclaw/workspace

更新（全局安装）

全局安装（任选其一）：

npm i -g openclaw@latest

pnpm add -g openclaw@latest

我们不推荐用 Bun 作为 Gateway runtime（WhatsApp/Telegram 相关 bug）。

切换更新通道（git + npm 安装都支持）：

openclaw update --channel beta
openclaw update --channel dev
openclaw update --channel stable

用 --tag <dist-tag|version> 进行一次性的 tag/version 安装。

通道语义与发布说明见 Development channels。

注意：npm 安装时，gateway 启动时会输出更新提示（会检查当前 channel tag）。可通过 update.checkOnStart: false 关闭。

然后：

openclaw doctor
openclaw gateway restart
openclaw health

备注：

• 如果你的 Gateway 作为 service 运行，优先用 openclaw gateway restart，不要直接 kill PID。
• 如果你固定在某个版本，见下方 “Rollback / pinning”。

更新（openclaw update）

对源码安装（git checkout），优先使用：

openclaw update

它会执行一个相对安全的更新流程：

• 要求 worktree 干净。
• 切换到你选择的通道（tag 或 branch）。
• 拉取并对配置的 upstream 做 rebase（dev 通道）。
• 安装依赖、构建、构建 Control UI，并运行 openclaw doctor。
• 默认重启 gateway（用 --no-restart 可跳过）。

如果你通过 npm/pnpm 安装（无 git 元数据），openclaw update 会尝试通过包管理器更新；如果无法识别安装方式，请改用上面的 “更新（全局安装）”。

更新（Control UI / RPC）

Control UI 提供 Update & Restart（RPC：update.run）。它会：

1. 运行与 openclaw update 相同的源码更新流程（仅 git checkout）。
2. 写入一个重启 sentinel，并记录结构化报告（stdout/stderr tail）。
3. 重启 gateway，并把报告发送到最近活跃的 session。

如果 rebase 失败，gateway 会中止并重启，但不会应用更新。

更新（从源码）

在仓库 checkout 内：

推荐：

openclaw update

手动（大致等价）：

git pull
pnpm install
pnpm build
pnpm ui:build # 首次运行时自动安装 UI 依赖
openclaw doctor
openclaw health

备注：

• 当你运行打包后的 openclaw 二进制（openclaw.mjs）或用 Node 运行 dist/ 时，pnpm build 很重要。
• 如果你从 repo checkout 运行且没有全局安装，请用 pnpm openclaw ... 运行 CLI。
• 如果你直接从 TypeScript 运行（pnpm openclaw ...），通常不需要 rebuild，但配置迁移仍然适用 → 仍要跑 doctor。
• 在全局安装与 git 安装间切换很容易：安装另一种方式，然后运行 openclaw doctor 让 gateway service 的 entrypoint 指向当前安装。

始终运行：openclaw doctor

Doctor 是“安全更新”命令。它刻意保持朴素：repair + migrate + warn。

注意：如果你是源码安装（git checkout），openclaw doctor 会先提示是否运行 openclaw update。

它通常会做：

• 迁移废弃的 config keys / 旧的 config 文件位置。
• 审计 DM policies，并对高风险 “open” 设置发出警告。
• 检查 Gateway 健康，并可能提供重启选项。
• 检测并迁移旧版 gateway services（launchd/systemd；旧 schtasks）到当前 OpenClaw services。
• Linux 上确保 systemd user lingering（让 Gateway 在登出后仍能存活）。

详情：Doctor

启动 / 停止 / 重启 Gateway

CLI（跨 OS 统一）：

openclaw gateway status
openclaw gateway stop
openclaw gateway restart
openclaw gateway --port 18789
openclaw logs --follow

如果你处于 supervised 模式：

• macOS launchd（app 内置 LaunchAgent）：launchctl kickstart -k gui/$UID/bot.molt.gateway（使用 bot.molt.<profile>；legacy com.openclaw.* 仍可用）
• Linux systemd user service：systemctl --user restart openclaw-gateway[-<profile>].service
• Windows（WSL2）：systemctl --user restart openclaw-gateway[-<profile>].service
  • launchctl/systemctl 只有在 service 已安装时才可用；否则先运行 openclaw gateway install。

Runbook 与精确 service labels：/gateway

Rollback / pinning（出问题时）

Pin（全局安装）

安装一个已知可用版本（把 <version> 替换为你最后一次可用的版本）：

npm i -g openclaw@<version>

pnpm add -g openclaw@<version>

提示：查看当前已发布版本可运行 npm view openclaw version。

然后重启并重新跑 doctor：

openclaw doctor
openclaw gateway restart

Pin（源码）按日期

选择某个日期下的 commit（示例：“2026-01-01 时 main 的状态”）：

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

然后重装依赖并重启：

pnpm install
pnpm build
openclaw gateway restart

想回到最新：

git checkout main
git pull

如果你卡住了

• 再跑一次 openclaw doctor 并仔细阅读输出（它经常直接告诉你怎么修）。
• 查看：Troubleshooting
• 去 Discord 求助：https://discord.gg/clawd