> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 云端工作节点计划

## 状态

提案，第 3 次修订。尚未实现。方向已于 2026-07 达成一致；第 2 次修订纳入了对抗性审查发现（专用工作节点协议、位置/环境状态机、支持 Git 的入站同步、v1 单向移交、受控出站安全措辞）。第 3 次修订确定了同步所有权模型（工作节点创建提交，Gateway 网关接纳并发布），新增无 Git 的普通同步模式，将工作节点 Exec 修正为在机器内部拥有完整权限，将互联网策略移至置备阶段，并将智能体调度恢复至里程碑 3。

## 问题

OpenClaw 智能体会话在一台机器的 Gateway 网关进程中运行其循环、工具和推理。计算能力受限于该机器，长时间任务会持续占用它，并行工作也会争用其资源。托管产品（Cursor 云智能体、网页版 Claude Code、Codex cloud）通过为每项任务提供临时云沙箱来解决这个问题，但这需要依赖供应商基础设施并信任供应商。

已经拥有闲置机器（或能以较低成本租用机器）的操作员无法指定：在那台机器上运行此会话，像其他会话一样将它显示在我的侧边栏中，并在完成后销毁该机器。

## 目标

* 在临时远程机器（“云端工作节点”）上运行完整的智能体会话（循环 + 工具），同时该会话在 Control UI 中的显示和流式传输与本地会话完全相同。
* 工作节点上不存放长期凭据（无提供商身份验证信息、无代码托管平台令牌），也不能直接出站访问网络；该机器只需运行可访问的 sshd。
* 置备、同步、运行、收集、销毁——全程自动化且提供商可插拔（首个提供商：Crabbox 风格的租约 CLI）。
* 在轮次边界将运行中的工作从 Gateway 网关调度到工作节点，而不丢失对话记录、会话身份或提供商缓存亲和性（当请求字节保持等价时）；并安全地拉回结果。
* 人类（UI）和智能体（工具）都能将工作调度到云端工作节点。
* 支持持续数天的会话；生命周期由策略决定，而非硬编码上限。

## 非目标（v1）

* 工作节点上不运行外部编程 harness（Claude Code、Codex CLI）。工作节点会话仅运行 OpenClaw 的嵌入式运行器。harness 支持是 v2 中的可选功能，因为 harness 会使用自己的凭据自行执行推理。
* 不支持 N 选优 / 并行尝试扇出。
* 不依赖 VPN/tailnet。仅使用 SSH 传输。
* 不新增沙箱运行时。工作节点机器是隔离边界；以后可以在机器内部叠加操作系统级沙箱隔离。
* v1 不支持对称实时迁移：调度方向为本地 → 工作节点；工作节点 → 本地要求会话已停止且工作区协调已完成。后续的实时双向移交将基于同一套屏障机制构建。
* Gateway 网关上不使用 JSON 辅助状态；环境、位置、游标和授权状态存储在 SQLite 中。

## 先例（借鉴什么，反转什么）

* Cursor 云智能体：智能体循环在其云端运行；VM 是工具执行目标；仅追加的对话存储会流式传输到所有客户端；安装后创建快照以便预热启动；自托管工作节点是仅出站的工作进程。我们借鉴“对话事实来源保留在编排器上”和流式传输模型；反转循环的运行位置（参见下方决策）。
* Codex cloud：两阶段运行时——联网设置阶段，随后是移除密钥的离线智能体阶段；使用容器状态缓存加速后续任务。我们借鉴这种阶段划分作为出站访问策略，并将缓存理念用于 v2 预热镜像。
* 网页版 Claude Code：每个会话独享 VM；使用隔离凭据的 Git 代理（真实令牌永远不会进入沙箱，推送仅限会话分支）；设置后创建文件系统快照；传送式移交 = 已推送的分支 + 重放的历史记录。我们借鉴凭据隔离和移交框架，但出站同步由 Gateway 网关通过 rsync 执行，因此脏工作树也能正常工作，机器附近的任何地方都不存在代码托管平台令牌。
* Copilot 编程智能体：默认拒绝出站访问，仅允许访问软件包注册表白名单。我们的稳态默认策略更严格（完全禁止直接出站访问），因为推理和 Web 搜索通过 SSH 隧道到达——但请参阅“安全”部分，了解为何这是“受控出站访问”，而非“零出站访问”。

