Skip to main content

​
更新 OpenClaw

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

​
更新前准备

在更新之前,请先确认以下信息:
1

确认安装方式

确认您的安装方式:全局(npm/pnpm)还是 源码(git clone)
2

确认 Gateway 运行方式

确认 Gateway 的运行方式:前台终端还是 守护服务(launchd/systemd)
3

备份定制内容

快照您的定制内容:
  • 配置:~/.openclaw/openclaw.json
  • 凭证:~/.openclaw/credentials/
  • 工作区:~/.openclaw/workspace

​
更新方式

​
全局安装更新

对于通过 npm 或 pnpm 全局安装的用户: 
npm i -g openclaw@latest
我们不推荐为 Gateway 运行时使用 Bun(WhatsApp/Telegram 存在问题)。

​
切换更新通道

切换更新通道(适用于 git + npm 安装): 
openclaw update --channel beta
openclaw update --channel dev
openclaw update --channel stable
使用 --tag <dist-tag|version> 可指定单次安装的标签或版本。
npm 安装时,Gateway 启动会输出更新提示(检查当前通道标签)。可通过 update.checkOnStart: false 关闭。

​
核心自动更新器(可选)

自动更新器默认关闭,是 Gateway 核心功能(非插件)。 
{
  "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 update 命令

对于源码安装(git 检出)首选: 
openclaw update
它运行相对安全的更新流程:
  • 需保证工作区干净
  • 切换至指定通道(标签或分支)
  • 拉取 + 变基配置的上游分支(dev 通道)
  • 安装依赖,构建,构建控制 UI,执行 openclaw doctor
  • 默认重启 Gateway(使用 --no-restart 可跳过)
如果您通过 npm/pnpm 安装(无 git 元数据),openclaw update 会尝试用包管理器更新。

​
从源码手动更新

在仓库检出目录内: 推荐: 
openclaw update
手动操作(大致等价): 
git pull
pnpm install
pnpm build
pnpm ui:build # 首次运行自动安装 UI 依赖
openclaw doctor
openclaw health
  • 当您运行打包好的 openclaw 二进制文件或用 Node 直接执行 dist/,pnpm build 的步骤很重要
  • 若仅从仓库检出运行且无全局安装,使用 pnpm openclaw ... 方式调用 CLI
  • 如直接从 TypeScript 运行(pnpm openclaw ...),通常不需重新构建,但配置迁移仍需执行 → 运行 doctor

​
更新后必做:运行 doctor

Doctor 是”安全更新”核心命令,故意设计简洁:修复 + 迁移 + 警告。 
openclaw doctor
若您是源码安装(git 检出),openclaw doctor 会建议先运行 openclaw update。
功能示例:
  • 迁移废弃配置键/旧配置文件位置
  • 审核私聊策略,并警告高风险”开放”设置
  • 检查 Gateway 健康,提供重启建议
  • 检测并迁移旧版 Gateway 服务(launchd/systemd;旧版 schtasks)到当前 OpenClaw 服务
  • Linux 上确保 systemd 用户保持活动(确保 Gateway 登出后存活)

​
启动/停止/重启 Gateway

CLI 命令(跨平台通用): 
openclaw gateway status
openclaw gateway stop
openclaw gateway restart
openclaw gateway --port 18789
openclaw logs --follow

​
守护运行时

launchctl kickstart -k gui/$UID/ai.openclaw.gateway
(使用 ai.openclaw.<profile>,旧版 com.openclaw.* 仍可用)
launchctl/systemctl 仅在服务已安装时有效,否则执行 openclaw gateway install。

​
回滚/锁定(出现故障时)

​
锁定版本(全局安装)

安装已知可用版本(将 <version> 替换为最后可用的版本): 
npm i -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

​
遇到卡住的问题

如果更新后遇到问题:
  1. 再次运行 openclaw doctor 并仔细阅读输出(通常会提示解决方案)
  2. 查看故障排查指南
  3. 进入 Discord 询问:https://discord.gg/clawd