更新

保持 OpenClaw 最新。

对于 Docker、Podman 和 Kubernetes 镜像替换，请参阅升级容器镜像。镜像入口点（entrypoint）会在启动 Gateway 之前运行 Doctor，如果挂载状态无法安全修复，则会退出。

在重大更新之前，创建经过验证的备份。自动配置副本和迁移恢复原始文件并不是完整状态备份。

升级非常旧的版本¶

对于早于 2026 年 6 月的安装，请先升级到 2026.9.5，运行其 Doctor 迁移，然后再升级到 latest。此桥接版本仍会导入旧的 tasks/runs.sqlite、flows/registry.sqlite 和 plugin-state/state.sqlite 数据库，导入 6 月之前的插件 JSON 状态和 credentials/oauth.json，修复已退役的 agent 和频道配置键，并包含旧的运行时别名。已退役的插件导入涵盖 Telegram、iMessage、Active Memory、Nostr 和 Microsoft Teams；请参阅旧状态迁移。当前版本会将这些已退役的状态文件保留不动。

如果你已经安装了最新版本，Doctor 会在重写仍包含这些已退役键的配置之前停止，并引导你通过同一桥接版本完成操作。

如果更新的版本已经升级了你的 SQLite 数据库，请为桥接版本使用兼容的更新前备份。旧版本无法打开较新的数据库模式；在对该状态运行 2026.9.5 之前，请遵循降级恢复。

请先备份状态，并使用受支持的 Node 版本：Node 24.x 系列中的 24.16+，或 Node 26.1+。在整个过程中保持相同的拥有账户、安装前缀、profile 以及状态/配置路径。

对于使用 OpenClaw 管理的 Gateway 服务的 npm 安装，请在终端中运行以下第一阶段命令：

openclaw gateway stop &&
  npm install -g openclaw@2026.9.5 --allow-scripts=openclaw &&
  openclaw --version &&
  openclaw doctor --fix

确认版本输出为 2026.9.5，并且 Doctor 已导入你需要的旧任务、流程、插件和频道状态。在继续之前，解决任何失败或冲突的导入。Doctor 仅为已启用的频道和账户导入频道状态。如有需要，请在 Gateway 停止时临时启用这些频道，重新运行桥接 Doctor，然后恢复之前的启用设置。请确保相关插件已安装，然后再运行其迁移。然后安装当前版本并重新启动：

npm install -g openclaw@latest --allow-scripts=openclaw &&
  openclaw doctor --fix &&
  openclaw gateway start &&
  openclaw gateway status --deep

这些 npm 命令适用于 npm 12 或 npm 11.16+；在 npm 11.15 及更早版本上，请省略 --allow-scripts=openclaw。对于 pnpm 拥有的安装，请将每条安装命令替换为 pnpm add -g --allow-build=openclaw openclaw@2026.9.5，然后执行 pnpm add -g --allow-build=openclaw openclaw@latest。对于 Bun，请使用 bun add -g --trust openclaw@2026.9.5，然后执行 bun add -g --trust openclaw@latest。在每条 openclaw 命令上保留任何常规的 --profile 选择器。对于自定义服务或前台 Gateway，请通过其实际所有者停止和启动，而不是使用上面的托管服务命令。

推荐：openclaw update¶

检测你的安装类型（npm、pnpm、Bun 或 git），在旧 Gateway 继续服务时检查新版本，然后激活并验证更新。

openclaw update

从引入候选包自有准入的版本开始，包更新会在私有暂存区中准备目标版本，并让其代码在激活之前判断配置、数据库模式、Node 要求和插件可用性。因此，对于已经使用支持该机制的更新器的用户，后续版本可以纠正这些准入决策。已安装的更新器会保留托管服务所有权、祖先链检查以及所有变更操作。较旧的已安装更新器会保持其暂存前的拒绝行为；更新的候选包无法修复这第一步。没有能力标记的目标会回退到已安装的检查机制，--admission installed 和 --dry-run（后者从不暂存包）也是如此。准入选择仅限 CLI：默认值为 --admission auto，并且没有环境变量覆盖。

托管服务检查是尽力而为的。如果服务管理器不可用（包括没有 systemd 的 Linux 主机），更新会继续并记录一条警告。它会保持未经验证的服务定义不变，并跳过其自动重启。更新后，请重新启动你手动启动的 Gateway，或使用其实际的监管程序（supervisor）。Doctor 仍会在迁移之前检查活动的状态写入者。

服务成员资格使用正在运行的 Gateway 的进程祖先链和原生监管程序事实来判断。一个继承了服务环境标记的外部终端，在原生成员资格被验证为外部后，仍然可以执行更新。被重新父进程化的子进程只要与 Gateway 共享 macOS 进程组或 launchd 任务，或共享其 systemd 单元 cgroup，就仍被视为内部。当核心已经是最新版本时，更新绝不会因服务成员资格而被拒绝。当成员资格无法被验证为外部时，更新会以 already-current 完成，并在该维护可能更改文件或停止 Gateway 之前，发出插件、运行时和服务维护已被推迟的警告。显式的频道更改也不会被应用，并会在警告中被点名，以便可以重试。真正的更新仍会执行包含性检查。存在但无法读取的原生成员资格会以 service-membership-unverified 拒绝更新；已确认的原生成员资格使用 inside-gateway-service。Windows 目前使用已验证的祖先链和继承标记回退，因为运行时无法获得作业对象（job object）成员资格。真正的 Gateway 后代进程必须使用受管更新交接（managed update handoff）或独立的终端。

Linux 同时支持 cgroup v2 和命名的 systemd v1 层级。当可读的原生观察结果确认此主机没有服务包含树或 launchd 任务时，完整的外部祖先链遍历和独立的进程组允许更新器自行停止、更新和启动该托管服务。服务定义仍必须属于此安装。报告和 openclaw update status --json 会记录一条警告：Service membership unverifiable on this host; using managed stop/update/start.

权限失败、冲突、不完整或格式错误的观测结果，以及已知服务成员，均不使用此回退。即使不存在原生单元树，Gateway 进程组中被重设父进程的调用方仍被视为位于服务内部。当存在原生事实信息但无法读取时，请在未由 Gateway 服务启动的交互式外部 Shell 中，以该安装的所属账户运行以下序列：

openclaw gateway stop && openclaw update --yes && openclaw gateway start

停止 Gateway 可消除实时容器判定的模糊性。全程保持相同的账户、配置文件和状态/配置路径，并在更新命令上重复任何请求的 --channel 或 --tag。如果更新报告错误，请先遵循其恢复指引，再启动 Gateway。在具备原生助手支持的情况下，openclaw gateway call update.run --params '{}'、Gateway 工具的 update.run 动作以及 /update 可以改为执行受管交接。Linux 瞬态用户交接需要 systemd-run；没有它的模拟管理器无法使用该途径。参见自动化和 SSH。

受管服务的拒绝会在失败报告和 openclaw update status --json 中保留特定代码，例如 inside-gateway-process-tree 或 service-definition-changed。共享报告在移除私有路径和进程 ID 的同时，保留该代码和恢复指引。这些检查在已安装的更新程序中运行：在软件包替换之前，新的候选版本无法修复旧驱动程序产生的拒绝，也无法恢复旧报告已丢弃的详细信息。

Control UI 更新使用经过验证的辅助程序来停止并重启受管 Gateway。在 macOS 上，该辅助程序将其实时更新所有权带入 LaunchAgent 激活；Gateway 内部的普通命令仍然无法停止其自身服务。如果旧版已安装更新程序在激活前报告 managed-service-stop-failed，则说明候选版本尚未替换该更新程序。请使用相同的安装所有者从外部终端执行更新，然后重试 Control UI 更新。

软件包替换后，来自旧版更新程序的兼容性配置读取会在使用更新后软件包及其依赖项的全新进程中运行。这也适用于由 2026.9.4 驱动的更新。如果可选读取失败，更新程序会打印 candidate-config-read-failed，并保持服务定义不变。回滚后，读取将基于已恢复的软件包进行。更新后请使用更新后的 CLI 检查所报告的问题。

Node 和 Bun 读取器每次读取仅运行一个子进程。尝试进行嵌套读取会在生成子进程前停止，并记录 candidate-config-read-recursion。两种运行时对同步和异步读取使用相同的结果通道；配置诊断与结果保持分离。

当可写的受管 Node Gateway 服务指向另一个全局安装时，更新会保留当前活动的 CLI 的安装作为其目标，并通过 gateway install --force 刷新服务，然后验证重启后的 Gateway。在该交接成功之前，旧的服务命令仍然是恢复标识。协调失败会记录为警告，并附带手动修复命令。代码更新可以报告成功，而服务协调仍处于待处理状态；已停止的服务将保持停止，直到修复完成。在 Linux 上，重新生成会保留既有 PATH 条目的顺序，并在前面添加新加入的受管条目。仅从旧定义中继承的路径仍会通过现有安全过滤器。如果无法保留定义，则协调需要手动修复。部署拥有的定义保留其现有的安装所有者。

位于不同软件包根目录的受管 Bun Gateway 使用现有的服务根更新路径：只有 Gateway 安装会前进，发起调用的 CLI 安装保持不变。更新程序会根据 Bun 1.4+ 和 WAL 安全的 node:sqlite 要求，验证服务的实际 Bun 可执行文件；Bun 的模拟 Node 版本不会针对 engines.node 进行校验。如果更新程序在 Node 上运行，则在软件包替换之前，其 Node 还必须满足目标软件包的引擎和 SQLite 要求，因为收尾阶段会使用该运行时。Bun 拥有的包管理器探测和安装会使用该已验证的可执行文件，现有的安装/重启路径会保留已记录的运行时固定版本。仅 ~/.openclaw 下的路径不足以确立 Bun 包管理器所有权。参见仅 Bun 安装。

