Worker 设置和 bundle 安装

在注册之前，租用的机器上运行什么，Gateway 如何准备并验证安装到该机器上的运行时归档，以及如何构建完整的自定义节点包。

设置命令¶

settings.setup 在 Crabbox 报告其就绪之后、临时节点注册之前，于租用的机器上运行。它在每次供应尝试时都会运行，包括调度中断后的重放，因此它必须是幂等的。请检查 Node 的版本，而不仅仅是可执行文件是否存在，并像示例中那样保留受支持的安装。在任何修复后，重新检查已安装的版本和 npm。如果最终检查仍然失败，请在再次调度前修复镜像的 PATH 或软件包选择。自动引导安装的是与 Gateway 匹配的 OpenClaw 运行时，而不是 Node.js；升级时，请保持镜像或设置先决条件与提供服务的 Gateway 的 package.json engines.node 要求一致。如果设置或注册失败，提供商会停止租约，调度会失败关闭；终端状态后面不会隐藏半配置的付费机器。

示例配置文件同时支持 OpenClaw 和 Codex。让设置专注于机器先决条件和项目工具。您不需要全局安装 OpenClaw，不需要在配置文件中追加带版本的 Codex 插件安装，也不需要维护软件包 URL。更新现有配置文件时，请删除那些旧的运行时安装步骤；引导会自动提供正在运行的 Gateway 的运行时。

当代理工具等待一个有界的进程内 Gateway 请求时，停滞运行的恢复会遵守当前活动的响应截止时间，包括嵌套的 Crabbox 创建调用。完成、失败、取消或超时等待都会移除其额度；先前运行中挂起的请求不能延长当前运行的预算。响应超时本身不会取消供应。在重试不确定的创建请求之前，请检查环境的状态。

原生 Windows 先决条件¶

对于 windows/normal，Crabbox 使用 Windows PowerShell 执行 settings.setup。为 PowerShell 编写设置命令；Linux、macOS 和 Windows (WSL2) 继续使用 POSIX 脚本。

例如，以下先决条件检查使用机器现有的 Node 和 npm 安装：

$ErrorActionPreference = 'Stop'
& (Get-Command node.exe -CommandType Application -ErrorAction Stop).Source --version
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
& (Get-Command npm.cmd -CommandType Application -ErrorAction Stop).Source --version
exit $LASTEXITCODE

请使用提供受支持 Node.js 版本和 npm 的 Crabbox 引导或镜像，并让它们位于机器 PATH 上，且 npm 的 CLI 安装在 node.exe 旁边的 node_modules/npm 下。如果 Node 或该 npm 安装缺失，OpenClaw 会以先决条件消息使注册失败；它不会安装 Node。npm 安装节点运行时归档，OpenClaw 使用其 Node 归档库提取 worker 捆绑包。

无头 Windows 来宾必须包含 Crabbox 的托管启动器，位置为 C:\Program Files\Crabbox\bin\Start-CrabboxDetachedProcess.ps1。它会在 Crabbox 关闭其 SSH 命令后保持节点存活。如果启动器缺失，注册会失败并给出指引。由于启动器不会继承 SSH 输出句柄，隐藏的 PowerShell 父进程会将节点输出重定向到其隔离状态目录下的 node.log。

重启重放会验证实际 node.exe 子进程的 PID、创建时间、可执行文件和命令行。Windows 不提供廉价的工作目录探测方式，因此启动记录会将运行时和状态目录绑定到该已验证的创建时间。身份缺失或不匹配会拒绝重放，并要求重新供应。启用了桌面的 Windows worker 则改用 Crabbox 的交互式桌面服务，并且还会绑定账户 SID 和交互式会话；请参阅 原生桌面先决条件。

捆绑包安装¶

在注册云节点之前，Gateway 会从其当前已构建的安装环境中的临时暂存目录准备一个可重用的运行时归档。这适用于已发布的软件包和源代码检出。它包含完整的节点主机，以及拥有所选执行模式所需的已注册远程执行命令的可信插件。因此，Codex 的插件及其原生依赖锁定会随节点发行版一起分发，而无需单独的配置文件配方。

该归档通过 SHA-256 内容摘要进行选择和验证，而不是仅凭 OpenClaw 版本字符串或 Git 提交。两个版本相同的源代码构建可能产生不同的归档，包括包含未提交更改的构建。使用 pnpm build 构建源代码更改，并在调度前重启 Gateway。引导不会编译未构建的检出内容，不会将原始编辑覆盖到正在运行的构建上，也不会重写正在运行的 Gateway 的安装。缺失或不匹配的构建元数据会产生一个可操作的“重新构建并重启”错误。

