配置 — 云工作器环境

位于 cloudWorkers.* 下的云工作器环境键。

完整的键索引及其他顶级配置域，请参阅配置参考。

云工作器环境¶

云工作器是可选加入的。如果 cloudWorkers 不存在，或者 profiles 为空，OpenClaw 将不接受新的云工作器创建，并且不会通告云目标。sessions.dispatch 对于符合条件的配对设备目标可能仍然可用。配置模式以及只读的 environments.list 和 environments.status 方法仍然可用。先前创建的持久记录仍会进行对账并保持可见；现有的 gateway/node 投影保持不变。

基于 SSH 的 remote-exec 提供程序必须返回可信的 hostKey，其格式严格为 algorithm base64，且不带主机名或注释。引导过程将该键写入一个隔离的 known_hosts 文件，并设置 StrictHostKeyChecking=yes；若提供程序省略该键，则在打开连接之前即失败。没有首次使用时的信任回退机制。这些提供程序还通过独立的固定 SSH 连接传输工作区流量，因此 rsync 不会阻塞控制流量。

基于节点的提供程序为 worker-turn 或 remote-exec 返回经过认证的节点设备 ID。Gateway 会安装当前固定的捆绑包，并通过节点传输通道传送工作区；这些租约不会返回或解析 OpenClaw SSH 端点凭据。worker-turn 需要节点租约，并启动一个受限制的 OpenClaw 工作器子进程。remote-exec 既可以使用已注册的节点，也可以使用现有的基于 SSH 的提供程序，并将执行框架及模型认证保留在 Gateway 上。

Crabbox 配置档¶

在 设置 → 连接 → 云工作器 中，配置档编辑器的 高级 分组可编辑热镜像、设置环境名称、就绪工作器以及暂停后时长。该页面还公开了共享的 预备池 上限。清除可选值将恢复其默认值；为热镜像选择 自动 将恢复自动选择。更改无需重启 Gateway 即可生效。保存配置档后，如需准备镜像，请使用 快照 → 构建快照。保存不会启动构建。

快照保留是插件级别的，与配置档设置相互独立。请在 快照 → 保留策略 卡片或配置中设置 plugins.entries.crabbox.config.warmImages.refreshAfter（默认 24h，最小 1h）、retainUnused（默认 14d，最小 1d）和 keepPrevious（0 或 1，默认 0）。时长接受整数分钟、小时或天。更改会重新加载 Crabbox 插件，而无需重启 Gateway。完整语法、固定豁免及上一代行为，请参阅保留策略。

内置的 crabbox 提供程序通过本地 Crabbox CLI 配置一台一次性机器，将其注册为临时出站节点，并为 OpenClaw worker-turn 或 Codex remote-exec 返回相同的节点传输通道。因此，两个执行框架都可以选择同一个已配置的配置档；所选会话运行时决定其执行语义。内部的 settings.provider 选择 Crabbox 后端；它与外部的 OpenClaw 提供程序 ID 是分开的。

{
  gateway: {
    nodes: {
      commands: {
        // Required only when this profile also runs Codex remote-exec sessions.
        allow: ["codex.exec-server.stdio.v1"],
      },
    },
  },
  cloudWorkers: {
    preparedPool: { maxTotal: 4 },
    profiles: {
      production: {
        provider: "crabbox",
        suspendAfter: "45m",
        readyWorkers: 1,
        settings: {
          provider: "aws",
          class: "standard",
          ttl: "24h",
          idleTimeout: "60m",
          // Optional preferred executable. OpenClaw manages a current copy when needed.
          binary: "/usr/local/bin/crabbox",
        },
      },
    },
  },
}

