云端工作节点计划

​

状态

​

问题

​

目标

• 在临时远程机器（“云端工作节点”）上运行完整的智能体会话（循环 + 工具），同时该会话在 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 网关继续作为身份验证配置文件、提供商路由和策略的唯一所有者；工作节点不持有任何密钥。

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

​

组件

​

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

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

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>; // 幂等，仅在确认已销毁后返回
};

​

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

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

​

3. 传输：全部通过 SSH

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

​

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

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

​

5. 会话后端 RPC

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

​

6. 工作区同步

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

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

​

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

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

​

分派与移交

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

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

​

安全模型

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

​

容量

​

生命周期

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

​

配置表面

​

里程碑

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

​

待解决问题

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