更新方法
安装类型切换、源服务器参考脚本、安装器以及手动包管理器更新。属于更新指南的一部分。
在 npm 和 git 安装之间切换¶
由安装器驱动的切换会在当前工作所有者被移除之前验证替换项。源包装器以原子方式发布；同路径 npm shim 过渡使用经过身份检查的备份，并在失败时恢复，因此失败的候选项会让先前命令仍可运行。在移除旧的源包装器之前，更新器会重新检查其身份和内容，并确认它仍然拥有该更新。openclaw update 命令只有在核心收敛后以及请求的重启健康检查成功后，才会打印最终成功结果。
候选验证失败会让旧 Gateway 继续提供服务。激活后，只有当共享的和受影响的现有每代理数据库架构版本未改变，并且自候选项激活 Doctor 检查以来配置未改变时，包恢复才能恢复保留的先前包。候选项首次创建的数据库仅在该数据库类型支持的架构版本下是中性的。恢复的 Gateway 必须通过相同的运行时检查，之后恢复才会被报告为完成。架构迁移会阻止自动包回滚；替换代码无法撤销已迁移的状态。不完整的文件回滚会保留其备份以供检查。请参阅自动回滚。如果较旧的目标不支持保留服务定义，自动恢复会停止并报告错误，而不会使用更弱的选项重试。修复报告的故障，重新运行 openclaw update，并检查 openclaw gateway status --deep。请参阅更新失败恢复。
在 macOS 上，如果 Doctor 在更新中断后报告了一个已安装但未加载且已禁用的 Gateway LaunchAgent，请先完成更新验证或 Doctor 并分诊。然后使用打印出的 openclaw gateway start 命令，保留其 profile 和 state/config 或自定义标签覆盖。doctor --fix 会诊断已禁用的标签，但会让已停止的 Gateway 保持停止。
使用通道来更改安装类型。更新器会保留 ~/.openclaw 中的状态、配置、凭据和工作区；它只更改 CLI 和 gateway 使用的 OpenClaw 代码安装。
# npm package install -> editable git checkout
openclaw update --channel dev
# git checkout -> npm package install
openclaw update --channel stable
先预览安装模式切换：
dev 会确保一个 git checkout，对其进行构建，并从该 checkout 安装全局 CLI。stable、extended-stable 和 beta 通道使用包安装。Extended-stable 在 git checkout 上会被拒绝，而不会修改或转换它。如果 gateway 已安装，openclaw update 会刷新服务元数据并重启它，除非你传入 --no-restart。
自动的包到 Git 转换目前需要一个由 npm 拥有的包符号链接。由 pnpm 或 Bun 拥有的安装会在停止 Gateway 之前拒绝 --channel dev；在更改该安装的所有者时，请使用Git 安装器。普通的包到包更新继续使用 pnpm 或 Bun。
Git 更新会在临时候选 worktree 中构建完整运行时，包括插件和 Control UI。Dev 更新通过在其构建前对候选项进行 rebase 来保留本地提交。更新器会在激活期间发布该已准备好的运行时，而不是在停止时重复构建。它会保留构建时间戳，因此普通 CLI 命令会继续使用该已验证的运行时，而不会在移动后重新生成它。 候选安装和嵌套构建命令使用私有的 pnpm 虚拟存储，因此准备更新不会修剪正在提供服务的 Gateway 所使用的依赖项。 在检查源更改之前，会恢复候选项的临时工作区设置；实时 checkout 的工作区设置会被保留。
在激活包或 Git 更新之前，更新器还会检查可发现的、共享同一物理安装的托管 Gateway。观察到的活动同级项会在所选 Gateway 停止之前阻止更新；更新器会在发布时再次检查。请通过其自己的服务管理器或确切的 Startup 条目停止同级项，然后重试。更新器不会停止或重启同级服务。包 --no-restart 仍允许所选服务继续运行，但该例外不涵盖使用相同文件的另一个服务或 Startup 条目。Gateway 的安装变更监视器仍可能重启它。如果更新 Doctor 维护停止了所选服务，最终处理会恢复匹配的服务并报告维护重启，包括使用 --no-restart 时。如果无法检查其当前身份，恢复将保持待定。
这是对观察到的消费者的检查，而不是针对新服务启动的锁；不可用的检查不能证明该安装没有消费者。
已在运行的较旧更新器保留其自身的激活和最终处理行为。
对于具有位于不同根目录下的自有托管 Bun Gateway 的包安装，openclaw update 会针对 Gateway 的包根目录，并保持调用 CLI 的安装不变。它会验证服务的实际 Bun 可执行文件是否满足 Bun 1.4+ 和 WAL 安全的 node:sqlite，并在服务安装和重启期间保留其记录的运行时 pin。Bun 模拟的 Node 版本从不与目标的 engines.node 要求进行比较。当更新器在 Node 上运行时，其 Node 也必须通过目标的引擎和 SQLite 检查，然后才能替换包，因为最终处理在更新器运行时下运行。
Node 服务保留现有路由：可写的自有定义通常会移动到调用 CLI 的安装；Windows、被覆盖或不可写的定义，以及 --no-restart 会保留服务根路由。所选 Node 必须满足目标版本的 engines.node 要求。有关所有权检查和较旧更新器的限制，请参阅托管服务更新。
源码检出服务器（参考脚本）¶
在手动重新构建源码检出之前，请停止所有正在提供其 dist 文件的 Gateway。构建入口点会检查可发现的受管 Gateway，包括同级配置文件，并在某个运行中的服务共享该输出时拒绝执行。在 systemd 上，这包括主 PID 退出后仍保留在服务 cgroup 中的进程。请使用外部终端，位于正在运行的 Gateway 的 agent 会话之外。按照报告的服务/配置文件停止命令操作，重新构建，然后启动这些相同的服务。对于默认配置文件，请从源码检出中运行以下命令：
在构建之前停止所有列出的同级项，并在构建后启动每一项。保留其配置文件和自定义服务覆盖项，或使用对应的原生服务命令。对于列出的 launchd 作业，请使用其命名域、作业和已加载的 plist 来选择这些控制项；仅凭配置文件名称可能会识别出不同的定义。仅 Startup 的同级项必须按照确切的 Startup 文件指南停止，并通过同一 Startup 条目重新启动；更新所选服务无法停止该同级项。仅在构建成功后启动服务。如果此检出中已构建的运行时缺失且 CLI 无法运行，请在重新构建之前使用这些原生控制项。
默认情况下，source-runner 的 gateway stop 和 gateway restart 会使用现有已构建的 CLI，因此恢复过程不会先重新构建。要应用源码更改，请使用上述停止、构建和启动序列。
openclaw update 可以应用可用更新，但 skipped / already-current 不会重新构建过时的 dist；对于这种情况，请使用外部停止、重新构建和启动序列。
具有独立输出的单独候选检出可以在已安装的 Gateway 继续提供服务时进行构建。此检查会观察当前服务；它不会阻止服务在编译期间启动，并且检查不可用并不证明没有 Gateway 正在运行。
发现机制使用已安装的服务定义和调用方服务选择器。
裸 systemd 模板会针对当前操作系统账户进行检查。其他没有已安装实例定义或显式选择器的活动模板实例不会被枚举。在构建之前，请使用其原生服务命令停止这些实例。发现的 macOS LaunchDaemons 会在 system 域中检查；全局 LaunchAgents 仍保留在调用用户的 GUI 域中。
此观察不会授予更新器对系统 LaunchDaemon 的控制权。
在服务器上直接从 git 检出运行 gateway 的团队，可以从该检出内部使用 scripts/update-gateway.sh 更新它。它是源码服务器更新的参考：它会拒绝已跟踪的本地更改（包括构建输出），并在私有检出中准备已获取的目标。它会检查 main 是否可以快进，或者使用 --rebase-merges 变基本地服务器分支。依赖项使用冻结的 lockfile 安装，并且候选项会在提供服务的检出更改之前构建。准备失败会保留现有服务继续运行。准备完成后，脚本会停止其选定的服务，并在一起发布源码、依赖项和生成输出之前检查其他观察到的受管消费者。请先通过其各自的服务所有者停止任何共享安装的同级项；此脚本不会替你停止或重启它们。
消费者检查先于首次源码更改；它不会在源码和运行时发布期间阻止新的服务启动。
与 openclaw update 类似，该脚本默认会构建运行时 JavaScript、插件资产和 Control UI，而不生成 TypeScript 声明。如果此检出还需要用于插件开发的新声明，请在调用脚本时设置 OPENCLAW_RUN_NODE_SKIP_DTS_BUILD=0。
此参考脚本需要 Corepack，并在获取之前创建临时 shims，而不进行全局激活。获取后，它会冻结目标提交，并检查其精确的 pnpm pin 能否通过那些 shims 在私有探测工作区中运行。探测工作区仅包含包管理器元数据，不包含目标的依赖项、hooks 或配置。缺失或无效的元数据、预配失败或版本不匹配会在检出更新或重启之前停止；请修复目标 pin 或安装兼容的 Corepack，然后重试。
相同的已获取提交用于快进或变基。所得候选项的 pnpm pin 会单独检查，因此本地分支覆盖项仍然有效。相同的范围化 shim 目录会置于嵌套命令的 PATH 之前，并且每个操作使用自己的工作区和 lockfile 根目录。已接受的未跟踪构建输入会被复制到候选项中，并在发布前再次检查。在检出内部解析的引用会遵循候选项中对应的文件。真正外部的链接仍保留为操作员拥有的引用：会检查其目标身份，但不会递归冻结外部目录内容。保留的运行时事务目录仍作为恢复材料，并在重试时从候选构建输入中排除。
如果在停止服务后发布失败，脚本会在重启之前恢复并验证之前的 Git 修订版本以及保留的依赖项/输出。它会保留原始故障。配置和外部操作员数据位于此运行时事务之外。已更改的源码或未经验证的子进程清理会阻止破坏性恢复；保留的路径会被报告以供检查。 如果已验证的新运行时重启失败，该运行时会保持原样，因为新进程可能已经在使用它，并且之前的工件仍可供操作员恢复。失败的自动调用也会保留其小型范围化 pnpm 启动器目录；仅在所有更新子进程停止后，才删除报告的路径。 托管的 安装程序 在 Corepack 不可用时也支持 npm 拥有的临时预配；此服务器脚本有意要求 Corepack。
Warning
正在运行的旧版更新程序或服务器脚本会保留其旧的引导代码，即使它检出了包含此修复的文件。如果该旧入口点调用了环境中的 pnpm，操作员必须在跨固定版本变更后的首次更新之前选择一个与目标兼容的 pnpm 启动器。在开始更新之前，针对预期目标和已知良好的回滚引用验证该启动器。仅更新目标文件并不能修复正在运行的旧二进制文件。
已经运行的 source-server 脚本如果调用旧的三参数构建适配器，仍然拥有其先前的 Git 和依赖项变更。该兼容性路径保留其仅输出恢复；加载较新的适配器无法将旧 shell 已完成的安装移动到停止边界之后。
已发布的 2026.9.4 source-server 脚本也会在其最终重启之前进行构建。候选构建入口点仅当所选的、由原生拥有的 Gateway 提供此检出的物理 dist 时，才识别其现有更新标记。现有 source-build 事务在写入之前停止该 Gateway。在已确定的构建失败时，它会恢复先前的输出，并通过其原生所有者重启所选服务，保留其定义并重新检查其绑定。原始构建失败仍然可见；自定义 shell 重启命令仅在旧调用方中构建成功后运行。单独的候选检出或仅同级匹配永远不会授予停止另一个服务的权限。如果该原生停止部分成功然后失败，候选会重新验证并通过其原生所有者重启原始服务，而不运行自定义 shell 命令或开始构建。原始停止失败仍会被报告，包括任何完成恢复的失败。
对于该第一跳，旧脚本仍然拥有其一次成功重启，包括已编写的自定义重启命令。其空或仅包含空白的重启设置保持手动，并且不会触发自动停止。旧脚本无法接收候选进程的恢复状态：在构建成功后，候选会确定原生自启动并在返回之前弃用其构建备份。因此，后续旧脚本重启失败需要操作员恢复；它不会获得较新脚本的保留备份保证。未加入的构建写入器或失败的输出恢复会使 Gateway 保持停止状态并保留恢复材料。
生成的输出根目录，例如 dist、dist-runtime 和包本地 dist 目录，必须是真实目录。构建在读取或修改其内容之前拒绝符号链接根目录，以便清理不会影响链接目标。在更新或构建 source 检出之前，将输出根符号链接替换为真实目录。
默认停止命令是 openclaw gateway stop --force，因此非交互式 SSH 更新可以停止服务。对于自定义服务单元，覆盖这两个命令：
OPENCLAW_UPDATE_STOP_CMD='systemctl --user stop openclaw-gateway.service' \
OPENCLAW_UPDATE_RESTART_CMD='systemctl --user restart openclaw-gateway.service' \
scripts/update-gateway.sh
自定义自动命令必须一起提供，并且不能为空。 完全为空的重启命令保持操作员拥有的手动生命周期： 在调用脚本之前自行停止 Gateway，然后在解决任何故障后自行重启它。在此模式下，不要同时设置停止覆盖。 脚本不会执行自动停止、重启或构建输出回滚：
对于普通的单用户 source 安装，请优先使用 openclaw update --channel dev——它会为你管理检出、构建和 Gateway 重启。
替代方案：重新运行安装程序¶
添加 --no-onboard 以跳过入门引导。若要强制指定特定安装类型，请传递
--install-method git --no-onboard 或 --install-method npm --no-onboard。
如果在失败的 npm 包替换后 openclaw triage 无法启动，请重新运行
安装程序。它会直接运行全局包安装，并可以恢复部分更新的 npm 安装。在修复未验证的 Gateway 时，保持其停止状态。
使用 --version 将恢复固定到特定版本或 dist-tag：
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm --version <version-or-dist-tag>
Homebrew 公式安装¶
对于 brew install openclaw-cli，通过 Homebrew 更新：
openclaw update 会保持公式不变，并打印这些命令。现有
配置会在 openclaw update status --json
和更新报告中保留该跳过结果和指引。在手动升级之前停止正在运行的 Gateway，以避免
从已移除的 keg 加载文件；先备份，并在重启前运行 openclaw doctor --fix。
新建或刷新的服务定义使用 Homebrew 的稳定 opt/openclaw-cli
路径。若要修复仍指向带版本号的 Cellar 路径的服务，请从升级后的 CLI 运行
openclaw gateway install --force。Homebrew 前缀下的全局 npm 包
继续使用 npm。
替代方案：手动使用 npm、pnpm 或 bun¶
下面的 npm 命令适用于 npm 12 或 npm 11.16+。在 npm 11.15 及更早版本中，
省略 --allow-scripts=openclaw。
对于受管安装，请优先使用 openclaw update：它可以协调包
替换与正在运行的 Gateway 服务。如果你在受管安装上手动更新，请先停止受管的 Gateway。包管理器会就地替换文件，否则正在运行的 Gateway 可能会在替换过程中尝试加载核心或插件文件。在包管理器完成后重启 Gateway，以便它加载新安装。
具有安装替换检测功能的 Gateway 还会在其维护周期检查已安装的构建版本。如果正在运行的构建与已安装的构建不同，Gateway 会记录该替换，停止接受新工作，并在移交给其服务管理器之前，为现有活动工作提供其既有的有界关闭窗口。前台 Gateway 会退出，并指示重新运行 openclaw gateway run。在 Gateway 排空期间，Status 和 Doctor 会报告该替换。之后，openclaw gateway status --deep、openclaw update status 和 Doctor 会将记录的替换显示为历史信息，直到下一次 Gateway 关闭。该记录本身并不能确认新 Gateway 是健康的。
如果回复的投递模块在开始发送之前消失，该回复仍符合恢复条件，而不会被当作不确定的发送处理。这种恢复无法防止包管理器就地替换过程中出现的所有故障；较旧且正在运行的 Gateway 也不会通过在其下方安装的文件获得此能力。openclaw update 仍是协调替换的受支持路径。
发布包包含为受支持升级窗口内更新程序的惰性导入而生成的兼容性文件，包括 2026.9.1 服务重启路径。这些文件让旧更新程序在其安装被替换后仍能完成运行。它们不会保留正在运行的 Gateway 的旧模块状态，不会涵盖任意插件导入，也不会让回滚到较旧已发布包在不重启的情况下变得安全。
对于以 root 拥有的 Linux 系统全局安装，如果 openclaw update 因 EACCES 失败，请在保持 Gateway 停止以进行手动替换的同时，使用系统 npm 进行恢复。使用你通常用于该 Gateway 的相同配置文件标志/环境。将 /usr/bin/npm 替换为宿主机上拥有 root 拥有的全局前缀的系统 npm：
下面的 npm 命令遵循相同的版本约定：在 npm 12 或 npm 11.16+ 上使用该标志，在 npm 11.15 及更早版本上省略它。
openclaw gateway stop
sudo /usr/bin/npm i -g openclaw@latest --allow-scripts=openclaw
openclaw gateway install --force
openclaw gateway restart
然后验证：
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 前缀中。候选包会在 preinstall 期间校验宿主机 Node 版本；OpenClaw 会在将干净的包树交换到真实全局前缀之前，验证打包的 dist 清单。待处理的生命周期工作记录在包根目录的 .openclaw-lifecycle-pending 中，位于 dist 清单之外。postinstall 会在完成后移除该标记。如果包脚本被跳过，CLI 会在运行任何命令（包括 --version）之前完成待处理的生命周期；失败会停止该命令并给出重装指引。更新程序会在变更前探测所属的 npm。在 npm 11.15 及更早版本上，它会省略不受支持的生命周期策略标志。在 npm 12 和 npm 11.16+ 上，它只批准候选 OpenClaw 生命周期；传递依赖脚本仍不被批准。
这避免了 npm 将新包覆盖到旧包的过时文件上。如果安装命令失败，OpenClaw 会使用 --omit=optional 重试一次，这有助于原生可选依赖无法编译的主机。当该重试省略了匹配的预编译 fs-safe 依赖时，打包的生命周期会恢复该依赖。它使用已安装的 fs-safe 包声明的版本，且不运行依赖构建脚本。可用的原生绑定无需额外下载。不受支持的主机或下载失败会产生警告并允许安装完成；显式禁用 fs-safe 原生支持也会跳过此修复。
对于 npm 12 上的本地 tarball 目标，归档文件名和每个父目录都不能包含逗号。参见安装程序路径要求。
OpenClaw 管理的 npm update 和 plugin-update 命令还会为子 npm 进程清除 npm 的 min-release-age 供应链隔离（或较旧的 before 配置键）。该策略的存在是为了提供一般性保护，但显式的 OpenClaw update 意味着“立即安装所选版本”。
如果 pnpm 11 安装了 OpenClaw 2026.7.1，请手动运行该命令一次。该版本早于 pnpm 11 的隔离全局包布局，因此其更新程序可能会将另一个 npm 安装误认为正在运行的 CLI。后续版本保留 pnpm 所有权，并在更新期间跟随替换后的包根目录。它们还会使用所属管理器报告的全局 bin 目录，并且当可用的 pnpm 命令报告另一个全局根目录，或调用包是孤立的/不是那里唯一的活动 OpenClaw 安装时，会在变更前停止。
pnpm 12 保留 global/v11 布局；布局编号不必与 pnpm CLI 主版本匹配。
分阶段（staged）的 pnpm 更新同时隔离全局项目及其启动器。OpenClaw 通过 pnpm 10/11 的 CLI 配置和 pnpm 12 的子进程环境配置设置暂存 bin，然后在安装前验证两个目标位置。如果某个管理器仍报告一个活动目标位置，则会在激活前停止更新。
如果 OpenClaw 与另一个包共享一个 pnpm 全局安装组，自动更新程序会在更改该组之前停止。请手动更新原始的逗号分隔组，以保持其同级包和构建策略不变。
--trust 允许 OpenClaw 的生命周期脚本。规范的 openclaw update 路径在拥有安装时应用同样的仅限 OpenClaw 的 Bun 信任。
对于 Bun 拥有的更新，在更新受管服务根目录时，包管理器探测和安装会使用已验证的服务 Bun。否则，当更新程序在 Bun 下运行时，它们使用 process.execPath，并将 PATH 中的裸 bun 仅作为最终回退。缺失或不同的 PATH Bun 不会替换显式选定的可执行文件。包管理器所有权检测不变；在 ~/.openclaw 下找到安装并不会使其成为 Bun 拥有。在 Windows 上，分阶段更新程序会在停止 Gateway 之前拒绝 Bun 安装，因为它无法重新定位 Bun 的二进制启动器。请手动运行 bun add -g --trust openclaw@<resolved-target-version>，然后运行 openclaw gateway restart；使用 openclaw update status 验证。
包生命周期与操作员状态¶
包生命周期钩子会验证 Node 运行时，并且只更新包本地工件：已安装的 dist 树和生命周期标记。插件注册表和操作员状态迁移属于 Doctor，而不是包安装。Doctor 还会移除真正悬空的全局插件运行时链接，但会保留共享和版本化运行时缓存以及指向它们的有效链接：其他安装或配置文件可能仍在使用它们。openclaw update 在安装候选版本后仍会运行 Doctor；手动替换包后，在重启 Gateway 之前运行 openclaw doctor --fix。
在已标记的 Windows 2026.9.4 更新期间，包生命周期还会要求 Doctor 的只读模式预检在激活前拒绝不兼容的共享状态升级。它不会迁移操作员状态。独立包安装不会运行此旧版更新器检查。
新的核心后继续处理会在插件收敛之前运行修复型 Doctor，包括当旧版更新器已经运行过未带 --fix 的 Doctor 时。即使配置本身无需修复，这也会完成待处理的旧版状态。
Doctor 还会将漂移的已启用官方 npm 插件更新到已安装的 OpenClaw 版本，并遵循记录的默认以外标签以及比其插件组更新的固定版本。它使用与 openclaw update 相同的插件更新器，并且不更改第三方插件。不可用的插件会产生带有原因的警告；它不会阻止其他修复完成。恢复注册表访问权限或等待缺失的包，然后重新运行 openclaw doctor --fix。
OPENCLAW_DISABLE_BUNDLED_PLUGIN_POSTINSTALL=1 会跳过包本地 postinstall 清理，但仍会完成生命周期标记。Doctor 迁移保持启用。
Warning
旧版包（包括 2026.8.1）即使在设置了该 postinstall 退出选项的情况下，也可能在安装期间迁移状态数据库。升级前请备份。若要评估受影响的包而不更改正在运行的 Gateway，请使用具有独立 home、config 和 state 目录的一次性环境。仅使用不同的 npm 前缀并不能隔离操作员状态。
卡在 2026.9.3¶
已发布的 2026.9.3 更新器有一个固定的五分钟限制，可能在升级完成前停止升级。目标版本中的超时修复无法替换已在运行的更新器。通过手动包安装一次性绕过该旧版更新器。
首先创建一个已验证的备份。保持相同的服务账户、npm 前缀、配置文件以及 state/config 覆盖设置。在替换包之前，通过其所属的 supervisor 停止 Gateway。对于受管理的 npm 安装：
openclaw gateway stop
npm install -g openclaw@latest --allow-scripts=openclaw
openclaw doctor --fix
openclaw gateway restart
openclaw gateway status --deep
在 npm 11.15 及更早版本中省略 --allow-scripts=openclaw。对于外部 supervisor，请使用其停止和重启命令。Doctor 会保持已停止的 Gateway 处于停止状态，因此在查看其修复结果后完成重启。
自动官方插件漂移修复是在 2026.9.5 之后添加的。如果已安装版本仍打印 修复每个漂移插件，请在重启前运行其打印的 openclaw plugins update 命令。安装后，具有自动漂移修复功能的构建会在 doctor --fix 期间执行这些官方插件更新；任何剩余的就绪警告都会指出仍需要关注的插件。
高级 npm 安装主题¶
只读包树
包生命周期完成后，OpenClaw 在运行时将打包的全局安装视为只读，即使全局包目录对当前用户可写。插件包安装位于用户配置目录下由 OpenClaw 拥有的 npm/git 根目录中，Gateway 启动不会修改 OpenClaw 包树。
某些 Linux npm 配置会将全局包安装在 root 拥有的目录（例如 /usr/lib/node_modules/openclaw）下。OpenClaw 支持该布局，因为插件安装/更新命令会写入该全局包目录之外。
加固的 systemd 单元
授予 OpenClaw 对其 config/state 根目录的写入权限，以便显式插件安装、插件更新和 doctor 清理可以持久化其更改：
磁盘空间预检
在包更新和显式插件安装之前，OpenClaw 会尽力对目标卷执行磁盘空间检查。空间不足会产生包含已检查路径的警告，但不会阻止更新，因为文件系统配额、快照和网络卷可能在检查后发生变化。实际的包管理器安装和安装后验证仍具有权威性。
对于包更新，该检查在注册表查找和数据库模式验证之前运行。受管理的更新运行会将警告保留在更新历史中，因此它也会显示在 Control UI 中。
在暂存替换之前，只读快照检查会测量已知的 SQLite 数据库族，包括 WAL、SHM 和 journal 文件。它在 openclaw update status --json 中的非警告诊断条目会记录每个族的大小以及现有快照预算：总族字节的两倍、最大族的三倍，以及元数据的 64 MiB。插件副本和已注册的外部数据库在暂存后的完整检查之前仍未知。
快照空间会在现有目标位置检查：TMPDIR、state 目录旁边的 capture 目录以及系统临时目录。只有当每个目标位置的已知可用空间都低于快照所有者的要求时，更新才会在暂存前拒绝，因为其私有状态副本无法创建。数据库大小是临时快照的清单，而不是数据库健康或增长警告。检查成功无需清理数据库。如果测量失败，更新器会警告将在暂存后再次检查。可用的替代方案或未知的可用空间读数本身不会阻止更新。已经是最新状态的包和 Git 目标无需候选快照。更新器保留的是配置副本，而不是完整状态备份。
此检查在已安装的更新器中运行；已安装的 2026.9.3 更新器在其自身首次升级跳转中保持原有行为。
本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw