更新

OpenClaw 目前迭代很快（还没到 “1.0” 版本）。把更新当作部署基础设施来对待：更新 → 运行检查 → 重启（或用 openclaw update，它会自动重启）→ 验证。

推荐方式：重新运行官网安装脚本（原地升级）

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

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

注意事项：

  • 如果不想再次运行引导向导，加上 --no-onboard 参数。
  • 对于源码安装，使用： 
    curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git --no-onboard
    安装脚本只会在仓库干净时执行 git pull --rebase。
  • 对于全局安装，脚本底层使用 npm install -g openclaw@latest。
  • 兼容性说明：openclaw 命令仍然可用作兼容性垫片。

更新前的准备

  • 确认你的安装方式：全局安装（npm/pnpm）还是源码安装（git clone）。
  • 确认 Gateway 的运行方式：前台终端还是守护服务（launchd/systemd）。
  • 备份你的配置：
    • 配置文件：~/.openclaw/openclaw.json
    • 凭证：~/.openclaw/credentials/
    • Workspace：~/.openclaw/workspace

更新（全局安装）

全局安装（选择其一）：

npm i -g openclaw@latest
pnpm add -g openclaw@latest

我们不推荐使用 Bun 作为 Gateway 运行时（WhatsApp/Telegram 有 bug）。

切换更新渠道（git + npm 安装都适用）：

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

使用 --tag <dist-tag|version> 可以一次性安装指定标签或版本。

查看开发渠道了解渠道语义和发布说明。

注意：在 npm 安装时，Gateway 启动时会记录更新提示（检查当前渠道标签）。可以通过 update.checkOnStart: false 禁用。

然后：

openclaw doctor
openclaw gateway restart
openclaw health

注意事项：

  • 如果你的 Gateway 作为服务运行，推荐使用 openclaw gateway restart 而不是杀进程。
  • 如果你锁定了特定版本，参见下面的”回滚/锁定版本”。

更新（openclaw update）

对于源码安装（git checkout），推荐使用：

openclaw update

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

  • 要求工作树干净。
  • 切换到选定的渠道（标签或分支）。
  • 拉取并 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. 写入重启标记和结构化报告（stdout/stderr 尾部）。
  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 很重要。
  • 如果你从仓库 checkout 运行而没有全局安装，使用 pnpm openclaw ... 执行 CLI 命令。
  • 如果你直接从 TypeScript 运行（pnpm openclaw ...），通常不需要重新构建，但配置迁移仍然适用 → 运行 doctor。
  • 在全局安装和 git 安装之间切换很简单：安装另一种方式，然后运行 openclaw doctor，这样 Gateway 服务入口点会被重写为当前安装。

始终运行：openclaw doctor

Doctor 是”安全更新”命令。它故意设计得很无聊：修复 + 迁移 + 警告。

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

它通常会做这些事：

  • 迁移已弃用的配置键/旧配置文件位置。
  • 审计 DM 策略并警告有风险的”开放”设置。
  • 检查 Gateway 健康状态，可以提示重启。
  • 检测并迁移旧的 Gateway 服务（launchd/systemd；旧版 schtasks）到当前 OpenClaw 服务。
  • 在 Linux 上，确保 systemd 用户持久化（这样 Gateway 在登出后仍能运行）。

详情：Doctor

启动/停止/重启 Gateway

CLI（适用于所有操作系统）：

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

如果你使用守护服务：

  • macOS launchd（应用捆绑的 LaunchAgent）：launchctl kickstart -k gui/$UID/bot.molt.gateway（使用 bot.molt.<profile>；旧版 com.openclaw.* 仍然可用）
  • Linux systemd 用户服务：systemctl --user restart openclaw-gateway[-<profile>].service
  • Windows（WSL2）：systemctl --user restart openclaw-gateway[-<profile>].service
    • launchctl/systemctl 只在服务已安装时有效；否则运行 openclaw gateway install。

运维手册和确切的服务标签：Gateway 运维手册

回滚/锁定版本（当出现问题时）

锁定版本（全局安装）

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

npm i -g openclaw@<version>
pnpm add -g openclaw@<version>

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

然后重启并重新运行 doctor：

openclaw doctor
openclaw gateway restart

锁定版本（源码）按日期

选择某个日期的提交（例如：“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

如果遇到问题