云端工作节点

​

各部分在哪里运行

​

要求

• 一个工作节点提供商插件。内置的 crabbox 插件驱动 Crabbox CLI，该 CLI 负责在各云后端（AWS、Hetzner 等）之间代理租约。crabbox 二进制文件必须位于 PATH 中（或设置 settings.binary），且提供商凭据必须已配置。AWS 准入要求 Crabbox 0.38.1 或更高版本。
• 对于 Crabbox AWS 工作节点，生效的 aws.instanceProfile 必须为空。提供商在分配前检查 crabbox config show --json，随后要求 crabbox inspect --json 报告来自 EC2 DescribeInstances 的 providerMetadata.instanceProfileAttached: false。具有实例角色或缺少权威元数据的租约会被停止并拒绝。
• 租用机器上需要安装 Node.js。裸云镜像通常不包含它——请在配置文件的 setup 命令中安装。
• 一个具有会话自有托管工作树的会话（使用 worktree: true 创建）。分派会移动该工作树的内容；普通目录则作为清单镜像同步。

​

配置

{
  "cloudWorkers": {
    "profiles": {
      "aws": {
        "provider": "crabbox",
        "install": "bundle",
        "settings": {
          "provider": "aws",
          "class": "standard",
          "ttl": "8h",
          "idleTimeout": "45m",
          "setup": "test -x /usr/bin/node || (curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - && sudo apt-get install -y nodejs)"
        }
      }
    }
  }
}

​

设置命令

​

安装渠道

• bundle 会打包当前运行中 Gateway 网关的 dist、经过精简的 package.json，以及构建所引用的所有工作区软件包，并以内容哈希覆盖所有这些内容。机器会根据该哈希验证原始软件包，然后安装生产环境 npm 依赖项（禁用脚本）。这是在工作节点上运行开发构建的方式。
• npm 会证明该发布版本存在于公共注册表中，固定其 SHA-512 完整性值，并安装与 Gateway 网关完全匹配的 openclaw@<version>。

​

分派会话

openclaw gateway call sessions.create \
  --params '{"key":"agent:main:big-refactor","worktree":true,"cwd":"/path/to/repo","worktreeName":"big-refactor"}'

openclaw gateway call sessions.dispatch \
  --timeout 1500000 \
  --params '{"key":"agent:main:big-refactor","profileId":"aws"}'

openclaw gateway call sessions.reclaim \
  --timeout 600000 \
  --params '{"key":"agent:main:big-refactor"}'

​

安全模型

• 封闭的工作节点入口。 工作节点通过隧道套接字使用专用协议通信，并受封闭的方法允许列表限制——工作节点无法调用操作员 RPC。
• Gateway 网关拥有的工具权限。 每个轮次开始前，Gateway 网关都会针对工作节点固定的编码工具目录，应用当前的配置文件、提供商、智能体、群组、发送者、沙箱、委托、继承及运行时上限策略。启动信封仅携带由最终封闭词汇表限定的子集。明确设置上限的定时轮次会复用其受信任的所有者群组上下文，而不会将该身份发送到机器，也不会重新应用新的发送者覆盖层。工作节点目录之外的工具仍不可用；如果结果为空，则不使用任何工具运行。
• 凭据按需签发，静态存储时采用哈希。 每次分派都会签发一个工作节点凭据；Gateway 网关仅存储其哈希。凭据轮换和所有者 epoch 栅栏可确保每个会话最多只有一个活跃所有者——过期工作节点重新连接时会被隔离，绝不会合并。
• 主机密钥固定。 提供商必须在预配时公开机器的 SSH 主机密钥；引导程序使用严格固定的密钥连接，如果没有该密钥则以关闭方式失败。
• 机器上不存放常驻的模型、代码托管平台或云凭据。 模型身份验证保留在 Gateway 网关上（推理通过 {provider, model} 引用传输），工作区 git 提交不使用代码托管平台凭据，且在设置前会以权威方式检查 Crabbox AWS 租约元数据中是否存在实例角色。设置命令也必须不含凭据。
• 由提供商控制出站流量。 反向隧道消除了 OpenClaw 直接访问模型的需要，但 OpenClaw 不会重写提供商防火墙。如果任务需要，请在工作节点提供商中限制出站流量。
• 持久且恰好一次的转录记录。 工作节点通过针对会话叶节点的比较并交换协议提交转录批次；过期的基准会让运行立即停止，而不会复制或变基已付费的输出。

​

故障排除

• sessions.dispatch 是未知方法——未配置 cloudWorkers.profiles，或调用方缺少 operator.admin。
• “云端工作节点轮次需要 OpenClaw 运行时”——选择已将运行时配置为 OpenClaw 的模型。claude-cli 等外部 CLI 运行时不支持工作节点推理。
• “工作节点引导需要租用主机安装 Node.js”——在 settings.setup 中添加 Node 安装步骤（见上文）。
• AWS 实例角色证明失败——清除 aws.instanceProfile（如果设置了 CRABBOX_AWS_INSTANCE_PROFILE，也将其清除）。安装 Crabbox 0.38.1 或更高版本；旧版二进制文件不会公开 AWS 准入所需的权威 providerMetadata.instanceProfileAttached 合约。
• 分派因提供商错误而失败——放置记录和 environments.list 会保留最后一个错误，包括设置/引导程序的 stderr 输出尾部。机器在失败时会被销毁，因此该输出尾部是主要的取证依据。
• 分派期间客户端超时——openclaw gateway call 默认超时时间为 10s；请为 --timeout 传入充足的值（无论如何，分派都会继续在服务器端运行；预配期间重试会被拒绝并返回 session cannot dispatch from placement provisioning）。
• 从 2026.7.2 beta 升级后工作节点被回收——这些 beta 版本使用了旧版工作节点启动合约。重启时，OpenClaw 会销毁空闲且不兼容的工作节点，保留会话和工作区，将放置标记为已回收，并在下一次分派或轮次中预配当前版本的工作节点。如果 beta 工作节点在仍处于启动状态时被中断，则会在清理后标记为失败；请重试分派，以使用当前合约进行预配。
• 云端工作区冲突通知——轮次已完成，并保留了所列各路径的本地版本。使用通知中的已暂存 ref 命令检查或采用云端版本；无需为无冲突的更改重试，因为这些更改已经应用。
• “上一个云端轮次的工作区结果仍在协调中”——Gateway 网关短暂等待了先前结果的持久栅栏，但无法取得会话声明。等待协调完成，然后重试该轮次；重启 Gateway 网关是安全的，因为恢复流程会先保留已暂存的结果，再回收已失效的工作节点。
• 租约日常维护——crabbox list --provider <backend> 显示活跃租约；crabbox stop --provider <backend> --id <lease> 可手动释放一个租约。空闲租约会在配置文件的 idleTimeout 到期。

​

相关内容

• 沙箱隔离——缩小本地工具执行的影响范围
• 会话 CLI——检查已存储的会话
• 配置参考