更新方法
安装类型切换、源服务器参考脚本、安装程序以及手动包管理器更新。属于 更新 指南的一部分。
在 npm 与 git 安装之间切换¶
安装程序驱动的切换会在正在运行的所有者退役之前验证替换版本。源包装器以原子方式发布;同路径 npm 垫片转换使用经过身份校验的备份,该备份在失败时恢复,因此失败的后选版本仍可让先前的命令保持可运行。在退役旧的源包装器之前,更新程序会重新检查其身份和内容,并确认它仍然拥有该更新。openclaw update 命令仅在核心后收敛以及所请求的重启健康检查成功之后,才会打印最终的成功结果。
候选版本验证失败时,旧 Gateway 会继续提供服务。激活之后,只有当共享的以及受影响的、预先存在的按代理数据库 schema 版本保持不变,并且自候选版本激活时的 Doctor 检查通过以来配置未发生变化,包恢复才能还原所保留的先前包。由候选版本首次创建的数据库,只有在其支持该数据库种类的 schema 版本下才是中性的。被还原的 Gateway 必须通过相同的运行时检查,恢复才会报告为完成。schema 迁移会阻止自动包回滚;替换代码无法撤销已迁移的状态。不完整的文件回滚会保留其备份以供检查。参见 自动回滚。如果较旧的目标不支持保留服务定义,自动恢复会停止并报告错误,而不会使用较弱选项重试。修复报告的错误,重新运行 openclaw update,并检查 openclaw gateway status --deep。参见 更新失败恢复。
在 macOS 上,如果因更新中断后 Doctor 报告某个已安装但未加载且已禁用的 Gateway LaunchAgent,请先完成更新验证或 Doctor 检查并进行分流。然后使用打印出的 openclaw gateway start 命令,并保留其配置文件、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 频道使用包安装。在 git checkout 上,extended-stable 会被拒绝,而不会对其进行修改或转换。如果 gateway 已安装,openclaw update 会刷新服务元数据并重启它,除非你传入 --no-restart。
自动的包到 Git 转换目前需要 npm 拥有的包符号链接。由 pnpm 或 Bun 拥有的安装会在停止 Gateway 之前拒绝 --channel dev;当需要更改该安装的所有者时,请使用 Git 安装程序。正常的包到包更新会继续使用 pnpm 或 Bun。
Git 更新会在一个临时候选工作树中构建完整的运行时,包括插件和 Control UI。Dev 更新通过在构建前对候选版本进行 rebase 来保留本地提交。更新程序会在激活期间发布该已准备好的运行时,而不是在停止状态下重复构建。它保留构建时间戳,因此普通 CLI 命令会继续使用该已验证的运行时,而不会在移动后重新生成它。
候选安装和嵌套构建命令使用私有的 pnpm 虚拟存储,因此准备更新不会剪除正在服务的 Gateway 所使用的依赖。在检查源更改之前,候选版本的临时工作区设置会被还原;活跃 checkout 的工作区设置会被保留。
候选命令在 PATH 上的 Node 提供程序中保持符合条件的 Node 优先,同时保留仅启动器前缀(如 scoped pnpm 垫片)位于其前面。这也适用于所选 Node 目录已在 PATH 中的情况;其包管理器可执行文件不会取代这些 scoped 启动器。
在激活包或 Git 更新之前,更新程序还会检查可发现的、共享同一物理安装的受管 Gateway。如果观察到存活的兄弟实例,则在所选 Gateway 停止之前阻止更新;更新程序会在发布时再次检查。通过其自身的服务管理器或确切的 Startup 条目停止该兄弟实例,然后重试。更新程序不会停止或重启兄弟服务。包的 --no-restart 仍允许所选服务保持运行,但该例外不涵盖使用相同文件的另一个服务或 Startup 条目。Gateway 的安装变更监视器仍可将其重启。如果更新 Doctor 维护停止了所选服务,则完成阶段会还原匹配的服务并报告维护重启,包括使用 --no-restart 的情况。如果无法检查其当前身份,恢复将保持待处理状态。
这是对已观察到的使用者的检查,而不是锁定以防止新服务启动;无法进行检查并不能证明该安装没有使用者。已运行的旧版更新程序会保留其自身的激活和完成行为。
对于在不同根目录下拥有受管 Bun Gateway 的包安装,openclaw update 以 Gateway 的包根目录为目标,并使调用 CLI 的安装保持不变。它会验证服务的实际 Bun 可执行文件是否为 Bun 1.4+ 且支持 WAL 安全的 node:sqlite,并在服务安装和重启期间保留其记录的运行时固定版本。Bun 模拟的 Node 版本永远不会与目标的 engines.node 要求进行比较。当更新程序在 Node 上运行时,其 Node 也必须通过目标的引擎和 SQLite 检查之后才能替换包,因为完成阶段在更新程序运行时下执行。
Node 服务保持现有路由:可写的自有定义通常会移至调用 CLI 的安装;Windows、被覆盖或不可写的定义,以及 --no-restart 保留 service-root 路由。所选 Node 必须满足目标版本的 engines.node 要求。有关所有权检查和旧版更新程序限制,请参阅托管服务更新。
源码检出服务器(参考脚本)¶
在手动重建源码检出之前,停止所有为其提供 dist 文件的 Gateway。构建入口点会检查可发现的受管 Gateway(包括同级配置文件),当有活动服务共享该输出时拒绝构建。在 systemd 上,这包括主 PID 退出后仍留在服务 cgroup 中的进程。请使用正在运行的 Gateway 的 agent 会话之外的外部终端。按照报告的服务/配置文件停止命令执行,重建,然后启动这些相同的服务。对于默认配置文件,请从源码检出目录运行以下命令:
在构建前停止所有列出的同级服务,并在之后逐个启动它们。保留其配置文件及自定义服务覆盖,或使用匹配的原生服务命令。对于列出的 launchd 任务,请使用其命名域、任务和已加载的 plist 来选择相应控制;仅凭配置文件名称可能对应不同的定义。仅限 Startup 的同级服务必须按照确切的 Startup 文件指引停止,并通过同一个 Startup 条目重新启动;更新所选服务无法停止该同级服务。仅在构建成功后才启动服务。如果此检出的构建好的运行时缺失且 CLI 无法运行,请在重建前使用这些原生控制。默认情况下,源码运行器的 gateway stop 和 gateway restart 使用现有已构建的 CLI,因此恢复不会先重建。要应用源码更改,请使用上述停止、构建和启动顺序。openclaw update 可以应用可用更新,但 skipped / already-current 不会重建过期的 dist;在这种情况下,请使用外部停止、重建和启动顺序。
具有独立输出的单独候选检出可以在已安装的 Gateway 继续服务的同时进行构建。此检查观察当前服务;它不会阻止服务在编译期间启动,且无法进行检查并不证明没有 Gateway 在运行。
发现机制使用已安装的服务定义和调用的服务选择器。裸 systemd 模板会针对当前操作系统账户进行检查。没有已安装实例定义或显式选择器的其他活动模板实例不会被枚举。在构建前,请使用其原生服务命令停止这些实例。发现的 macOS LaunchDaemons 在 system 域中检查;全局 LaunchAgents 保留在调用用户的 GUI 域中。此观察不会授予更新程序对系统 LaunchDaemon 的控制权。
在服务器上直接从 git 检出运行网关的团队,可以在该检出目录内使用 scripts/update-gateway.sh 进行更新。它是源服务器更新的参考:它拒绝已跟踪的本地更改(包括构建输出),并在私有检出中准备获取到的目标。它检查 main 是否可以快进,或使用 --rebase-merges 对本地服务器分支执行 rebase。依赖项使用冻结的 lockfile 安装,候选版本在服务检出变更之前构建。准备失败时,现有服务会保持运行。准备完成后,脚本停止其选定的服务,并在发布源码、依赖项和生成的输出之前检查其他观察到的受管消费者。请先通过它们各自的服务所有者停止任何共享安装的同级服务;此脚本不会为您停止或重启它们。消费者检查先于第一次源码更改;它不会在源码和运行时发布期间阻止新的服务启动。
与 openclaw update 类似,该脚本默认构建运行时 JavaScript、插件资源和 Control UI,而不生成 TypeScript 声明。如果此检出还需要新的声明用于插件开发,请在调用脚本时设置 OPENCLAW_RUN_NODE_SKIP_DTS_BUILD=0。
此参考脚本需要 Corepack,并在获取之前在无全局激活的情况下创建临时 shims。获取后,它会冻结目标提交,并检查其确切的 pnpm 固定版本能否通过那些 shims 在私有检查工作区中运行。该检查仅包含包管理器元数据,不包含目标的依赖项、钩子或配置。元数据缺失或无效、供应失败或版本不匹配会在检出更新或重启之前停止;修复目标固定版本或安装兼容的 Corepack,然后重试。
相同的获取提交用于快进或 rebase。结果候选版本的 pnpm 固定版本会被单独检查,因此本地分支覆盖仍然生效。相同的作用域 shim 目录引导嵌套命令的 PATH,每个操作使用其自己的工作区和 lockfile 根目录。已接受的未跟踪构建输入会被复制到候选版本中,并在发布前再次检查。在检出内解析的引用遵循候选版本的相应文件。真正的外部链接仍是操作者所有的引用:其目标身份会被检查,但外部目录内容不会被递归冻结。保留的运行时事务目录仍是恢复材料,并在重试时从候选构建输入中排除。
如果在停止服务后发布失败,脚本会在重启之前恢复并验证先前的 Git 修订版以及保留的依赖项/输出。它会保留原始失败信息。配置和外部操作者数据不在此运行时事务范围内。已更改的源码或未经验证的子进程清理会阻止破坏性恢复;保留的路径会被报告以供检查。如果验证过的新运行时重启失败,该运行时会保留在原位,因为新进程可能已在使用它,并且先前的工件仍可供操作者恢复。失败的自动调用也会保留其小型作用域 pnpm 启动器目录;仅在所有更新子进程停止后,才删除所报告的目录。托管的安装程序在 Corepack 不可用时也支持 npm 拥有的临时供应;此服务器脚本特意要求 Corepack。
Warning
正在运行的旧更新器或服务器脚本会保留其旧的引导代码,即使它检出了包含此修复的文件。如果该旧入口点调用了环境中的 pnpm,操作员必须在跨越固定版本变更的第一次更新之前,选择一个与目标兼容的 pnpm 启动器。在开始更新之前,请针对预期目标和已知良好的回滚 ref 验证该启动器。仅更新目标文件并不能修复正在运行的旧二进制文件。
已在运行的 source-server 脚本如果调用旧的三参数构建适配器,仍会负责其先前的 Git 和依赖变更。该兼容性路径保留其仅输出恢复;加载较新的适配器无法将旧 shell 已完成的安装移到停止边界之后。
已发布的 2026.9.4 source-server 脚本也会在其最终重启之前进行构建。候选构建入口点仅当所选的、由原生所有者管理的 Gateway 正在提供此检出的物理 dist 时,才会识别其现有的更新标记。现有的 source-build 事务会在写入之前停止该 Gateway。在已确定的构建失败时,它会恢复先前的输出,并通过其原生所有者重启所选服务,同时保留其定义并重新检查其绑定。原始构建失败仍然可见;自定义 shell 重启命令仅在旧调用方中构建成功后运行。单独的候选检出或仅同级匹配永远不会授予停止其他服务的权限。如果该原生停止部分成功然后失败,候选会重新验证,并通过其原生所有者重启原始服务,而不运行自定义 shell 命令或启动构建。原始停止失败仍会被报告,包括任何未能完成恢复的失败。
对于该第一跳,旧脚本仍拥有其一次成功重启,包括已编写的自定义重启命令。其空或仅包含空白的重启设置仍为手动,并且不会触发自动停止。旧脚本无法接收候选进程的恢复状态:在构建成功后,候选会确定原生自动启动,并在返回之前弃用其构建备份。因此,随后旧脚本的重启失败需要操作员恢复;它不会获得较新脚本的保留备份保证。未加入的构建写入器或失败的输出恢复会使 Gateway 保持停止状态,并保留恢复材料。
生成的输出根目录(例如 dist、dist-runtime 以及包本地 dist 目录)必须是真实目录。构建会在读取或修改其内容之前拒绝符号链接根目录,以便清理不会影响链接目标。在更新或构建源检出之前,请将输出根符号链接替换为真实目录。
默认停止命令是 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,然后在解决任何故障后自行重启它。在此模式下,不要同时设置停止覆盖。 脚本不会执行自动停止、重启或构建输出回滚:
对于普通的单用户源安装,请优先使用 openclaw update --channel dev——它会为你管理检出、构建和 Gateway 重启。
替代方案:重新运行安装程序¶
添加 --no-onboard 以跳过入门引导。若要强制指定特定安装类型,请传递
--install-method git --no-onboard 或 --install-method npm --no-onboard。
如果 openclaw triage 在 npm 包替换失败后无法启动,请重新运行安装程序。它会直接运行全局包安装,并且可以恢复部分更新的 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 失败,请使用系统 npm 进行恢复,同时保持 Gateway 停止状态以进行手动替换。请使用您通常用于该 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 包声明的版本,并且不运行依赖项构建脚本。修复在 Node 和 Bun 上有效,并保留任何现有的原生包。正常工作的原生绑定不需要额外下载。不受支持的主机或下载失败会产生警告并允许安装完成;显式禁用 fs-safe 原生支持也会跳过此修复。
对于 npm 12 上的本地 tarball 目标,归档文件名和所有父目录必须不包含逗号。请参阅安装程序路径要求。
OpenClaw 管理的 npm update 和 plugin-update 命令还会为子 npm 进程清除 npm 的 min-release-age 供应链隔离(或较旧的 before 配置键)。该策略旨在提供通用保护,但显式的 OpenClaw 更新意味着“立即安装所选版本”。
如果 pnpm 11 安装了 OpenClaw 2026.7.1,请运行一次该手动命令。该版本早于 pnpm 11 的隔离全局包布局,因此其更新器可能会将另一个 npm 安装误认为是正在运行的 CLI。后续版本保留 pnpm 所有权,并在更新期间跟随替换包根目录。它们还使用所属管理器报告的全局 bin 目录,并在可用 pnpm 命令报告另一个全局根目录,或当调用包成为孤立包或不是该处唯一活动的 OpenClaw 安装时,在变更之前停止。
pnpm 12 保留了 global/v11 布局;布局编号不需要与 pnpm CLI 主版本号匹配。分阶段的 pnpm 更新会隔离全局项目及其启动器。OpenClaw 通过 CLI 配置为 pnpm 10/11 设置暂存 bin,通过子进程环境变量配置为 pnpm 12 设置,然后在安装前验证这两个目标位置。仍然报告活动目标位置的管理器会在激活之前停止更新。
如果 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 还会移除真正悬空的全局插件运行时链接,但会保留共享和版本化运行时缓存以及指向它们的有效链接:其他安装或 profile 可能仍在使用它们。openclaw update 在安装候选版本后仍会运行 Doctor;在手动替换包后,请在重启 Gateway 前运行 openclaw doctor --fix。
在标记的 Windows 2026.9.4 更新期间,包生命周期还会要求 Doctor 的只读 schema 预检在激活前拒绝不兼容的共享状态升级。它不会迁移操作员状态。独立包安装不会运行此旧版更新器检查。
新的核心后继续流程会在插件收敛前运行修复型 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 前缀、profile 和 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 之后添加的。如果已安装版本仍打印 Fix each drifted plugin,请在重启前运行其打印的 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 会尽力对目标卷执行磁盘空间检查。空间不足会产生包含已检查路径的警告,但不会阻止更新,因为文件系统配额、快照和网络卷可能在检查后发生变化。实际的包管理器安装和安装后验证仍具有权威性。
对于包更新,该检查在注册表查询和数据库 schema 验证之前运行。受管理的更新运行会将警告保留在更新历史中,因此它也会显示在 Control UI 中。
在暂存替换之前,只读快照检查会测量已知的 SQLite 数据库族,包括 WAL、SHM 和 journal 文件。它在 openclaw update status --json 中的非警告诊断条目会记录每个族的大小以及现有快照预算:总族字节的两倍、最大族的三倍,以及元数据的 64 MiB。插件副本和已注册的外部数据库在暂存后的完整检查之前仍未知。
快照空间会在现有目标位置检查:TMPDIR、state 目录旁的 capture 目录,以及系统临时目录。仅当每个目标位置的已知可用空间都低于快照所有者的要求时,更新才会在暂存前拒绝,因为其私有状态副本无法获取。数据库大小是临时快照的清单,而不是数据库健康或增长警告。检查成功无需清理数据库。如果测量失败,更新器会警告说它将在暂存后再次检查。可用的替代方案或未知的可用空间读数本身不会阻止更新。已经处于最新状态的包和 Git 目标无需候选快照。更新器保留的是配置副本,而不是完整状态备份。
对于直接 CLI 更新,由调用操作者设置的临时变量(TMPDIR、TMP 和 TEMP)优先于托管服务默认值。例如,TMPDIR="$HOME/.cache" openclaw update 会首先检查该目录,并在快照容量报告中将其标记为 explicit-tmpdir。服务仍负责安装、配置文件、状态和运行时路径选择。此优先级修复属于已安装的更新器,并会在其安装后执行的更新中生效;较新的候选版本无法更改较旧更新器的环境合并。
此检查在已安装的更新器中运行;已安装的 2026.9.3 更新器在其自身的第一次升级跳转中会保留先前行为。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw