openclaw update¶

更新 OpenClaw，并在 stable/extended-stable/beta/dev 频道之间切换。

如果你通过 npm/pnpm/bun 安装（全局安装，无 git 元数据），更新将按照 更新 中描述的包管理器流程进行。

自定义 npm 前缀（例如 ~/.npm-global）可从 npm 配置的前缀和已安装的 OpenClaw 启动器识别。在 ~/.npmrc 中配置的前缀不需要匹配的 NPM_CONFIG_PREFIX 环境变量。如果无法识别所有者，CLI 会在其引导中包含所检查的包、前缀和启动器路径，以及包管理器探测结果。安装检查还会报告根目录、Git 元数据、node_modules 布局和服务单元目标（或未检查的原因）。无法识别的根目录会跳过目标预检，并给出确定所属安装的命令。

在暂存之前停止的旧版更新程序无法使用此修复。对于已知的 npm 安装，请为该更新显式提供其配置的前缀：NPM_CONFIG_PREFIX="$(npm prefix -g)" openclaw update。

未检测到包管理器所有者的安装会记录一次 skipped 更新，以成功状态退出，并保持 Gateway 运行。对于 Docker/容器镜像，请拉取或构建新镜像，并使用相同的状态/配置挂载重新创建容器。对于独立或解压的 tarball 安装，请使用原始方法重新安装；Yarn 全局安装必须使用 Yarn 更新。CLI 会显示此后续操作。现有配置文件也会在更新历史中记录它，并在 JSON 中以 run.origin.nextAction 包含它。使用 --json 时，新的配置文件会将引导输出到 stderr，并且不会为跳过的更新创建状态数据库。这些非结果不会运行回滚验证，也不会提供更新失败报告。

用法¶

openclaw update
openclaw update status
openclaw update repair
openclaw update cleanup --dry-run
openclaw update wizard
openclaw update --channel extended-stable
openclaw update --channel beta
openclaw update --channel dev
openclaw update --tag beta
openclaw update --dry-run
openclaw update --no-restart
openclaw update --yes
openclaw update --accept-capabilities
openclaw update --json
openclaw --update

openclaw --update 会被重写为 openclaw update（对 shell 和启动脚本很有用）。

无效配置会先于数据库模式检查报告 invalid-config。不可读取的配置文件或加载配置失败则报告 config-read-failed，并在可用时附带可识别的文件系统错误码。对于受支持的软件包目标，候选版本会在私有暂存后做出该决定；参见 候选版本准入。本地诊断会识别无效字段并建议运行 openclaw doctor --fix，然后再修正剩余错误。试运行会在 JSON notes 中保留此引导，而不更改配置。公开失败报告会保留被拒绝的模式区域（例如 gateway.*），同时隐藏操作者定义的键和被拒绝的值。当所选包版本与已安装版本相同，准入仍会运行；no-op 决定会在对所选工件和当前安装进行验证后作出。引导式恢复在后续更新成功后识别已保存的配置失败，并仍会验证已安装的运行时和 Gateway 就绪状态。

2026.9.4 更新程序会将此情况报告为 database-schema-preflight，并且即使在解析 npm 目标之后也可能显示 mode: unknown。在另一次更新或试运行替换最新历史之前，请运行 openclaw update status --json 并检查 lastRun.origin.nextAction 和 lastRun.target，以获取记录的原因和目标。候选版本无法修复在暂存候选版本之前即拒绝的已安装更新程序；请先更正配置，再重试。

缺少准入修复的更新程序于 2026.7.2-beta.5 首次发布（包括 2026.6.34–2026.6.35 以及 2026.7.33–2026.7.35 extended-stable 系列），这些更新程序同样会在暂存前以 plugins.load.paths: plugin path not found 拒绝更新；请恢复缺失的自定义插件目录或移除其配置路径，然后再重试。openclaw doctor --fix 可以修复可识别的捆绑路径别名，并保留无关的自定义路径。