源代码构建可能还包含私有 QA 工具。仅当块的字节与构建生成的归属元数据匹配，且所有归属者都是私有 QA 插件时，引导才会省略完整块。与公共插件共享的块，或被保留运行时引用的块，会保留在归档中。缺失的归属元数据不能授权省略；而过期的归属或不完整的导入闭包会使准备失败，且不会改变正在运行的 Gateway。

Crabbox 对每个运行时准备或注册命令使用核心引导操作窗口。核心窗口根据总归档字节数计算传输时间，以 125 KB/s 吞吐量为下限，上限为 60 分钟，并包含安装和操作余量。当前操作窗口的范围是 45 到 95 分钟；对于没有更大窗口的授权，Crabbox 保留 15 分钟的最低值。当项目捕获可行时，供应截止时间会在分配前预留最大窗口，外加单独的十分钟节点连接等待，用于两个阶段。配置文件设置、桌面工作、诊断、取消和清理保留各自的额度。运行时准备为两个下载授权提供相同的合并窗口。HTTP 下载在套接字空闲两分钟后重试，并从保留的部分字节处恢复。持续接收字节的传输没有单次尝试的时间限制；所有尝试仍共享外层命令的截止时间。命令截止时间绝不会续期已过期的下载授权，也不会绕过实时所有者检查。初始配对凭据在签发后仍会在十分钟后过期，因此冷注册可以在其命令窗口内完成下载，但随后配对失败；更长的命令截止时间并不能解决这个独立的限制。

每次注册都会获得限定于该实时配置操作的短生命周期下载权限。项目镜像准备首先获得一个仅运行时的工件授权：它安装已验证的运行时，而不铸造节点身份或注册凭据。该授权在注册开始前关闭，关闭配置操作会撤销它。节点验证归档声明的大小和摘要，以节点用户身份安装它，并仅在注册期间在隔离的按租约状态中启用其所需插件。归档包含运行时代码和包元数据，不包含 Gateway 的配置、身份验证配置文件、会话状态或进程环境。下载和注册凭据不会传递给 npm 或启动的节点进程。

原生依赖项由 npm 针对云机器的操作系统和 CPU 安装；归档不会复制构建主机的原生 node_modules。仍需要注册表访问，这不是离线依赖包。引导流程不会仅因版本匹配就选择全局 OpenClaw 安装。

引导流程将 CRABBOX_PHASE:openclaw-bootstrap-* 标记输出到 Crabbox 命令流中，用于下载、安装、验证、插件激活和节点启动。Crabbox 将这些记录为命令阶段计时；缓存运行仅输出其执行的工作。

注册在发布运行时指针或启动节点之前，通过一次 CLI 调用按顺序启用其所需插件。每个插件保留其常规策略和能力同意检查；启用失败会停止注册。当云桌面同时需要执行插件和计算机使用插件时，这避免了重复启动 CLI。

如果注册在发布其运行时指针之后、记录节点 PID 之前被中断，重放需要释放并重新配置该 worker。分离进程可能仍在运行，因此缺失 PID 不会授权再次启动。保留的无 PID 启动回执具有相同的恢复要求。

在项目镜像准备期间，运行时和可选 worker 归档使用各自独立的短生命周期令牌并发下载。一旦运行时归档通过大小和摘要验证，npm 安装和运行时验证将继续进行，同时 worker 归档继续下载。installation-and-worker-download 阶段标记此重叠；worker 下载失败保留其自身的传输阶段。终止失败会取消未完成的下载或重试退避，并保留第一个错误。两个分支（包括任何已启动的 npm 进程）必须在删除临时文件之前完成。worker 归档发布和运行时发布等待汇合。

Gateway 对后续具有相同执行模式的注册复用其已准备的归档。节点将成功安装保存在 ~/.openclaw-worker/node-runtimes/<sha256> 下，因此热镜像可以复用精确工件。不同摘要会选择不同安装，即使版本未变。运行时归档省略 worker 部署工件和 Gateway 的控制 UI 资产，减少传输和安装工作。Gateway 继续提供仪表板服务。缺失的 worker 包会在远程节点安装期间准备，以便打包可以在节点就绪前完成。注册后，OpenClaw worker-turn 从保留在已准备项目镜像中的匹配归档安装内容寻址 worker 包，或者当该归档缺失时通过已认证的节点通道下载它。已准备的归档仍会经过验证；参见 热镜像。Codex remote-exec 直接启动受管理的 exec-server。现有放置检查、节点命令允许列表和调用审批仍然控制执行。

