跳转至

工作节点设置与捆绑包安装

设置命令

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

在配置文件设置、节点运行时准备或节点注册脚本启动之前发生的 Crabbox 协调器传输超时,允许在现有阶段预算内进行最多三次带退避的重试。只有完全由协调器超时诊断组成的输出才符合重试条件;任何脚本输出都会阻止重试。租约检查、就绪读取、心跳和释放使用相同的有限重试策略;分配仍归 Gateway 预配重放所有。重试耗尽时,会保留协调器诊断并报告尝试次数。

settings.setup 在 Crabbox 报告租用机器就绪后、临时节点注册前运行。它在每次预配尝试中都会运行,包括中断派发后的重放,因此它必须是幂等的。全新的云镜像在 setup 启动时往往仍在运行 cloud-init 或 unattended-upgrades;安装包的脚本应等待它们(cloud-init status --wait)并传入 apt 锁超时(-o DPkg::Lock::Timeout=600),否则首次派发会因 /var/lib/apt/lists/lock 被占用而失败,而同一台机器上的重试则会成功。检查 Node 的版本,而不只是可执行文件是否存在,并按示例保留受支持的安装。在任何修复后重新检查已安装的版本和 npm。如果最终检查仍然失败,请在再次派发前修复镜像的 PATH 或软件包选择。自动 bootstrap 会安装与 Gateway 匹配的 OpenClaw 运行时,而不是 Node.js;升级时,请保持镜像或 setup 先决条件与提供服务的 Gateway 的 package.json 中的 engines.node 要求一致。如果 setup 或注册失败,提供方会停止租约,派发会以失败关闭(fail closed)结束;半配置的付费机器不会被隐藏在终态之后。

示例配置文件同时支持 OpenClaw 和 Codex。让 setup 专注于机器先决条件和项目工具。你无需全局安装 OpenClaw,也无需在配置文件中附加带版本的 Codex 插件安装,或维护包 URL。在更新现有配置文件时,请移除这些旧的运行时安装步骤;bootstrap 会自动提供正在运行的 Gateway 的运行时。

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

原生 Windows 先决条件

对于 windows/normal,Crabbox 使用 Windows PowerShell 执行 settings.setup。请为 PowerShell 编写 setup 命令;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

请使用 Crabbox bootstrap 或镜像,使其在机器的 PATH 中提供受支持的 Node.js 版本和 npm,并且 npm 的 CLI 安装在 node.exe 旁边的 node_modules/npm 下。如果缺少 Node 或该 npm 安装,OpenClaw 会以先决条件消息使注册失败;它不会安装 Node。npm 会安装 node 运行时归档,OpenClaw 则会使用其 Node 归档库解压 worker 捆绑包。

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

重启重放会验证实际 node.exe 子进程的 PID、创建时间、可执行文件和命令行。Windows 不提供低成本的工作目录检查,因此启动记录会将运行时和状态目录绑定到该已验证的创建时间。身份缺失或不匹配将拒绝重放并要求重新预配。启用了桌面功能的 Windows worker 改用 Crabbox 的交互式桌面服务,并额外绑定账户 SID 和交互式会话;参见 原生桌面先决条件。

捆绑安装

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

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

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

Crabbox 为每个运行时准备或注册命令使用核心引导操作窗口。Core 根据其 125 KB/s 吞吐量下限,从归档总字节数计算传输时间,上限为 60 分钟,并包含安装和操作余量。当前操作窗口范围为 45 到 95 分钟;对于没有更大窗口的授权,Crabbox 保留其 15 分钟最低值。供应截止期限在分配前为运行时准备和认证注册两者预留最大窗口,外加单独的十分钟节点连接等待。项目捕获添加其单独的允许量。配置文件设置、桌面工作、诊断、取消和清理保留各自的允许量。运行时准备为两个下载授权提供相同的合并窗口。HTTP 下载在套接字无活动两分钟后重试,并从保留的部分字节恢复。持续接收字节的传输没有每次尝试的时间限制;所有尝试仍共享外层命令截止期限。命令截止期限永远不会续期已过期的下载授权或绕过实时所有者检查。初始配对凭据对实时注册保持有效,包括其由大小推导的引导窗口和节点连接等待。关闭或超时一个未完成注册会撤销其配对凭据;重放会为同一设置身份签发新凭据。在 Gateway 重启后,实时替换注册可能采用存留的待处理凭据,而该凭据在没有该实时绑定时无法注册首个设备。

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

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

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

注册会在发布运行时指针或启动节点之前,通过一次 CLI 调用按顺序启用其所需插件。每个插件都保留其正常的策略和能力同意检查;启用失败会停止注册。当云桌面同时需要执行插件和 computer-use 插件时,这可避免重复启动 CLI。

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

在常规云配置和项目镜像准备期间,运行时归档和 worker 归档使用各自独立的短生命周期令牌并发下载。一旦运行时归档通过大小和摘要验证,npm 安装和运行时验证就会继续,同时 worker 归档继续下载。installation-and-worker-download 阶段标记此重叠;worker 下载失败保留其自身的传输阶段。终止失败会取消未完成的下载或重试退避,终止任务拥有的 npm 进程树,并保留第一个错误。两个分支(包括任何已启动的 npm 进程)都必须结束,然后才能删除临时文件。worker 归档发布和运行时发布等待汇合。

Gateway 会为其后续具有相同执行模式的注册复用其已准备的归档。节点将成功安装保留在 ~/.openclaw-worker/node-runtimes/<sha256> 下,因此预热镜像可以复用确切的工件。不同的摘要会选择不同的安装,即使版本未改变。运行时归档省略 worker 部署工件和 Gateway 的 Control UI 资源,减少传输和安装工作。Gateway 继续提供仪表盘。Core 在配置之前准备 worker 包,与运行时归档一起,以便两个不可变工件都可用于运行时准备。注册后,OpenClaw worker-turn 会从运行时准备期间下载的匹配归档或保留在已准备项目镜像中的归档安装内容寻址 worker 包;如果该归档不存在,则通过认证节点通道下载它。本地归档验证成功会在节点日志中输出 Worker bundle already prepared locally: <sha256>,并跳过 worker-bundle HTTP GET。已准备的归档仍会经过验证;参见 预热镜像。Codex remote-exec 直接启动受管理的 exec-server。现有的放置检查、节点命令允许列表和调用审批仍然控制执行。

节点上的 worker 包下载在瞬时传输失败后从保留的暂存字节恢复。重试使用抖动退避,并在连续三次失败且没有保留进度后停止。每个授权在其现有生命周期和实时所有者检查内最多允许 256 次串行服务。节点在安装前验证完整归档的大小和 SHA-256 摘要,并在终止失败或取消时删除暂存;部分下载不会在失败安装后保留。

在已准备好的 worker 进行配置期间,缓存清理会保留在准入时记录的精确 worker bundle,包括在 readiness 生成 bootstrap receipt 之前。当环境达到终态后,如果没有其他环境或 placement 需要这些字节,常规 bundle 清理可以回收它们。

Worker bundle 包含其 JavaScript 依赖项,包括 WebSocket 传输。即使由 Bun 执行构建,它们的目标仍是 Node.js;目标端仍需要受支持的 Node.js 安装。

在 Gateway 重启后复用 node 运行时归档

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

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

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

发行版扫描、导入验证、归档构建和哈希计算在 worker 线程中运行,因此准备过程不会阻塞 Gateway 的事件循环。注册和 prepared-pool 维护等待同一个已验证工件;取消一个注册不会取消为其他消费者进行的准备。

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

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

构建完整的自定义 node 包

自动 cloud bootstrap 不需要手动发布的包。对于独立的部署或包验证工作流,规范的包构建器仍可以生成完整的自定义发行版,并显式包含普通核心包排除的 source-owned 插件:

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 匹配的运行时插件包含在同一个自定义包中;仅核心归档无法更新它们单独发布的代码。

通过现有的不可变工件路径交付生成的归档,并在启用常规 npm 生命周期脚本安装之前验证其 SHA-256。同时记录源 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。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw