Cloud Workers

云工作器会将某个会话的编码工作转移到一次性云机器上，同时该会话仍显示在侧边栏中，其转录记录仍由 Gateway 拥有。内置的 Crabbox 提供商会启动该机器，运行配置文件设置，并启动 openclaw connect --ephemeral。对于启用预热镜像的 Gateway 源项目，它会在注册节点之前，为捕获准备已提交的检出和节点运行时。一个已配置的 Crabbox 配置文件可通过同一已注册的出站节点传输，同时支持 OpenClaw worker-turn 和 Codex remote-exec。OpenClaw 会启动一个受限的 openclaw worker 子进程；Codex 会在节点上运行其托管的 exec-server，同时让 app-server 和模型身份验证保留在 Gateway 上。

注册由环境拥有且可安全重放。Gateway 会在节点注册之前持久化一个设置身份，将首个经过身份验证的设备身份绑定到该确切环境，并在配置恢复时复用持久设备令牌。初始注册和重放都只为该节点进程启用工作器托管；它们不会更改持久工作器主机配置。回收或销毁会释放云租约，并移除环境拥有的节点配对。如果配置在返回租约之前失败，清理会解析原始操作的句柄，而不会重新运行配置、设置或注册。该句柄可能指向一个从未创建机器的操作；清理只有在提供商确认释放或不存在后才完成。拆除会等待进行中的提供商操作和心跳进程稳定下来。Crabbox 的释放请求和清理观察具有独立的截止时间；OpenClaw 在终止停滞的停止命令之前会同时预留两者。

当工作完成（或机器失效）后，该机器会被丢弃。转录记录、已接受的工作区更改和放置记录仍保留在 Gateway 中。

云会话可以从 GitHub 仓库 URL 和可选 ref 启动，而无需 Gateway 检出。所选节点会获取仓库，固定已解析的提交，并创建会话分支。Gateway 会保留源元数据和已接受更改的不可变检查点，而不是保留一份检出的副本。OpenClaw 和 Codex 都支持在托管云节点和配对节点上使用该流程；仅具有 SSH 载体的提供商无法准备仅仓库会话。节点主机运行时和工作器捆绑包都必须为最新：较旧的主机无法完成所需的工作区排空，并会保持隔离状态。请更新配对节点主机或重新配置云工作器，然后重试。

从现有 Gateway 检出生成的会话仍保留其会话拥有的托管工作树镜像。该流程会保留本地和未发布的源内容。其默认数量 100 是清理目标，而不是准入上限，并且其 Gateway 磁盘空间检查仍然适用。

选择 新建工作区 以在不提供仓库的情况下从空状态开始。OpenClaw 会创建一个隔离的会话工作区，具有其自身的内部 Git 元数据，以及相同的托管快照、回收、恢复和清理行为。它不会复制代理的常规工作区。Git 仍然是内部依赖项，但不需要用户仓库或初始提交。

缺失的设置环境值、当前 Crabbox CLI/后端的拒绝，或已更改的提供商元数据，并不能证明较早的尝试未分配任何资源。这些失败仍可基于原始操作身份进行重试。清理会解析该操作的句柄，并重试拆除，直到提供商确认释放或不存在；它绝不会重新运行配置、设置或注册来发现租约。格式错误的不可变配置文件仍会永久失败；策略和设置拒绝只有在确认清理之后才会变为永久。

Note

云工作器为可选启用。在配置配置文件之前，客户端会隐藏云目标，且配置文件分发不可用。sessions.dispatch 仍可能为符合条件的配对设备目标进行通告。cloudWorkers 配置架构以及只读的 environments.list 和 environments.status 方法仍可用于配置和环境发现。

各页面涵盖的内容¶

