negodiy/openclaw
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
157d6d2db7e004ca4bfa1dfd0142d5bbd6aa8e45
openclaw/docs/zh-CN/refactor/clawnet.md
Josh Palmer 5676a6b38d Docs: normalize zh-CN terminology + tone 
What: switch to 你/你的 tone; standardize Skills/Gateway网关/local loopback/私信 wording
Why: align zh-CN docs with issue 6995 feedback + idiomatic tech style
Tests: pnpm docs:build
2026-02-02 16:38:25 +01:00

12 KiB
Raw Blame History

read_when, summary, title, x-i18n
read_when summary title x-i18n
规划节点 + 操作者客户端的统一网络协议
重新设计跨设备的审批、配对、TLS 和在线状态
Clawnet 重构：统一网络协议、角色、认证、审批、身份 Clawnet 重构
generated_at model provider source_hash source_path workflow
2026-02-01T21:37:22Z claude-opus-4-5 pi 719b219c3b326479658fe6101c80d5273fc56eb3baf50be8535e0d1d2bb7987f refactor/clawnet.md 15

Clawnet 重构（协议 + 认证统一）

你好

你好 Peter — 方向很棒；这将带来更简洁的用户体验和更强的安全性。

目的

一份严谨的统一文档，涵盖：

  • 现状：协议、流程、信任边界。
  • 痛点：审批、多跳路由、UI 重复。
  • 新方案：单一协议、作用域角色、统一认证/配对、TLS 固定。
  • 身份模型：稳定 ID + 可爱别名。
  • 迁移计划、风险、待解决问题。

目标（来自讨论）

  • 所有客户端（mac 应用、CLI、iOS、Android、无头节点）使用同一协议。
  • 每个网络参与者均经过认证和配对。
  • 角色清晰：节点 vs 操作者。
  • 集中审批，路由到用户所在位置。
  • 所有远程流量使用 TLS 加密 + 可选固定。
  • 最小化代码重复。
  • 单台机器只显示一次（不出现 UI/节点重复条目）。

非目标（明确声明）

  • 移除能力隔离（仍需最小权限）。
  • 在无作用域检查的情况下暴露完整 Gateway网关控制平面。
  • 让认证依赖人类标签（别名仍为非安全性要素）。

现状（当前状态）

两套协议

1) Gateway网关 WebSocket（控制平面）

  • 完整 API 接口：配置、渠道、模型、会话、智能体运行、日志、节点等。
  • 默认绑定：local loopback。远程访问通过 SSH/Tailscale。
  • 认证：通过 connect 使用令牌/密码。
  • 无 TLS 固定（依赖 local loopback/隧道）。
  • 代码：
    • src/gateway/server/ws-connection/message-handler.ts
    • src/gateway/client.ts
    • docs/gateway/protocol.md

2) Bridge（节点传输）

  • 窄白名单接口，节点身份 + 配对。
  • 基于 TCP 的 JSONL；可选 TLS + 证书指纹固定。
  • TLS 在发现 TXT 记录中广播指纹。
  • 代码：
    • src/infra/bridge/server/connection.ts
    • src/gateway/server-bridge.ts
    • src/node-host/bridge-client.ts
    • docs/gateway/bridge-protocol.md

当前控制平面客户端

  • CLI → 通过 callGateway网关 连接 Gateway网关 WS（src/gateway/call.ts）。
  • macOS 应用 UI → Gateway网关 WS（Gateway网关Connection）。
  • Web 控制 UI → Gateway网关 WS。
  • ACP → Gateway网关 WS。
  • 浏览器控制使用独立的 HTTP 控制服务器。

当前节点

  • macOS 应用在节点模式下连接 Gateway网关 bridge（MacNodeBridgeSession）。
  • iOS/Android 应用连接 Gateway网关 bridge。
  • 配对 + 每节点令牌存储在 Gateway网关。

当前审批流程（执行）

  • 智能体通过 Gateway网关使用 system.run。
  • Gateway网关通过 bridge 调用节点。
  • 节点运行时决定审批。
  • UI 提示在 mac 应用上显示（当节点 == mac 应用时）。
  • 节点向 Gateway网关返回 invoke-res。
  • 多跳，UI 绑定在节点主机上。

当前在线状态 + 身份

  • Gateway网关在线状态条目来自 WS 客户端。
  • 节点在线状态条目来自 bridge。
  • mac 应用可能为同一台机器显示两个条目（UI + 节点）。
  • 节点身份存储在配对存储中；UI 身份独立存储。

问题 / 痛点

  • 需要维护两套协议栈（WS + Bridge）。
  • 远程节点的审批：提示出现在节点主机上，而非用户所在位置。
  • TLS 固定仅存在于 bridge；WS 依赖 SSH/Tailscale。
  • 身份重复：同一台机器显示为多个实例。
  • 角色模糊：UI + 节点 + CLI 的能力未清晰分离。

新方案（Clawnet）

单一协议，两种角色

带角色 + 作用域的单一 WS 协议。

  • 角色：node（能力宿主）
  • 角色：operator（控制平面）
  • 操作者可选作用域：
    • operator.read（状态 + 查看）
    • operator.write（智能体运行、发送）
    • operator.admin（配置、渠道、模型）

角色行为

节点

  • 可注册能力（caps、commands、权限）。
  • 可接收 invoke 命令（system.run、camera.*、canvas.*、screen.record 等）。
  • 可发送事件：voice.transcript、agent.request、chat.subscribe。
  • 不能调用配置/模型/渠道/会话/智能体控制平面 API。

操作者

  • 完整控制平面 API，受作用域限制。
  • 接收所有审批请求。
  • 不直接执行 OS 操作；路由到节点执行。

关键规则

角色按连接划分，而非按设备划分。一个设备可以分别打开两种角色。

统一认证 + 配对

客户端身份

每个客户端提供：

  • deviceId（稳定，从设备密钥派生）。
  • displayName（人类可读名称）。
  • role + scope + caps + commands。

配对流程（统一）

  • 客户端未认证连接。
  • Gateway网关为该 deviceId 创建配对请求。
  • 操作者收到提示；批准/拒绝。
  • Gateway网关签发绑定以下信息的凭据：
    • 设备公钥
    • 角色
    • 作用域
    • 能力/命令
  • 客户端持久化令牌，重新认证连接。

设备绑定认证（防止持有者令牌重放）

推荐方案：设备密钥对。

  • 设备一次性生成密钥对。
  • deviceId = fingerprint(publicKey)。
  • Gateway网关发送 nonce；设备签名；Gateway网关验证。
  • 令牌签发给公钥（持有证明），而非字符串。

替代方案：

  • mTLS（客户端证书）：最强，运维复杂度更高。
  • 短期持有者令牌仅作为临时过渡（尽早轮换 + 撤销）。

静默审批（SSH 启发式）

需精确定义以避免薄弱环节。推荐以下方案之一：

  • 仅限本地：客户端通过 local loopback/Unix socket 连接时自动配对。
  • SSH 验证：Gateway网关签发 nonce；客户端通过获取 nonce 证明 SSH 访问。
  • 物理存在窗口：在 Gateway网关主机 UI 上进行本地审批后，在短时间窗口内（如 10 分钟）允许自动配对。

始终记录自动审批日志。

全面启用 TLS（开发 + 生产）

复用现有 bridge TLS

使用当前 TLS 运行时 + 指纹固定：

  • src/infra/bridge/server/tls.ts
  • src/node-host/bridge-client.ts 中的指纹验证逻辑

应用到 WS

  • WS 服务器使用相同证书/密钥 + 指纹支持 TLS。
  • WS 客户端可固定指纹（可选）。
  • 发现服务为所有端点广播 TLS + 指纹。
    • 发现服务仅作为定位提示；绝不作为信任锚点。

原因

  • 减少对 SSH/Tailscale 的机密性依赖。
  • 使远程移动端连接默认安全。

审批重新设计（集中化）

现状

审批发生在节点主机上（mac 应用节点运行时）。提示出现在节点运行的位置。

新方案

审批由 Gateway网关托管，UI 推送到操作者客户端。

新流程

  1. Gateway网关收到 system.run 意图（智能体）。
  2. Gateway网关创建审批记录：approval.requested。
  3. 操作者 UI 显示提示。
  4. 审批决定发送到 Gateway网关：approval.resolve。
  5. 如果批准，Gateway网关调用节点命令。
  6. 节点执行，返回 invoke-res。

审批语义（加固）

  • 广播给所有操作者；仅活跃 UI 显示模态框（其他显示通知提示）。
  • 首个决定生效；Gateway网关拒绝后续的重复决定。
  • 默认超时：N 秒后拒绝（如 60 秒），记录原因。
  • 决定需要 operator.approvals 作用域。

优势

  • 提示出现在用户所在位置（mac/手机）。
  • 远程节点的审批行为一致。
  • 节点运行时保持无头；无 UI 依赖。

角色清晰示例

iPhone 应用

  • 节点角色用于：麦克风、摄像头、语音聊天、位置、按键通话。
  • 可选 operator.read 用于状态和聊天查看。
  • 仅在明确启用时才有可选 operator.write/admin。

macOS 应用

  • 默认为操作者角色（控制 UI）。
  • 启用"Mac 节点"时为节点角色（system.run、屏幕、摄像头）。
  • 两个连接使用相同 deviceId → 合并为一个 UI 条目。

CLI

  • 始终为操作者角色。
  • 作用域由子命令决定：
    • status、logs → read
    • agent、message → write
    • config、channels → admin
    • 审批 + 配对 → operator.approvals / operator.pairing

身份 + 别名

稳定 ID

认证必需；永不更改。 推荐方案：

  • 密钥对指纹（公钥哈希）。

可爱别名（龙虾主题）

仅作为人类标签。

  • 示例：scarlet-claw、saltwave、mantis-pinch。
  • 存储在 Gateway网关注册表中，可编辑。
  • 冲突处理：-2、-3。

UI 分组

相同 deviceId 跨角色 → 单个"实例"行：

  • 标记：operator、node。
  • 显示能力 + 最后在线时间。

迁移策略

阶段 0：文档 + 对齐

  • 发布本文档。
  • 盘点所有协议调用 + 审批流程。

阶段 1：在 WS 中添加角色/作用域

  • 扩展 connect 参数，增加 role、scope、deviceId。
  • 为节点角色添加白名单控制。

阶段 2：Bridge 兼容

  • 保持 bridge 运行。
  • 并行添加 WS 节点支持。
  • 通过配置开关控制功能。

阶段 3：集中审批

  • 在 WS 中添加审批请求 + 决定事件。
  • 更新 mac 应用 UI 以显示提示和响应。
  • 节点运行时停止 UI 提示。

阶段 4：TLS 统一

  • 使用 bridge TLS 运行时为 WS 添加 TLS 配置。
  • 为客户端添加固定。

阶段 5：弃用 bridge

  • 将 iOS/Android/mac 节点迁移到 WS。
  • 保留 bridge 作为回退；稳定后移除。

阶段 6：设备绑定认证

  • 所有非本地连接要求基于密钥的身份认证。
  • 添加撤销 + 轮换 UI。

安全说明

  • 角色/白名单在 Gateway网关边界强制执行。
  • 无操作者作用域的客户端无法获得"完整"API。
  • 所有连接均需配对。
  • TLS + 固定降低移动端中间人攻击风险。
  • SSH 静默审批是便利功能；仍被记录且可撤销。
  • 发现服务绝不作为信任锚点。
  • 能力声明由服务器按平台/类型的白名单验证。

流式传输 + 大负载（节点媒体）

WS 控制平面适合小消息，但节点还需要处理：

  • 摄像头片段
  • 屏幕录制
  • 音频流

方案：

  1. WS 二进制帧 + 分块 + 背压规则。
  2. 独立流式端点（仍使用 TLS + 认证）。
  3. 对媒体密集型命令保留 bridge 更久，最后迁移。

实现前选定一个方案，避免分歧。

能力 + 命令策略

  • 节点报告的 caps/commands 视为声明。
  • Gateway网关执行按平台的白名单。
  • 任何新命令需要操作者审批或显式白名单变更。
  • 带时间戳审计变更。

审计 + 速率限制

  • 记录：配对请求、批准/拒绝、令牌签发/轮换/撤销。
  • 对配对请求和审批提示进行速率限制。

协议规范

  • 显式协议版本 + 错误码。
  • 重连规则 + 心跳策略。
  • 在线状态 TTL 和最后在线语义。

待解决问题

  1. 单设备运行两种角色：令牌模型

    • 建议每个角色使用独立令牌（节点 vs 操作者）。
    • 相同 deviceId；不同作用域；更清晰的撤销。

  2. 操作者作用域粒度

    • read/write/admin + 审批 + 配对（最小可行方案）。
    • 后续考虑按功能划分作用域。

  3. 令牌轮换 + 撤销用户体验

    • 角色变更时自动轮换。
    • 按 deviceId + 角色撤销的 UI。

  4. 发现服务

    • 扩展当前 Bonjour TXT 以包含 WS TLS 指纹 + 角色提示。
    • 仅作为定位提示。

  5. 跨网络审批

    • 广播给所有操作者客户端；活跃 UI 显示模态框。
    • 首个响应生效；Gateway网关保证原子性。

摘要（简述）

  • 现状：WS 控制平面 + Bridge 节点传输。
  • 痛点：审批 + 重复 + 两套协议栈。
  • 方案：带显式角色 + 作用域的单一 WS 协议，统一配对 + TLS 固定，Gateway网关托管审批，稳定设备 ID + 可爱别名。
  • 成果：更简洁的用户体验、更强的安全性、更少的重复、更好的移动端路由。