Clawnet 重构(协议 + 认证统一)
目的
单一严谨文档,涵盖:当前状态(协议、流程、信任边界)、痛点(审批、多跳路由、UI 重复)、提案新状态(一个协议、作用域角色、统一认证/配对、TLS pinning)、身份模型(稳定 ID + 可爱 slug)、迁移计划、风险和待定问题。
目标
- 所有客户端(mac 应用、CLI、iOS、Android、无头节点)使用一个协议
- 每个网络参与者都已认证 + 配对
- 角色清晰:节点 vs 运维者
- 审批集中路由到用户所在位置
- 所有远程流量 TLS 加密 + 可选 pinning
- 最小代码重复
- 同一台机器只出现一次(不重复 UI/节点条目)
当前状态
两个协议:Gateway WebSocket(控制平面,完整 API 表面)和 Bridge(节点传输,窄白名单表面,JSONL over TCP,可选 TLS)。
核心痛点:两套协议栈要维护、审批出现在节点主机上而非用户所在位置、TLS pinning 只存在于 bridge、身份重复、角色不明确。
提案新状态(Clawnet)
一个协议,两个角色
单一 WS 协议加角色 + 作用域。
- 角色:节点(能力宿主)— 注册能力、接收 invoke 命令、发送事件,不能调用控制平面 API。
- 角色:运维者(控制平面)— 完整控制平面 API(按作用域门控)、接收所有审批、不直接执行 OS 操作。
角色是按连接的,不是按设备的。同一设备可以分别打开两个角色。
统一认证 + 配对
每个客户端提供 deviceId(稳定,源于设备密钥)、displayName、role + scope + caps + commands。
配对流程:客户端未认证连接 -> Gateway 创建配对请求 -> 运维者审批/拒绝 -> Gateway 发出绑定到设备公钥、角色、作用域和能力的凭证。
首选设备绑定认证:设备密钥对。deviceId = fingerprint(publicKey)。Gateway 发 nonce,设备签名,Gateway 验证。
TLS 全面覆盖
复用现有 bridge TLS 运行时和指纹 pinning,应用到 WS。Discovery 通告 TLS + 指纹(仅作定位提示,绝非信任锚点)。
审批重设计(集中化)
审批改为 Gateway 托管,UI 投递给运维者客户端。Gateway 收到 system.run 意图后创建审批记录,广播给所有运维者,第一个解决获胜,默认超时后拒绝。
身份 + slug
稳定 ID:密钥对指纹(公钥哈希)。可爱 slug(龙虾主题):人类标签,如 scarlet-claw、saltwave,可编辑。同一 deviceId 跨角色合并为单行。
迁移策略
六个阶段:文档对齐 -> WS 添加角色/作用域 -> Bridge 兼容 -> 集中审批 -> TLS 统一 -> 弃用 Bridge -> 设备绑定认证。
安全说明
角色/白名单在 gateway 边界强制。配对对所有连接必需。TLS + pinning 降低移动端 MITM 风险。Discovery 绝非信任锚点。能力声明对照服务器白名单验证。
待定问题
- 同一设备运行两个角色时的 token 模型(建议每角色独立 token)
- 运维者作用域粒度
- Token 轮换 + 撤销 UX
- Discovery 扩展
- 跨网络审批(广播所有运维者客户端,活跃 UI 显示模态)