云工作器预热镜像 — 捕获边界、镜像复用与刷新、快照固定、删除与回滚、保留策略，以及恢复暂停的捕获或旧版预热镜像状态。
按项目默认配置文件 — cloudWorkers.projectProfiles，以及固定的 Crabbox 租约 ID 如何使中断的配置可重放。
工作器设置与捆绑包安装 — 幂等的 settings.setup 契约、Gateway 准备好的运行时归档，以及构建完整的自定义节点包。
验证云工作器配置文件 — 配置验证、应用更改、Codex 命令启用，以及在依赖配置文件之前进行的端到端检查。
分发云会话 — 资格门槛、全新工作区和仓库选择、云子会话，以及哪些运行时支持云放置。
放置与机器选择 — 配对设备上的 Codex、Crabbox 配置文件上的任一框架，以及按会话的操作系统和机器类别覆盖。
云会话生命周期与持久性 — sessions.dispatch 的作用、工作区协调与冲突、移动、停止与回收、恢复，以及机器失效后仍保留的内容。
云工作器桌面 — 桌面实验室和 settings.desktop、Crabbox 配置的内容，以及查看器如何在没有公共入站访问的情况下访问它。
云工作器安全模型 — 封闭的工作器入站访问、Gateway 拥有的工具权限、铸造的凭据、注册绑定和凭据边界。
云工作器故障排查 — 通告、授权、引导、注册、协调、发布和拆除的症状与修复方法。

在哪里运行¶

关注点	OpenClaw `worker-turn` 模式	Codex `remote-exec` 模式
Agent 运行时和轮次循环	云盒（`openclaw worker`）	Gateway（Codex app-server）
命令、文件系统与 HTTP 操作	云盒	云节点、配对设备或 SSH 支持的提供商
模型推理和提供商身份验证	Gateway，通过 `{provider, model}` 引用进行代理	Gateway，包括 ChatGPT 订阅或 API 密钥身份验证
转录和实时会话状态	Gateway，由 worker 的可重放事件流提供	Gateway，通过常规本地 harness 路径
工作区文件状态	在云盒上变更；由 Gateway 协调	在远程变更；由 Gateway 协调

自行发起模型 API 调用的应用需要单独的凭据路由。对于独占拥有的、由协调器支持的 Linux 租约，使用 openclaw crabbox run 将已配置的 API 密钥保留在主机上，同时应用使用受保护的出口桥接。

捆绑的 Crabbox 云提供商通过其已注册节点传输同时通告 worker-turn 和 remote-exec，因此相同的云配置文件可供两种 harness 使用。Codex 也可以使用明确授权的配对设备，或保留 SSH 支持的远程执行载体的提供商。仅通告一种模式的配置文件对另一种运行时仍不可用。

在 Crabbox 设置完成后，云节点通过出站 WebSocket 拨号到 Gateway 的公共 TLS 端点。Worker 控制、Codex 远程执行和工作区传输使用经过身份验证的节点或 worker 通道，而不是 Gateway 创建的逆向隧道或 rsync。当 Crabbox 的 CLI 运行提供商拥有的设置命令时，Crabbox 本身可能仍需要 SSH 可达性。出站互联网访问和设置可达性遵循所选后端的网络策略；在 Crabbox 中配置它们。

OpenClaw worker-turn 会话可以在基于节点的云 worker 上打开门户，包括捆绑的 Crabbox 提供商。对于每个代理的 HTTP 或 WebSocket 连接，已注册节点通过 TLS 固定的 WebSocket 向 Gateway 兑换一次性票据，并连接到 worker 选定的回环端口。这保留了现有 Control UI → Portals 体验、身份验证和实时重新加载，而无需开放入站 worker 端口或创建 SSH 隧道。只有当节点通告 portal-stream 支持时，该工具才可用；较旧的节点捆绑包不会获得它。SSH 支持的 remote-exec 部署（包括 Codex 会话）不会运行 OpenClaw worker 工具循环，因此 portal 工具在那里不适用。当需要 Gateway 托管的门户时，更新不支持的节点，或使用 sessions.move 将会话移回 Gateway。

对于位于公共 HTTPS 入口后面的回环 Gateway，将 gateway.publicOrigin 设置为代理的裸源。云节点注册会明确请求共享配对解析器优先使用公共入口：plugins.entries.device-pair.config.publicUrl 优先，然后是 gateway.publicOrigin，再然后是现有的远程/Tailscale/绑定发现。这保留了云注册行为，并避免在配置了公共源时将新 worker 引导到私有 LAN 或 tailnet 地址。目标为本地 Gateway 的调用方省略远程 URL。HTTP(S) URL 会变成匹配的 ws:/wss: 配对端点。

设备加入代码、/pair 和 openclaw qr 使用同一解析器的默认意图，保留其通告的地址：配对覆盖、首选远程 URL、Tailscale Serve/Funnel、非首选远程 URL，然后是绑定派生地址。它们仅在仅限回环错误之前将 gateway.publicOrigin 用作最终回退，因此添加公共源不会更改现有设备配对路由。

云调度在分配机器之前会拒绝回环、链路本地或未指定的 Gateway 地址。如果任一公共 URL 位于反向代理后面（包括 cloudflared、nginx 或外部管理的 Tailscale Serve），gateway.trustedProxies 必须包含代理的源地址（对于同主机代理通常为回环）。否则，转发的客户端头会导致节点注册失败，并返回 proxy_attribution_required。

代理还必须将 /__openclaw__/worker-bootstrap/artifacts/<sha256> 转发到 Gateway，与其公共节点和 worker 路由一起。新的云节点在能够通过 WebSocket 连接之前，会通过此经过身份验证的 HTTP 路由下载其运行时。保留 Authorization 头；不要通过未经身份验证的静态文件路由公开这些归档。

节点和 SSH 工作区访问及协调会持续到 worker RPC 凭据过期之后，因此空闲会话仍可以安全地停止、移动或挂起。两者都保留现有的吊销和所有者纪元检查；节点传输也保留其自身的十分钟过期和会话所有权检查。

要求¶

Worker 提供商插件。捆绑的 crabbox 插件驱动 Crabbox CLI；Crabbox 拥有受支持的云后端及其配置。该插件会自动为其支持的 CLI 准备 Gateway 用户，将受管发行版与操作员安装的二进制文件分开。它也可以使用来自 PATH 或 settings.binary 的支持的可执行文件。有关版本要求、Doctor 准备和受限主机升级，请参阅 Crabbox 配置。
对于 Crabbox AWS worker，有效的 aws.instanceProfile 必须为空。提供商在分配前检查 crabbox config show --json，然后要求 crabbox inspect --json 报告来自 EC2 DescribeInstances 的 providerMetadata.instanceProfileAttached: false。具有实例角色或缺少权威元数据的租约会停止并被拒绝。本地 CLI/配置准备失败会在分配边界之前结束，并且不会为非存在的租约留下清理请求。分配请求之后的失败仍保留其确切的清理所有者，直到 Stop 证明释放。
租约机器上受支持的 Node.js 版本和 npm。裸云镜像可能缺少它们——通过镜像、Crabbox 引导或配置文件的 setup 命令提供它们。原生 Windows 要求机器 PATH 上有 Node 和 npm。无头 Windows worker 还需要 Crabbox 的受管分离进程启动器；请参阅 Windows 先决条件。OpenClaw 不安装 Node。机器还需要注册表访问权限，以安装其操作系统和 CPU 的运行时依赖项。
Worker 的 PATH 上需要 GitHub CLI（gh），用于 GitHub 命令和 HTTPS 推送。密封的 worker 捆绑包包含凭据绑定启动器，而不是 GitHub CLI。Crabbox 开发者镜像包含 gh；对于其他镜像，请在 settings.setup 中安装它。
使用 repository: { url, ref? } 创建的仓库会话，或使用 worktree: true 创建的实时、注册表拥有的会话托管 worktree。添加 worktreeSource: "empty" 可在没有用户仓库的情况下创建新工作区。仓库源需要受管节点以及对上游 Git 仓库的访问权限。任意的普通 Gateway 文件夹不会被复制或分发；请改为选择新工作区。

Crabbox 提供商支持 ¶

使用 settings.provider 选择 Crabbox 后端。有关支持的提供商、身份验证、规格、快照、网络以及提供商特定限制，请参阅 Crabbox 提供商参考。OpenClaw 不维护单独的后端目录；接受配置文件并不表示该后端可以托管云会话。