• settings.provider（必需）：来自 Crabbox 提供程序参考 的后端，通过 --provider 传入。直接操作或由协调器支撑的操作遵循 Crabbox 的配置。
• settings.class：可选的 Crabbox 机器类别，传递给 --class。除非放置配置提供了 machineClass，否则省略该值会将选择留给 Crabbox；OpenClaw 不会自行设定默认值或硬件规格。显式的 null、空字符串或仅含空白的字符串以及非字符串值均无效。可通过 设置 → 高级 编辑无类别配置档。
• settings.ttl 和 settings.idleTimeout（必需）：正的 Go 时长字符串，作为提供程序端的安全失效保护传递给 --ttl 和 --idle-timeout。
• settings.warmImage：在注册之前，准备项目的已提交检出内容及节点运行时以供捕获，然后从该镜像启动该项目和配置档的后续工作器。如果没有准备好的 Git 项目，捕获仍会在符合条件的工作器拆除时进行。与 suspendAfter 搭配使用，使暂停的会话能够热唤醒。当存在已知的配置类别或放置类别，且 setupEnv 为空或省略时，默认启用。没有有效类别时，省略该设置仍保持冷启动。非空的 setupEnv 会使默认保持冷启动，因为转发的主机环境可能会在共享镜像中留下从设置派生的凭据。显式 true 选择启用，但需要先有已知的有效类别，才能执行提供程序命令；显式 false 则始终冷启动。解析出的类别以及原始的冷启动/检查点选择会在分配前记录，并在重试和重启期间保持不变。镜像会产生提供程序快照存储费用，并保留机器级缓存（包括原始的 Git 种子），以及 setup 在已擦洗的工作器状态之外写入的任何内容。擦洗操作有三分钟的超时时间。检查点创建会在 Crabbox 的原生捕获预算以及命令、源生命周期和子进程结算宽限内等待；不会延长配置的租约 TTL 或空闲超时时间。不确定的项目捕获会阻止其来源的注册，但仍允许进行租约清理。关于刷新、保留以及 Doctor 迁移和恢复，请参阅热镜像。
• settings.binary：可选的 Crabbox 可执行文件绝对路径。未设置时，OpenClaw 会先检查同级 Crabbox 检出目录，再检查 PATH 中的可执行条目。该插件要求所有目标都使用 Crabbox 0.67.0 或更高版本，包括 Daytona 固定 ID 准备、重放和确认清理。如果所选二进制文件缺失、过旧或无法报告受支持的版本，插件会将受支持的发行版下载到其自身的版本化目录中，即 $OPENCLAW_STATE_DIR/tools/crabbox（默认为 ~/.openclaw/tools/crabbox）。在使用该副本之前，它会验证官方发行版校验和及可执行文件版本。现有二进制文件和配置档设置会被保留。后续命令会复用受管安装，而无需再次下载。损坏的受管安装会被自动替换；原目录会以 .recovery-<id> 后缀保留在替换目录旁边，以供检查。openclaw doctor --fix 会在首次工作器操作之前安装受管副本。安装失败会在分配之前停止操作并报告原因。
• readyWorkers：每个符合条件的本地项目或仓库及配置档的非负整数目标值；默认为 1。设置为 0 可禁用此配置档的预备资源，同时保留热镜像复用。
• cloudWorkers.preparedPool.maxTotal：Gateway 范围内的非负整数预备资源上限；默认为 4。准备中的工作器及未确认的清理都会计入这两个限制。设置为 0 可排空未使用的预备资源并停止补充。预备资源会产生运行中的机器费用，并会在成功满足项目需求后，依据提供程序现有的空闲策略过期。请参阅就绪工作器。

托管发布归档会流式写入私有暂存文件，大小上限为 128 MiB，然后才进行校验和验证与解包。下载进度具有 30 秒空闲限制和独立的 10 分钟总时限；失败的下载会在获取返回前清理。

受支持的 CLI 也用于检查和停止现有租约。在发布下载访问受限或托管工具写入权限受限的主机上，请在现有配置使用的确切路径处预置受支持的可执行文件，或在推出 OpenClaw 更新之前暂存托管发行版。受支持的可执行文件和已安装的托管副本不需要发布下载访问权限。如果两者都不可用，则获取必须在租约检查或拆除继续之前成功；拆除会在尝试获取之前停止心跳。

未知设置会被拒绝。Crabbox 凭据和后端特定账户配置仍由 Crabbox 拥有；不要将它们放在 settings 中。OpenClaw 仅调用本地 CLI，并且不会从此插件发起提供商网络调用。预置会通过 --lease-id 传递一个确定性的规范租约 ID，仅将 --slug 保留为显示元数据，并且始终传递 --keep=true；OpenClaw 拥有外部生命周期，并使用 crabbox stop --id <canonical-id> 销毁租约。在出现模糊结果后，Gateway 协调会重复相同的固定 ID 操作。Crabbox 必须返回完全证明的租约，否则必须失败关闭；OpenClaw 绝不回退到 slug 采用或替换分配。

提供商支持和后端特定设置属于 Crabbox。请在那里配置凭据、协调器访问、网络和快照，而不是在 OpenClaw 设置中重复它们。已安装的后端必须满足 OpenClaw 的 cloud-worker 生命周期要求。

Crabbox 设置使用环境拥有的一次性配对凭据和已配置的公共 Gateway URL。提供商返回确切的已认证节点 ID；然后 Gateway 安装其当前捆绑包，并通过已认证节点路由传输工作区。对于 Codex 远程执行，Crabbox 会在节点的私有状态中准备捆绑的 Codex 插件和固定版本的托管二进制文件，并且 Gateway 要求每次尝试都显式允许 codex.exec-server.stdio.v1 命令，外加关键的一次性允许审批。该模式下不使用任何 OpenClaw worker 子进程或 worker 槽位。OpenClaw 不会持久化 Crabbox SSH 端点、密钥、主机密钥或回退端口输出。

静态 SSH 开发配置¶

{
  cloudWorkers: {
    profiles: {
      development: {
        provider: "static-ssh",
        settings: {
          host: "worker.example.test",
          port: 22,
          user: "openclaw",
          hostKey: "ssh-ed25519 <base64-public-host-key>",
          keyRef: {
            source: "env",
            provider: "default",
            id: "OPENCLAW_WORKER_SSH_KEY",
          },
        },
      },
    },
  },
}

• profiles：具有非空、已去除首尾空白 ID 的命名 worker 配置。每个配置会选择由插件注册的提供商。
• provider：非空的 worker 提供商 ID。示例使用捆绑的 crabbox 提供商和 QA Lab 的 static-ssh 提供商。
• install：基于 SSH 的 remote-exec worker 安装方法。"bundle"（默认）会传输 gateway 已安装构建的内容哈希捆绑包，并支持已发布、开发版和未发布版本。"npm" 是针对未修改的打包发布版的可选优化；它会从公共 npm 注册表安装 openclaw@<exact gateway version>，并且从不安装 latest。基于 Node 的 worker-turn 和 remote-exec 提供商则通过 node 传输安装固定版本的 Gateway 捆绑包。
• suspendAfter：可选的配置级时长，例如 45m、90m 或 2h；最小值为 1m。当 worker 的会话空闲达到该时长后，Gateway 会安全回收该 worker。下一条消息会预置一个替换 worker，如果存在镜像则为热替换。省略此字段可让 worker 保持运行，直到显式停止。
• 捆绑的提供商插件在配置后会自动选择，但显式禁用和 plugins.allow 仍然适用。配置了允许列表时，请包含提供商 ID（例如 crabbox）。外部提供商插件还必须已安装并显式启用。
• settings：提供商拥有的有界 JSON。所选插件定义并验证其键；对于包含秘密的值，请使用 SecretRef 对象。静态 SSH 提供商要求 host、user、hostKey 和 keyRef；port 默认为 22。hostKey 必须是一行 OpenSSH 公共主机密钥（algorithm base64），从已知主机或其他可信渠道获取，且没有选项前缀。

worker 上必须已安装具有 WAL 重置安全 SQLite 的受支持 Node 运行时（24.16+ 或 26.1+）。可选的 "npm" 方法还要求 npm 以及对公共 npm 注册表的出站 HTTPS 访问。联网工具链设置属于提供商策略；引导过程会报告可操作的错误，而不是自行安装工具链。

基于 Node 的 worker-turn 会启动自包含的 worker 循环，并通过 Gateway 代理模型推理。基于 Node 或基于 SSH 的 remote-exec 会将模型循环保留在 Gateway 上，并将沙箱操作路由到远程主机。基于 Node 的 Codex 接受进程、文件系统、能力以及无凭据 HTTP 操作；已认证 HTTP 会在到达节点之前被拒绝。两种模式都会通过持久化放置生命周期协调会话工作区和转录。断开的基于 Node 的 Codex 尝试是终态；重新连接只允许全新尝试，绝不恢复进程或流。

每个持久化环境记录都会在创建时的配置快照中保留其已验证的提供商设置和已解析的安装方法。更改或删除命名配置会影响新创建；只要所属插件仍然可用，现有记录会继续使用该快照进行生命周期协调。

默认 gateway.reload.mode: "hybrid" 下，配置文件和资源池变更无需重启 Gateway 即可生效。新分配会使用更新后的配置文件；现有分配保留其已准入的提供商设置。未使用的预留资源会对照当前配置文件和资源池限制进行检查，不兼容或超额的工作节点会在其提供商工作结束后退役。Suspend-after 变更会在现有空闲会话的下次自动排空之前应用于这些会话。若 reload mode 为 "off"，请重启 Gateway 以加载配置变更。