跳转至

Cloud Workers

Cloud workers 将会话的编码工作转移到一次性云机器上,而会话在侧边栏中保持可见,其会话记录仍归 Gateway 所有。随附的 Crabbox provider 会启动机器,运行 profile 设置,并启动 openclaw connect --ephemeral。对于启用了预热镜像且源自 Gateway 的项目,它会在注册节点前准备好已提交的 checkout 和节点运行时以供捕获。一个配置好的 Crabbox profile 可以通过同一个已注册的出站节点传输同时支持 OpenClaw worker-turn 和 Codex remote-exec。OpenClaw 启动受限的 openclaw worker 子进程;Codex 在节点上运行其受管 exec-server,同时将 app-server 和模型认证保留在 Gateway 上。

注册由环境持有,并且可重放。Gateway 在节点注册前持久化一个 setup 身份,将第一个经过身份验证的设备身份绑定到该确切环境,并在置备恢复时复用持久的设备令牌。初始注册和重放都只针对该节点进程启用 worker 托管;它们不会改变持久的 worker-host 配置。回收或销毁会释放云租约,并移除属于该环境的节点配对。如果置备在返回租约之前失败,清理会解析原始操作的句柄,而不会重新运行置备、setup 或注册。该句柄可能指向一个从未创建机器的操作;清理只在 provider 确认释放或不存在之后完成。拆除会等待进行中的 provider 操作和心跳进程稳定下来。Crabbox 的 release 请求和清理观测有各自的截止时间;OpenClaw 在终止停滞的 stop 命令之前会同时预留这两者。

当工作完成(或机器失效)时,机器会被丢弃。会话记录、被接受的工作区更改和放置记录仍留在 Gateway。

云会话可以从 GitHub 仓库 URL 和可选 ref 开始,而无需 Gateway checkout。所选节点会获取仓库,固定解析出的 commit,并创建会话分支。Gateway 保留源代码元数据和被接受更改的不可变检查点,而不是一份检出的副本。OpenClaw 和 Codex 都支持在受管云节点和配对节点上执行此流程;仅具备 SSH 传输层的 provider 无法准备纯仓库会话。节点主机运行时和 worker bundle 都必须是最新的:较旧的主机无法完成所需的工作区排空,因此仍会被隔离。更新配对节点主机或重新置备 cloud worker,然后重试。

从现有 Gateway checkout 创建的会话仍保留其会话自有的受管工作树镜像。该流程保留本地且未发布的源代码内容。其默认数量 100 是清理目标,而不是准入上限,并且 Gateway 磁盘空间检查仍然适用。

选择 New workspace 可在不提供仓库的情况下从空工作区开始。OpenClaw 会创建一个隔离的会话工作区,带有自己的内部 Git 元数据,并具备相同的受管快照、回收、恢复和清理行为。它不会复制 agent 的常规工作区。Git 仍然是内部依赖项,但不需要用户仓库或初始提交。

缺少 setup 环境值、当前 Crabbox CLI/后端拒绝,或 provider 元数据发生变化,都不能证明之前的尝试没有分配任何资源。这些失败仍可使用原始操作身份重试。清理会解析该操作的句柄,并重试拆除,直到 provider 确认已释放或不存在;它绝不会重新运行置备、setup 或注册来发现租约。格式错误且不可变的 profile 仍然会永久失败;策略和 setup 拒绝只有在确认清理完成后才会变为永久性的。

Note

Cloud workers 为选择启用功能。在配置 profile 之前,客户端会隐藏 Cloud 目标,且 profile 调度不可用。sessions.dispatch 仍可能面向符合条件的配对设备目标进行通告。cloudWorkers 配置 schema 以及只读的 environments.list 和 environments.status 方法仍然可用于配置和环境发现。

每页涵盖内容

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

在哪里运行

关注点 OpenClaw worker-turn 模式 Codex remote-exec 模式
代理运行时和回合循环 云盒(openclaw worker) 网关(Codex app-server)
Shell 命令和工作区文件 云盒 云节点、配对设备或基于 SSH 的提供商
模型推理和提供商身份验证 网关,通过 {provider, model} 引用进行代理 网关,包括 ChatGPT 订阅或 API 密钥身份验证
转录和实时会话状态 网关,由 worker 的可重放事件流提供 网关,通过常规本地 harness 路径
工作区文件状态 在盒子上更改;由网关协调 在远程更改;由网关协调

OpenClaw 用于网页搜索、网页抓取、记忆和消息的工具在网关上执行,遵循会话的预配置策略和实时权限。由命令或应用程序发出的 HTTP 请求仍在其部署位置执行。

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

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

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

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

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

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

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

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

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