已安装的 Crabbox 版本和所选后端必须支持固定 ID warmup --lease-id、用于设置和注册的通过 run --script-stdin 的目标原生脚本执行、租约检查，以及通过规范租约 ID 进行拆除。脚本在原生 Windows 上使用 PowerShell，在 Linux、macOS 和 Windows (WSL2) 上使用 POSIX shell。切勿移除 --lease-id 以绕过后端能力拒绝：它可防止中断的调度后发生重复分配。OpenClaw 会保留不受支持后端的诊断信息；仅升级 CLI 并不能建立后端支持。心跳支持使已放置的工作器在配置的闲置策略下保持存活。可选的桌面和预热镜像功能具有额外要求，描述于预热镜像和 Cloud Worker Desktop。

当所选后端支持时，Crabbox 会通告 Linux、Windows (WSL2)、Windows 和 macOS。插件在读取后端目录之前会准备受支持的 CLI。Windows 指原生 Windows（windows/normal），使用 PowerShell 设置命令。桌面支持 Linux、原生 Windows 和已准备的 macOS 镜像；不支持 WSL2 桌面。预热镜像仍仅限 Linux。参见桌面先决条件。AWS macOS 工作器需要可用的 EC2 Mac Dedicated Host，并使用按需分配。对于固定的 Dedicated Host，请通过 Gateway 主机上的 Crabbox 环境变量或配置提供主机固定和所需的协调器管理员身份验证。切勿将代理凭据放入 OpenClaw 配置文件设置中。有关每个会话的覆盖设置，参见操作系统选择。

为运行 Gateway 的操作系统用户配置 Crabbox。对于协调器访问，请遵循其身份验证指南；对于直接凭据，请遵循所选提供商的指南。请勿将凭据放入 OpenClaw 配置文件设置和命令参数中，并在 Gateway 重启之间保留 Crabbox 的状态目录，以便分配和清理可以安全恢复。

检查已安装的提供商契约，并在不分配机器的情况下检查就绪状态：

crabbox providers --json
crabbox providers describe <backend> --json
crabbox doctor --provider <backend> --json

只读就绪状态不能证明分配、设置、注册或清理。在依赖新配置文件之前，请验证完整的会话流程；参见验证配置文件。

配置¶

在控制界面的 设置 → 连接 → 云工作器 下管理配置文件，或直接编辑 openclaw.json 中的 cloudWorkers.profiles — 两者写入相同的配置键。设置页面以通俗语言列出每个配置文件的后端、类别、生命周期和闲置停止，并显示其是否通告到 environments.list。保存的更改无需重启 Gateway 即可生效。当 gateway.reload.mode: "off" 时，从此页面保存会重启 Gateway 以应用更改，而直接编辑 openclaw.json 则需等待手动执行 openclaw gateway restart。未配置任何配置文件时，它会说明该功能、链接回此页面，并启动添加流程。

机器类别 在基于类别的编辑器中为必填项。输入所选 Crabbox 后端和二进制文件接受的类别；提供商决定其有效规格。更改后端或二进制文件不会更改类别，因此保存前请验证其是否被接受。要配置无类别配置文件，请使用 设置 → 高级 并省略 settings.class；对现有无类别配置文件点击编辑会打开高级设置。然后 OpenClaw 会省略 --class，除非放置提供类别，从而将资源选择交给 Crabbox，而不声称默认大小。显式 null、空字符串或仅空白字符串，以及非字符串类别值均无效。

操作系统 选择器使用配置文件已通告的操作系统来设置 settings.target。当至少通告了两个系统，或已保存的目标不再被通告时，它会显示，这样你可以使用 提供商默认 清除它。捆绑的 Crabbox 提供商默认为 Linux，也接受 Windows (WSL2)、原生 Windows 和 macOS；参见操作系统选择。不可用的选项仍会显示提供商的修复提示，且无法选择。没有已通告目录的新配置文件不显示选择器。高级 JSON 保留相同设置。

在 openclaw.json 的 cloudWorkers.profiles 下添加配置文件。此 Debian/Ubuntu 安装示例会保留受支持的 Node.js 安装，在缺少 Node 或不受支持时安装 Node.js 24（包括降级不受支持的新版 APT 软件包），并在缺少时安装 GitHub CLI。它在注册前重新检查 Node 和 npm。当前运行时要求 24.x 系列中的 Node.js 24.16.0 或更高版本，或 26.1.0 或更高版本；Node.js 22 和 25 不受支持。

