Appearance
OpenClaw 推荐使用 openclaw update 命令自动检测安装类型并升级，同时支持手动 npm 或重新运行安装脚本。自动更新默认关闭，需在配置文件中启用。升级后运行 openclaw doctor 检查健康，若出现问题可通过 npm 或 git 回滚到指定版本。openclaw update --dry-run 可预览变更，--channel beta 优先使用 beta 渠道但回退到稳定版。
OpenClaw 升级更新与版本回滚配置
推荐方式：openclaw update
openclaw update 是最快的升级方式。它自动检测你的安装类型（npm 或 git），拉取最新版本，运行 openclaw doctor，然后重启网关。
bash
openclaw update切换发布渠道或指定版本：
bash
openclaw update --channel beta # 优先 beta，不可用时回退到 stable
openclaw update --channel dev # 切换到 git main 分支开发版
openclaw update --dry-run # 预览更新计划但不实际执行
openclaw update --json # 输出结构化结果openclaw update 不接受 --verbose 参数。如需诊断升级过程，使用 --dry-run 预览动作，--json 获取结构化结果，或 openclaw update status --json 查看渠道和可用性状态。安装器自身有 --verbose 标志，但不属于 openclaw update。
--channel beta 优先使用 beta 渠道，但若 beta 标签缺失或版本低于最新稳定发布，则回退到 stable/latest。若需要直接获取 npm 原始 beta dist-tag 进行一次性包更新，使用 --tag beta。
--channel dev 用于跟踪 GitHub main 分支的最新提交。包更新不支持对 openclaw/openclaw 的 npm GitHub 源码安装，需目标发布版本、精确版本号或构建好的 tarball。
对于托管插件，beta 渠道回退会发出警告：核心更新可能成功，而插件由于没有 beta 可用而使用其记录的默认/最新发布版本。
渠道语义详见：Development channels
切换 npm 与 git 安装类型
通过渠道切换安装类型。更新器会保留状态、配置、凭据和工作区（在 ~/.openclaw 中），仅更改 CLI 和网关使用的 OpenClaw 代码安装。
bash
# npm 包安装 → git 可编辑检出
openclaw update --channel dev
# git 检出 → npm 包安装
openclaw update --channel stable先用 --dry-run 预览确切的安装模式切换：
bash
openclaw update --channel dev --dry-run
openclaw update --channel stable --dry-rundev 渠道确保 git 检出、构建并从该检出安装全局 CLI。stable 和 beta 渠道使用包安装。若网关已在运行，openclaw update 会刷新服务元数据并重启，除非传递 --no-restart。
对于包安装且托管网关服务的情况，openclaw update 会定位该服务使用的包根目录。如果 shell 中的 openclaw 命令来自不同安装，更新器会打印两个根路径和管理服务的 Node 路径。包更新会使用拥有服务根目录的包管理器，并在替换包前检查管理服务 Node 版本是否满足目标发布版本引擎要求。
备用方式：重新运行安装脚本
bash
curl -fsSL https://openclaw.ai/install.sh | bash添加 --no-onboard 跳过引导向导。强制指定安装类型：
bash
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git --no-onboard
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm --no-onboard如果 openclaw update 在 npm 包安装阶段失败，重新运行安装脚本。安装器不会调用旧的更新器，而是直接运行全局包安装，可以恢复部分更新的 npm 安装。
bash
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm要固定到特定版本或 dist-tag，添加 --version：
bash
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm --version <version-or-dist-tag>备用方式：手动 npm、pnpm 或 bun
对于有管理服务的安装，优先使用 openclaw update，因为它能协调包替换与运行中的网关。如果手动更新，请在包管理器开始前停止托管网关。包管理器会原地替换文件，运行时网关可能尝试加载核心或插件文件而包树半替换。包管理器完成后重启网关，使服务加载新安装。
bash
npm i -g openclaw@latestbash
pnpm add -g openclaw@latestbash
bun add -g openclaw@latest对于 root 拥有的 Linux 系统全局安装，如果 openclaw update 因 EACCES 失败，使用系统 npm 恢复：
bash
openclaw gateway stop
sudo /usr/bin/npm i -g openclaw@latest
openclaw gateway install --force
openclaw gateway restart验证服务：
bash
openclaw --version
curl -fsS http://127.0.0.1:18789/readyz
openclaw plugins list --json
openclaw gateway status --deep --json
openclaw doctor --lint --json当 openclaw update 管理全局 npm 安装时，它先将目标安装到临时 npm 前缀，验证打包的 dist 清单，然后将干净包树替换到真实全局前缀。这避免了 npm 将新包叠加到旧包残留文件上。如果安装命令失败，OpenClaw 会重试一次，加上 --omit=optional。该重试有助于主机上原生可选依赖无法编译的情况，若回退也失败则保留原始错误可见。
OpenClaw 管理的 npm 更新和插件更新命令还会清除子 npm 进程的 min-release-age 隔离策略。npm 可能将该策略报告为派生的 before 截止时间；两者都是通用供应链隔离策略，但显式的 OpenClaw 更新意味着“立即安装选定的 OpenClaw 版本”。
高级 npm 安装补充
只读包树：OpenClaw 在运行时将打包的全局安装视为只读，即使全局包目录对当前用户可写。插件包安装在用户配置目录下的 OpenClaw 拥有的 npm/git 根目录中，网关启动不会修改 OpenClaw 包树。某些 Linux npm 配置将全局包安装在 root 拥有的目录中（如 /usr/lib/node_modules/openclaw），OpenClaw 支持该布局，因为插件安装/更新命令写入此目录外部。
强化 systemd 单元：授予 OpenClaw 对其配置/状态根的写权限，以便显式插件安装、插件更新和 doctor 清理能持久化更改：
ini
ReadWritePaths=/var/lib/openclaw /home/openclaw/.openclaw /tmp磁盘空间预检：在包更新和显式插件安装前，OpenClaw 会尽力检查目标卷的磁盘空间。空间不足会产生警告及检查路径，但不会阻止更新，因为文件系统配额、快照和网络卷在检查后可能变化。实际的包管理器安装和安装后验证才是权威的。
自动更新配置
自动更新默认关闭。在 ~/.openclaw/openclaw.json 中启用：
json5
{
update: {
channel: "stable",
auto: {
enabled: true,
stableDelayHours: 6,
stableJitterHours: 12,
betaCheckIntervalHours: 1,
},
},
}| 渠道 | 行为 |
|---|---|
stable | 等待 stableDelayHours 小时，然后在 stableJitterHours 范围内用确定性抖动应用（分散推送）。 |
beta | 每 betaCheckIntervalHours 小时（默认每小时）检查一次，立即应用。 |
dev | 不自动应用，需要使用 openclaw update 手动更新。 |
网关启动时也会记录更新提示（用 update.checkOnStart: false 禁用）。如需降级或事故恢复，在网关环境中设置 OPENCLAW_NO_AUTO_UPDATE=1 可阻止自动应用，即使配置了 update.auto.enabled。启动更新提示仍会运行，除非同时禁用 update.checkOnStart。
通过实时网关控制面处理器请求的包管理器更新不会替换运行中的网关进程内的包树。在管理服务安装中，网关启动一个分离的交接，退出，然后让正常的 openclaw update --yes --json CLI 路径停止服务、替换包、刷新服务元数据、重启、验证网关版本和可达性，并在可能时恢复已安装但未加载的 macOS LaunchAgent。如果网关无法安全交接，update.run 会报告安全的 shell 命令，而不是在进程中运行包管理器。
升级后的操作
运行 doctor：
bashopenclaw doctor迁移配置、审计 DM 策略并检查网关健康。详情：Doctor
重启网关：
bashopenclaw gateway restart验证：
bashopenclaw health
版本回滚
固定到指定版本（npm）
bash
npm i -g openclaw@<version>
openclaw doctor
openclaw gateway restart提示：npm view openclaw version 查看当前发布版本。
固定到某个 commit（源码安装）
bash
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并仔细阅读输出。 - 对于源码检出的
openclaw update --channel dev，更新器会在需要时自动引导pnpm。如果看到 pnpm/corepack 引导错误，手动安装pnpm（或重新启用corepack）然后重试更新。 - 查看：故障排除
- 在 Discord 提问：https://discord.gg/clawd
常见问题
OpenClaw 自动更新怎么配置？
在 ~/.openclaw/openclaw.json 的 update.auto 中设置 enabled: true，并指定 stableDelayHours 和 stableJitterHours（稳定版）或 betaCheckIntervalHours（beta 版）。默认关闭。通过环境变量 OPENCLAW_NO_AUTO_UPDATE=1 可临时禁用自动更新。
openclaw update 后网关无法启动怎么办？
先运行 openclaw doctor 修复配置并检查健康。重启网关：openclaw gateway restart。如果仍然失败，尝试重新运行安装脚本（curl -fsSL https://openclaw.ai/install.sh | bash）或用 npm 回滚到之前可用的版本（npm i -g openclaw@<版本号>）。
如何回滚到旧版本 OpenClaw？
npm 安装：npm i -g openclaw@<版本号>，然后 openclaw doctor 和 openclaw gateway restart。git 源码安装：git checkout <commit-hash>（或使用日期），然后 pnpm install && pnpm build，最后重启网关。查看当前发布版本用 npm view openclaw version。