## 架构决策：循环在工作节点上运行，推理经由 Gateway 网关

考虑了三种运行位置：

1. 循环保留在 Gateway 网关上，工作节点执行工具（Cursor 模型）。这是最安全的故障域（对话记录、推理、审批和重启恢复都保留在本地），也是审查者倾向采用的第一个里程碑。未选作产品架构：OpenClaw 的非 Exec 工具是在进程内执行的文件系统操作，因此每次文件读取/编辑/grep 都会变成一次网络往返，或需要将大范围工具接口重构为粗粒度工作区 RPC；运行时交互频繁且受延迟限制。对于已经实现的场景（将 Exec 卸载到节点），我们沿用其思路，但不构建工具远程调用层。
2. 循环和推理都在工作节点上运行。故障域最简单，但模型凭据（包括 OAuth 配置文件）必须发送到一次性机器，Gateway 网关会失去策略、路由和审计控制，而且迁移会切换调用提供商的身份，使提供商缓存失效。
3. 循环 + 工具在工作节点上运行，模型调用通过 Gateway 网关代理。选用此方案。每个模型轮次只需一次往返，而非每次工具调用都往返；工具在代码旁运行；Gateway 网关继续作为身份验证配置文件、提供商路由和策略的唯一所有者；工作节点不持有任何密钥。

方案 3 的代价是每个模型轮次都同步依赖 Gateway 网关，因此其持久性规则属于该决策本身，而不是事后补救：

* Gateway 网关在轮次中途丢失会导致当前提供商调用失败。该轮次会标记为失败，并在重新连接后作为新轮次重试；不会透明重放进行中的提供商流（存在重复计费/重复工具调用的风险）。
* 每项工作节点↔Gateway 网关操作都携带持久身份信息（参见“工作节点协议”），因此重新连接后会恢复操作或获取已缓存的终态结果，而不会使操作悬空。
* Gateway 网关是受容量管理的组件：并发工作节点限制、流量控制和负载削减均属于 v1 范围（参见“容量”）。

由于 Gateway 网关既存储对话记录又发起所有提供商流量，会话与位置无关：在 Gateway 网关和工作节点之间移动循环，不会改变提供商侧的任何内容，也不会改变 UI 数据路径。这正是调度和拉回成本较低的原因。

## 组件

### 1. 环境状态机 + 提供商契约

Gateway 网关协议中的 `environments.*` 目前只是状态投影。持久核心是由 SQLite 管理的环境记录和状态机，需先于 RPC 形态完成设计：

`requested → provisioning → bootstrapping → ready → (attached|idle) → draining → destroying → destroyed | failed | orphaned`

* 置备具备崩溃安全性：在调用提供商之前，先持久化意图记录及确定性的操作 ID，使 Gateway 网关重启后可以接管进行中的租约，而不是重复置备或遗留仍在计费的孤立机器。
* 重启协调和孤立资源清理器（提供商 `inspect` 与本地记录对比）是 v1 要求，而非加固措施。

提供商契约（由插件实现；核心中不包含提供商名称或策略）：

```ts theme={"theme":{"light":"min-light","dark":"min-dark"}}
type WorkerProvider = {
  id: string;
  provision(profile: WorkerProfile, opId: string): Promise<WorkerLease>; // → SSH 主机/端口/用户/密钥材料
  inspect(lease: { leaseId: string; profile: WorkerProfile }): Promise<LeaseStatus>; // 接管/健康检查/孤立资源扫描
  renew?(leaseId: string): Promise<void>; // 长期会话与提供商 TTL 的协调
  destroy(lease: { leaseId: string; profile: WorkerProfile }): Promise<void>; // 幂等，仅在确认已销毁后返回
};
```

