配置 — 云工作器环境
cloudWorkers.* 下的云工作器环境键。
有关完整键索引和其他顶层配置域,请参阅 配置参考。
云工作器环境¶
云工作器是可选加入的。如果 cloudWorkers 不存在,或 profiles 为空,OpenClaw 不会接受新的云工作器创建,也不会公布云目标。sessions.dispatch 仍可对符合条件的已配对设备目标保持可用。配置模式以及只读的 environments.list 和 environments.status 方法仍然可用。先前创建的持久化记录仍会重新协调并保持可见;现有的网关/节点投影保持不变。
基于 SSH 的 remote-exec 提供程序必须返回可信的 hostKey,其格式必须严格为 algorithm base64,不能包含主机名或注释。Bootstrap 会将该键写入独立的 known_hosts 文件,使用 StrictHostKeyChecking=yes,并且当提供程序省略该键时,会在打开连接之前失败。不存在首次使用时信任的回退机制。这些提供程序还通过独立的固定 SSH 连接传输工作区流量,因此 rsync 不会阻塞控制流量。
基于节点的提供程序会为 worker-turn 或 remote-exec 返回一个经过身份验证的节点设备 ID。Gateway 会安装当前固定的捆绑包,并通过节点传输通道传送工作区;这些租约不会返回或解析 OpenClaw SSH 端点凭据。worker-turn 需要节点租约,并启动一个受限的 OpenClaw 工作器子进程。remote-exec 可以使用已注册的节点或现有的基于 SSH 的提供程序,并将执行框架和模型身份验证保留在 Gateway 上。
必需的工作器配置文件¶
当 Gateway 必须在某个 OpenClaw 工作器配置文件上运行每个代理会话时,请将 cloudWorkers.requiredProfile 设置为已配置的配置文件 ID。这是一项服务器策略,而不是供位置选择器使用的建议值。保持未设置状态即可保留可选的按会话放置和 Gateway 本地执行。
{
cloudWorkers: {
requiredProfile: "dedicated-native",
profiles: {
"dedicated-native": {
provider: "device",
settings: { device: "PAIRED_DEVICE_ID", inference: "worker" },
},
},
},
}
新建会话和必需的首轮恢复通过 agents.list(带有 includeSessionPlacement: true)读取目标指令。该投影对会话范围内的写入者可用,并且仅包含必需配置文件的标识、推理位置以及支持的必需执行模式——不包含工作器清单、机器选项、端点设置或命令授权。普通的 agents.list 回复保持不变。控制界面显示必需目标,但不提供位置、操作系统或机器选择器。必需放置使用 OpenClaw worker-turn 运行时;仅支持 remote-exec 的提供程序无法满足此策略。普通会话创建使用由服务器拥有的放置流程;用户无需获得选择或管理云工作器的权限。手动放置管理保留其现有权限。
Gateway 也会对 API 和渠道轮次强制执行该策略。当未选择仓库时,它会准备一个会话拥有的空工作区,使用现有的持久化调度/恢复流程,并且如果放置失败,则不会在本地运行该轮次。配置文件缺失或工作器断开连接是可处理的错误,而不是回退到 Gateway 推理。即使所需配置文件尚不可用,Gateway 仍可启动,以便操作员可以注册或修复节点。
现有的放置会保留其记录的工作区和工作器标识。更改必需配置文件不会静默迁移它们。如果失败的放置引用了缺失的环境记录,请在重试前修复该记录:Gateway 无法证明其原始配置文件,也不会自动选择新的配置文件。停止和恢复保留正常的放置生命周期;停止工作器并不会授权本地轮次。
无会话模型辅助工具和本地 CLI 执行无法绕过该策略。
此设置选择的是执行方式,而非提供程序凭据或操作系统沙箱。对于仅限节点的凭据,请按照 工作器本地推理 中的说明配置必需配置文件和节点。
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(必填):传递给--ttl和--idle-timeout的正 Go 持续时间字符串,作为提供商侧的故障保护。settings.warmImage:在注册前,为项目的已提交检出和节点运行时准备捕获,然后让该项目和配置项后续的 worker 从镜像启动。空的已提交 Git 树会跳过项目准备及其 pack 传输,改为共享该配置项的运行时镜像。如果没有已准备的 Git 项目,捕获将保留到符合条件的 worker 拆除时进行。与suspendAfter搭配使用,使挂起的会话能够以预热状态唤醒。当已知配置类或放置类,并且setupEnv为空或省略时,默认启用。如果没有有效类,省略时保持冷启动。非空的setupEnv会保持默认冷启动,因为转发的宿主环境可能将 setup 派生的凭据留在共享镜像中。显式true表示启用,但要求在提供商命令之前已知有效类;显式false始终保持冷启动。解析后的类和原始的冷启动/检查点选择在分配前记录,并在重试和重启过程中保持固定。镜像会产生提供商快照存储费用,并保留机器级缓存,包括原始 Git 种子,以及setup在已清理 worker 状态之外写入的任何内容。清理具有三分钟超时。检查点创建在 Crabbox 的原生捕获预算加上命令、源生命周期和子进程结算宽限内等待;它不会延长配置的租约 TTL 或空闲超时。不确定的项目捕获会阻止其源上的注册,但仍允许租约清理。有关刷新、保留以及 Doctor 迁移和恢复,请参阅 预热镜像。settings.binary:可选的 Crabbox 可执行文件绝对路径。未设置时,OpenClaw 会检查同级 Crabbox 检出,然后检查PATH上的可执行项。该插件要求所有目标都使用 Crabbox 0.73.0 或更高版本,包括 Daytona 固定 ID 准备、重放和已确认清理。如果所选二进制文件缺失、过旧或无法报告受支持的版本,插件会将受支持的版本下载到其自身位于$OPENCLAW_STATE_DIR/tools/crabbox下的带版本号目录中(默认为~/.openclaw/tools/crabbox)。在使用该副本之前,它会验证官方发布校验和可执行文件版本。现有二进制文件和配置项设置会被保留。后续命令会复用受管安装,而不会再次下载。损坏的受管安装会被自动替换;旧目录会保留在替换目录旁边,并带有.recovery-<id>后缀以供检查。openclaw doctor --fix会在首次 worker 操作之前安装受管副本。安装失败会在分配前停止操作并报告原因。readyWorkers:每个符合条件的本地项目或仓库以及配置项的非负整数目标;默认为1。设置为0可禁用该配置项的预留,同时保留预热镜像复用。cloudWorkers.preparedPool.maxTotal:整个 Gateway 范围的预留上限,为非负整数;默认为4。准备中的 worker 和未确认的清理会计入这两个限制。设置为0可排空未使用的预留并停止补充。预留会产生运行中机器费用,并在使用提供商现有空闲策略的情况下,因成功的项目需求而过期。请参阅 就绪 worker。
受管发布归档会先流式传输到私有暂存文件中,大小限制为 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 的 云 worker 生命周期要求。
Crabbox 设置使用环境拥有的一次性配对凭据和已配置的公共 Gateway URL。提供商返回确切的已认证节点 ID;然后 Gateway 安装其当前捆绑包,并通过已认证节点路由传输工作区。对于 Codex 远程执行,Crabbox 会在节点的私有状态中准备捆绑的 Codex 插件和固定版本的受管二进制文件,并且 Gateway 要求每次尝试都使用明确允许的 codex.exec-server.stdio.v1 命令以及关键的一次性允许审批。该模式下不使用 OpenClaw worker 子进程或 worker 插槽。OpenClaw 不会持久化 Crabbox SSH 端点、密钥、主机密钥或回退端口输出。
Note
AWS 准入要求 providerMetadata.instanceProfileAttached 为 false。
Crabbox 机器目录¶
OpenClaw 将 Crabbox 目录映射为机器选项,规则如下:
- 来源和架构: 仅当
classCatalog.disposition为mapped时,从crabbox providers --json读取classCatalog.profiles。对于每个目标,如果可用则优先选择 amd64 条目;否则保留 mixed 或 arm64 条目。 - 顺序和默认值: 最多包含 64 个选项,按可注册的操作系统排序,然后按目录顺序排序。为每个操作系统分别将已配置的 class 标记为默认值。无 class 的配置没有虚构的默认值。
- 维度: 独立报告 vCPU 和 RAM。在 Crabbox 的摘要契约下,RAM 接受正整数 GB/GiB 值;其他单位、小数以及缺失的维度保持未知。具有
mixed架构且维度缺失的 macOS 条目仍然可选。切勿从原生类型名称推断维度。 - 不可用元数据: 未映射、缺失、未知、失败、空或不可用的元数据不会生成机器选择器,即使存在旧版
classes也是如此。该配置仍然可选;在不覆盖的情况下进行 dispatch 或 Move 会保留其配置。
静态 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 的命名工作节点配置。每个配置选择由插件注册的提供者。provider:非空的工作节点提供者 ID。示例使用内置的crabbox提供者和 QA Lab 的static-ssh提供者。install:基于 SSH 的remote-exec工作节点安装方法。"bundle"(默认)传输网关已安装构建的内容哈希包,并支持已发布、开发版和未发布版本。"npm"是针对未修改的打包发布版本的可选优化;它从公共 npm 注册表安装openclaw@<exact gateway version>,并且从不安装latest。基于 Node 的worker-turn和remote-exec提供者改为通过 node 传输安装固定版本的 Gateway 包。suspendAfter:可选的配置级时长,例如45m、90m或2h;最小值为1m。当会话空闲达到该时长后,Gateway 会安全回收工作节点。下一条消息会预配替代节点;如果存在镜像,则为热启动。省略此字段可让工作节点持续运行,直到显式停止。- 内置提供者插件在配置后会自动选择,但显式禁用和
plugins.allow仍然适用。当配置了允许列表时,请包含提供者 ID(例如crabbox)。外部提供者插件还必须安装并显式启用。 settings:由提供者拥有的有界 JSON。所选插件定义并验证其键;对于包含秘密的值,请使用 SecretRef 对象。静态 SSH 提供者要求host、user、hostKey和keyRef;port默认为22。hostKey必须是来自已知主机或其他可信渠道的一条 OpenSSH 公共主机密钥行(algorithm base64),且没有选项前缀。
工作节点上必须已安装受支持的 Node 运行时(24.16+ 或 26.1+)以及支持 WAL 重置安全的 SQLite。可选的 "npm" 方法还要求 npm 以及对公共 npm 注册表的出站 HTTPS 访问。联网工具链设置属于提供者策略;bootstrap 会报告可操作的错误,而不是自行安装工具链。
基于 Node 的 worker-turn 会启动自包含工作节点循环,并默认通过 Gateway 代理模型推理。具有 settings.inference: "worker" 的设备提供者配置则使用 工作节点本地原生推理 和节点本地提供者凭据。基于 Node 或基于 SSH 的 remote-exec 会将模型循环保留在 Gateway 上,并将沙箱操作路由到远程主机。基于 Node 的 Codex 接受进程、文件系统、能力以及无凭据 HTTP 操作;已认证 HTTP 会在到达节点之前被拒绝。两种模式都通过持久化放置生命周期协调会话工作区和转录。已断开的基于 Node 的 Codex 尝试是终态的;重新连接只允许新的尝试,绝不恢复进程或流。
每个持久化环境记录都会在其创建时的配置快照中保留经过验证的提供者设置和已解析的安装方法。更改或删除命名配置会影响新创建;只要所属插件仍然可用,现有记录会继续使用该快照进行生命周期协调。
使用默认的 gateway.reload.mode: "hybrid" 时,配置和池更改会在不重启 Gateway 的情况下生效。新分配使用更新后的配置;现有分配保留其已准入的提供者设置。未使用的预留会针对当前配置和池限制进行检查,不兼容或超出的工作节点会在其提供者工作结束后退役。suspend-after 更改会在现有空闲会话的下次自动排空前应用于这些会话。当 reload 模式为 "off" 时,请重启 Gateway 以加载配置更改。
Warning
static-ssh 提供者是源代码树中的 QA Lab remote-exec 测试框架,不包含在打包发行版中。运行在其共享主机上的工作节点可以读取无关的主机数据,因此请勿将此提供者用作生产隔离边界。
其操作者必须提供预期的 hostKey;OpenClaw 不会从首次连接学习或接受密钥。
销毁其租约只会释放 OpenClaw 的逻辑记录;它不会停止或清理主机。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw