云端工作节点

云端工作节点允许会话在一次性云端机器上运行其智能体循环，同时会话的所有相关内容仍保留在原处：在侧边栏中可见、实时流式传输，并且对话记录由 Gateway 网关所有。Gateway 网关租用一台机器，在其上安装固定版本的 OpenClaw，将会话的工作区同步过去，然后把轮次循环交给受限的 openclaw worker 进程。模型调用通过 Gateway 网关代理返回，因此提供商凭证绝不会离开你的机器；由于提供商看到的是一个连续的数据流，提示词缓存也能继续工作。

工作完成后（或机器故障时），该机器会被丢弃。持久状态——对话记录、工作区提交、放置记录——保留在 Gateway 网关一侧。

各部分在哪里运行

除 sshd 外，该机器不需要任何入站端口：Gateway 网关通过固定的 SSH 主动连接，反向隧道将工作节点的 WebSocket 传回。内置的 Crabbox 提供商强制使用公共 SSH 路由，并禁用托管式 Tailscale 注册。出站互联网访问由提供商策略决定；除非限制其网络或安全组，否则默认 AWS 个人资料可以访问互联网。

要求

• 一个工作节点提供商插件。内置的 crabbox 插件驱动 Crabbox CLI，该 CLI 代理跨云后端（AWS、Hetzner 等）的租约。crabbox 二进制文件必须位于 PATH 中（或设置 settings.binary），并且已配置提供商凭证。AWS 准入要求 Crabbox 0.38.1 或更高版本。
• 对于 Crabbox AWS 工作节点，有效的 aws.instanceProfile 必须为空。提供商在分配前检查 crabbox config show --json，然后要求 crabbox inspect --json 报告来自 EC2 DescribeInstances 的 providerMetadata.instanceProfileAttached: false。具有实例角色或缺少权威元数据的租约会被停止并拒绝。
• 租用机器上的 Node.js。裸云镜像通常不包含它——请在个人资料的 setup 命令中安装。
• 具有会话所有的托管工作树的会话（使用 worktree: true 创建）。调度会移动该工作树的内容；普通目录则同步为清单镜像。

配置

在 openclaw.json 的 cloudWorkers.profiles 下添加个人资料：

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

个人资料字段：

设置命令

settings.setup 在租用机器的 SSH 准备就绪后、安装 OpenClaw 之前运行。它会在每次预配尝试时运行（包括调度中断后的重放），因此必须具备幂等性——请像示例一样，使用 command -v/test -x 检查来保护安装操作。如果设置失败，提供商会停止租约，调度也会以关闭方式失败；不会留下仍在运行的半配置机器。

安装渠道

• bundle 会打包正在运行的 Gateway 网关的 dist、经过精简的 package.json，以及构建引用的所有工作区软件包，并用内容哈希覆盖全部内容。机器根据该哈希验证原始软件包，然后安装生产环境 npm 依赖项（禁用脚本）。这是在工作节点上运行开发构建的方式。
• npm 会验证该发布版本存在于公共注册表中，固定其 SHA-512 完整性值，并安装与 Gateway 网关完全匹配的 openclaw@<version>。

调度会话

在 Control UI 中，打开 New Session，选择配置的运行时为 OpenClaw 的智能体，从 Where 菜单中选择已配置的 Cloud · profile 目标，然后启动任务。选择云端目标会自动启用所需的托管工作树；Gateway 网关创建会话、完成调度，然后才发送第一个轮次。会话侧边栏中的服务器徽章会显示持久放置状态。外部 CLI 会话目录不提供云端目标。

等效的 RPC 流程如下：

创建一个具有托管工作树的会话，然后调度它（RPC 要求 operator.admin，并且仅在已配置个人资料时存在）：

