云工作器

​

运行位置说明

​

要求

• 一个 worker provider 插件。捆绑的 crabbox 插件驱动 Crabbox CLI，该 CLI 跨云后端（AWS、Hetzner 及其他后端）协调租约。请为运行 Gateway 的操作系统用户安装 Crabbox 0.41.1 或更高版本，并将其放入该用户的 PATH 中，或者将 settings.binary 设置为其绝对路径。云端 worker 需要 Crabbox 固定的租约 ID 契约；旧版本的二进制文件会在分配前失败。
• 对于 Crabbox AWS worker，有效的 aws.instanceProfile 必须为空。provider 会在分配前检查 crabbox config show --json，随后要求 crabbox inspect --json 根据 EC2 DescribeInstances 报告 providerMetadata.instanceProfileAttached: false。带有实例角色或缺少权威元数据的租约将被停止并拒绝。
• 租用机器上的 Node.js。裸云镜像通常不包含它 — 请在 profile 的 setup 命令中安装。
• 一个由 registry 管理的、正在运行的 session worktree（使用 worktree: true 创建）。云端 dispatch 不接受任意的普通目录。dispatch 通过准入后，如果 Git 元数据之后变得不可用，工作区传输可能会使用清单镜像；这种传输行为不会使普通目录变得可 dispatch。

​

由协调器支持的 Crabbox

curl -fsS https://checkip.amazonaws.com

aws:
  sshCIDRs:
    - 203.0.113.10/32

crabbox login --url <coordinator-url> --provider aws
crabbox config show --json
crabbox whoami --json
crabbox doctor --provider aws --json

printf '%s' "$CRABBOX_COORDINATOR_TOKEN" | crabbox login \
  --url <coordinator-url> \
  --provider aws \
  --token-stdin

​

配置

{
  "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)"
        }
      }
    }
  }
}

​

setup 命令

​

安装通道

• bundle 会打包当前运行的 Gateway 的 dist、经过裁剪的 package.json，以及构建所引用的任何工作区包，所有内容都由内容哈希覆盖。机器会先用该哈希验证原始 bundle，然后安装生产环境的 npm 依赖（禁用脚本）。这就是你在 worker 上运行开发构建的方式。
• npm 会证明该发布版确实存在于公共注册表中，固定其 SHA-512 完整性，并安装与 Gateway 完全一致的 openclaw@<version>。

​

验证配置文件

openclaw config validate --json
openclaw plugins inspect crabbox --runtime --json

openclaw gateway call environments.list --params '{}'
crabbox list --provider aws --json

​

调度会话

1. 已连接的操作员拥有 operator.admin 作用域。
2. environments.list 至少公布了一个已配置的配置。
3. 选定的 Gateway 文件夹是一个可使用托管工作树的 Git 检出目录。

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。
• 由网关拥有的工具权限。 在每一轮开始之前，网关会将当前的配置、提供商、代理、组、发送方、沙箱、委派、继承和运行时能力策略应用到工作者固定的编码工具目录上。启动信封仅携带最终的封闭词汇子集。明确设置上限的计划轮次会复用其受信任的所有者组上下文，而不会将该身份发送到盒中，也不会重新应用新的发送方覆盖层。工作者目录之外的工具仍不可用；空结果会在无工具的情况下运行。
• 铸造凭据，静态哈希存储。 每次调度都会铸造一个工作者凭据；网关仅存储其哈希值。凭据轮换和所有者纪元隔离保证每个会话最多只有一个有效所有者——重新连接的过期工作者会被隔离，绝不会被合并。
• 主机密钥固定。 提供商必须在配置时提供盒的 SSH 主机密钥；引导程序使用严格固定的密钥进行连接，缺少该密钥时将安全失败。
• 盒上不保留长期有效的模型、代码托管或云凭据。 模型身份验证保留在网关上（推理通过 {provider, model} 引用传递），工作区 Git 提交在没有代码托管凭据的情况下创建，并且会在设置之前权威检查 Crabbox AWS 租约元数据以确认实例角色。设置命令也必须不包含凭据。
• 由提供商负责的出口流量。 反向隧道消除了 OpenClaw 直接访问模型的需要，但 OpenClaw 不会重写提供商防火墙。任务需要时，请在工作者提供商处限制出站流量。
• 持久化、严格一次的转录记录。 工作者通过针对会话叶节点的比较并交换协议提交转录批次；基准过期时会停止运行，而不是重复或重新调整已付费的输出。

​

故障排查