Doctor 和 openclaw update repair 不会将 Bun Gateway 移到其他 CLI 安装上。从其他安装调用修复时，会报告漂移并在停止 Gateway 之前拒绝服务维护。请从 Gateway 自身的安装运行修复，例如 <bun> <service-root>/openclaw.mjs update repair，或使用 openclaw update 就地推进其安装。

已安装的更新程序首先运行。在 Linux 拆分根目录测试环境中，已发布的 2026.9.6 在 PATH 中缺少 Bun 时以 ENOENT 提前拒绝，使 Gateway 和两个安装均保持不变。当 PATH 中存在 fork 版 Bun 时，该已发布的驱动程序就地更新了 Gateway 安装，并使其健康重启，同时保持发起调用的 CLI 不变。上述路由和显式 Bun 选择仅适用于驱动更新的更新程序包含此修复的情况。安装较新的候选版本无法改变这第一跳。

CLI 或所选服务安装中待处理的软件包发布恢复会阻塞可写准备。请先遵循更新所报告的软件包恢复命令，然后再重试；Doctor 不会清除这些产物。

已安装的 2026.9.4 更新程序可以在目标代码运行之前以 managed-service-preflight 拒绝。要到达包含此修复的版本，请使用手动包管理器流程，并保持相同的所属包管理器、前缀和状态/配置。首先备份，通过其实际的监督程序或前台进程所有者停止 Gateway，替换软件包，运行 Doctor，然后通过同一所有者重启。--no-restart 无法修复旧的准入检查。

未包含准入修复的更新器首次随 2026.7.2-beta.5 发布，包括 2026.6.34–2026.6.35 以及 2026.7.33–2026.7.35 扩展稳定线，当已配置的插件路径缺失时，会在暂存前以 plugins.load.paths: plugin path not found 拒绝。 恢复自定义插件目录，或移除其已配置路径，然后再更新。 openclaw doctor --fix 会修复可识别的捆绑路径别名，但保留无关的自定义路径。

选择 Node 的软件包更新会在激活前检查确切候选版本的 Node 要求。 不兼容的运行时会产生 node-runtime-preflight，其中包含目标版本、所需引擎范围、所选 Node 版本以及升级命令。 npm 目录权限失败会产生 global-install-permission-denied，其中指明目录、可用时的所有者以及下一步操作。 试运行 JSON 会在 failures 中包含这些结果；更新报告和 Doctor 的更新历史会保留已记录的失败。 在这些预检期间，正在服务的 Gateway 保持原位。

目录权限检查仍位于已安装的更新器中。较旧的更新器无法从尚未暂存的候选版本获得新的准入行为。 如果从较旧的版本升级，请先检查 Node 要求 和 npm 前缀的权限； 参见 更新故障排除。

已安装的 registry 软件包版本或 Git 目标 SHA 仍会运行插件维护，修复符合条件的旧 OpenClaw 版本固定， 并在插件发生变化或其服务指向另一个安装时重启正在运行的受管 Gateway，除非设置了 --no-restart。 未发生变化的运行会以 skipped / already-current 结束。

插件维护不会导致本可成功的核心更新失败。如果某个插件无法更新，OpenClaw 会继续处理其余插件， 在可能的情况下保留先前的安装，并打印简短的下一步操作。正在运行的已更新 Gateway 也可以报告某个插件未加载， 而不会将核心更新变为失败。单个插件的结果仍可在 --json 输出中查看。 安装核心、修复必需的配置或状态，或启动已更新 Gateway 的失败仍属于更新失败。 通过 plugins.load.paths 选择的本地副本由操作员管理。更新和 openclaw update repair 会保留所选副本及其遮蔽的任何 npm 安装，并在结果和更新历史中记录 plugin-operator-managed 警告。 请针对已更新的 OpenClaw 版本验证该副本，或将其路径从 plugins.load.paths 中移除， 以再次使用受管安装。这不会授予本地副本受信任插件权限。 显式软件包工件（例如 tarball 路径或 URL）即使版本匹配也会经过验证并安装； 版本匹配并不能证明两个工件包含相同的代码。 显式的 --channel 选择仍会成为已保存的更新通道。 对于支持安装前检查的版本，健康检查、配置和插件规划，以及在复制状态上启动测试 Gateway， 会在服务停止前完成。停止区间包含交换、所需迁移、插件下载和收敛，以及服务启动。 插件工作使用已安装目标，而不需要正在服务的 Gateway。发生变化的插件快照会在重启前运行全新的 Doctor 迁移； 未变化的插件不会再次运行完整的 Doctor 检查。最终报告会记录直至收敛和最终验证的停机时间， 以及验证结果。有关检查，请参见 验证和激活。

源更新在停止 Gateway 之前，也会允许已安装 checkout 中的构建工件所有权和运行时暂存访问。 保留的 .artifacts/dist-artifacts.lock 会在正在服务的 Gateway 保持运行的同时， 以记录的所有者、时间戳和确切恢复命令拒绝更新。 在释放该锁之前，请确认所有相关构建/检查进程（包括已分离的后代进程）均已停止； 仅所有者 PID 已失效并不足够。 更新器会保留该所有权，直到其工作稳定，并将准备好的运行时结果带入完成。 已为当前版本的修复会复用已允许的所有权；提升的运行时输出无需重新生成。 传递源构建缓存位置的已发布更新器（包括 2026.9.6）也会在候选版本构建期间接受已安装 checkout 检查。

The canary uses a temporary loopback Gateway port and suppresses background listeners, including the MCP Apps sandbox, browser control, and channel services. This lets validation run while the serving Gateway keeps its configured ports. It preserves non-secret Gateway auth settings such as gateway.auth.rateLimit for policy checks, while using a temporary token and disabling Tailscale identity authentication. The activated Gateway retains your normal listener settings. The canary verifies the copied plugin payloads without downloading replacements. It warns when plugin refresh is deferred; live update finalization owns that refresh, so a slow registry cannot consume the canary's startup budget. This candidate-side behavior also applies when the installed updater is 2026.9.3. That older updater still caps the entire validation sequence at five minutes; its --timeout option cannot increase this cap.

Plugin rehearsal copies are temporary and rebuilt after interruption. Copying uses up to four concurrent file copies and avoids a disk flush for every file. If a copy fails, active copies finish before cleanup; link publication and verification run only after all file copies succeed. Canonical state and recovery backups retain their existing durability guarantees. An older installed updater keeps its initial snapshot behavior until you launch an update from the newer version.

Database rehearsal also avoids a second full backup of each private snapshot. Update schema inspection and rehearsal use SQLite online backup with a pinned read transaction, so a busy Gateway can keep writing while the copy includes committed WAL data. Each acquisition makes one copy instead of retrying until the database becomes quiet. On rollback-journal volumes, SQLite can delay writer commits until the consistent read finishes. Rehearsal records copied pages, bytes, and elapsed time in the update ledger, then checks, compacts, and publishes the private copy for validation. Source databases and recovery backups retain their existing protection; the faster preparation takes effect when the newer updater runs.

Package updates also check npm availability for enabled configured plugins before stopping the serving Gateway or replacing the installed core. Registry targets are checked early; explicit package artifacts are checked using the privately staged package version before private validation, live-state preparation, or activation. The check uses the same plugin version rules as post-update synchronization, including release-cohort tracking, beta selection, and extended-stable targets. A missing plugin version or registry error produces a warning naming the affected plugin; the core update can continue. Registry-target --dry-run includes those warnings. For explicit artifacts, --dry-run does not stage the package and reports that plugin availability checking remains pending. Extended-stable does not accept --tag. Bundled and path-installed plugins do not require registry requests.

This metadata check does not reserve downloads. Plugin-only download, install, or load failures remain actionable warnings after an otherwise successful core update. Candidate rehearsal also reports a plugin source parse failure as a warning with the plugin ID, source path, and parser error, then continues checking other plugin entries. Valid ESM plugins can use import.meta during dependency inspection. The updater preserves recorded choices and retains the previous plugin payload where possible. Follow the reported openclaw plugins update <id> command for a failed install or update, or openclaw doctor --fix for a load problem. Invalid configuration or state, ownership errors, and failed core startup or readiness checks still prevent completion.

包发布恢复¶

受支持的 POSIX npm 更新会在将暂存包移交给恢复保管之前，打印一个外部 Node 恢复命令。请保留打印的命令；每个命令都指定一个操作，并带有必需的 --anchor 和 --operation 参数。初始日志和辅助程序仅在两者都完成后，才会一起发布到私有控制目录中。后续更新会先打印一个临时暂存命令，然后在辅助程序移动后打印稳定命令。暂存命令仅在该移动之前有效；较早操作的命令无法选择较晚的操作。辅助程序在使用该日志之前，会验证其自身记录的路径、身份和内容。它位于实时包和一次性恢复目录之外。status 读取操作，repair 仅恢复其记录的包发布，retire 仅删除其记录的过时对象。这些命令不会替代更新后的插件、迁移或服务恢复。在恢复操作期间，请保持其他包管理器停止。

退役会在记录辅助程序的最终解除链接意图之前，记录一次性目录的删除。然后辅助程序被删除。有界的最后收据保留在控制目录中，并可通过 openclaw update status --json 作为 packageActivation 读取，即使在辅助程序删除后也是如此。已完成的收据仅当下一次更新通过同一原始执行器存储被接受时才会被替换；它不是修改安装的权限。

缺失、遗留或身份不匹配的恢复工件会阻止下一次可变更新。它们不会被静默迁移或删除。请保留它们并使用其原始恢复所有者；不要重新创建日志或删除它们以绕过拒绝。