{
  "cloudWorkers": {
    "profiles": {
      "aws": {
        "provider": "crabbox",
        "install": "bundle",
        "suspendAfter": "45m",
        "settings": {
          "provider": "aws",
          "class": "standard",
          "ttl": "8h",
          "idleTimeout": "45m",
          "warmImage": true,
          "setup": "#!/usr/bin/env bash\nset -euo pipefail\nnode_supported() { command -v node >/dev/null && node -e 'const [major, minor, patch] = process.versions.node.split(\".\").map(Number); process.exit([major, minor, patch].every(Number.isInteger) && ((major === 24 && minor >= 16) || (major === 26 && minor >= 1) || major > 26) ? 0 : 1)'; }\nif ! node_supported; then\n  curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -\n  sudo apt-get install -y --allow-downgrades 'nodejs=24.*'\nfi\nnode_supported || { printf '%s\\n' 'Worker setup requires a supported Node.js version; inspect PATH and the package installation above.' >&2; exit 1; }\nnpm --version\ncommand -v gh >/dev/null || { sudo apt-get update && sudo apt-get install -y gh; }"
        }
      }
    }
  }
}

配置文件字段：

键	含义
`provider`	插件注册的 Worker 提供商 ID（捆绑插件为 `crabbox`）。
`install`	基于 SSH 的提供商的安装偏好。捆绑的 Crabbox 提供商会从当前 Gateway 的运行时工件引导节点，然后在需要时安装 Worker 捆绑包，复用匹配的预置镜像归档，或通过已认证的节点通道下载。
`suspendAfter`	可选的空闲时长，例如 `45m`、`90m` 或 `2h`；最小值为 `1m`。使用与手动回收相同的安全停止方式，自动挂起空闲 Worker。下一条消息会配置一个替代 Worker，如果存在快照，则以热状态启动。挂起期间，仅对保留的快照存储计费；省略此字段可让 Worker 持续运行，直到显式停止。
`settings`	由提供商拥有的 JSON。对于 crabbox：`provider`（后端）、`class`（机器类别）、`target`（操作系统）、`ttl`、`idleTimeout`（Go 时长）、可选的幂等 `setup`、可选的 `desktop`，以及绝对 `binary` 路径。当会话保持已放置状态时，OpenClaw 会以 `idleTimeout` 的安全比例对其租约进行心跳；拆除前会先停止心跳，再释放机器。`desktop: true` 会要求 Crabbox 在节点注册前，使用其浏览器和回环 RFB 桌面预热租约。
`settings.target`	默认操作系统：省略时为 `linux`，或 `windows/wsl2`、`windows/normal`、`macos`。放置可以提供 `os`；不支持的值会被拒绝。
`settings.warmImage`	可选。在注册前捕获已准备好的项目和节点运行时，然后从该镜像启动该项目和配置文件的后续 Worker。仅限 Linux。当已知配置类别或放置类别，且 `setupEnv` 为空或省略时默认启用；显式设置为 `true` 或 `false` 可覆盖。将其与 `suspendAfter` 配合使用，以便挂起的会话可以热唤醒。镜像会产生提供商快照存储费用。有关捕获边界、刷新和先决条件，请参阅热镜像。

每个章节移动到了哪里¶

此页面以前发布的每个标题都会在此保留其锚点，因此现有链接（例如 /gateway/cloud-workers#bundle-installation）仍然可以解析。每个条目都指向现在承载该内容的页面。

沙箱化 — 降低本地工具执行的影响范围
会话 CLI — 检查已存储的会话
配置参考
openclaw worker — Gateway 拥有的启动器在准备好的 worker 环境中启动的受限运行时入口点
Gateway RPC 方法 — RPC 方法族、发现以及事件族
操作员作用域 — 这些 worker 调用所授权的作用域

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

Cloud Workers

各页面涵盖的内容¶

在哪里运行¶

要求¶

Crabbox 提供商支持¶

配置¶

每个章节移动到了哪里¶

相关¶

Crabbox 提供商支持 ¶