维护

更新

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。
  • 遗留说明：clawdbot 仍作为兼容性垫片可用。

更新前准备

  • 了解你的安装方式：全局（npm/pnpm）还是源码（git clone）。
  • 了解你的网关运行方式：前台终端还是受监管的服务（launchd/systemd）。
  • 备份你的定制配置：
    • 配置：~/.openclaw/openclaw.json
    • 凭证：~/.openclaw/credentials/
    • 工作空间：~/.openclaw/workspace

更新（全局安装）

全局安装（任选其一）：

npm i -g openclaw@latest

pnpm add -g openclaw@latest

我们不推荐将 Bun 用于网关运行时（WhatsApp/Telegram 存在 bug）。要切换更新频道（git + npm 安装）：

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

使用 --tag <dist-tag|version> 进行一次性安装指定标签/版本。有关频道语义和发布说明，请参阅开发频道。注意：在 npm 安装中，网关启动时会记录更新提示（检查当前频道标签）。可通过 update.checkOnStart: false 禁用。

核心自动更新器（可选）

自动更新器默认关闭，是核心网关功能（非插件）。

{
  "update": {
    "channel": "stable",
    "auto": {
      "enabled": true,
      "stableDelayHours": 6,
      "stableJitterHours": 12,
      "betaCheckIntervalHours": 1
    }
  }
}

行为：

  • stable：当检测到新版本时，OpenClaw 等待 stableDelayHours，然后在 stableJitterHours 内应用一个确定性的、按安装实例的抖动（分散式推出）。
  • beta：按 betaCheckIntervalHours 节奏（默认：每小时）检查，并在有更新可用时应用。
  • dev：不自动应用；使用手动 openclaw update。

在启用自动化之前，使用 openclaw update --dry-run 预览更新操作。然后：

openclaw doctor
openclaw gateway restart
openclaw health

注意：

  • 如果你的网关作为服务运行，openclaw gateway restart 优于直接终止 PID。
  • 如果你固定使用特定版本，请参阅下面的"回滚 / 固定版本"。

更新（openclaw update）

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

openclaw update

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

  • 要求工作树干净。
  • 切换到选定的频道（标签或分支）。
  • 获取并针对配置的上游（dev 频道）进行变基。
  • 安装依赖、构建、构建控制 UI，并运行 openclaw doctor。
  • 默认重启网关（使用 --no-restart 跳过）。

如果你通过 npm/pnpm 安装（无 git 元数据），openclaw update 将尝试通过你的包管理器更新。如果无法检测到安装方式，请改用"更新（全局安装）"。

更新（控制 UI / RPC）

控制 UI 提供更新并重启功能（RPC：update.run）。它会：

  1. 运行与 openclaw update 相同的源码更新流程（仅限 git checkout）。
  2. 写入一个重启哨兵文件，并附带结构化报告（stdout/stderr 尾部）。
  3. 重启网关，并将报告发送给最后一个活跃的会话。

如果变基失败，网关将中止并在不应用更新的情况下重启。

更新（源码安装）

在仓库检出目录中：推荐：

openclaw update

手动（大致等效）：

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

注意：

  • 当你运行打包的 openclaw 二进制文件（openclaw.mjs）或使用 Node 运行 dist/ 时，pnpm build 很重要。
  • 如果你在没有全局安装的情况下从仓库检出目录运行，请使用 pnpm openclaw ... 执行 CLI 命令。
  • 如果你直接从 TypeScript 运行（pnpm openclaw ...），通常不需要重新构建，但配置迁移仍然适用 → 运行 doctor。
  • 在全局安装和 git 安装之间切换很容易：安装另一种方式，然后运行 openclaw doctor，以便网关服务入口点被重写为当前安装。

始终运行：openclaw doctor

Doctor 是"安全更新"命令。它故意设计得简单：修复 + 迁移 + 警告。注意：如果你使用的是源码安装（git checkout），openclaw doctor 会先提示运行 openclaw update。它通常执行以下操作：

  • 迁移已弃用的配置键 / 遗留配置文件位置。
  • 审计 DM 策略并警告有风险的"开放"设置。
  • 检查网关健康状况，并可提议重启。
  • 检测并迁移旧的网关服务（launchd/systemd；遗留的 schtasks）到当前的 OpenClaw 服务。
  • 在 Linux 上，确保 systemd 用户常驻（以便网关在用户注销后仍能存活）。

详情：Doctor

启动 / 停止 / 重启网关

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/ai.openclaw.gateway（使用 ai.openclaw.<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。

运行手册 + 确切的服务标签：网关运行手册

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

固定版本（全局安装）

安装一个已知良好的版本（将 <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

如果遇到问题

Bun（实验性）迁移指南