对于较旧的目录内激活日志，openclaw update status --json 会报告记录的阶段和原始辅助程序的 status 命令。当前更新器仅检查这些日志；在开始另一个更新之前，请使用其原始辅助程序来恢复或退役该操作。

包恢复不会重放完整状态检查点或反向数据库迁移。自动回滚会保留兼容的数据库，并保留较新的写入。如果先前运行时无法读取当前数据库，更新器会保留候选和恢复工件，并报告拒绝回滚的原因。

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

openclaw update --channel beta
openclaw update --channel extended-stable
openclaw update --channel dev
openclaw update --dry-run   # preview without applying

openclaw update 没有 --verbose 标志（安装器有）。用于诊断时，请使用 --dry-run 预览计划操作，使用 --json 获取结构化结果，或使用 openclaw update status --json 检查通道和可用状态。

--channel beta 会按语义化版本顺序，从 beta 和 latest npm dist-tags 中选择最新版本。如需一次性包更新并固定到原始 npm beta dist-tag，请使用 --tag beta。

已保存的 update.channel 仍作为未来更新、自动 检查和更新状态的通道。例如，在已保存的稳定通道上的一次性 beta 包，之后仍会继续检查稳定通道。使用 --channel beta 可订阅 beta 更新。出于兼容性要求，插件仍会遵循已安装的核心版本。

--channel extended-stable 仅限包，并且安装仍仅限 前台。OpenClaw 会读取公共 npm extended-stable 选择器， 验证所选的精确包，并安装该精确版本。缺失 或不一致的注册表数据会失败关闭；它绝不会回退到 latest。 如果所选版本旧于已安装版本，正常的 降级确认仍然适用。CLI 会在成功的核心更新后持久化通道；直接 npm install -g openclaw@extended-stable --allow-scripts=openclaw 不会 更新 update.channel，但最终的 extended-stable 包版本仍 仅检查已验证的 extended-stable 选择器以判断更新可用性。 该直接命令适用于 npm 12 或 npm 11.16+。在 npm 11.15 及更早版本中， 请省略 --allow-scripts=openclaw。 核心切换后，符合条件的官方 npm 插件和受信任的官方 ClawHub 插件，如果具有裸/默认或 latest 意图，将收敛到该精确核心版本。符合条件的旧 OpenClaw 版本 固定项会恢复该默认更新策略。显式非 latest 标签、独立 版本固定的固定项、第三方插件、自定义 ClawHub 注册表以及其他来源会保留 其现有行为。 版本绑定的运行时插件在核心为修正版本时，会收敛到基础发布群组（例如，YYYY.M.P-2 使用插件 YYYY.M.P）。 由当前 OpenClaw 版本创建的目录安装会保留该默认 意图。已验证的 OpenClaw 拥有的包，如果记录在不超过核心的精确 OpenClaw 版本上，在成功 更新后会恢复其目录的默认选择器。 这包括旧的自动和手动固定项。其记录的注册表 和插件设置会被保留，后续更新将继续遵循 所选通道。显式提供给插件更新命令的版本 仍适用于该操作。

--channel dev 会为 npm 拥有的 包安装和现有 Git 检出提供持久且持续移动的 GitHub main 检出。包 安装会拒绝 --tag main 简写，因为工作区检出 不是自包含的包工件。请使用 openclaw update --channel dev 切换到受支持的检出和构建流程。其他显式包规范 保留其包管理器行为。

在源码安装中，Doctor 和插件更新会保留与宿主一起构建的插件。 具有相同版本字符串的注册表插件可能面向不同的 SDK，因此 在没有匹配的 SDK 构建证据时，它不会替换源码构建。 现有注册表代际保留在磁盘上；收敛会报告捆绑选择并跳过它们的刷新。不需要 OPENCLAW_DEV_SOURCE_ROOT。

beta 通道上的受管 npm 插件使用相同的 beta/latest 最新版本选择，包括 @openclaw/codex 等官方插件。较旧的 beta 标签不会使插件落后于当前稳定版本。启动修复 会保留已经最新的包，因此无操作刷新不需要 再次重启。

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

从 2026.9.2 更新并跨越模式版本提升¶

由 OpenClaw 2026.9.2 驱动的更新可以正常跨越共享状态模式版本提升。 目标在应用迁移内容的同时保留旧的已发布 模式版本，因此旧更新器可以完成其账本写入和最终 报告。Doctor 会说明模式内容已应用，版本发布 被延迟。在此期间，新的 Gateway 基于已迁移的内容运行。

发布会等待，直到每个受影响的更新运行都已终止至少 五分钟。对于发布目的而言，一个已运行且超过 30 分钟未变化的行 被视为已放弃；这不会使无标识的更新历史行终止。Gateway 监视器会在截止时间后发布； 稍后的数据库打开也可以发布它。有关精确时序和残留的旧 CLI 限制，请参阅 数据库模式。