在已准备的 worker 配置期间，缓存清理会保留在准入时记录的精确 worker 包，包括在就绪产生引导回执之前。环境达到终止状态后，当没有其他环境或放置需要这些字节时，常规包清理可以回收这些字节。

在 Gateway 重启后复用节点运行时归档¶

Linux 和 macOS 部署镜像可以在正在运行的 OpenClaw 包根目录中保留一个已准备的节点运行时归档，作为 node-runtime.tgz，位于 package.json 旁边。在镜像准备期间，在关闭生产者之前，将生产者的归档复制到该位置：

cp /path/to/prepared/node-runtime.tgz /path/to/openclaw/node-runtime.tgz

新 Gateway 进程中的首次云节点准备会将该可选输入复制到私有临时存储，并针对正在运行的发行版和所选插件验证其实际文件、内容、大小和权限。它仍会检查构建身份、精确依赖固定和已构建的导入闭包。版本字符串或相邻校验和清单不会授权复用。匹配的归档会跳过压缩；缺失、损坏、不安全或不匹配的输入会使用现有构建器。不同执行模式可以选择不同插件，因此可以从相同镜像输入重新构建。

部署镜像拥有保留的文件。Gateway 关闭仅在活动使用者完成后删除其临时副本。当发行版或插件更改时，替换镜像归档；删除它会恢复普通准备。Windows Gateway 会继续构建其归档，因为共享的 Windows 归档读取器会规范化权限，而不是保留此比较所需的 tar 模式。

这避免了重启后重复构建归档。它不会复用注册凭据、跳过 worker 授权，或消除 worker 安装和启动。在评估冷启动节省时，应将归档验证与端到端 worker 就绪分开测量。

构建完整的自定义节点包¶

自动云引导不需要手动发布的包。对于单独的部署或包验证工作流，规范包构建器仍可以生成完整的自定义发行版，并明确包含普通核心包排除的源拥有插件：

source_sha="$(git rev-parse HEAD)"
node scripts/package-openclaw-for-docker.mjs \
  --bundle-plugin codex \
  --pnpm-pack \
  --allow-unreleased-changelog \
  --output-dir .artifacts/cloud-node \
  --output-name "openclaw-cloud-${source_sha}.tgz"
shasum -a 256 ".artifacts/cloud-node/openclaw-cloud-${source_sha}.tgz"

在已安装依赖的干净、可信检出中运行此命令。构建器会编译运行时，包含所选插件的已构建入口点和导入闭包，并重新生成安装清单。它会临时将插件的精确运行时依赖固定添加到发行版清单中，拒绝冲突或未固定的依赖，并将所选插件标记为发行版所有。打包完成后，源清单和安装清单会恢复。对额外的源插件重复使用 --bundle-plugin <id>。如果没有该选项，常规核心包和外部插件发布契约保持不变。

更新期间，Doctor 会删除符合条件的受管 npm 副本，这些副本遮蔽了包含在此发行版中的插件，即使它们的版本字符串匹配。由其他操作保留的副本会保留其现有保护。插件设置和数据仍保留在状态目录中。必须与未发布宿主 SDK 匹配的运行时插件应包含在同一个自定义包中；仅核心的归档无法更新它们单独发布的代码。

通过现有的不可变制品路径交付生成的归档，并在安装前验证其 SHA-256，安装时启用常规 npm 生命周期脚本。同时记录源 SHA 和归档摘要：不同的未发布构建可能共享同一版本。不要将插件复制到已安装的发行版中，也不要使用独立的 npm-pack: 插件归档替代此发行版。Cloud 配置不会使用此 URL；其注册制品来自正在运行的 Gateway。

验证下载的归档后，将掩码限定在 root 命令作用域内安装它，然后以将运行该程序的用户身份验证版本：

sudo sh -c 'umask 022 && npm install -g /tmp/openclaw-cloud.tgz'
openclaw --version

使用已验证归档的路径替代 /tmp/openclaw-cloud.tgz。更改安装掩码不会修复现有的仅 root 可访问的父目录；如果之前的安装无法访问，请在重试注册之前修正对该包及其父目录的访问权限。

原生依赖在发行版根目录中声明，并针对目标操作系统和 CPU 安装；归档不会复制构建主机上的插件 node_modules。目标安装仍需要注册表访问权限，并且不是离线依赖包。验证你部署的每个目标架构。仅当复用来自同一源修订的完整构建，并且所有所选插件输出都存在时，才使用 --skip-build。