RPC：`environments.create`、`environments.destroy`、扩展后的 `environments.list/status`（提供商、租约 ID、状态、存续时间、空闲时间、已附加会话）。首批提供商：Crabbox 形态的租约 CLI 包装器（产品路径），以及标记为仅供开发使用的静态 SSH 主机提供商——共享主机上的工作节点可以读取该主机上不相关的数据，因此静态主机用于功能开发，而不是默认安全策略。

### 2. 工作节点引导：在机器上安装 OpenClaw

不使用定制工作节点工件，也不依赖 npm 可用性：

* 所有模式的规范安装方式：由 Gateway 网关生成并按内容哈希的工作节点捆绑包（将 Gateway 网关自身的构建输出打包为 tarball），通过 SSH 推送并安装到机器上。按设计，这同时涵盖开发构建和未发布提交。
* 当 Gateway 网关运行已发布版本时，`npm i -g openclaw@<exact gateway version>` 是一种优化；绝不使用 `latest`。
* 引导过程具有幂等性；具有匹配捆绑包哈希的预热租约会跳过安装。原始机器可能需要联网的工具链阶段（Node 运行时）——这是设置阶段的一部分，完成后即关闭网络。
* 握手会验证工作节点构建哈希、协议功能集和运行时兼容性。现有 Gateway 网关版本/协议检查对此并不充分（通过 SSH 隧道连接的节点不受精确版本拒绝规则约束），因此工作节点准入会执行自己的精确构建检查。

工作节点模式（`openclaw worker`）是一个入口点，而非分支版本：它包含连接处理和嵌入式智能体运行器，并由 Gateway 网关 RPC 支持会话持久化和模型调用。它不得启动 Gateway 网关接口：不启动任何渠道，除会话工具集外不自动启动任何插件，使用一次性状态目录，不包含本地身份验证配置文件。

### 3. 传输：全部通过 SSH

Gateway 网关负责连接；工作节点除 sshd 外无需任何其他服务：

* Gateway 网关连接到工作节点的 SSH（凭据来自提供商租约，主机密钥固定为置备输出——不使用 `StrictHostKeyChecking=no`），并建立反向隧道，将工作节点本地套接字转发至 Gateway 网关的 WS 端点。
* 控制/模型流量与工作区传输使用独立的 SSH 连接，并共享相同的固定信任材料，因此 rsync 不会发生队头阻塞而延迟令牌流。
* 隧道生命周期（保活、断线后退避重连）由 Gateway 网关上的环境运行时管理。隧道短暂中断在会话层面不可见：持久协议状态（见下文）使工作节点能够重新附加并恢复。

### 4. 工作节点协议（专用；不是节点协议）

针对当前节点接口进行的对抗性审查排除了直接复用：待处理的节点调用是进程本地 Promise，会随连接断开而消失；节点幂等键虽会被解析，但不会用于去重；最关键的是，已连接节点可以发送普通节点事件（包括智能体运行请求），因此“节点类型 + 能力上限”并不是入口安全边界。因此，工作节点使用经过身份验证的 `worker` 角色，并采用封闭且版本化的 RPC/事件白名单；工作节点连接无法访问任何旧版节点事件处理程序。

身份和凭据：置备过程会生成短期工作节点凭据，并将其绑定到环境 ID、工作节点密钥、捆绑包哈希、唯一允许的会话、允许的 RPC 集及过期时间。仍然需要经过 SSH 验证的配对（机器由我们置备并且密钥由我们持有），但授权来自生成的凭据，而不是声明的节点接口。

持久操作语义（形态借鉴现有 ACP 运行时及其事件账本——稳定句柄、按会话串行化、持久 `(session, seq)` 重放）：

* 每项操作的作用域均限定为 `(sessionId, lifecycleRevision, runId, ownerEpoch, streamKind, seq)`。
* 所有权纪元会隔离过期工作节点：替代工作节点会推进纪元；旧纪元的迟到结果将被确定性拒绝。
* 采用至少一次交付，并在 SQLite 中持久化 ACK 游标和缓存终态结果；去重是确定性的。不承诺恰好一次交付。
* 为取消、关闭、恢复和终态结果定义显式帧；对流采用基于信用额度/窗口的流量控制。
* 协议功能协商独立于通用节点协议版本。

### 5. 会话后端 RPC

两个截然不同的契约——当前代码库将持久化转录变更（由会话管理器所有，具有父级/叶节点状态的 JSONL 树）与进程本地实时事件（流式增量、工具生命周期、审批）分离，工作节点协议必须保留这种划分：

* 持久化转录提交：工作节点提交带有 `runEpoch` 和基于叶节点比较并交换的语义追加批次；Gateway 网关会话管理器生成条目 ID 和父级 ID。工作节点绝不能提供可信转录行、条目 ID、父级 ID 或其他会话的 ID。
* 可重放的实时事件：一种类型化事件联合，包含工作节点序列号、Gateway 网关 ACK、有界保留和迟到事件隔离，并馈送到现有智能体事件扇出机制，使聊天视图、工具行和未读/状态逻辑的行为与本地会话完全一致。

推理代理：复用现有运行时代理流客户端（`src/agents/runtime/proxy.ts`）的事件词汇，但移动信任边界。工作节点仅发送会话/运行身份、经批准的模型引用、上下文和受限的生成选项；Gateway 网关根据自身目录解析提供商、端点、身份验证、标头、路由和成本策略。工作节点提供的模型对象（例如攻击者控制的 `baseUrl`）将被拒绝。请求大小限制、取消、审计和终态结果重放同样适用。驻留在 Gateway 网关上的工具（websearch）在 Gateway 网关上执行，并通过同一渠道返回结果。

### 6. 工作区同步

同步锚点是一个由 Gateway 网关本地管理且具有独占放置所有权的工作区：对于 git 工作区，使用专用的托管 worktree（现有托管 worktree 元数据——分支、基线、快照所有权——作为基础）；对于非 git 工作区，使用 Gateway 网关所有的目标目录。绝不能使用用户的实时检出目录。会话远程放置期间的独占所有权，从设计上确保了入站同步不会发生冲突。

所有权划分——提交与发布：

* 工作节点侧的智能体在其副本中正常创作提交（`git commit` 是无需凭据的本地操作；作者身份从 Gateway 网关配置投射）。在 Gateway 网关接纳这些提交之前，它们只是惰性的对象。
* Gateway 网关负责所有需要信任的操作：验证入站提交基于已记录的基线、快进本地 worktree、推送、创建 PR，以及可选的签名/重新签名——所有操作均使用 Gateway 网关本地凭据。工作节点绝不持有 git 或代码托管平台凭据，也绝不接触远程仓库。

根据工作区是否为 git 仓库选择两种同步模式：

* Git 模式。出站：通过隧道的 SSH 身份使用 rsync 同步 worktree（包括未提交文件和符合条件的未跟踪文件；使用 crabbox 风格的包含/排除规则，并遵循 `.worktreeinclude`），并将其记录为不可变的基线清单（内容哈希 + 基线提交）。入站：新提交以 git bundle 或相对于已记录基线的临时引用形式返回；未跟踪工件通过显式清单返回，并进行大小/类型/符号链接包含性检查。接纳时验证基线祖先关系，并在出现分歧时停止——不会静默覆盖任何一方。删除、重命名、子模块和符号链接逃逸由清单规则处理，而不是依赖 rsync 启发式规则。
* 普通模式（无 git——例如在工作节点上从零开始构建项目）。出站使用相同的 rsync + 基线清单。入站则通过清单差异比对，将镜像同步回 Gateway 网关所有的目标目录，并传播删除操作。它与 Git 模式具有相同的安全理由：独占所有权意味着不存在并发本地编辑，因此不会产生冲突；基线清单仍会检测意外的本地漂移，并停止操作而不是覆盖内容。

检查点可保护持续数天的会话免受租约丢失影响：定期执行入站检查点（Git 模式下为会话分支提交，普通模式下为清单快照）；频率由配置文件策略决定（默认按轮次）。

### 7. 放置状态机、会话和 UI

运行时放置是由 SQLite 所有、以会话为键的状态机，而不是一对松散的行字段：

`local → requested → provisioning → syncing → starting → active(worker) → draining → reconciling → local | reclaimed | failed`

它会持久化环境 ID、转换代次、活动所有者纪元、工作区基线清单、工作节点 bundle 哈希和最后的 ACK 游标。在任一循环开始轮次之前，轮次准入会以原子方式认领放置，因此根据过期快照准入的本地消息绝不可能与工作节点轮次发生竞争——任何时刻都只有一个循环拥有该会话。

UI：

* 工作节点会话是普通会话行加放置元数据。它位于常规存储中，通过 `sessions.list` 列出，并通过现有订阅进行流式传输——侧边栏和聊天无需新的数据路径，只需添加呈现内容：工作节点徽章以及放置/环境状态（`provisioning / syncing / running / idle / reconciling / reclaimed`）。
* 创建体验：会话目标栏（会话侧边栏重新设计）在 Gateway 网关和节点之外新增云端工作节点目的地。需要已配置的提供商配置文件；配置之前此功能不可见。
* 智能体分派：会话工具允许智能体像人类一样将工作交给云端工作节点（由工作节点支持的子会话，采用子智能体风格）。它与人工分派在同一里程碑中发布，并由相同的选择启用式提供商配置控制。递归在结构上受到限制（v1 中工作节点会话自身不能再分派工作节点）；支出控制采用按环境核算/审计，而非配额机制。

## 分派与移交

v1 特意采用非对称设计：

* 本地 → 工作节点（分派）：通过下述迁移屏障，预配或复用工作节点、同步、切换放置，下一轮在远程执行。
* 工作节点 → 本地（拉回）：停止会话（按照同一屏障排空工作节点），完成入站协调，将放置切换为本地。这不是实时迁移。
* 对称实时移交（无需停止即可双向移动正在工作的会话）复用相同的屏障和协调机制，并在故障注入测试证明该屏障后发布。

迁移屏障（仅有“轮次边界”并不足够——审批、后台进程和释放锁后的转录合并都可能跨越该边界）：

1. 停止接纳新轮次（放置认领）。
2. 取消或排空活动运行。
3. 撤销待处理的 Exec 审批和执行授权。
4. 排空转录旁路写入和实时事件 ACK。
5. 终止工作节点子进程。
6. 推进所有者纪元，隔离旧所有者。
7. 协调工作区（入站、感知冲突）。
8. 激活新所有者。

缓存亲和性：由于两种放置方式下的提供商请求均源自 Gateway 网关，只要序列化的提供商请求保持等价——工具顺序、系统指令、提供商包装器和缓存元数据均相同（且保留在 Gateway 网关侧）——缓存亲和性就得以保留。这是可测试的属性，而非假设：为每种受支持的提供商传输方式编写跨本地/工作节点放置的字节等价性测试，是引入工作节点循环这一里程碑的一部分。

## 安全模型

准确来说：工作节点没有直接网络出口，也没有常驻的提供商/代码托管平台凭据。它并非“零出口”——推理和由 Gateway 网关执行的工具是受控出口渠道（遭受提示注入的工作节点仍可将工作区字节放入模型上下文或 websearch 查询）。因此：

* 受控出口核算：对推理代理和 Gateway 网关工具进行按环境审计，并提供操作员可见的核算。速率/字节限制作为协议流量控制（容量）存在，而非支出配额机制。
* 工作节点到 Gateway 网关的入口由封闭的工作节点协议允许列表控制；转录写入受到结构性约束（由 Gateway 网关生成 ID，仅绑定单个会话）。
* 工作节点 Exec 在工作节点内拥有完整权限。工作节点是一次性的且不含凭据，因此逐命令审批只会增加阻力，无法提供任何保护；受防护的边界是入站协调与审计。Exec 绝不经过 Gateway 网关节点审批路径。
* 互联网策略是在预配时由提供商决定：环境配置文件在创建工作节点时作出决定（防火墙/安全组/无出口网络），还可选用联网设置阶段，由提供商在智能体阶段开始前关闭网络。核心不实现运行时网络开关。
* 预配时的工作节点卫生措施：阻止云元数据端点或验证其不存在、不设置实例配置文件、不继承 SSH agent、不提供 Docker socket，并使用干净的环境/主目录。根据预配输出固定 SSH 主机密钥。
* 对于 Gateway 网关侧的任何操作（推送、PR、提供商调用），审批和策略仍在 Gateway 网关上运行。