当代理数据库也需要迁移时，候选项会先在私有副本上预演 Doctor，此时已发布的更新器仍可以回滚其包。 在包提交后，新的核心后进程获得当前执行器权限并委托 Doctor。Doctor 在迁移实时状态之前，会验证一个覆盖每个代理数据库的保留恢复归档。然后更新器重启 Gateway。

缺失的状态元数据或未验证的备份覆盖仍可能产生带有数据库版本和恢复说明的 update-schema-bump-unfenced。 在包提交之前，请让失败的更新完成恢复之前的包。OpenClaw 2026.9.2 在安装后验证失败后会保持 Gateway 服务停止。在包提交后，旧包备份已消失： 请使用已安装的兼容构建完成 openclaw doctor --fix，然后运行 openclaw gateway start。包回滚无法撤销已迁移的状态。

如果兼容包仍需要安装，请在 Gateway 之外的 shell 中运行手动更新，并将 <target> 替换为拒绝信息中的精确目标版本：

openclaw gateway stop
npm install -g openclaw@<target> --allow-scripts=openclaw
openclaw doctor --fix
openclaw gateway start

仅在上一条命令成功后再运行下一条命令。对于 npm 11.15 及更早版本， 省略 --allow-scripts=openclaw。对于由 pnpm 管理的安装，请将安装 命令替换为 pnpm add -g --allow-build=openclaw openclaw@<target>；对于 Bun，请使用 bun add -g --trust openclaw@<target>。

同模式更新、较早的无账本更新器（例如 2026.9.1）以及 2026.9.3 及之后的带围栏事务性更新器会保留其现有行为。 回退机制不会撤销较早的迁移；如果数据库已经比恢复的包更新，请安装兼容的目标版本，并在启动 Gateway 之前完成 Doctor。

对于由 2026.9.2 更新的 Git 检出，如果在状态写入之前 Doctor 拒绝继续，并且该检出的 reflog 能明确识别出上一个提交，则会打印源代码恢复命令。请等待更新器退出，然后在独立的 shell 中按照打印的检出、pnpm install、pnpm build 和服务启动指引操作。如果无法验证上一个提交，Doctor 会转而指向 reflog。状态修复后的拒绝会保留迁移所有者的说明：仅恢复源代码并不会恢复状态。 这些诊断信息也会进入警告日志，并受常规日志设置和轮转影响。解决拒绝原因后，请重试更新。升级成功后，后续更新会在激活前检查新版本。

通过聊天¶

让代理更新 OpenClaw，或从 Discord 或其他已连接的聊天发送 /update。自然语言请求会使用现有 gateway 工具的 update.run 操作。minimal、coding 和 messaging 配置文件会暴露该更新 操作，但不会授予配置读取权限或其他 Gateway 控制权限。显式的工具 限制仍然适用。

由操作员创建的计划自动化也可以在不具备聊天所有者身份的情况下调用 gateway → update.run。 Gateway 会使用当前计划运行的权限；通知目标不会成为其请求者。由外部聊天用户和 webhook 轮次创建的任务不会获得此权限。外部 聊天更新请求仍然需要当前的命令所有者权限。

/update 是不依赖模型的后备方案：即使没有可用的模型 或无法访问 gateway 工具，它也能工作。该工具、斜杠命令和 Control UI 都使用 同一个 Gateway 更新处理程序和当前授权检查。

新版本会在旧 Gateway 继续提供服务期间进行检查。对于已经是当前版本的更新，当插件发生变化或其服务指向不同的安装时，会重启正在运行的 Gateway。更新运行可以在 Gateway 观察到已记录里程碑时，在该聊天中发送以下通知：

1. 更新被接受时的确认。
2. ⏳ Restarting the gateway now (v<from> → v<to>)…，在 Gateway 停止前记录激活时发送。
3. 🔁 Back on v<to>, verifying…，在新 Gateway 开始验证时发送。
4. 最终报告，包括成功更新。

外部更新和重启通知会发送到列在 commands.ownerAllowFrom 中的目标，或已链接管理员的直接对话。 通道会在检查管理员链接之前，将直接接收者解析为其稳定的发送者身份；群组目标和通道目标不会继承某个人的 管理员权限。在 Control UI 中选择非所有者聊天不会 授权向该联系人发送通知。如果无法解析任何所有者目标，OpenClaw 会记录被跳过的通知，并将更新结果保留在运行记录和 Control UI 中；它不会将通知重定向到另一个聊天，也不会用诊断信息唤醒被拒绝的 会话。

更新生命周期通知也会遵循目标账户的 actions.sendMessage 策略。显式账户设置会覆盖通道默认值；如果两者都未设置该标志，则允许发送通知。被禁用的发送会被记录为跳过的通知， 而不会阻止更新或其 Control UI 报告。

由 systemd 或 launchd 管理的更新可能会在中间通知送达之前停止 Gateway。 对于这些安装，不保证完整的四条消息序列；持久化运行报告在重新连接后仍然可用。

具有内部源会话的运行（包括 Control UI 和 webchat）会直接在该会话的对话记录中接收 这些通知。仅传递 sessionKey 即可；调用方无需提供 deliveryContext。 在停止受管服务之前，更新器会等待正在提供服务的 Gateway 完成其重启通知尝试。该等待时间上限为 10 秒，因此停滞的通知不会阻塞激活。

报告包括结果、已记录的阶段持续时间、失败步骤、 验证事实，以及必要时所需的下一步操作。失败步骤摘要会保留 触发原因，并将其置于后续恢复建议之前，在可用时使用已记录的失败 事实。本地运行历史会将验证结果和备份 恢复路径与摘录分开保留。一次运行最多发送每条通知一次； 在重启前停止的更新只会发送其已到达阶段的通知。如果更新无法 启动，机器人会记录并解释原因，并在可用时提供手动命令。 代理会将返回的恢复说明转达给操作员。手动 更新命令在 Gateway 服务之外的终端中运行；代理不得 在其会话所在 Gateway 的 shell 中执行这些命令。缺少 所有者权限需要设置所有者，而由外部监督的安装 会使用其部署所有者的更新工作流。

对于由 OpenClaw 自身更新的安装，聊天、CLI、Control UI 和自动更新共享一个持久化运行 ID。 使用 openclaw update status 读取当前或最新报告，包括重启后；--json 会暴露 activeRun 和 lastRun 记录。 有关 Gateway 历史查询，请参阅 运行历史记录和报告。

发送者必须位于 commands.ownerAllowFrom 中，或拥有到当前 Gateway 管理员的已验证通道链接。 允许聊天并不会授予所有者权限。如果你的账户不是 所有者，回复会说明 Gateway 操作员如何将其连接。通道 设置和配对会区分所有者访问和聊天访问； 现有允许的用户不会被自动提升。 聊天更新会在受管交接、 修复工作程序和 Doctor 运行中保留原始授权来源。每个工作程序在操作前都会检查原始安装的 当前策略和配置文件状态。将通道账户重新分配给 另一位管理员不会转移已在进行中的更新；当前 所有者必须启动新的更新。没有捕获配置文件 来源的旧更新器交接会保留其配置所有者检查，并且无法在恢复期间获得链接配置文件 权限。 通过 /update 或工具进行的外部聊天更新需要 commands.restart （默认启用），包括受管安装。斜杠命令还会 遵循命令访问限制；工具调用遵循工具策略。聊天更新使用宿主安装的 已配置更新通道和安装方法。 代理永远不得在聊天 shell 中运行 npm install -g openclaw 或停止 Gateway 服务；请使用 /update 或更新操作，以便重启和通知 保持协调。

检查 FreeBSD 服务发现¶

独立的 scripts/freebsd-service-inspect.mjs 诊断会报告原生配置选择了哪些 openclaw rc.d 定义。它需要一个 root 拥有的 Node 安装、脚本和共享发现辅助模块。它不 需要 OpenClaw Ports 服务包。

从现有的 root shell 中，从受信任的 OpenClaw 包安装脚本：

install -d -o root -g wheel -m 0755 /usr/local/libexec/lib
install -o root -g wheel -m 0644 /path/to/openclaw/scripts/freebsd-service-inspect.mjs /usr/local/libexec/openclaw-service-inspect.mjs
install -o root -g wheel -m 0644 /path/to/openclaw/scripts/lib/freebsd-service-discovery.mjs /usr/local/libexec/lib/freebsd-service-discovery.mjs
(cd / && /usr/bin/env -i HOME=/ PATH=/sbin:/bin:/usr/sbin:/usr/bin LC_ALL=C /usr/local/bin/node /usr/local/libexec/openclaw-service-inspect.mjs)

如果 root 拥有的 Node 路径不同，请使用你的 root 拥有的 Node 路径。如所示，在 Node 启动前清空环境，以排除 Node 预加载选项。该命令不接受参数。 它以 root 身份读取原生管理员 shell 配置，并且不请求任何服务生命周期操作。管理员配置是受信任的 shell 代码， 而不是沙箱化的数据格式。

结果包括用于发现的精确干净环境和工作目录。它对应于以相同上下文调用的 service。依赖其他环境或目录的配置 可能选择不同的服务。

单个 JSON 结果报告 absent、present 或 unknown。present 结果 包括可执行和不可执行定义、它们的原生搜索顺序， 以及第一个可执行定义。符号链接、不安全的拥有权、不完整的 检查或意外的配置输出会产生 unknown 并退出 1。 配置内容和子进程错误不包含在结果中。

这是一个诊断观察。它不会建立进程或包 拥有权，授权更新，或启用 CLI 管理的 rc.d 服务更新。 继续使用上述安装所有者的更新流程。

过期的更新历史¶

