更新

让 OpenClaw 保持最新。

对于 Docker、Podman 和 Kubernetes 镜像替换，请参阅 升级容器镜像。Gateway 网关会在就绪前执行启动安全的升级工作；如果挂载状态需要手动修复，则会退出。

推荐方式：openclaw update

检测你的安装类型（npm 或 git）、获取最新版本、运行 openclaw doctor，然后重启 Gateway 网关。

openclaw update

切换渠道或指定特定版本：

openclaw update --channel betaopenclaw update --channel extended-stableopenclaw update --channel devopenclaw update --dry-run   # 预览但不应用

openclaw update 没有 --verbose 标志（安装程序有）。若要进行诊断，请使用 --dry-run 预览计划执行的操作，使用 --json 获取结构化结果，或使用 openclaw update status --json 检查渠道和可用性状态。

--channel beta 优先使用 npm 的 beta dist-tag，但如果 beta 标签不存在，或其版本早于最新稳定版， 则回退到 stable/latest。若要执行一次性软件包更新并固定到原始 npm beta dist-tag，请改用 --tag beta。

--channel extended-stable 仅适用于软件包安装，并且安装仍只能在前台进行。 OpenClaw 会读取公开 npm 的 extended-stable 选择器， 验证所选的精确软件包，并安装该精确版本。注册表数据缺失或不一致时会以安全方式失败， 绝不会回退到 latest。 如果所选版本早于已安装版本，仍会进行常规的降级确认。核心更新成功后， CLI 会持久保存该渠道；直接运行 npm install -g openclaw@extended-stable 不会更新 update.channel。 核心版本替换后，使用裸/default 或 latest 意图的合格官方 npm 插件会收敛到与核心完全相同的版本。精确固定版本和明确指定的 非 latest 标签、第三方插件以及非 npm 来源均保持不变。 由当前 OpenClaw 版本创建的目录安装会保留该默认 意图。仅包含精确版本的旧记录将继续保持固定，因为 OpenClaw 无法安全区分旧的自动固定与用户固定；请在 extended-stable 渠道上运行一次 openclaw plugins update @openclaw/name， 让该插件重新选择精确跟随核心版本。

--channel dev 提供持久跟随更新的 GitHub main 检出。对于一次性 软件包更新，--tag main 会映射到 github:openclaw/openclaw#main 软件包 规范，并通过目标软件包管理器（npm/pnpm/bun）直接安装。

对于托管插件，缺少 beta 版本只会产生警告，而不会导致失败： 即使插件回退到其记录的 default/latest 版本，核心更新仍可成功。

有关渠道语义，请参阅发布渠道。

在 npm 和 git 安装之间切换

使用渠道更改安装类型。更新程序会保留 ~/.openclaw 中的状态、配置、 凭据和工作区；它只会更改 CLI 和 Gateway 网关所使用的 OpenClaw 代码安装。

# npm 软件包安装 -> 可编辑的 git 检出openclaw update --channel dev # git 检出 -> npm 软件包安装openclaw update --channel stable

先预览安装模式切换：

openclaw update --channel dev --dry-runopenclaw update --channel stable --dry-run

dev 会确保存在 git 检出、构建该检出，并从中安装全局 CLI。 stable、extended-stable 和 beta 渠道使用软件包 安装。在 git 检出中选择 extended-stable 会被拒绝，且不会修改或 转换该检出。如果已经安装 Gateway 网关，openclaw update 会刷新 服务元数据并重启服务，除非你传入 --no-restart。

对于使用托管 Gateway 网关服务的软件包安装，openclaw update 会以 该服务使用的软件包根目录为目标。如果 shell 中的 openclaw 命令 来自另一个安装，更新程序会打印两个根目录和托管 服务的 Node 路径，并在替换软件包前检查该 Node 版本是否满足目标版本的 engines.node 要求。

替代方式：重新运行安装程序

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

添加 --no-onboard 可跳过新手引导。若要强制使用特定安装类型，请传入 --install-method git --no-onboard 或 --install-method npm --no-onboard。

如果 openclaw update 在 npm 软件包安装阶段后失败，请改为重新运行 安装程序。它不会调用更新程序，而是直接执行全局软件包 安装，因此可以恢复部分更新的 npm 安装。

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

使用 --version 将恢复操作固定到特定版本或 dist-tag：

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm --version <version-or-dist-tag>

替代方式：手动使用 npm、pnpm 或 bun

npm i -g openclaw@latest

对于受监管的安装，优先使用 openclaw update：它可以协调软件包 替换与正在运行的 Gateway 网关服务。如果你在受监管的 安装中手动更新，请先停止托管 Gateway 网关。软件包管理器会原地替换文件， 否则正在运行的 Gateway 网关可能会在替换过程中尝试加载核心或插件文件。 软件包管理器完成后重启 Gateway 网关，使其使用 新安装。

对于由 root 拥有的 Linux 系统级全局安装，如果 openclaw update 因 EACCES 失败，请使用系统 npm 恢复，并在 手动替换期间保持 Gateway 网关停止。请使用你通常为 该 Gateway 网关使用的相同配置文件标志/环境。将 /usr/bin/npm 替换为主机上 拥有 root 全局前缀的系统 npm：

openclaw gateway stopsudo /usr/bin/npm i -g openclaw@latestopenclaw gateway install --forceopenclaw gateway restart

然后验证：

openclaw --versioncurl -fsS http://127.0.0.1:18789/readyzopenclaw plugins list --jsonopenclaw gateway status --deep --jsonopenclaw doctor --lint --json

当 openclaw update 管理全局 npm 安装时，它会先将目标版本 安装到临时 npm 前缀中，验证打包的 dist 清单，然后 将干净的软件包目录树替换到实际的全局前缀中，从而避免 npm 将新软件包覆盖到旧版本残留的过期文件上。如果安装 命令失败，OpenClaw 会使用 --omit=optional 重试一次，这有助于处理 无法编译原生可选依赖项的主机。

由 OpenClaw 管理的 npm 更新和插件更新命令还会为子 npm 进程清除 npm 的 min-release-age 供应链隔离策略（或旧版 before 配置键）。 该策略用于提供常规保护，但显式执行 OpenClaw 更新意味着“立即安装所选版本”。

pnpm add -g openclaw@latest

bun add -g openclaw@latest

高级 npm 安装主题

ReadWritePaths=/var/lib/openclaw /home/openclaw/.openclaw /tmp

自动更新程序

默认关闭。在 ~/.openclaw/openclaw.json 中启用：

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

Gateway 网关还会在启动时记录更新提示（可通过 update.checkOnStart: false 禁用）。已存储的 extended-stable 选择使用此 只读提示路径和现有的 24 小时提示间隔，但绝不会调用 自动安装、移交、重启、stable 延迟/抖动或 beta 轮询。 若要降级或进行事件恢复，请在 Gateway 网关环境中设置 OPENCLAW_NO_AUTO_UPDATE=1，以便即使配置了 update.auto.enabled 也阻止自动应用。除非同时禁用 update.checkOnStart，否则启动更新提示仍可运行。

通过实时 Gateway 网关控制平面请求的软件包管理器更新 （update.run）不会替换正在运行的 Gateway 网关 进程内的软件包目录树。在托管服务安装中，Gateway 网关会启动一个分离的移交流程， 随后退出，让常规 openclaw update --yes --json CLI 路径停止 服务、替换软件包、刷新服务元数据、重启、验证 Gateway 网关版本和可达性，并在可能时恢复已安装但未加载的 macOS LaunchAgent。如果 Gateway 网关无法安全完成该移交， update.run 会报告一条安全的 shell 命令，而不是在进程内运行软件包 管理器。

Control UI 侧边栏中的更新卡片会启动同一个 update.run 流程。在 已签名的 macOS 应用中，该卡片会先通过 Sparkle 更新应用；重新启动后， 应用会将其托管的本地 Gateway 网关更新到匹配版本。

更新后

openclaw doctor

openclaw gateway restart

openclaw health

回滚

固定版本（npm）

npm i -g openclaw@<version>openclaw doctoropenclaw gateway restart

固定提交（源代码）

git fetch origingit checkout "$(git rev-list -n 1 --before=\"2026-01-01\" origin/main)"pnpm install && pnpm buildopenclaw gateway restart

若要返回最新版本：git checkout main && git pull。

如果遇到困难

• 再次运行 openclaw doctor，并仔细阅读输出。
• 对于源代码检出上的 openclaw update --channel dev，更新程序会在需要时自动引导安装 pnpm。如果看到 pnpm/corepack 引导错误，请手动安装 pnpm（或重新启用 corepack），然后重新运行更新。
• 查看：故障排查
• 在 Discord 中提问：https://discord.gg/clawd

相关内容

• 安装概览：所有安装方式。
• Doctor：更新后的健康检查。
• 迁移：主要版本迁移指南。