Cloud worker 预热镜像

OpenClaw 如何在注册前捕获已准备的项目和节点运行时，将该镜像复用于后续工作节点，以及如何恢复不明确的捕获。

预热镜像¶

Crabbox 插件会在预热镜像操作之前自动准备其支持的 CLI。其配置的 CLI 版本探测允许 30 秒（包括在繁忙的 Gateway 启动期间），然后才尝试受管回退。请保持固定的租约 ID：它可以在派发重试时防止重复分配。

预热镜像和用于镜像捕获的项目准备仅限 Linux。

在 Linux 上，当从 settings.class 或放置（placement）的 machineClass 得知某个类时，预热镜像默认开启，除非配置文件声明了非空的 setupEnv。如果没有有效类且没有显式的 warmImage，则预配保持冷态，无需 warmImage: false。放置覆盖项会在选择此默认值之前解析。macOS 和两种 Windows 模式始终以冷态预配，即使共享配置文件启用了 warmImage；Linux 镜像设置绝不会阻止原生操作系统的选择。

转发的主机环境值会到达 setup，因此 setup 从中衍生的任何内容都可能持久化在共享镜像中。具有非空 setupEnv 的配置文件只有在显式设置 settings.warmImage: true，并检查确认 setup 不会在磁盘上留下任何凭据之后，才会进行捕获。显式的 true 要求在任何提供方命令之前存在已知的已配置类或放置类。显式的 false 始终使预配保持冷态，例如当不需要快照存储费用或提供方保留仓库内容时。

对于带有 Git 提交的 Gateway 工作树项目，捕获发生在预配期间、节点注册之前。配置文件设置之后，OpenClaw 准备所接受提交的全新检出，并且当派发调用方授权设置时，在最终的工作空间和 HOME 路径下运行其已提交的可执行文件 .openclaw/worktree-setup.sh。它会安装经过验证的节点运行时，并在需要镜像时捕获完整的环境。显式的设置跳过会使用单独的已准备缓存；如果没有设置权限，可执行脚本会保留现有的 Git 种子路径。首次派发包含该工作；后续会话可以复用该镜像，而无需等待首次会话停止。会话编辑、符合条件的未跟踪文件以及节点注册凭据仅在捕获之后到达。仅仓库会话使用相同的准备流程：OpenClaw 通过 GitHub 解析仓库实例、提交和可执行设置脚本。公共来源会在工作节点上获取该确切提交，无需凭据。私有来源会将经过身份验证的 Git 对象获取到临时 Gateway 存储，然后传输经过验证的 Git pack；此准备步骤绝不会将 GitHub 凭据放入提供方脚本、工作节点文件或快照中。Gateway 不会为此传输创建受管检出，也不会运行项目设置。没有项目准备的提供方在注册后会保留普通检出。

私有准备需要临时 Gateway 磁盘空间来存放浅 Git 对象和出站 pack。现有的 4 GiB pack 限制适用于所传输的工件；它不会限制 Git 在生成该 pack 之前下载的字节数。Fetch 使用有界的命令超时，临时文件会在所属工作完结后（包括取消时）被移除。

当传输的项目没有可执行设置脚本，或者设置被显式跳过时，种子传输也会在同一个远程命令中完成已准备的工作空间。可执行脚本在执行前会进行单独的当前权限检查。运行时安装和凭据清理也会在项目捕获前共享一个远程命令；快照创建仍会等待两者成功完成。如果任一步骤失败，派发会在注册前停止不完整的工作节点并报告错误。

本地项目准备保留主 Git 仓库作为其传输源，包括一个支撑链接检出的裸主仓库。它会保持已接受的会话提交固定，因此归档和删除链接的会话检出不会阻止储备补充，也不会选择主检出较新的 HEAD。会话文件同步仍使用会话检出。

项目镜像还会在已安装的运行时包中保留一个经过验证的压缩 worker 归档，位于节点身份和会话状态之外。匹配的新节点会使用这些字节，而不是再次下载 worker 归档。它仍会正常注册，并解压和验证自己的安装。OpenClaw worker 轮次会在能力足够的节点上预热 worker 运行时；Codex 远程执行会跳过该未使用的启动。如果 Gateway 请求不同的归档，节点会使用正常的经过身份验证的下载；存在但已损坏或不安全的已准备归档会使安装明显失败。准备替换归档会在捕获前移除已被取代的已发布归档。精简节点运行时归档不包含独立 worker 有效负载。