更新准入将父任务缺失的孤立 task_delivery_state 行识别为可修复。当它能获取 Doctor 的所有权栅栏时，会在创建更新历史之前运行相同的 保留优先恢复。恢复及其账本条目会一起提交；该条目记录行数和恢复目录。活动的 Gateway 所有者、只读存储或保留失败会阻止修复，并将 openclaw doctor --fix 报告为后续操作。其他外键违规和结构性损坏仍会拒绝准入。--dry-run 会报告可修复的情况，但不会恢复行，也不会为该被拒绝的预览创建更新账本条目。

已安装的 2026.9.4 更新程序在更新自身之前无法使用此恢复。如果它以数据库完整性错误拒绝，请手动安装修复版本并运行 openclaw doctor --fix。

失败的更新和修复尝试会在服务恢复和清理完成后进入 恢复分诊。预检和最终化会在移交所有权或报告完成之前，加入对已准入命令的清理。如果清理无法确认相关工作已停止，更新程序会保留任何已获得的所有权和恢复工件，并跳过自动服务补偿和修复。检查 openclaw update status 并解决挂起的执行，然后再重试。已验证的回滚不会自动启动分诊：上一代版本已重新运行，报告会将失败的检查保留为原因。交互式更新会提供诊断/报告菜单，默认选中 Exit。拒绝或取消会保留失败更新的非零退出状态。JSON、非交互、--yes 和托管服务交接调用在回滚后不会提示。

更新完成时（包括意外失败的情况）会在退出前打印最终结果和本地 Markdown 报告路径。失败的运行会在已发布的 8 KiB 限制范围内保留面向回滚的诊断 JSON。该文件链接到另一个产物，其中包含每一项分别限界的 Doctor 发现；Markdown 报告还保留完整的清单。JSON 输出包含 reportPath；报告写入失败会打印警告并保留更新结果。

当 Gateway 处理请求期间 Dashboard 更新失败时，Gateway 会记录一条包含公开原因和安全错误摘要的警告。成功及有意为之的 no-op 更新日志保持不变。这仅影响 Gateway 日志记录，不影响已安装的更新程序、回滚或 Dashboard RPC 响应。

在交互式更新最终失败后，诊断更新失败 和 报告更新失败 是两个独立的选项。报告操作首先显示脱敏后的准确 issue 正文，并将确认默认设为 否。确认后，OpenClaw 会在创建 issue 之前，通过静默的只读请求检查 GitHub CLI 当前激活的 github.com 账户。回退和待处理结果会在本地保留脱敏报告；已确认的 issue 仅保留其持久化 issue URL。如果 CLI 缺失、身份验证不可用，或 GitHub 拒绝上传，OpenClaw 会在本地保留脱敏报告并返回之前的操作菜单。修复问题后，选择 报告更新失败 并再次确认以重试同一份报告，或选择 在浏览器中报告，使用浏览器中的 GitHub 账户查看并提交该报告。当准备好的报告适合放入预填链接且没有不确定的上传处于待处理状态时，浏览器选项可用；它不要求安装 GitHub CLI。已完成的更新和 Doctor 检查不会重新运行。准备或提交出错也会返回菜单。不确定的上传保持待处理状态：检查报告状态 会查找已有的 issue 而不创建新 issue，并且不提供浏览器移交选项。成功提交、显式退出和取消保持其正常行为；诊断仅在显式选择时运行。

在 Control UI 中，中断的创建前准备工作会在其本地预留过期后变为可重试。在创建结果不确定后，OpenClaw 会查找与确切报告匹配的 issue。如果既没有已验证的 issue URL，也没有明确的拒绝结果，报告将保持待处理状态且不提供重放链接，因为 issue 可能已存在。--yes、--json、非交互式运行以及托管服务移交都不会提交报告。

对于已获准入的更新，意外异常会在更新历史中保留受限的、经过脱敏的错误标识和源位置，以及已执行到的操作和迄今已解析的安装与目标事实。失败报告包含发起操作和所有者记录的回滚结果。失败步骤在报告正文和 issue 标题中使用稳定标识符，如 candidate-state-snapshot、candidate-doctor-lint 和 post-install-verify；命令行参数和私有路径保持脱敏。快照错误会指明当前数据库、执行审批或插件阶段。数据库快照完成并不代表后续插件路径可读；请检查失败阶段所指明的源路径和文件系统错误。安装或目标解析过程中发生的失败会保持该解析步骤可见。较旧的更新程序进程无法恢复已丢弃的细节；由较新代码生成的报告仅包含处理该失败的更新程序所记录的事实。

npm 安装失败会在更新历史和供审阅的报告中记录已识别的错误码（或 unknown）以及 npm ERR! / npm error 行的脱敏摘录。现有历史格式最多保留五行，每行 200 个 UTF-8 字节；权限指引占用其中一个条目。在记录摘录之前，主目录路径、凭据和已认证的注册表 URL 会被脱敏。对于 EACCES 或 EPERM，请检查 npm prefix -g，并以对该前缀具有写权限的安装账户身份运行更新。对于 ENOSPC，请释放前缀和 npm 缓存卷上的空间。对于 E404 或 ETARGET，请检查已配置的注册表以及所请求的版本或标签。生成的报告包含适用的后续步骤。已在运行的较旧更新程序无法从其候选包中获得此诊断捕获能力。

候选包主导的准入¶

对于包管理器更新，openclaw update 会以私有方式暂存所选的包一次，然后由该候选包决定是否可以更新正在运行的安装。注册表目标和显式产物（如 --tag ./openclaw.tgz）使用相同的流程。暂存会被复用于验证、金丝雀预演和激活；拒绝或变更前失败会移除暂存，并保持已安装的包和运行中的 Gateway 不变。在准入和包验证之后，如果已安装版本与产物构建标识匹配，则保持为 no-op（无操作），除非更新需要替换安装方法或单独的服务根目录。临时候选包会被移除，而不会被激活。

当需要替换时，更新程序会在更改已安装的包之前保留其运行中的 worker 文件。Linux OverlayFS 安装使用私有副本，从而硬链接 copy-up 不会使所保留文件的标识检查失效。其他受支持的文件系统保留硬链接快速路径和复制回退。

当仅剩被忽略的 node_modules 目录时，源码更新会保留一条已退役的工作区依赖链接。在 updater-runtime-retention 步骤失败的较旧已安装更新程序，需要在其运行中的代码中应用此修正后才能重试；较新的候选包无法修复更早的那一步。

已安装的更新程序会在运行候选包待执行的生命周期脚本之前读取其 package.json。openclaw.updateAdmissionProtocol: 1 通告内部准入命令。读取此标记不会执行候选包代码。在候选包准入流程启动之前，托管服务预检仍会在已安装的更新程序中运行。

候选方以只读方式检查当前安装，使用相同选定的 profile、状态目录、配置路径和环境。它不会获取租约、写入历史、运行 Doctor 修复、启动 Gateway，或接收更新执行权限。因此，缺失的自定义 plugins.load.paths 条目可能会产生准入警告，同时保留已配置的路径和插件配置字节。准入不承诺修复该路径。

遗留插件配置，例如 Discord 的嵌套 dm.policy 和 dm.allowFrom，在候选方的 Doctor 规划器生成完全有效的配置时，会以警告方式被准入。准入会检查投影的数据库目标，同时保留原始配置和状态字节。正常的更新时 Doctor 仍负责保存修复、备份和回滚。

有效的 admit 裁决仅替换其报告的候选方拥有的检查。对于包更新，已安装的 Node 预检始终运行，包括在信息性 Node 警告之后选择或私有配置兼容运行时。有效的 refuse 裁决会通过常规变更前错误和 JSON 输出报告候选方的原因和下一步操作。历史会在 candidate-admission 步骤中记录这些检查。已安装更新器在准入后继续拥有更新，包括所有变更。

如果标记缺失或无效，更新器会使用其已安装的准入检查并记录 update-admission-unsupported-target。如果候选方超时、崩溃，或未返回有效的 protocol-1 裁决，它会记录 update-admission-fallback 并使用相同的已安装检查。这些警告仅为信息性；已安装检查决定更新是否继续。当历史在 128 步或 16 KiB 限制处压缩时，两个警告步骤都会保留其身份、状态和时间戳。警告文本可以被压缩以适应该限制。这不需要迁移，也不会改变准入决定。

使用 --admission installed 强制使用已安装检查。默认选项是 --admission auto；该选项没有环境变量形式。--dry-run 始终使用已安装检查，并且不会暂存包或调用候选方准入。Git/源更新保留其现有流程。

openclaw update admit 是内部命令，从帮助中隐藏。supervisor 会将 --context <absolute-path> 传递到一个私有的 mode-0600 上下文文件；该命令路径和必需参数选择准入子模式。该命令输出一个 JSON 文档，包含 protocol、verdict、reasons、warnings 和 facts，其中包含候选方/已安装版本、候选方声明时的 nodeEngines 要求，以及命名检查结果。它在准入时退出 0，拒绝时退出 3，或在无有效裁决的内部错误时退出 2。它会以退出 2 拒绝继承的更新权限变量，使 supervisor 能够回退。它不执行托管服务祖先检查。默认准入预算为 120 秒，并遵循 canary 超时预算解析。

运行 JSON 包含 run.admission，其 owner: "candidate" 或 "installed"，以及可选的 protocol、candidateVersion、checks 和 fallbackReason。账本将此元数据存储在其现有 origin JSON 中；run.origin.candidateAdmission 保留有界、脱敏的裁决，包括所有已记录的原因和警告。较旧的历史记录可以省略准入元数据。

准入元数据是诊断性的，当恢复回执使用完整历史预算时，可以从历史中省略。

此交接仅在已安装更新器已经支持时有效。在暂存前拒绝的较旧更新器不能使用较新候选方的判断；请先遵循该已安装版本的恢复指南。

自动化与 SSH¶

对于另一台主机上的授权更新，请使用目标安装的所有者账户和非交互式 SSH 命令：

ssh -T user@gateway-host 'openclaw update --yes' </dev/null

确保 openclaw 在该账户的 SSH 环境中解析到预期安装。当目标是命名 profile 时，在 update 前添加现有的全局 --profile <name>。

仅有一个活动聊天会话并不会阻止显式更新。--yes 会跳过确认和可选的 shell 补全提示。没有它时，普通升级仍可以通过管道输入运行，但需要确认的操作（例如降级）会立即失败。当 stdin 不是终端时，失败报告菜单和分诊同意提示不会等待输入。--yes 不会授予 exec 批准，也不会接受已更改的插件能力。

更新承载其自身会话的 Gateway 的代理在可用时应使用 gateway 工具的 update.run 操作。SSH 配方用于另一台主机；请验证目标不是同一个 Gateway。常规执行审批和部署所有权仍然适用。

更新期间的原生服务命令¶

更新器通过目标 CLI 启动的原生服务安装、重启和停止命令，在其子进程稳定期间会保留原始更新所有者。如果命令的所有者退出或失去租约，则该命令无法启动另一个原生变更，也无法提交其待处理的配置更改。只要已注册的子进程或其进程组仍然存活，新的更新就会保持被排除状态。

目标运行时必须支持这种所有权交接。候选验证会在停止 Gateway 或激活其替代项之前检查该支持。缺少目标 CLI 或不支持该功能的旧目标会被拒绝；更新器不会调用旧运行时安装程序作为替代。经过授权的安装根更改会单独绑定目标 CLI，同时保留原始更新所有者。由更新拥有的命令还会拒绝无法保留此所有权的非托管重启/停止、分离式重启或 Windows 启动文件夹回退。普通用户调用的 openclaw gateway 命令保持现有行为。

在 Windows 上，能力探测会保持存活，直到更新器完成对其进程身份的绑定。如果 Windows 无法提供进程创建时间戳，更新器会保留由存活父进程建立的身份，或使用子进程记录的启动器身份，并在运行历史和诊断日志中记录警告。观察到不同身份时，仍会拒绝交接。使用 InteractiveToken 的计划任务仍受支持；这不需要存储任务密码。

此目标 CLI 保护并不涵盖每个 Doctor 或插件子进程，也不涵盖包变更前的进程内服务准备。

选项¶

核心修复后的 Doctor 和 openclaw update finalize 默认不会使用单独的每个 Doctor 截止时间，除非操作员提供 --timeout。新的核心后进程会单独接收操作员选择，与其内部步骤配额分开。旧目标保留其现有配额和截止时间行为。

当省略 --timeout 时，当前 CLI 和 RPC 最终处理不会添加聚合激活截止时间。显式操作员限制和继承的激活配额仍然适用；旧版或无法识别的交接保留其现有有限截止时间行为。探测、所有权准入、就绪状态、恢复和清理保留各自的边界。显式 --timeout <seconds> 会限制每个最终处理阶段及其子命令。准入和配置阶段会根据共享 SQLite 状态进行扩展。

在激活或回滚经过验证后，过期的包和启动器备份树共享五分钟清理预算。超时会保留剩余备份，并将其路径记录为警告，而不会撤销已验证的安装。清理会在文件系统操作之间检查此预算，并等待已在进行中的操作稳定，因此停滞的存储可能会延长清理等待时间。所有权和路径身份失败与清理超时保持区分。

插件后的配置验证和就绪检查使用 Doctor 完成后测量的共享数据库和代理数据库大小，包括 WAL 文件。当省略 --timeout 时，核心后的插件安装和更新工作没有默认截止时间；显式操作员限制和旧调用方配额仍然适用。当存在聚合激活预算时，它会使用测量的数据库大小、观察到的候选启动、插件数量和调用方的步骤配额。迁移后的最终处理会保留显式或继承的配额。聚合超时会报告 update-activation-timeout，并在写入者稳定之前保留所有权；它不会授权回滚或重启。使用 openclaw update status 和 Doctor 获取恢复指导。

没有 --verbose 标志。使用 --dry-run 预览计划操作，使用 --json 获取机器可读结果，并使用 openclaw update status --json 查看通道、可用性和最新的持久更新报告。Gateway 控制台详细程度（--verbose）和文件日志级别（logging.level: "debug"/"trace"）是独立的调节项；参见 Gateway 日志。

交互式更新会显示阶段转换、当前步骤和已用时间。阶段与 Control UI 一致：已请求、暂存、校验、激活、重启、验证和完成。当输出通过管道传输或捕获到日志中时，进度会无动画打印，并在步骤运行期间每 30 秒报告一次已用时间。更新、验证和回滚不需要推理或模型身份验证。模型身份验证发现仍保持为警告。自动推理修复属于更新以失败结果结束并释放其更新所有权之后的分诊；它不会更改该已记录结果。来自旧版更新器的报告仍可能包含 repairing 阶段。失败步骤包含来自两个输出流的最终诊断信息；超时会明确标注。最终报告包括结果、记录的阶段持续时间、失败步骤、验证事实和恢复指导。--json 保持 stdout 机器可读，并且不打印进度步骤。

当没有活动更新时，openclaw update status 会将保存的结果标记为 Last recorded update，并附带记录的开始时间，因此历史结果与当前更新活动有所区分。

当从开发检出切换到包时，更新器会替换 npm 的安装链接，并保持外部检出不变。如果激活失败，恢复该链接及其启动器不会验证可变检出的运行时。恢复保持未验证状态，并且不会授权自动重启；在重启之前，请检查检出和恢复报告。

对于没有运行时数据库的配置文件，较旧的 npm 目标会在更新器记录历史之前初始化其兼容状态。所选版本的 Doctor 会在激活之前运行，包括当 npm 的安装钩子已经创建数据库时。现有数据库保留其降级保护。

如果数据库架构预检无法检查已配置的路径，因为配置无效，其拒绝信息会列出配置文件和无效字段。运行 openclaw doctor --fix 以修复已弃用或不识别的字段，更正任何剩余错误，然后重试更新。预检不会更改配置。

在全新配置文件上使用显式包规范时，会先使用临时 OpenClaw 配置文件进行暂存。更新器会在允许更改所选配置文件之前，检查暂存运行时声明的架构和 Node 要求。没有声明架构支持的工件会被拒绝，而不会创建配置文件的运行时数据库。准备过程使用原始包规范和所属包管理器。

全新配置文件的 --dry-run 会保持数据库不存在，并且不记录一次运行。 对于包目标，它会使用与真实更新相同的运行时规划器，检查精确目标的 Node 要求。文本输出和 JSON notes 会在没有可用运行时可用时报告 Would refuse update，或者在更新器能够将其拥有的托管服务刷新到兼容的 Node 时报告 Would replace。预览仍会成功退出，并且不会安装包或更改服务。 如果无法解析包元数据，请使用精确的已发布 --tag 重试；目标选择失败不会使用更新器的 schema 初始化配置文件。 元数据失败会保留检测到的更新模式，以及针对注册表查找、dist-tag 解析、版本不匹配、schema 声明或 Git 目标检查的具体失败事实。 摘要和 openclaw update status --json 会包含原因和下一步；受限失败报告会包含相同的公开描述，而不会发布本地路径或注册表响应文本。现有更新器在候选版本安装之前无法获得这些诊断信息。

--dry-run --json 会为包安装和 Git 安装报告 currentVersion 中已知的已安装版本，包括一个已保存的 dev 通道，该通道会选择转换为 Git。如果目标版本未解析，targetVersion 保持为 null，并且附加的 targetVersionReason 字段会解释原因。已解析的目标会省略此字段。文本预览也会显示已安装版本并解释未解析的目标。

--yes 还会跳过可选的 shell 补全设置提示。现有的补全配置文件和缓存仍会在需要时修复；在新 shell 配置文件中安装补全仍然是交互式选择。

--tag 只更改本次包更新。已保存的 update.channel 仍会继续控制后续的前台更新和自动更新，即使是一次性 beta 安装之后。使用 --channel 更改该策略。

对于显式包工件，配置好的插件可用性会在演练或激活之前，针对私有暂存的包版本进行检查。--dry-run 不会暂存工件，并报告此检查仍处于待定状态。

托管更新交接会保留所选工件，包括已为最新的重复项，因此目标检查会使用该工件的数据库 schema 和运行时要求。

对于源代码检出，--dry-run 会预览更新流程，而不会获取 Git 引用或检查工作树更改。真实更新会在修改检出之前检查未提交的更改。使用 openclaw update status 检查当前分支、版本和更新可用性。

update wizard¶

交互式流程，用于选择更新通道并确认之后是否重启 Gateway（默认重启）。在没有 git 检出的情况下选择 dev 时，会提供创建检出的选项。

通道选择器会读取本地安装身份，而不会检查 Git 新鲜度或依赖项。这些检查会在你应用更新时运行；请先使用 openclaw update status 检查可用性。

详细主题¶

状态和运行历史

update status、持久运行账本，以及每次运行写入的报告。

修复和恢复

更新失败后的排查、update repair 和 update cleanup。

更新如何运行

通道切换、验证、重启交接以及 Git 检出流程。

• 恢复失败的更新
• update status
• 运行历史和报告
• update repair
• update cleanup
• 它的作用
• 验证和激活
• 恢复限制
• 经过兼容性检查的包回滚
• 重启交接
• 控制平面响应形状
• Git 检出流程
• 通道选择
• 更新步骤
• 验证干净的工作树
• 解析目标
• 构建候选版本
• 验证候选版本
• 激活并验证
• 同步插件
• 插件同步详情

相关¶

• openclaw doctor（在 git 检出中会提示先运行更新）
• 开发频道
• 更新
• CLI 参考