要求

  • 一个 worker 提供商插件。捆绑的 crabbox 插件驱动 Crabbox CLI;Crabbox 拥有受支持的云后端及其配置。该插件会自动为网关用户准备其支持的 CLI,将受管发行版与操作员安装的二进制文件分开。它还可以使用来自 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 仓库的访问。任意的普通网关文件夹不会被复制或调度;请改为选择新的工作区。

Crabbox 提供商支持

如果一次新的分配以完全相同的 provider=<backend> does not support fixed idempotent lease IDs 能力拒绝退出,则会永久失败,并且不会为不存在的租约安排清理。请选择支持固定租约 ID 的后端。在重放期间出现相同的拒绝并不能否定更早的分配,因此其清理责任会一直保留,直到确认释放或确认不存在。

通过 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 并不能证明后端支持。心跳支持可在配置的闲置策略下保持已放置的工作节点存活。可选的桌面和预热镜像功能具有额外要求,详见 预热镜像 和 云工作节点桌面。

当所选后端支持时,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 环境变量或配置提供主机固定以及所需的协调器管理员身份验证。切勿将 broker 凭据放入 OpenClaw 配置文件设置中。有关按会话覆盖,请参阅 操作系统选择。

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

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

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

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

配置

在 Control UI 的 设置 → 连接 → 云工作节点 下管理配置文件,或直接编辑 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 安装,在首次启动时等待 cloud-init 完成后再处理软件包,当 Node 缺失或不受支持时安装 Node.js 24(包括降级不受支持的新版 APT 软件包),就地升级在 PATH 中遮蔽 Node 的 nvm 安装,并在缺失时安装 GitHub CLI。apt 锁超时可防止在首次启动时仍在运行的包管理器导致分发失败。它会在注册前重新检查 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 2>&1 && 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  node_path=\"$(command -v node 2>/dev/null || true)\"; case \"$node_path\" in */nvm/*) shadow_nvm=\"${node_path%%/nvm/*}/nvm\";; *) shadow_nvm=\"\";; esac\n  nvm_sh=\"\"; for d in \"$shadow_nvm\" \"${NVM_DIR:-}\" /usr/local/nvm /usr/local/share/nvm \"$HOME/.nvm\"; do [ -n \"$d\" ] && [ -s \"$d/nvm.sh\" ] && { nvm_sh=\"$d/nvm.sh\"; break; }; done\n  if [ -n \"$nvm_sh\" ]; then\n    # An nvm-managed Node earlier on PATH would shadow an apt-installed one; upgrade it in place.\n    export NVM_DIR=\"$(dirname \"$nvm_sh\")\"; . \"$nvm_sh\"; nvm install 24 >/dev/null; nvm alias default 24 >/dev/null; hash -r\n  elif command -v apt-get >/dev/null 2>&1; then\n    command -v cloud-init >/dev/null 2>&1 && sudo cloud-init status --wait >/dev/null 2>&1 || true\n    export DEBIAN_FRONTEND=noninteractive\n    curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -\n    sudo apt-get -o DPkg::Lock::Timeout=600 install -y --allow-downgrades 'nodejs=24.*'\n    hash -r\n  else\n    printf '%s\\n' 'Worker setup: no apt-get or nvm; cannot install Node.js 24 on this image.' >&2; exit 1\n  fi\nfi\nnode_supported || { printf 'Worker setup requires Node.js 24.16+ or 26.1+; PATH resolves %s (%s). Remove or upgrade the shadowing installation.\\n' \"$(command -v node || echo none)\" \"$(node --version 2>/dev/null || echo unknown)\" >&2; exit 1; }\nnpm --version\ncommand -v gh >/dev/null 2>&1 || { (sudo apt-get -o DPkg::Lock::Timeout=600 update && sudo apt-get -o DPkg::Lock::Timeout=600 install -y gh) || true; }\n\n"
        }
      }
    }
  }
}

配置文件字段:

键 含义
provider 由插件注册的 Worker 提供商 id(捆绑插件为 crabbox)。
install 基于 SSH 的提供商的安装偏好。捆绑的 Crabbox 提供商会从当前 Gateway 的运行时工件引导节点,然后在需要时安装 worker bundle,复用匹配的预置镜像归档,或通过已认证节点通道下载它。
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 可选。在注册前捕获已准备好的项目和 Node 运行时,然后从该镜像启动该项目和配置文件的后续 worker。仅支持 Linux。当已知配置或放置类,并且 setupEnv 为空或省略时默认启用;显式设置为 true 或 false 可覆盖。请将其与 suspendAfter 配合使用,以便挂起的会话可以热唤醒。镜像会产生提供商快照存储费用。有关捕获边界、刷新和先决条件,请参阅 热镜像。

每个章节迁移到哪里

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

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