• 未公布云配置文件——以管理员身份运行 openclaw gateway call environments.list --params '{}'。如果响应中没有 profiles，请验证 cloudWorkers.profiles，检查 provider 插件，然后重启 Gateway。这是配置或 provider 激活问题，而不是授权结果。
• 云目标被隐藏或 RPC 被拒绝——已连接的操作员缺少 operator.admin。请使用管理员范围重新连接；配置配置文件不会授予该范围。
• “云 worker 轮次需要 OpenClaw runtime”——请选择配置的 runtime 为 OpenClaw 的直接模型。映射到外部 Codex 或 Claude CLI runtime 的模型不支持 worker 推理。
• “Worker 引导需要租用主机上的 Node.js”——将 Node 安装添加到 settings.setup 中（见上文）。
• AWS 实例角色证明失败——清除 aws.instanceProfile（以及已设置的 CRABBOX_AWS_INSTANCE_PROFILE）。安装 Crabbox 0.41.1 或更高版本；旧版二进制不满足 AWS 准入所需的固定 ID 和权威 providerMetadata.instanceProfileAttached 契约。
• 调度或工作区恢复失败——检查 environments.list 和 sessions.describe。失败的环境会公开其有界环境错误。失败的放置会公开 recoveryError 以及其持久化的每会话 terminalReason；选定的 Control UI 聊天会在编辑框上方显示该终止原因。如有必要进行更深入的诊断，Gateway 主机上的操作员可以只读方式检查持久化的 worker 状态。不要编辑状态数据库来绕过生命周期围栏。
• 无法连接任何 SSH 候选项——将 Gateway 主机当前的出站 IPv4 与 crabbox config show --json 中显式配置的 aws.sshCIDRs 策略进行比较。如果匹配的 /32 不存在，请修正 Crabbox 的配置，并在重试前运行 crabbox doctor --provider aws --json。配置列表为空是有效的，因为 Crabbox 通常会在请求租约时发现并注入调用方的 /32；如果仍然无法连接，请显式固定该 /32。然后确保 Gateway 的出站路由和 worker 入站策略至少允许一个已公布的候选项。OpenClaw 仅会针对幂等探测、内容寻址传输、由收据／锁保护的构件安装、收敛式 managed-worktree 镜像以及隧道重连，使用相同身份和固定主机密钥轮换有序端口。含糊且未受保护的有状态命令会安全失败，不会在下一个端口上重放。
• 调度时客户端超时——openclaw gateway call 默认超时时间为 10 秒；请传入足够大的 --timeout。无论结果如何，调度都会继续在服务器端运行，并且在同一 Gateway 上进行相同重试时，会加入正在进行的操作，而不是再配置一个 worker。使用不同配置文件或会话身份进行的重试会被拒绝。
• 通过 doctor 后直接 AWS 授权仍然失败——doctor 证明的是只读 AWS 访问权限，而不是完整的变更策略。检查被拒绝的操作名称，只授予 Crabbox 所需的配置／清理操作，或改为配置由协调器支持的 Crabbox。新的直接 AWS 租约通常需要在 RunInstances 之前导入密钥对；此处的授权失败不会创建实例。
• 从 2026.7.2 beta 升级后 worker 被回收——这些 beta 版本使用了较旧的 worker 启动契约。重启时，OpenClaw 会销毁空闲的不兼容 worker，保留会话和工作区，将放置标记为已回收，并在下一次调度或轮次时配置当前版本的 worker。在仍处于启动阶段时被中断的 beta worker 会在清理后被标记为失败；请重试调度，以使用当前契约配置它。
• 云工作区冲突通知——该轮次已完成，并保留了所列每个路径的本地版本。使用通知中的 staged-ref 命令检查或获取云端版本；对于非冲突变更无需重试，因为这些变更已经应用。
• “上一个云轮次的工作区结果仍在协调中”——Gateway 曾短暂等待上一个结果的持久化围栏，但无法获取会话声明。请等待协调完成，然后重试该轮次；重启 Gateway 是安全的，因为恢复过程会在回收失效 worker 前保留暂存结果。
• 租约维护——crabbox list --provider <backend> --json 是只读清单。crabbox stop --provider <backend> --id <lease> 和 crabbox release --provider <backend> --id <lease> 具有破坏性，会手动释放租约。空闲租约会在配置文件的 idleTimeout 时间到达后过期。

​

相关

• 沙箱化 — 减少本地工具执行的影响范围
• Sessions CLI — 检查已存储的会话
• 配置参考。