推荐：openclaw update
检测你的安装类型（npm、pnpm、Bun 或 git），获取最新版本，运行 openclaw doctor，并重启网关。
openclaw update 没有 --verbose 标志（安装器有）。如需诊断，请使用
--dry-run 预览计划执行的操作，使用 --json 获取结构化结果，或使用
openclaw update status --json 查看通道和可用性状态。
--channel beta 会优先使用 beta 的 npm 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，但最终为 extended-stable 的包版本检查更新可用性时，仍只会检查经过验证的 extended-stable 选择器。
核心替换完成后，符合条件且使用裸版本/默认意图或 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 发布是警告，而不是失败：核心更新仍然可以成功，
同时插件会回退到其记录的默认/latest 发布版本。
有关通道语义，请参阅 发布通道。
在 npm 和 git 安装之间切换
使用 channel 来更改安装类型。更新器会保留你的状态、配置、 凭据和工作区在~/.openclaw 中；它只会更改 CLI 和 gateway 使用的 OpenClaw
代码安装方式。
dev 会确保使用 git 检出，构建它，并从该
检出中安装全局 CLI。stable、extended-stable 和 beta channel 使用包
安装。extended-stable 在 git 检出上会被拒绝，且不会进行修改或
转换。如果 gateway 已经安装，openclaw update 会刷新
服务元数据并重启它，除非你传入 --no-restart。
对于带有受管理 Gateway 服务的包安装，openclaw update 会定位到
该服务所使用的包根目录。如果 shell 中的 openclaw 命令来自不同的安装，
更新器会打印这两个根目录以及受管理
服务的 Node 路径，并在替换包之前将该 Node 版本与目标发布的
engines.node 要求进行检查。
源码检出服务器（参考脚本）
在服务器上直接从 git 检出目录运行网关的团队，可以在该检出目录中使用scripts/update-gateway.sh 进行更新。它是高效更新源码服务器的参考方案：恢复
pnpm build 会重写的已跟踪构建输出，对其他任何本地更改采取失败关闭策略，将
main 快进更新（或将本地服务器分支变基到 origin/main），安装依赖，执行干净构建，
并重启网关。
诸如 dist、dist-runtime 以及包本地的
dist 目录等生成输出根目录必须是真实目录。构建会在读取或修改其内容之前拒绝符号链接根目录，
因此清理操作不会影响链接目标。在更新或构建源码检出目录之前，请将输出根目录符号链接替换为真实目录。
openclaw update --channel dev —
它会为你管理检出目录、构建和网关重启。
替代方案：重新运行安装器
--no-onboard 可跳过引导流程。若要强制指定安装类型，请传入
--install-method git --no-onboard 或 --install-method npm --no-onboard。
如果在 npm 包安装阶段之后 openclaw update 失败，请改为重新运行安装器。
它不会调用更新器；它会直接执行全局包安装，并且可以恢复部分更新的 npm 安装。
--version 将恢复固定到特定版本或 dist-tag：
备选方案：手动使用 npm、pnpm 或 bun
openclaw update：它可以与正在运行的 Gateway 服务协调包替换。如果你在受监管的安装上手动更新，请先停止受管控的 Gateway。包管理器会原地替换文件，而运行中的 Gateway 否则可能会在替换过程中尝试加载核心或插件文件。包管理器完成后重启 Gateway，以便它加载新的安装。
对于 root 拥有的 Linux 系统全局安装，如果 openclaw update 因 EACCES 失败，请在保持 Gateway 停止的情况下使用 system npm 进行手动替换来恢复。使用你通常为该 Gateway 使用的相同 profile 参数/环境变量。将 /usr/bin/npm 替换为你主机上拥有 root-owned global prefix 的 system npm：
openclaw update 管理全局 npm 安装时，它会先将目标安装到临时 npm 前缀中。候选软件包会在 preinstall 阶段验证主机的 Node 版本；只有通过验证后，OpenClaw 才会检查打包的 dist 清单，并将干净的软件包树替换到实际的全局前缀中。预期清单中会省略打包完成保护文件，并且只有在 preinstall 成功后才会将其移除，因此即使生命周期脚本被跳过，也会在替换前失败。在 npm 12 及更高版本中，更新程序只会批准候选 OpenClaw 的生命周期；传递依赖的软件包脚本仍会被阻止。这样可以避免 npm 将新软件包覆盖到旧软件包的过时文件上。如果安装命令失败，OpenClaw 会使用 --omit=optional 重试一次，这有助于处理无法编译原生可选依赖的主机。
OpenClaw 托管的 npm 更新和插件更新命令还会为子 npm 进程清除 npm 的 min-release-age 供应链隔离（或较旧的 before 配置键）。该策略用于一般性保护，但显式的 OpenClaw 更新意味着“现在安装所选版本”。
高级 npm 安装主题
只读包树
只读包树
OpenClaw 在运行时将打包的全局安装视为只读，即使当前用户对全局包目录具有写权限。插件包安装位于用户配置目录下由 OpenClaw 拥有的 npm/git 根目录中，而网关启动不会修改 OpenClaw 的包树。某些 Linux npm 配置会将全局包安装到 root 拥有的目录下，例如
/usr/lib/node_modules/openclaw。OpenClaw 支持这种布局，因为插件安装/更新命令写入的是该全局包目录之外的位置。加固的 systemd 单元
加固的 systemd 单元
授予 OpenClaw 对其配置/状态根目录的写入权限，以便显式插件安装、插件更新和 doctor 清理能够持久保存更改：
磁盘空间预检查
磁盘空间预检查
在包更新和显式插件安装之前，OpenClaw 会尽力对目标卷执行磁盘空间检查。空间不足会产生一条带有已检查路径的警告，但不会阻止更新，因为文件系统配额、快照和网络卷可能会在检查后发生变化。实际的包管理器安装和安装后验证仍然具有最终决定权。
自动更新器
默认关闭。在~/.openclaw/openclaw.json 中启用它：
/settings/updates）中选择更新频道并启用自动更新。
对于 dev git 安装，打开此页面会刷新所跟踪的上游，并显示当前检出状态：是否为最新、领先、分叉、不可用，或落后具体数量的提交。它还会显示精确和相对的构建时间、验证安装时间以及最近提交时间。现有检出在下一次验证成功的更新之前，会显示未知的安装时间。
更新活动
当自动更新到期时，活动会等待进行中的工作完成，然后开始一分钟倒计时。倒计时开始后，新工作不会重置倒计时，也不会使活动返回等待状态。即使仍有工作未完成，15 分钟的硬性期限也会启动更新，并使用正常的重启排空和会话恢复路径。打开的终端会话不会推迟倒计时或应用更新。Gateway 重启会结束这些进程本地的 PTY，之后不会恢复终端会话。 管理员可以使用一次 暂停 1 小时 来推迟活动并顺延其硬性期限，或者从侧边栏更新卡片或 设置 → 更新 中选择 立即更新。对于dev git 安装，活动会安装其所宣布的确切提交。显示的列表会从该固定目标中预览最多五个提交；即使上游 main 在倒计时期间前进，该列表也不会移动。
每次应用更新失败都会结束活动，以免界面停留在 正在更新…。受管服务交接开始后发生的失败也会记录在重启标记中，并在 Gateway 返回后显示；直接的、无人监管的失败则保留在运行中 Gateway 的日志里。
OPENCLAW_NO_AUTO_UPDATE=1 和外部监管器模式会完全禁用自动应用更新。启动更新提示仍可运行，除非同时禁用 update.checkOnStart。
Gateway 还会在启动时记录更新提示（使用 update.checkOnStart: false 禁用）。已保存的 extended-stable 选择会使用此只读提示路径和现有的 24 小时提示间隔，但永远不会调用自动安装、交接、重启、stable 延迟／抖动或 beta 轮询。
通过实时 Gateway 控制平面（update.run）请求的包管理器更新，不会替换正在运行的 Gateway 进程内的包树。在受管服务安装中，Gateway 会启动一个分离的交接，退出，并让正常的 openclaw update --yes --json CLI 路径去停止服务、替换包、刷新服务元数据、重启、验证 Gateway 版本和可达性，并在可能时恢复已安装但未加载的 macOS LaunchAgent。如果 Gateway 无法安全地完成该交接，update.run 会返回一个安全的 shell 命令，而不是在进程内运行包管理器。
Control UI 侧边栏更新卡片会在将直接启动此 update.run 流程时显示 更新 Gateway。这适用于浏览器托管的 Control UI、远程 Gateway 以及手动管理的本地 Gateway。
从 Control UI 启动的手动更新始终会先询问。首次点击侧边栏更新卡片或 设置 → 更新 → 立即更新 时，会打开确认对话框，其中会说明目标、已安装和可用版本（若已知）以及重启影响；只有在你选择 更新并重启 后才会发送请求。取消、按 Escape 键以及关闭对话框都会使 Gateway 保持不变。自动活动、CLI 和 update.run API 客户端不受影响。
在签名的 macOS 应用中，本地应用自有的 Gateway 会将该卡片改为 更新 Mac 应用 + Gateway。Sparkle 会先更新应用；重新启动后，应用运行 openclaw update --tag <app-version> --json，重启其 Gateway，并在类似设置流程的进度窗口中验证健康状态。只有当受管 Gateway 需要更新、修复或安装时，才会显示该窗口；仅应用更新会直接重新启动进入应用。失败详情会保持可见，并提供重试、更新指南 和 Discord 操作。对于远程或外部管理的 Gateway，应用从不使用此协调路径；从不降级较新的 Gateway；也从不覆盖 extended-stable 频道固定设置。
当更新成功时，应用会为最近一次具有真实用户／频道交互的顶层直接会话排队一个一次性的欢迎事件。Cron 运行、心跳以及仅后台的会话更新都不会改变该选择。在远程模式下，应用只会更新其本地 Mac 节点运行时，并且仅当已连接的远程 Gateway 至少与应用一样新时才发送该事件。
更新后
回滚
回滚分为两层：- 重新安装较旧的 OpenClaw 代码，同时保留当前状态。
- 仅当较旧代码无法使用已迁移的配置或数据库时，才恢复更新前的状态。
更新前：创建经过验证的备份
openclaw update 会保留更新前的自动配置副本，但不会创建完整的状态恢复点。在进行重大更新之前，请显式创建一个：
回滚软件包安装
列出已发布的版本，然后预览并安装已知可用版本：openclaw update --tag。它会检测降级操作并请求确认，针对已安装的目标版本运行受管理插件的收敛和兼容性检查，刷新服务元数据，重启 Gateway，并验证运行中的版本。如果存储的频道为 extended-stable，请使用 --channel stable --tag <known-good-version>，因为精确的一次性标签不能与 extended-stable 选择器结合使用。
软件包更新会在激活前暂存并验证候选版本。如果文件系统交换或命令垫片替换失败，OpenClaw 会自动恢复旧软件包。交换成功后，如果 Gateway 健康检查在之后失败，系统会报告先前的版本和手动回滚说明，而不会再次自动替换软件包。
如果 CLI 更新路径不可用，请使用拥有当前 Gateway 的同一个软件包管理器和安装范围：
pnpm 或 bun 管理，请将 npm 替换为相应的管理器。在故障恢复期间，请通过在 Gateway 环境中设置 OPENCLAW_NO_AUTO_UPDATE=1，防止已启用的自动更新器立即应用较新的版本。
回滚源代码检出
使用干净的检出，并选择已知可用的标签或提交：git checkout main && git pull。
更新器会在 Git 更新开始后，如果依赖安装、构建、UI 构建或 doctor 失败，自动将 Git 检出恢复到之前的分支和 SHA。若你是有意选择较旧的提交，仍需手动检出。
跨越会话 SQLite 迁移进行降级
在启动较旧的基于文件的 OpenClaw 版本之前，请使用当前 CLI 恢复已归档的旧版转录文件：仅在必要时恢复状态
如果较旧代码无法读取更新后的配置或数据库架构，请停止 Gateway，并恢复经过验证的更新前文件系统、卷或虚拟机快照。在恢复之前，请单独保留当前状态，因为此操作会删除快照之后所做的更改。 广泛的openclaw backup create 归档支持创建和验证，但不支持就地激活整个归档。请将广泛归档解压到暂存目录，并使用其中的 manifest.json 源路径到归档路径映射执行离线恢复。openclaw backup sqlite restore 同样会将经过验证的数据库写入新的目标位置；激活该目标仍需由操作人员显式执行离线步骤。
验证回滚
如果遇到问题
- 再次运行
openclaw doctor，并仔细阅读输出内容。 - 对于使用
openclaw update --channel dev的源码检出版本，更新器会在需要时自动引导安装pnpm。如果你看到 pnpm/corepack 引导错误，请手动安装pnpm（或重新启用corepack），然后再次运行更新。 - 参见：故障排除
- 在 Discord 中提问：https://discord.gg/clawd。