跳到主要内容

更新

Clawdbot 正在快速迭代（处于 “1.0” 之前）。请像对待生产基础架构一样对待更新：更新 → 运行检查 → 重启（或使用会执行重启的 clawdbot update）→ 验证。

推荐：重新运行官网安装程序（就地升级）​

首选的更新路径是重新运行来自官网的安装程序。它会检测现有安装，进行就地升级，并在需要时运行 clawdbot doctor。

curl -fsSL https://clawd.bot/install.sh | bash

注意：

  • 如果你不想再次运行新手引导向导，请添加 --no-onboard。
  • 对于 源码安装，请使用： 
    curl -fsSL https://clawd.bot/install.sh | bash -s -- --install-method git --no-onboard
    只有在仓库状态干净的情况下，安装程序才会执行 git pull --rebase。
  • 对于 全局安装，脚本底层会使用 npm install -g clawdbot@latest。

更新前​

  • 了解你的安装方式：全局（npm/pnpm）还是 源码（git clone）。
  • 了解你的 Gateway 运行方式：前台终端 还是 受控服务（launchd/systemd）。
  • 备份你的自定义配置：
    • 配置：~/.clawdbot/clawdbot.json
    • 凭据：~/.clawdbot/credentials/
    • 工作区：~/clawd

更新（全局安装）​

全局安装（任选其一）：

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

我们 不推荐 将 Bun 用于 Gateway 运行时（存在 WhatsApp/Telegram 相关的 bug）。

切换更新频道（git + npm 安装）：

clawdbot update --channel beta
clawdbot update --channel dev
clawdbot update --channel stable

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

有关频道语义和发布说明，请参阅 开发频道。

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

然后：

clawdbot doctor
clawdbot gateway restart
clawdbot health

注意：

  • 如果你的 Gateway 作为服务运行，推荐使用 clawdbot gateway restart 而不是直接杀死进程 ID (PID)。
  • 如果你固定在特定版本，请参阅下文的“回滚 / 版本固定”。

更新 (clawdbot update)​

对于 源码安装（git checkout），首选：

clawdbot update

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

  • 需要干净的工作树。
  • 切换到选定的频道（标签或分支）。
  • 对配置的上游进行 fetch + rebase（开发频道）。
  • 安装依赖、构建、构建 Control UI 并运行 clawdbot doctor。
  • 默认重启 Gateway（使用 --no-restart 跳过）。

如果你是通过 npm/pnpm 安装的（没有 git 元数据），clawdbot update 将尝试通过你的包管理器进行更新。如果无法检测到安装，请改用“更新（全局安装）”。

更新 (Control UI / RPC)​

Control UI 提供了 更新并重启（RPC：update.run）。它会：

  1. 运行与 clawdbot update 相同的源码更新流程（仅限 git checkout）。
  2. 写入一个带有结构化报告（stdout/stderr 尾部内容）的重启哨兵文件。
  3. 重启 Gateway 并将报告推送到最后一次活跃的会话。

如果 rebase 失败，Gateway 将中止并重启，而不应用更新。

更新（源码安装）​

在仓库检出目录下：

首选：

clawdbot update

手动（等效操作）：

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

注意：

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

务必运行：clawdbot doctor​

Doctor 是“安全更新”命令。它有意设计得很乏味：修复 + 迁移 + 警告。

注意：如果你使用的是 源码安装（git checkout），clawdbot doctor 会提议先运行 clawdbot update。

它通常执行的操作：

  • 迁移已弃用的配置键 / 旧版配置文件位置。
  • 审计私信 (DM) 策略并对有风险的“开放”设置发出警告。
  • 检查 Gateway 健康状态，并可提议重启。
  • 检测并迁移旧的 Gateway 服务（launchd/systemd；旧版 schtasks）到当前的 Clawdbot 服务。
  • 在 Linux 上，确保 systemd 用户驻留（以便 Gateway 在注销后继续运行）。

详情：Doctor

启动 / 停止 / 重启 Gateway​

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

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

如果你使用的是受控服务：

  • macOS launchd（应用绑定的 LaunchAgent）：launchctl kickstart -k gui/$UID/com.clawdbot.gateway（如果已设置，请使用 com.clawdbot.<profile>）
  • Linux systemd 用户服务：systemctl --user restart clawdbot-gateway[-<profile>].service
  • Windows (WSL2)：systemctl --user restart clawdbot-gateway[-<profile>].service
    • launchctl/systemctl 仅在服务已安装时有效；否则请运行 clawdbot gateway install。

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

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

固定版本（全局安装）​

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

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

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

然后重启并重新运行 doctor：

clawdbot doctor
clawdbot 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
clawdbot gateway restart

如果你以后想回到最新版本：

git checkout main
git pull

如果你遇到困难​