工作节点会话遭入侵后的影响范围：已同步的工作区副本，以及经审计的代理渠道所允许的内容——无凭据、无直接网络，除允许列表外无任何 Gateway 网关表面。

## 容量

Gateway 网关会中继 N 个工作节点的每个提示和令牌流，因此 v1 会明确规定容量模型，而不是等到生产环境才发现问题：每个 Gateway 网关的并发工作节点限制、每个流的信用额度窗口（当前事件流队列无界，而节点套接字缓冲区上限会强制关闭响应缓慢的消费者——二者均不适合直接使用）、用于突发流量的有界磁盘缓冲，以及负载削减，并在 UI 中显示可见的背压状态。工作区传输继续使用独立的 SSH 渠道。

## 生命周期

* 空闲自动停止和 TTL 是提供商配置文件策略，而非固定常量。默认值较为宽裕，并提供显式保活；持续数天的工作是一等场景（用于基于租约的后端时存在提供商 `renew`）；有进行中轮次或近期活动的会话绝不会被回收。
* 工作节点死亡或被回收时：放置转为 `reclaimed`，会话行仍然保留，下一条消息会预配新的工作节点，并从最后一个检查点重新同步。对话绝不会丢失（存储在 Gateway 网关侧）；最后一个检查点之后的工作区更改会丢失，UI 会明确说明这一点。
* 从第一天起支持复用温租约（针对支持此功能的提供商）；引导完成后的镜像快照是 v2 的快速启动路径。

## 配置表面

保持最小化且选择启用：一个提供商配置文件块（提供商 ID、凭据/CLI 引用、同步规则、生命周期策略、预算、可选设置阶段），以及按会话选择放置位置。不新增环境变量。未配置的安装不会显示任何相关内容。

## 里程碑

实现将以小型、可独立合并的 PR 形式落地；下列每个里程碑都是一个 PR 系列，而不是单个变更。

1. 基础：环境状态机 + 提供商契约 + crabbox 形态的提供商（以静态 SSH 作为开发测试框架）、工作节点包引导启动 + 准入握手、SSH 隧道 + 主机密钥固定、托管工作树快照 + 出站同步（git + 普通模式）。孤立资源清理 + 重启后接管。
2. 工作节点协议 + 工作节点循环：经过身份验证的工作节点角色、持久化操作/纪元/ACK 游标、转录提交 + 实时事件契约、使用 Gateway 网关解析模型的推理代理、流量控制。仅支持一个提供商，仅允许人工分派新会话，不支持移交。故障注入测试（隧道分区、Gateway 网关重启、工作节点终止）作为退出门槛。
3. 分派 + 拉回 + 智能体分派：迁移屏障、连接到 UI 目标栏的放置状态机、入站协调 + 检查点、按环境审计、容量限制、智能体分派工具（工作节点会话无法递归）。提示缓存字节等价性测试。
4. 对称实时移交，在里程碑 3 的故障注入验证之后。

后续：工作节点上的 ACP 测试框架支持按环境选择启用凭据注入；通过快照/预热镜像快速启动；扇出（N 个租约，相同提示词）；箱内操作系统沙箱隔离；通过工件架构捕获更丰富的工件。

## 待解决问题

* 工作节点上的插件/Skills 可用性：仓库携带的 Skills 随工作区免费同步；Gateway 网关配置的智能体 Skills/插件需要明确决定同步还是排除（无论哪种方式，工具/插件清单都是准入握手的一部分）。
* 检查点频率默认值：对于消息非常频繁的会话，是按轮次还是按时间。
* 环境配置文件如何与多智能体路由交互（按智能体设置默认配置文件，还是仅允许按会话选择）。