Daytona 要求文件系统快照使用已停止的源。OpenClaw 允许 Crabbox 停止已清理的 worker 以进行捕获。成功的捕获会等待快照完成，并在项目注册继续之前恢复先前正在运行的源。

镜像复用以后端、设置命令、排序后的 setupEnv 变量名（不是其值）、桌面设置、有效操作系统、精确的有效机器类，以及（如果存在）项目身份作为键。项目身份来自 Gateway 的命名空间和规范共享 Git 目录。来自同一仓库的链接会话工作树共享该身份；新会话或新提交不会创建另一个项目身份。不同的仓库克隆具有不同的身份。已准备的仓库身份包括规范 URL、GitHub 仓库 ID、当前代理绑定、所选共享 GitHub 账户/个人资料或经显式验证的匿名访问，以及一个用于私有内容的单独作用域。Token 绝不会持久化在该身份中。每个已准备的种子还会记录其确切提交，因此更改过的提交可以刷新同一项目的镜像。

在发出该租约的首次提供者分配命令之前，OpenClaw 会记录租约是以冷启动开始，还是从特定检查点开始，以及其解析出的操作系统和类别。重试和 Gateway 重启都会复用该确切选择；丢失的响应无法将冷分配切换为新可用的镜像，也无法选择不同的检查点。该记录会在准备和注册过程中推进，并且在提供者确认租约已停止之前，所选检查点仍受保护，不会被删除。失败的 fork 会报告错误，而不是静默更改已记录的分配。该分配的运行时身份也会被冻结。重放会拒绝已更改或缺失的身份，而不是重新标记现有工作器；在创建新分配之前先停止重放。较旧的分配不能仅仅因为运行时摘要不同，就替换来自不同来源代发布的镜像。

热镜像通过 Crabbox 的 --strategy image 在 machine0 上工作；其他后端保留其原生检查点策略。OpenClaw 使用 Crabbox 已验证的 fork 就绪结果来确定后端特定的镜像状态，包括 Machine0 的 ACTIVE 状态。未固定的项目镜像会在后台预留或显式构建准备期间，在请求的提交发生变化时刷新。已 fork 兼容镜像的前台会话会准备其新提交，而无需等待替换捕获。运行时更改、初始准备、中断的捕获重放和基于期限的刷新均保留其现有的捕获检查；refreshAfter 默认为 24 小时。非项目镜像会在运行时更改时，或超过该间隔后，在下一个符合条件的工作器停止时刷新。运行时身份包括节点归档摘要、执行模式，以及当该归档包含在镜像中时的工作器归档摘要。未记录运行时身份的镜像会在同一捕获边界处刷新。较旧的兼容镜像仍是可用的设置基础：第一个会话安装当前运行时，然后将其捕获，以便后续会话可以复用该安装。

当前镜像在整个捕获过程中保持已记录且可用。默认情况下，OpenClaw 在同一配置文件记录中以原子方式记录替换及其前代的删除义务，然后在没有任何分配仍需要前代时删除前代。使用 keepPrevious: 1 时，它会将前代保留为 Previous 以用于回滚，并首先让更早的上一代退役。无论 keepPrevious 如何设置，固定的前代都会被保留；现有的固定上一代永远不会被删除以腾出空间。如果当前代和上一代都被固定，OpenClaw 会跳过替换发布，并就单一固定上一代的限制发出一次警告。取消固定其中一个检查点即可允许该替换。删除失败会发出警告，在 Gateway 重启和热复用后仍会保留，并在定期维护、后续捕获维护或支持热镜像的工作器拆除期间重试。该配置文件的进一步刷新会等待删除成功；替换 fork 和租约拆除会继续进行。

分配选择不会重试保留的删除，也不会等待它们完成，包括其他配置文件的删除。在前代等待删除期间，它仍可选择可用的替换。如果当前镜像本身正在退役，新的分配会选择冷置备。普通过期和缺失镜像清理仍可在分配期间运行；保留的删除重试会在捕获、拆除或定期维护期间共享一分钟的维护预算。

OpenClaw 会在 retainUnused（默认 14 天）之后删除未使用且未固定的镜像，并在接纳第 129 个配置文件记录之前回收最近最少使用的符合条件的镜像。回收容量时，它首先让符合条件的上一代退役。当前代和上一代共享一个配置文件槽位；仅删除上一代并不会释放该槽位。提供者删除必须成功，之后才能移除其所有权记录。固定、待处理的捕获、退役和未完成的分配会保留其槽位；退役还会等待使用该检查点的分配停止。如果所有 128 个槽位均被保留，新的热镜像分配将失败，并附带清理指引。每个配置文件记录最多接纳 256 个未完成的分配，并拥有其当前镜像、一个可选的上一代，以及最多一个捕获或退役操作。容量回收永远不会驱逐重试选择或清理义务。

只要 Crabbox 保持启用且配置了工作器配置文件，Gateway 的现有维护循环大约每分钟也会检查一次未使用的镜像，即使没有剩余工作器。清理独立于分配运行，会重试保留的删除，并且不会延长镜像的最后使用时间。Gateway 关闭和插件重载会在其所有者停止之前，取消并排空活动中的清理命令。维护会按固定顺序通过每个不同的已配置可执行文件尝试删除，并且只有在删除成功或每个可执行文件都报告检查点不存在后，才会释放记录。删除错误会保留该记录以供稍后重试。自动清理不会重新激活已移除或已禁用的提供者。

在捕获之前，OpenClaw 会移除每个租约的工作器身份、设备令牌和会话状态，包括 ~/.openclaw-worker/workspaces 下的节点宿主工作区和 SSH 传输工作区。机器级缓存有意保留：npm 缓存、~/.openclaw-worker 下以内容寻址的节点运行时和工作器捆绑包安装，以及 ~/.openclaw-worker/git-seeds 下的原始 Git 种子。项目准备从不可变的 Git 内容开始。已完成的设置可能会保留被忽略的依赖/构建输出，并更改符合条件的源文件；OpenClaw 会分别维护原始清单和已完成清单。一个新的专用节点会验证该完成状态，并将固定工作区和 HOME 绑定到单个会话。初始项目同步将相对于原始提交的会话更改应用到已完成的设置上，同时保留设置生成的文件以及会话未更改的受跟踪设置编辑。在发生更改的路径上，会话编辑优先。一轮之后，协调会将符合条件的生成输出带回 Gateway。已接受的协调结果和显式检查点恢复会应用其确切快照，包括删除设置生成的文件。其他会话不能声称拥有该绑定，退役会留下永久墓碑标记，即使工作区文件已被移除。镜像还会保留 settings.setup 写入其他位置的任何内容，因此请保持设置无凭据，并且仅对相互信任的工作负载启用复用。

清理操作有三分钟超时。检查点创建会要求 --wait --wait-timeout 2700000ms，这与 Crabbox 在注册前的 45 分钟原生捕获预算一致。在 Daytona 上，源准备和停止操作与快照创建及就绪检查共享该预算。一次成功等待的捕获会被记录为可用，并可在无需再次进行可用性检查的情况下复用。命令截止期限会额外增加三分钟作为命令开销，并加上独立的源生命周期时间：Daytona 恢复三分钟，或两个默认 15 分钟的 Machine0 停止/恢复窗口。预配和拆除的截止期限也涵盖捕获维护、清理和子进程收尾。这些限制不会给予另一次捕获尝试的机会。清理失败只会释放其自身的捕获预留。一旦创建开始，失败、超时或不可用输出都会使其结果不确定：该 profile 会保持暂停，直到显式恢复。例外情况是 Crabbox 为同一提供方和租约返回的、完整且正常退出的 not_submitted 失败回执，它确认其本地预留已被移除。OpenClaw 随后只清除该捕获预留。预配仍然失败并停止源租约，因为该回执并不能证明源回滚成功。可选的拆除捕获会发出警告，而不会使成功的源租约清理失败。未解决的项目捕获会阻止在该源上进行节点注册，因此新的节点凭据无法进入可能仍在运行的捕获。租约清理仍会运行，而保留的可用镜像可服务于新的分配。捕获需要支持固定 ID 检查点分支的 Crabbox CLI 和后端。要继续处理协调器保留的 checkpoint_pending 响应，需要 Crabbox #1698 中的 CLI 修复；旧版二进制文件可以接受 --wait，但仍会在该响应上失败。在恢复不确定的捕获之前，请先修正缺失的能力或权限。

热启动会分配一个全新租约，并进行全新的节点注册。冷分配和快照分支使用相同的已配置租约生命周期、空闲超时、桌面设置，以及不使用 Tailscale 的公网连接。热启动复用机器级缓存，而不是每会话快照或挂起进程。

项目准备会在构建或上传 Git pack 之前，检查是否存在已验证的完整检出和原始种子。其串行化的注册前操作会一次性验证保留的 Git 对象和工作区内容，然后在后续阶段之前重新检查确切的完成证明和 Git 身份。该观察结果绝不会被持久化，也不会被新操作复用；设置过程会在变更之前使完成状态失效，节点注册会独立验证最终工作区。复用同一提交会跳过克隆和设置过程。已更改的 Gateway 项目提交会通过精简 Git 传输刷新现有检出，移除过时的符合条件的设置输出，并重新运行其已接受的配方，同时保留兼容的忽略缓存和绝对路径。新提交中的被跟踪路径优先于冲突的缓存文件或目录；无关的忽略缓存和准备好的 HOME 保持不变。如果 Gateway 在重写历史后对先前提交执行了垃圾回收，它会传输当前提交的完整快照，同时保留已验证的远程工作区和缓存。完成状态在变更之前即失效，因此被中断的设置过程无法宣告就绪，也无法静默重新运行。在注册前，重放已分配的已准备 worker 时，如果它仍拥有当前源镜像，则会保守地捕获其已完成的设置过程。如果一次已完整的热复用（warm reuse）在注册前被中断，则可能额外产生一个快照；已发布的替换镜像和已注册会话的重放不会再次捕获。已注册的预配重试只会检查原始的完成证明；它绝不会运行设置过程，也不会捕获会话。已绑定会话的重启会通过存储的绑定保留用户的编辑内容。没有完成检出的放置操作保留现有流程：将种子的 Git 对象复制到新仓库，重建其 Git 元数据，并应用当前符合条件的文件清单。匹配的种子会跳过从 origin 拉取和完整 Git pack 下载，即使提交是私有或未发布的也是如此。缺少种子时使用 Gateway pack；无效的已准备种子会明确失败。没有已准备项目的工作区保留符合条件的 origin/种子路径。Gateway 仅按需构建传输包，并且每次传输都保留其原始基础提交，即使本地提交后续发生变化。

保留策略¶

在 plugins.entries.crabbox.config.warmImages 下设置插件级策略，或使用 快照 中的 保留策略 卡片。保存会重新加载 Crabbox 插件，而无需重启 Gateway。worker 租约生命周期和 128 个 profile 的容量上限保持不变。

时长值接受一到八位数字后跟一个单位，例如 90m 或 14d；组合时长和小数时长无效。

{
  plugins: {
    entries: {
      crabbox: {
        config: {
          warmImages: {
            refreshAfter: "24h",
            retainUnused: "14d",
            keepPrevious: 1,
          },
        },
      },
    },
  },
}

已固定的检查点不受基于时长的刷新、未使用过期、容量淘汰和替换退役的影响。对于已准备的项目镜像，固定操作会让检查点保持可用，但运行时或配方变更仍会冷启动新的 worker，直到有兼容的捕获发布。其他分配兼容性规则也保持不变。同一 profile 记录的较新捕获会将固定的当前检查点移至 上一代，即使 keepPrevious: 0 也是如此；回滚可以将其恢复。取消固定会在下一次维护轮次或捕获边界恢复常规策略。上一代镜像在不使用时可以过期，将 keepPrevious 降至 0 允许它们退役，除非已固定或仍被某个分配持有。

就绪工作器¶

打开 设置 → 连接 → 云工作器 → 池 以检查正在运行的已准备工作器。该视图按配置文件对工作器分组，并显示就绪、准备中、释放中和需关注计数、项目和已准备的提交、过期时间以及记录的失败。容量包括准备中和未确认的清理；已消耗的工作器会离开此视图，除非待处理清理仍预留容量。当视图可见时，清单每 10 秒刷新一次。刷新失败会保留最后一次结果可见并显示警告。配置文件选项卡控制预留目标和共享池上限；快照管理可复用的磁盘镜像。

池详情需要当前管理员访问权限。API 客户端在 environments.list 或 environments.status 上使用 includePreparedDetails: true 请求它们；默认响应为旧客户端保留现有清单结构。

对于符合条件的本地 Git 项目或仅仓库会话，成功的会话激活可以在后台为下一个会话准备专用工作器。默认目标是每个项目和配置文件一个未分配工作器，Gateway 全局上限为 4。下一次匹配的调度会一次性消耗一个就绪工作器，然后安排补充；如果没有符合条件的工作器就绪，调度将使用普通配置。配对设备调度不使用此池。仓库准入、补充和重启绑定会重新检查当前源访问权限和可见性。公共仓库和私有仓库使用不同的准备身份；可见性变更或访问权限丢失会阻止复用先前准备的容量。保留和清理使用本地所有权事实，无需 GitHub 访问。变更的仓库实例或所选账户无法消耗为先前所有者准备的容量。 命中就绪工作器会绕过配置。前台未命中时，如果可用，会从兼容镜像配置一个工作器。如果只有项目提交变更，它会刷新检出并继续注册，而无需等待新快照；后台预留或显式构建可以发布该刷新后的镜像。首个镜像和不兼容准备仍遵循现有捕获要求。禁用预留也会禁用此自动后台刷新。

按需构建。 调用 environments.prepare 并传入 { profileId, projectPath } 和 operator.admin 范围，可在没有会话的情况下准备本地 Git 检出的 HEAD。配置文件必须支持项目准备。这会授权已提交的项目设置配方，并返回 { environmentId, preparationKey, reused }；匹配的实时、未消耗构建或预留会被复用。未完成的预留会变成构建，而不会续期其过期时间。当 readyWorkers 为零时，构建可以完成，但准入仍需要 preparedPool.maxTotal 下有空间。就绪后，普通预留策略会保留它，或在下次池遍历时将其作为多余资源退役。其需求会启动正常的补充和提供商空闲超时窗口。在 environments.list 或 environments.status 中跟踪其 preparation: { purpose, key }；environments.destroy 会取消它，并等待提供商工作稳定且清理完成。同一命令会取消未使用的自动预留，包括已过期的预留。

设置 cloudWorkers.profiles.<id>.readyWorkers 以更改每个项目的目标，设置 cloudWorkers.preparedPool.maxTotal 以更改共享上限。零会禁用相应预留并排空未使用容量，而无需重启 Gateway，同时保留活动会话和镜像复用。准备中的工作器和等待确认清理的工作器计入限制。就绪工作器会产生运行机器费用，直到提供商确认删除。在确认分配清理后，失败的准备会记录其原始错误并结束该准备。任何后续符合条件的补充都会启动新分配。不确定的清理会保持工作器计入，直到提供商确认释放。

每个预留从创建其需求的成功激活或显式构建开始过期，使用提供商现有的空闲超时。补充和 Gateway 重启不会延长该窗口。已准入的捕获可以在过期后于其提供商预算内完成，同时其工作器仍被计入。过期会阻止后续注册、就绪和消耗；清理遵循已确定的捕获托管。提供商 TTL 和空闲超时设置保持不变。失败的调度不会创建新需求。认领工作器和分配其放置提交是同时进行的；失败的附加或放置删除不能使该工作器可供另一个会话使用。 过期、禁用、不兼容和多余的工作器会被清理，而无需等待无关的项目准备。

临时提供商或运行时工件观察失败会推迟维护，而不会丢弃现有未使用工作器或延长其原始过期时间。被推迟的工作器仍计入容量，且在观察成功之前不会运行新的准备。已确认的配置文件、源所有者或运行时变更仍会退役不兼容工作器。失败的补充不会丢弃独立验证的就绪工作器。会话调度在消耗预留之前始终执行新的准入。

已准备项目镜像仅在成功会话激活后记录前台需求。失败的注册或调度不会续期镜像需求。新捕获的镜像会受其生产工作器保护，直到确认源停止；如果没有成功需求，则随后符合普通清理条件。

Crabbox 预留需要符合条件的专用 Linux 热镜像配置文件、已知的机器类别，以及不含 setupEnv 的不可变设置输入。缓存身份变更可能需要冷准备。项目配方和正常运行时安装仍会在就绪前完成，但该冷工作器不能替代无关的镜像生成。这可能会减少快照复用，直到符合条件的生成可以发布；它不允许不完整的设置，也不会延长旧镜像的需求窗口。

在控制界面中检查快照¶

打开 设置 → 连接 → 云 worker → 快照 以检查本地 warm-image 所有权，按已配置的 profile 分组。刷新 会同时重新加载快照和 worker 构建。当构建或捕获正在进行时，两个列表每 10 秒刷新一次；当两者都不再处于活动状态时，轮询停止。该视图显示可用镜像、进行中的捕获、由未决分配持有的镜像，以及需要关注的捕获或检查点删除。待删除项会显示检查点和重试指引；正在退役的当前镜像会标记为 退役中，而当只有较旧镜像等待清理时，可用的后继镜像会保留其状态。组标题优先使用已记录的主机事实，并回退到已配置 profile 的 backend、class 和操作系统。缺失的行详情会被省略；未知 profile ID 会显示在 未标记 profile 下。旧版分配会显示在 需要迁移 下，并附带 Doctor 恢复指引。

Crabbox 插件会通告 crabbox.images.list、crabbox.images.recover、crabbox.images.pin、crabbox.images.delete 和 crabbox.images.rollback；所有操作都需要 operator.admin。每个操作仅在其方法被通告时出现。如果列表方法未被通告，该视图会说明必须启用 Crabbox worker provider。列表操作读取本地状态，不会联系 provider，并返回分配计数以及每个镜像最多 20 条分配条目。

固定 和 取消固定 会立即生效，如果请求被拒绝，会显示失败通知。已固定 徽章标记受保护的检查点。固定是操作员的选择；持有 表示未决分配仍需要该检查点。当 profile 存在捕获或退役操作时，固定变更不可用，因此它们不会与 provider 副作用竞争。

删除 会请求确认，并且当镜像被持有、正在捕获或已固定时，会附带原因禁用。OpenClaw 会保留所有权记录，直到 provider 删除成功。删除失败会使镜像保持 退役中，并在维护期间重试；它不会将该检查点报告为已删除。

当存在上一代时，其 上一代 行会显示检查点和创建时间，并提供 固定 或 取消固定 以及 回滚 操作。确认 回滚 会原子地将该检查点恢复为当前版本。被降级为上一代的当前镜像在 keepPrevious: 1 或它被固定时会成为上一代；否则，它会在分配释放它之后退役。因此，即使将 keepPrevious 降低为 0，回滚仍然有效，同时上一代检查点仍会被记录。具有活动捕获或退役操作的 profile 无法回滚。

底部的 保留策略 卡片通过常规配置补丁流程编辑上述三个由插件拥有的键。保存时会验证它们的时长和代际数量，然后重新加载 Crabbox 插件以应用该策略。

构建快照 在 environments.prepare 可用且具有 operator.admin 时，会打开 profile 和本地仓库选择器。仓库目录与新建会话共享。关闭 warm images 的 profile 会附带原因禁用。构建会准备所选 checkout 的已提交 HEAD，并授权其已提交的 setup recipe，而不会启动会话。该通知会区分新构建与复用现有构建或保留。池已满时，需要先提高 prepared pool 上限或销毁未使用的 worker，然后再重试。

重建 使用项目镜像上记录的项目根目录。未记录根目录的旧镜像会省略此操作；请使用 构建快照 选择仓库。重建使用常规准备和镜像刷新策略，包括复用已在进行中的匹配工作；它不会强制替换当前镜像。

活动构建会显示在其已配置的 profile 组中，并带有 worker 状态和运行时长。取消 会请求确认，然后调用 environments.destroy，并等待 provider 工作和清理完成。已完成或已附加的 worker 不再显示为活动构建。构建中 总数还包括活动的镜像捕获；当构建及其捕获共享同一个 lease ID 时，只计算一次。失败和孤立的构建仍会显示其报告的错误，并计入 需要关注。它们不会保持轮询活动，也不提供取消。失败的构建提供 忽略，它会确认、调用 environments.destroy 并隐藏该行；Gateway 会保留终态记录，直到保留期过期，因此重新加载后可能再次列出它。孤立构建不提供忽略，因为其 provider 产物仍在等待清理。

恢复 仅对不确定的捕获可用。其必填复选框确认拥有该捕获的 worker 已停止，且 provider 产物已完成对账，含义与 CLI 的 --acknowledge-provider-cleanup 相同。确认前请遵循下面的清理步骤。恢复仅清除所选保留；它不会停止 worker 或删除 provider 产物。仅存在过期捕获并不允许恢复。

新分配会记录可选的 profileId、backend、machineClass、os、projectLabel 和 projectRoot 显示事实，这些也会包含在 openclaw crabbox warm-images --json 中。JSON 输出还包括可选的 pinned 元数据（atMs）和 previous 检查点详情（checkpointId、createdAtMs，以及记录的 baseCommit 和 runtimeIdentity）。现有 version-3 行如果没有这些字段，则保持未固定，且不保留上一代；它们不需要状态迁移。profileId 表示最近从该镜像键分配出来的已配置 profile；它会在每次分配时被覆盖，并且不会更改镜像键或复用策略。projectRoot 是用于重建的规范 Gateway 本地仓库根目录。项目标签使用规范化后的 origin 仓库标识 host/owner/repo，或者当无法解析 origin 时使用项目根目录的 basename。

恢复已暂停的捕获¶

在不联系云端的情况下检查本地所有权：

openclaw crabbox warm-images --json

该有界状态包括检查点 ID、项目密钥、已记录的运行时身份、分配选择和阶段、捕获选择器、源租约 ID、后端名称以及时间戳；它不包括设置命令或环境值。Doctor 会报告待处理的捕获和退役，但绝不会通过 doctor --fix 清除它们。超过 20 分钟的捕获会产生警告，并且可能仍在准备其源或等待提供商就绪；请等待所属捕获稳定。只有明确不确定的结果才带有强制恢复指引。经过的时间本身不授予接管权限。同一预留项在重启之间仍然有效；较早的空预留标记也需要显式恢复。如果检查要求迁移，请先遵循 升级 warm-image 状态。

Gateway 会将不确定的捕获归并为一条警告，并包含其数量和选择器。当该集合发生变化或插件重启时，它会再次报告。这报告的是保留的所有权；它不会尝试另一次捕获。

在恢复之前，停止所属 Gateway、任何原始捕获进程以及被恢复的 worker。使用源租约和捕获时间，在 Crabbox 的检查点目录中对不确定的操作进行对账，并解决任何未跟踪的提供商工件。只有在这些步骤之后，才从状态中复制确切的捕获选择器：

openclaw crabbox warm-images --recover <capture-selector> --acknowledge-provider-cleanup

该确认声明原始捕获和 worker 已停止，且未跟踪工件已解决；仅凭经过的时间不能确立这些事实。恢复只会清除该捕获预留，保留已知的检查点引用和分配选择，并拒绝已被替换的选择器。它不会停止进程、运行提供商命令、删除快照或分配 worker。之后重启 Gateway；下一个符合条件的 worker 可以再次捕获。失败的检查点退役会在提供商删除错误解决后，于后续的捕获维护或启用 warm-image 的 worker 拆除过程中重试；它们不使用捕获恢复。

升级 warm-image 状态¶

Warm 配置文件使用现有 warm-images 插件状态命名空间中的 version-3 封装；SQLite 架构版本不会改变。停止所属 Gateway 和原始捕获进程，然后运行：

openclaw doctor --fix

Doctor 会在 Gateway 的独占维护锁下执行此迁移。它会保留旧版镜像元数据、分配选择、操作系统/运行时身份、捕获选择器以及退役义务。历史记录不会获得准备、预留用途或成功需求相关事实。较早的空捕获标记会成为明确的不确定捕获，并带有其原始恢复选择器。不受支持的记录保持不变，并产生警告。运行时配置需要规范封装；它不会静默转换旧行。

较早的 warm-leases 行记录了已注册的类别，但无法确定租约最初是冷启动还是从检查点启动。这些行会阻止新的 warm-image 分配，直到被解决。Doctor 会报告其数量和确切的恢复命令。通过其原始 Gateway 或提供商解决每个租约，停止其 worker 和所属进程，并在使用报告的选择器之前对提供商工件进行对账：

openclaw crabbox warm-images --recover <legacy-allocation-selector> --acknowledge-provider-cleanup
openclaw doctor --fix

此恢复只会删除与该选择器匹配的未更改旧版行。它不会确立提供商缺失，也不会替你清理机器。当清理不确定时，保留该行。已被旧代码遗忘的检查点不会被重新发现；请通过 Crabbox 手动对账这些检查点。当分配、捕获或退役仍未解决时，不要针对同一状态运行旧版和新版写入器，也不要降级。