未触及的、无身份的遗留准入记录如果超过 24 小时，可以在 Gateway 启动或状态检查期间 自动过期。该行会保留为 failed， 原因为 legacy-driver-expired，并带有重试建议；对于该形态， 不需要显式 repair。

如果 Gateway 健康但更新状态仍停留在进行中，请检查是否没有 更新仍在运行。在已更新的安装上运行：

openclaw update repair
openclaw update status

对于超过 30 分钟的非活动遗留行，repair 会验证 正在运行的 Gateway 与已安装的版本和构建匹配，然后清除过期的 运行，而无需维护或服务重启。新的显式 openclaw update 也可以取代单个过期的无身份行。最近的行和已记录的 活动 driver 受到保护。处于遗留过期形态之外的无身份行 需要显式恢复；Control UI 的配置写入暂停会在 协调后清除。

在所属更新内启动的 repair 可以继续使用匹配的继承 run ID 和活动进程身份；该运行会记录该延续。repair 仍然拒绝无关的活动或停滞 updater。错误会标识其 运行、阶段、driver PID、主机、启动时长和最后活动时长，以及观察到的存活状态。 等待该更新完成，或者在其主机上停止指定 driver，并在其退出后重新运行 repair。有关维护和恢复行为，请参阅 更新修复。

OpenClaw 2026.9.2 不会仅因为存在较旧的活动运行行而拒绝新的 CLI 更新：其 准入路径 会创建新运行，并且其 账本 仅检查重复 run ID。正常升级，然后如果旧历史仍然存在，请使用更新后的 openclaw update repair。对于此账本缺陷，不需要包管理器逃生路径。请参阅 更新运行历史。

退役更新恢复数据¶

一旦你验证了更新和你的会话，预览保留的 迁移原始文件：

openclaw update cleanup --dry-run

使用与更新相同的 profile 和 state/config 覆盖，并检查 报告中打印的状态目录。仅元数据的预览可以在 Gateway 活动时运行。要应用，请你自己停止该 Gateway，等待其他 SQLite 维护完成，并停止数据库读取器，例如会话列表 监视器。在 openclaw update cleanup 退出前保持它们停止；只读 连接可能会更改 WAL/SHM 辅助文件并使验证失效。cleanup 从不 停止或重启 Gateway。确认默认为 否；自动化必须 显式传递 --yes，包括使用 --json 时。

cleanup 永久放弃回滚到符合条件的原始文件，包括已修复的 分支和旧 provider 元数据。当前 SQLite 历史、操作员备份， 以及受保护或未知工件保留。它不能替代 更新前备份。请参阅 更新清理 了解适用条件、JSON 输出，以及 恢复中断的删除。 私有包、command-shim 和 Git 运行时备份仍由更新 事务拥有，并且不在此迁移清理范围内。更新历史中的中断条目 不会阻止清理其他符合条件的迁移归档。

更新后¶

成功的管理式 openclaw update 运行已经会重启并验证 Gateway。 在手动安装后或检查报告的问题时使用这些步骤。

运行 doctor¶

openclaw doctor

迁移配置、审计 DM 策略，并检查 Gateway 健康。doctor 还会比较活动官方插件与托管服务在重启后将加载的 OpenClaw 包。在继续之前解决任何插件重启就绪警告。详情：doctor

如果你使用的是未打包的 Chrome 扩展，请同时运行 openclaw browser doctor --browser-profile chrome。 如果出现版本不匹配警告，请从 chrome://extensions 重新加载扩展； 如果警告仍然存在，请完全重启 Chrome。

重启网关¶

openclaw gateway restart

验证¶

openclaw health

更新后的后台 exec 通知¶

[OpenClaw exec completion] 用于标识后台命令的自动后续处理，而不是周期性心跳轮询。这些后续处理可以在 agents.defaults.heartbeat.every: "0m" 下运行。若要保留后台 exec 但不产生这些 额外的模型调用，请设置 tools.exec.notifyOnExit: false，并在 agents.entries.<id>.tools.exec.notifyOnExit 中检查每个 agent 的覆盖设置。使用 process poll 收集结果。有关该设置何时生效，请参阅 后台 exec 通知。

详细主题¶

其他更新方法

在 npm 安装与 git 安装之间切换、源码服务器、安装程序以及手动包管理器。

自动更新

自动更新器、按渠道的行为以及更新活动。

回滚与恢复

降级、自动回滚、更新前备份以及排查。

• 在 npm 安装和 git 安装之间切换
• 源码检出服务器（参考脚本）
• 替代方案：重新运行安装程序
• 替代方案：手动使用 npm、pnpm 或 bun
• 包生命周期和 operator 状态
• 高级 npm 安装主题
  • 只读包树
  • 加固的 systemd 单元
  • 磁盘空间预检
• 自动更新器
• 更新活动
• 降级
• 完整状态恢复需要备份
• 自动模式中性回滚
• 更新前：创建已验证的备份
• 如果卡住了
• 在自有推理上执行无人值守修复

相关¶

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