云端工作节点运行 OpenClaw 智能体运行时。选择 openai/* 或其他可解析到该运行时的模型；配置为外部 CLI 运行时（如 claude-cli）的会话无法调度。

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"}'

sessions.dispatch 会关闭本地轮次准入、排空活动工作、预配租约、运行设置、引导 OpenClaw、同步工作区，并在放置达到 active 工作节点所有权后返回。第一次调度请预留几分钟；如果提供商支持，租约和安装会被缓存。之后，像往常一样与会话交互——轮次会自动路由到工作节点。

已完成的工作节点轮次会在释放轮次声明之前，将符合条件且大小受限的工作区文件协调回会话的托管工作树。终止工作节点事件在得到确认前会创建持久的待处理结果屏障，因此 Gateway 网关重启恢复会先拉回远程工作区，然后过期轮次清理才能销毁其所有者。协调过程会验证工作节点清单，并在本地出现分歧时停止，而不会覆盖任一侧。在更改文件之前，Gateway 网关会在其 SQLite 状态数据库中存储一个有界回滚日志；如果 Gateway 网关进程中断，重试会恢复该日志。工作区结果使用 Git 文件语义：保留常规文件、可执行位、符号链接、新增、修改和删除，而不保留空目录及其他目录模式。远程提交对象不会被保留；产生的文件更改会留在托管工作树中，以便进行常规审查和提交。

工作完成且没有轮次正在运行时，打开会话菜单并选择 Stop cloud worker…。Gateway 网关会在销毁环境前执行最后一次工作区协调。已处于 draining 或 reconciling 的放置正在完成拆除；请等待其徽章变为 reclaimed 后再删除会话。

对于故障或失控且仍处于附加状态的工作节点，操作员可将 environments.destroy 与 { "force": true } 搭配调用，作为最后手段。强制拆除会持久地将放置标记为失败，并在销毁环境前放弃所有未协调的远程结果。

等效的管理 RPC 如下：

openclaw gateway call sessions.reclaim \  --timeout 600000 \  --params '{"key":"agent:main:big-refactor"}'

放置会经过持久状态机（local → requested → provisioning → syncing → starting → active）转换，因此 Gateway 网关在调度期间重启时会进行协调，而不是泄漏机器。失败的模型轮次会保留活动放置，以便重试。如果入站工作区协调失败，工作节点也会保持活动状态，以便操作员解决本地冲突并重试，而不会丢失远程结果；生命周期故障则会将放置转入错误或已回收状态，并保留其诊断尾部。

安全模型

• 封闭的工作节点入口。 工作节点通过隧道套接字上的专用协议通信，该协议具有封闭的方法允许列表——工作节点无法调用操作员 RPC。
• 签发的凭证，以哈希形式静态存储。 每次调度都会签发一个工作节点凭证；Gateway 网关仅存储其哈希。凭证轮换和所有者纪元隔离保证每个会话最多只有一个活动所有者——重新连接的过期工作节点会被隔离，绝不会合并。
• 主机密钥固定。 提供商必须在预配时公开机器的 SSH 主机密钥；引导过程使用严格固定的密钥进行连接，缺少密钥时以关闭方式失败。
• 机器上不保留常驻的模型、代码托管平台或云凭证。 模型身份验证保留在 Gateway 网关上（推理通过 {provider, model} 引用传输），工作区 Git 提交在没有代码托管平台凭证的情况下创建，并且在设置前会以权威方式检查 Crabbox AWS 租约元数据中是否存在实例角色。设置命令也必须不包含凭证。
• 提供商所有的出站访问。 反向隧道消除了 OpenClaw 直接访问模型的任何需求，但 OpenClaw 不会重写提供商防火墙。当任务需要时，请在工作节点提供商中限制出站流量。
• 持久、恰好一次的对话记录。 工作节点通过针对会话叶节点的比较并交换协议提交对话记录批次；过期的基准会使运行停止，而不是复制付费输出或为其变基。

故障排查

• sessions.dispatch 是未知方法 — 未配置任何 cloudWorkers.profiles，或调用方缺少 operator.admin。
• “云端工作节点轮次需要 OpenClaw 运行时” — 请选择已配置使用 OpenClaw 运行时的模型。claude-cli 等外部 CLI 运行时不支持工作节点推理。
• “工作节点引导需要租用主机上安装 Node.js” — 在 settings.setup 中添加 Node 安装步骤（见上文）。
• AWS 实例角色证明失败 — 清除 aws.instanceProfile（如果设置了 CRABBOX_AWS_INSTANCE_PROFILE，也需清除）。安装 Crabbox 0.38.1 或更高版本；旧版二进制文件不会公开 AWS 准入所需的权威 providerMetadata.instanceProfileAttached 契约。
• 分派因提供商错误而失败 — 放置记录和 environments.list 会保留最后一次错误，包括设置/引导过程的 stderr 尾部。Box 会在失败时销毁，因此该尾部信息是主要的取证依据。
• 分派时客户端超时 — openclaw gateway call 的默认超时时间为 10s；请为 --timeout 设置充足的值（无论如何，分派都会继续在服务器端运行；在预配期间重试会被拒绝并返回 session cannot dispatch from placement provisioning）。
• 租约维护 — crabbox list --provider <backend> 显示有效租约；crabbox stop --provider <backend> --id <lease> 可手动释放租约。空闲租约会按照配置文件的 idleTimeout 到期。

相关内容

• 沙箱隔离 — 缩小本地工具执行的影响范围
• 会话 CLI — 检查已存储的会话
• 配置参考