人工智能大模型LLM 网关AI Agent即时通讯【免费下载链接】openclaw-zero-tokenOpenClaw: Use All Major AI Models NO API Token! Claude/ChatGPT/Gemini/DeepSeek/Doubao/Grok/Qwen/Manus/Kimi项目地址https://gitcode.com/gh_mirrors/op/openclaw-zero-token点击查看免费下载导读本文基于仓库内 docs/refactor/clawnet.md 这一重构设计文档系统梳理 OpenClaw 网络层的演进路线从「Gateway WebSocket 控制面 Bridge 节点传输」的双协议并存走向「单协议、双角色、按作用域授权」的统一网络模型Clawnet。你会了解到新的operator/node角色划分与operator.read/write/admin/approvals/pairing作用域体系、基于设备密钥对的稳定身份与配对流程、网关托管的集中式审批以及 TLS 指纹钉扎的落地方式。更重要的是文档中相当一部分设计已在当前仓库的网关协议docs/gateway/protocol.md与源码中实现本文将对照源码给出可验证的实操与原理依据。一、重构背景为什么要统一Goals / Non-goalsClawnet 重构的目标非常明确来自项目内部讨论并沉淀为文档中的 Goals单一协议服务所有客户端macOS 应用、CLI、iOS、Android、无头节点全部走同一条协议通道每个网络参与者都必须被认证并完成配对角色清晰区分「节点node能力宿主」与「操作者operator控制面」集中审批审批请求路由到用户当前所在的客户端而不是停留在节点宿主上全链路 TLS 可选钉扎所有远程流量加密并支持证书指纹固定最小化代码重复同一台机器只出现一次不再有「UI 实例 节点实例」的重复条目。同时文档明确列出了Non-goals非目标防止重构跑偏不取消能力隔离仍然需要最小权限原则不把完整网关控制面暴露给没有作用域检查的客户端认证不依赖人类可读标签slug 永远不是安全要素。理解这是一次「协议与信任边界」的重构而不是功能堆叠。二、现状as-is两套协议栈与五类客户端2.1 协议一Gateway WebSocket控制面完整 API 面config、channels、models、sessions、agent 运行、日志、节点管理等默认绑定 loopback远程访问依赖 SSH / Tailscale 隧道认证通过connect携带 token/password无 TLS 钉扎依赖回环与隧道本身的安全性。文档指出的关键代码路径src/gateway/server/ws-connection/message-handler.tsWS 消息处理器负责connect握手、认证与角色判定src/gateway/client.ts网关客户端封装docs/gateway/protocol.md协议文档。2.2 协议二Bridge节点传输窄小的 allowlist 面只暴露节点所需方法JSONL over TCP可选 TLS 证书指纹钉扎启用 TLS 时发现discovery的 TXT 记录会广播指纹关键代码src/infra/bridge/server/connection.ts、src/gateway/server-bridge.ts、src/node-host/bridge-client.ts、docs/gateway/bridge-protocol.md。关于 Bridge 的现状需要补充一个重要背景docs/gateway/bridge-protocol.md 明确标注当前 OpenClaw 构建已不再启用 TCP bridge 监听器该文档仅保留作历史参考bridge.*配置键也已从配置 schema 中移除。也就是说Clawnet 文档中描述的「双协议并存」在仓库当前状态中正处于「Bridge 已退役、WS 一统」的收尾阶段——这正好印证了迁移策略中 Phase 5「Deprecate bridge」的推进。2.3 今天的控制面客户端客户端接入方式CLI通过callGateway走 Gateway WSsrc/gateway/call.tsmacOS 应用 UIGateway WSGatewayConnectionWeb 控制 UIGateway WSACPGateway WS浏览器控制自己的 HTTP 控制服务器独立于 WS2.4 今天的节点macOS 应用节点模式通过MacNodeBridgeSession连接 Gateway bridgeiOS/Android 应用连接 Gateway bridge配对 每节点 token 存储在网关上。2.5 今天的审批流exec与身份审批流现状Agent 通过 Gateway 调用system.runGateway 经 bridge 向节点发起 invoke节点运行时自行决定是否审批当「节点 macOS 应用」时UI 提示出现在 macOS 应用上节点向 Gateway 返回invoke-res。问题多跳路由且 UI 被绑定在节点宿主上。Presence 身份现状Gateway 的 presence 条目来自 WS 客户端节点 presence 条目来自 bridgemacOS 应用可能为同一台机器显示两个条目UI 一个、节点一个节点身份存在配对存储里UI 身份是另一套。2.6 痛点清单文档原文归纳两套协议栈需要同时维护WS Bridge远程节点审批时提示出现在节点宿主而非用户所在处TLS 钉扎只存在于 bridgeWS 依赖 SSH/Tailscale身份重复同一台机器显示为多个实例角色含糊UI、节点、CLI 的能力边界不清晰。三、新状态Clawnet一个协议两种角色按作用域授权3.1 核心模型单一 WS 协议连接时声明role scopeRole: node能力宿主注册能力接收 invoke上报事件但不能调用控制面 APIRole: operator控制面完整控制面 API按 scope 门控不直接执行 OS 动作而是路由到节点可选 scopeoperatoroperator.read状态查看operator.writeagent 运行、消息发送operator.adminconfig、channels、models 等管理操作。3.2 角色行为细则Node节点可注册能力caps、commands、权限可接收invoke命令system.run、camera.*、canvas.*、screen.record等可发送事件voice.transcript、agent.request、chat.subscribe不可调用 config/models/channels/sessions/agent 等控制面 API。Operator操作者完整控制面 API由 scope 门控接收所有审批请求不直接执行 OS 动作路由到节点。关键规则角色是**按连接per-connection**而非按设备划分的。同一台设备可以分别建立两条连接一条以 operator 角色、一条以 node 角色互不干扰。3.3 源码级印证角色与作用域已经落地这一设计在当前仓库已经实现可以逐项对证角色常量定义在 src/gateway/role-policy.tsexport const GATEWAY_ROLES [operator, node] as const;方法级授权在 src/gateway/role-policy.tsisNodeRoleMethod(method)判定的方法只允许node角色调用其余默认归operator。作用域常量与方法归属映射在 src/gateway/method-scopes.tsexport const ADMIN_SCOPE operator.admin as const; export const READ_SCOPE operator.read as const; export const WRITE_SCOPE operator.write as const; export const APPROVALS_SCOPE operator.approvals as const; export const PAIRING_SCOPE operator.pairing as const;METHOD_SCOPE_GROUPS把每个方法精确归类例如status、logs.tail、sessions.list归operator.readsend、agent、chat.send、node.invoke归operator.writeconfig.*前缀匹配、sessions.reset、channels.logout归operator.adminexec.approval.*归operator.approvalsdevice.token.rotate/revoke、node.pair.*归operator.pairing。节点专属方法集合NODE_ROLE_METHODS包括node.invoke.result、node.event、node.pending.*、skills.bins等——对应文档中「节点可注册能力、可接收 invoke、可上报事件」的行为边界。授权判定函数authorizeOperatorScopesForMethodsrc/gateway/method-scopes.ts实现了最小权限逻辑持有operator.admin可放行一切operator.read方法对持有 read 或 write 的客户端放行未分类方法默认拒绝default-deny。CLI 默认作用域在 src/gateway/method-scopes.tsexport const CLI_DEFAULT_OPERATOR_SCOPES: OperatorScope[] [ ADMIN_SCOPE, READ_SCOPE, WRITE_SCOPE, APPROVALS_SCOPE, PAIRING_SCOPE, ];与文档中「CLI 恒为 operator 角色作用域由子命令推导」的设计一致见下文角色示例。四、统一认证与配对4.1 客户端身份声明每个客户端在connect时必须提供deviceId稳定由设备密钥派生displayName人类可读名rolescopecapscommands。在 docs/gateway/protocol.md 的 connect 示例中这一结构已经完全落地{ type: req, id: …, method: connect, params: { minProtocol: 3, maxProtocol: 3, client: { id: cli, version: 1.2.3, platform: macos, mode: operator }, role: operator, scopes: [operator.read, operator.write], caps: [], commands: [], permissions: {}, auth: { token: … }, locale: en-US, userAgent: openclaw-cli/1.2.3, device: { id: device_fingerprint, publicKey: …, signature: …, signedAt: 1737264000000, nonce: … } } }节点示例则携带caps如camera/canvas/screen/location/voice、commands如camera.snap、screen.record、location.get和细粒度permissions如camera.capture: true、screen.record: false对应文档中「节点注册能力」的行为。4.2 统一配对流程文档设计客户端未认证连接Gateway 为这个deviceId创建pairing requestOperator 收到提示并批准/拒绝Gateway 签发与以下内容绑定的凭据设备公钥角色role(s)作用域scope(s)能力/命令caps/commands客户端持久化 token之后以认证状态重连。4.3 设备绑定认证防 bearer token 重放首选方案是设备密钥对device keypair而非裸 token设备一次性生成密钥对deviceId fingerprint(publicKey)公钥哈希Gateway 下发 nonce设备签名Gateway 验证Token 签发给公钥proof-of-possession而不是签发一个字符串。备选方案mTLS客户端证书安全性最强但运维复杂度更高短期 bearer token仅作为过渡阶段需尽早轮换与吊销。源码印证设备身份src/infra/device-identity.ts 实现了完整的密钥对身份用crypto.generateKeyPairSync(ed25519)生成密钥对deviceId fingerprintPublicKey(publicKeyPem)即对 SPKI 原始公钥做 SHA-256 后取 hexsrc/infra/device-identity.ts身份持久化在状态目录identity/device.jsonresolveStateDir()/identity/device.json文件权限0600若存储的deviceId与从公钥重新推导的不一致会自动修正保证 deviceId 恒等于公钥指纹。源码印证设备配对存储src/infra/device-pairing.ts 定义了完整的配对状态机export type DevicePairingPendingRequest { requestId: string; deviceId: string; publicKey: string; displayName?: string; role?: string; roles?: string[]; scopes?: string[]; silent?: boolean; ts: number; }; export type PairedDevice { deviceId: string; publicKey: string; roles?: string[]; scopes?: string[]; approvedScopes?: string[]; tokens?: Recordstring, DeviceAuthToken; createdAtMs: number; approvedAtMs: number; };pending 请求 TTL 为 5 分钟PENDING_TTL_MS 5 * 60 * 1000对应 pairing.md 中「pending 请求 5 分钟自动过期」token 按role维度存储tokens?: Recordstring, DeviceAuthToken即文档开放问题 1 推荐的「同一 deviceId 不同角色持有不同 token」支持device.token.rotate/device.token.revoke方法归operator.pairingscope。4.4 静默审批SSH 启发式文档要求精确定义静默审批避免引入薄弱环节优先选择以下一种Local-only客户端经 loopback/Unix socket 连接时自动配对SSH challengeGateway 下发 nonce客户端通过 SSH 取回以证明持有 SSH物理在场窗口在网关主机 UI 本地批准后允许短时间窗口例如 10 分钟内自动配对。必须始终记录自动批准日志。源码印证message-handler.ts中通过isLocalDirectRequest、isLoopbackAddress、isTrustedProxyAddress判定连接是否本地shouldAllowSilentLocalPairingsrc/gateway/server/ws-connection/handshake-auth-helpers.ts实现本地静默配对判定。docs/gateway/protocol.md 也明确本地连接包括 loopback 与网关主机自身的 tailnet 地址同主机 tailnet 绑定也可自动批准。配对存储方面docs/gateway/pairing.md 说明 macOS 应用可在请求标记silent: true且能通过 SSH 验证网关主机同一用户时尝试静默批准失败则回退到普通「Approve/Reject」提示。4.5 与node.pair.*的区别重要澄清docs/gateway/pairing.md 特别强调WS 节点使用设备配对rolenode在connect时完成node.pair.*是另一套独立配对存储不参与 WS 握手门控只有显式调用node.pair.*的客户端才走该流程。别把两套配对混为一谈。五、TLS 全覆盖开发与生产一致5.1 复用现有 Bridge TLS文档要求复用现有的 bridge TLS 运行时与指纹钉扎逻辑src/infra/bridge/server/tls.tssrc/node-host/bridge-client.ts中的指纹验证逻辑。5.2 应用到 WSWS 服务器使用相同的证书/密钥 指纹WS 客户端可选钉扎指纹发现discovery对所有端点广播 TLS 指纹发现信息只是定位提示locator hints永远不是信任锚点trust anchor。5.3 为什么降低对 SSH/Tailscale 的机密性依赖让远程移动连接默认安全。源码印证src/infra/tls/gateway.ts已实现网关 TLS 配置与证书指纹计算fingerprintSha256src/infra/tls/gateway.ts并有配套测试 src/infra/tls/fingerprint.test.ts 与 src/infra/tls/gateway.test.ts。docs/gateway/protocol.md 说明 WS 已支持 TLS客户端可选钉扎配置gateway.remote.tlsFingerprint或 CLI 参数--tls-fingerprint见 docs/gateway/remote.md。六、审批重构网关托管、集中交付6.1 现状 vs 提案现状审批发生在节点宿主macOS 应用节点运行时提示出现在节点运行之处。提案审批由网关托管gateway-hostedUI 交付给 operator 客户端。6.2 新流程六步Gateway 收到system.run意图来自 agentGateway 创建审批记录approval.requestedOperator UI一个或多个展示提示审批决定发送给 Gatewayapproval.resolve若批准Gateway 向节点发起 invoke节点执行并返回invoke-res。6.3 审批语义硬化硬性规则广播给所有 operator只有当前活跃 UI 显示模态框其他客户端收到 toast 通知首次决议生效first resolution winsGateway 拒绝后续 resolve视为已定案默认超时拒绝N 秒例如 60 秒后自动拒绝并记录原因决议需要operator.approvals作用域。6.4 收益提示出现在用户所在处mac 或手机远程节点获得一致的审批体验节点运行时保持无头headless不依赖 UI。6.5 源码印证协议与实现均已落地协议侧docs/gateway/protocol.md 的「Exec approvals」小节写明需要审批时网关广播exec.approval.requestedoperator 客户端调用exec.approval.resolve要求operator.approvalsscopehostnode的请求必须携带systemRunPlan规范化的argv/cwd/rawCommand/session 元数据缺少则被拒绝。实现侧src/gateway/exec-approval-manager.ts 就是「first resolution wins 超时 幂等」的落地register()幂等重复注册返回同一 pending promise已决议的 id 禁止重新注册approval id ... already resolved记录带expiresAtMs超时并记录requestedByConnId/DeviceId/ClientId防止其他客户端重放审批 id。审批方法归属operator.approvalsscope在 src/gateway/method-scopes.ts 中可见exec.approval.request、exec.approval.waitDecision、exec.approval.resolve等。节点侧审批错误处理见 src/gateway/node-invoke-system-run-approval-errors.ts 与node-invoke-system-run-approval.ts说明system.run走节点时审批已由网关侧接管。七、角色清晰度示例文档原文iPhone 应用Node 角色mic、camera、voice chat、location、push-to-talk可选operator.read状态与聊天查看可选operator.write/admin仅显式开启时。macOS 应用默认operator 角色控制 UI启用「Mac node」后开node 角色system.run、screen、camera两条连接使用同一 deviceId→ 合并为一条 UI 条目。CLI恒为operator 角色作用域由子命令推导子命令作用域status、logsoperator.readagent、messageoperator.writeconfig、channelsoperator.admin审批 配对operator.approvals/operator.pairing这一「子命令推导作用域」的设计在 CLI 默认配置中有迹可循CLI_DEFAULT_OPERATOR_SCOPES默认授予全部五个 scope见 src/gateway/method-scopes.ts配合方法级 scope 映射即可实现按子命令/方法的最小权限授权。八、身份与昵称稳定 ID 可爱 slug8.1 稳定 ID认证必需永不变化首选密钥对指纹公钥哈希——已在 4.3 节印证deviceId SHA-256(publicKey)。8.2 可爱 slug龙虾主题仅作人类标签非安全要素示例scarlet-claw、saltwave、mantis-pinch存储在网关注册表中可编辑冲突处理追加-2、-3。8.3 UI 分组同一deviceId跨角色连接 → 合并为单个「Instance」行徽标operator/node显示能力 最后在线时间。源码印证docs/gateway/protocol.md 的 Presence 一节写明system-presence返回以设备身份为 key 的条目包含deviceId、roles、scopes因此即使同一设备同时以 operator 与 node 连接UI 也可按设备显示单行。九、迁移策略Phase 0 → 6阶段内容当前仓库状态对照Phase 0发布本文档盘点所有协议调用与审批流本文即文档本身Phase 1扩展connect参数role、scope、deviceId为 node 角色增加 allowlist 门控已落地connect 携带role/scopes/caps/commands/permissions/devicemethod-scopes.tsrole-policy.ts实现门控Phase 2保留 bridge 运行并行增加 WS 节点支持用配置开关门控新特性bridge 已退役docs/gateway/bridge-protocol.md 标注不再随构建发布Phase 3在 WS 中增加审批请求/决议事件macOS 应用 UI 提示与响应节点运行时停止弹 UI已落地exec.approval.requested/exec.approval.resolveExecApprovalManagerPhase 4用 bridge TLS 运行时为 WS 增加 TLS客户端增加钉扎已落地src/infra/tls/gateway.tsgateway.remote.tlsFingerprint/--tls-fingerprintPhase 5迁移 iOS/Android/mac 节点到 WS保留 bridge 作 fallback稳定后移除bridge 已移除节点统一走 WS见server-mobile-nodes.ts、server-node-events.ts等Phase 6所有非本地连接要求基于密钥的身份增加吊销与轮换 UI已落地device.token.rotate/device.token.revokeoperator.pairingscopeDEVICE_AUTH_*迁移诊断整体看Clawnet 文档提出的愿景在当前仓库中已完成大部分双协议收敛为单协议角色与作用域、设备级认证、集中式审批、TLS 钉扎均已实现迁移正处于尾声Phase 5 完成、Phase 6 已部分完成。十、安全注意事项文档原文要点角色/allowlist 在网关边界强制执行任何客户端没有 operator scope 就拿不到「完整」API所有连接都必须配对TLS 钉扎降低移动端 MITM 风险SSH 静默审批只是便利措施仍须记录且可撤销发现discovery永远不是信任锚点能力声明capability claims由服务器按平台/类型与 allowlist 校验。对照实现authorizeOperatorScopesForMethod对未分类方法默认拒绝default-denyroleCanSkipDeviceIdentitysrc/gateway/role-policy.ts仅允许 operator 在共享认证通过时跳过设备身份其他情况一律要求设备身份——正是「所有连接都必须配对」的代码形态。能力校验方面resolveNodeCommandAllowlistsrc/gateway/node-command-policy.ts与node-invoke-sanitize.ts说明节点上报的 caps/commands 作为 claims 由网关按服务器端 allowlist 校验后再放行 invoke。十一、流媒体与大负载节点媒体WS 控制面对小消息没问题但节点还要传输摄像头片段camera clips屏幕录制screen recordings音频流audio streams。文档给出三种选项并要求实现前选定其一避免漂移WS 二进制帧 分块 背压规则独立流媒体端点仍要求 TLS 认证媒体密集型命令继续保留 bridge最后再迁移。现状提示既然 bridge 已不再随构建发布媒体传输实际上已偏向选项 1 与 2WS/独立端点的组合但从文档设计角度这是实现前必须明确的决策点。十二、能力与命令策略Capability Command Policy节点上报的 caps/commands 视为claims声明不是事实网关按平台强制 allowlist任何新命令需要 operator 审批或显式 allowlist 变更变更必须带时间戳审计。十三、审计与速率限制记录配对请求、批准/拒绝、token 签发/轮换/吊销速率限制配对垃圾请求与审批提示轰炸。实现印证网关侧已有 src/gateway/auth-rate-limit.ts认证暴力破解防护、src/gateway/control-plane-rate-limit.ts控制面速率限制、src/gateway/control-plane-audit.ts控制面审计WS 连接侧还有 unauthorized-flood-guard.ts 防未认证洪泛。十四、协议卫生显式协议版本 错误码重连规则 心跳策略Presence TTL 与 last-seen 语义。实现印证PROTOCOL_VERSION位于 src/gateway/protocol/schema.ts客户端在connect中携带minProtocol/maxProtocol服务器拒绝不匹配版本schema 由 TypeBox 定义通过pnpm protocol:gen含 Swift 生成protocol:gen:swift与pnpm protocol:check生成与校验见 docs/gateway/protocol.md。心跳策略见 docs/gateway/heartbeat.mdhello-ok中的policy.tickIntervalMs示例 15000ms即为心跳间隔。十五、开放问题Open Questions单设备双角色下的 token 模型推荐按角色分别签发 tokennode 与 operator 各一个同一 deviceId、不同 scope吊销更清晰。→ 已在PairedDevice.tokens: Recordrole, DeviceAuthToken中落地。Operator scope 粒度read/write/admin approvals pairing 为最小可行集后续再考虑按特性细分 scope。Token 轮换与吊销 UX角色变更时自动轮换提供按 deviceId role 吊销的 UI。发现Discovery扩展当前 Bonjour TXT加入 WS TLS 指纹与角色提示仅作为定位提示。跨网络审批广播给所有 operator 客户端活跃 UI 显示模态首个响应生效网关保证原子性。十六、总结TL;DR今天文档写作时WS 控制面 Bridge 节点传输并存痛点审批错位、实例重复、两套协议栈提案Clawnet单一 WS 协议 显式角色与作用域、统一配对 TLS 钉扎、网关托管审批、稳定设备 ID 可爱 slug预期收益更简单的 UX、更强的安全性、更少重复代码、更好的移动端路由。而对照当前仓库docs/gateway/protocol.md、src/gateway/role-policy.ts、src/gateway/method-scopes.ts、src/infra/device-identity.ts、src/infra/device-pairing.ts、src/gateway/exec-approval-manager.ts、src/infra/tls/gateway.ts 等文件表明这份重构蓝图的核心内容已基本落地——Clawnet 不再只是一份设计文档而是 OpenClaw 当前网络层的真实形态。若你要开发新的 operator 或 node 客户端直接以 docs/gateway/protocol.md 为准实现 WS 连接即可若你是老 bridge 客户端维护者则需按 docs/gateway/pairing.md 的 WS 设备配对流程迁移。赞分享人工智能大模型LLM 网关AI Agent即时通讯【免费下载链接】openclaw-zero-tokenOpenClaw: Use All Major AI Models NO API Token! Claude/ChatGPT/Gemini/DeepSeek/Doubao/Grok/Qwen/Manus/Kimi项目地址https://gitcode.com/gh_mirrors/op/openclaw-zero-token点击查看免费下载相关推荐OpenClaw Gateway WebSocket 协议详解connect 握手、帧结构、角色权限与设备认证迁移OpenClaw Gateway WebSocket 协议详解connect 握手、帧结构、角色权限与设备认证迁移 本文以 OpenClaw 官方文档 doc人工智能大模型LLM 网关AI Agent即时通讯多协议网关架构Authelia协议转换与统一认证多协议网关架构Authelia协议转换与统一认证 引言现代应用认证的挑战 在当今复杂的微服务架构中应用认证面临着前所未有的挑战。不同服务可能使用不同的认证后端认证鉴权单点登录身份认证应用安全Agno Agent 输入输出全解9 个示例控制回复格式让结构化输出一次到位Agno Agent 输入输出全解9 个示例控制回复格式让结构化输出一次到位 你向 Agent 提了个问题答案却是一整段散文你想要列表还想要代码能读的人工智能大模型AI AgentAgent 框架多智能体工具调用RAGAgent 工作流Agent 记忆创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/10/15 16:47:27 · 阅读 1.2k OpenClaw「Clawnet」重构全解：统一网络协议、角色与作用域、设备级认证与集中式审批
人工智能大模型LLM 网关AI Agent即时通讯【免费下载链接】openclaw-zero-tokenOpenClaw: Use All Major AI Models NO API Token! Claude/ChatGPT/Gemini/DeepSeek/Doubao/Grok/Qwen/Manus/Kimi项目地址https://gitcode.com/gh_mirrors/op/openclaw-zero-token点击查看免费下载导读本文基于仓库内 docs/refactor/clawnet.md 这一重构设计文档系统梳理 OpenClaw 网络层的演进路线从「Gateway WebSocket 控制面 Bridge 节点传输」的双协议并存走向「单协议、双角色、按作用域授权」的统一网络模型Clawnet。你会了解到新的operator/node角色划分与operator.read/write/admin/approvals/pairing作用域体系、基于设备密钥对的稳定身份与配对流程、网关托管的集中式审批以及 TLS 指纹钉扎的落地方式。更重要的是文档中相当一部分设计已在当前仓库的网关协议docs/gateway/protocol.md与源码中实现本文将对照源码给出可验证的实操与原理依据。一、重构背景为什么要统一Goals / Non-goalsClawnet 重构的目标非常明确来自项目内部讨论并沉淀为文档中的 Goals单一协议服务所有客户端macOS 应用、CLI、iOS、Android、无头节点全部走同一条协议通道每个网络参与者都必须被认证并完成配对角色清晰区分「节点node能力宿主」与「操作者operator控制面」集中审批审批请求路由到用户当前所在的客户端而不是停留在节点宿主上全链路 TLS 可选钉扎所有远程流量加密并支持证书指纹固定最小化代码重复同一台机器只出现一次不再有「UI 实例 节点实例」的重复条目。同时文档明确列出了Non-goals非目标防止重构跑偏不取消能力隔离仍然需要最小权限原则不把完整网关控制面暴露给没有作用域检查的客户端认证不依赖人类可读标签slug 永远不是安全要素。理解这是一次「协议与信任边界」的重构而不是功能堆叠。二、现状as-is两套协议栈与五类客户端2.1 协议一Gateway WebSocket控制面完整 API 面config、channels、models、sessions、agent 运行、日志、节点管理等默认绑定 loopback远程访问依赖 SSH / Tailscale 隧道认证通过connect携带 token/password无 TLS 钉扎依赖回环与隧道本身的安全性。文档指出的关键代码路径src/gateway/server/ws-connection/message-handler.tsWS 消息处理器负责connect握手、认证与角色判定src/gateway/client.ts网关客户端封装docs/gateway/protocol.md协议文档。2.2 协议二Bridge节点传输窄小的 allowlist 面只暴露节点所需方法JSONL over TCP可选 TLS 证书指纹钉扎启用 TLS 时发现discovery的 TXT 记录会广播指纹关键代码src/infra/bridge/server/connection.ts、src/gateway/server-bridge.ts、src/node-host/bridge-client.ts、docs/gateway/bridge-protocol.md。关于 Bridge 的现状需要补充一个重要背景docs/gateway/bridge-protocol.md 明确标注当前 OpenClaw 构建已不再启用 TCP bridge 监听器该文档仅保留作历史参考bridge.*配置键也已从配置 schema 中移除。也就是说Clawnet 文档中描述的「双协议并存」在仓库当前状态中正处于「Bridge 已退役、WS 一统」的收尾阶段——这正好印证了迁移策略中 Phase 5「Deprecate bridge」的推进。2.3 今天的控制面客户端客户端接入方式CLI通过callGateway走 Gateway WSsrc/gateway/call.tsmacOS 应用 UIGateway WSGatewayConnectionWeb 控制 UIGateway WSACPGateway WS浏览器控制自己的 HTTP 控制服务器独立于 WS2.4 今天的节点macOS 应用节点模式通过MacNodeBridgeSession连接 Gateway bridgeiOS/Android 应用连接 Gateway bridge配对 每节点 token 存储在网关上。2.5 今天的审批流exec与身份审批流现状Agent 通过 Gateway 调用system.runGateway 经 bridge 向节点发起 invoke节点运行时自行决定是否审批当「节点 macOS 应用」时UI 提示出现在 macOS 应用上节点向 Gateway 返回invoke-res。问题多跳路由且 UI 被绑定在节点宿主上。Presence 身份现状Gateway 的 presence 条目来自 WS 客户端节点 presence 条目来自 bridgemacOS 应用可能为同一台机器显示两个条目UI 一个、节点一个节点身份存在配对存储里UI 身份是另一套。2.6 痛点清单文档原文归纳两套协议栈需要同时维护WS Bridge远程节点审批时提示出现在节点宿主而非用户所在处TLS 钉扎只存在于 bridgeWS 依赖 SSH/Tailscale身份重复同一台机器显示为多个实例角色含糊UI、节点、CLI 的能力边界不清晰。三、新状态Clawnet一个协议两种角色按作用域授权3.1 核心模型单一 WS 协议连接时声明role scopeRole: node能力宿主注册能力接收 invoke上报事件但不能调用控制面 APIRole: operator控制面完整控制面 API按 scope 门控不直接执行 OS 动作而是路由到节点可选 scopeoperatoroperator.read状态查看operator.writeagent 运行、消息发送operator.adminconfig、channels、models 等管理操作。3.2 角色行为细则Node节点可注册能力caps、commands、权限可接收invoke命令system.run、camera.*、canvas.*、screen.record等可发送事件voice.transcript、agent.request、chat.subscribe不可调用 config/models/channels/sessions/agent 等控制面 API。Operator操作者完整控制面 API由 scope 门控接收所有审批请求不直接执行 OS 动作路由到节点。关键规则角色是**按连接per-connection**而非按设备划分的。同一台设备可以分别建立两条连接一条以 operator 角色、一条以 node 角色互不干扰。3.3 源码级印证角色与作用域已经落地这一设计在当前仓库已经实现可以逐项对证角色常量定义在 src/gateway/role-policy.tsexport const GATEWAY_ROLES [operator, node] as const;方法级授权在 src/gateway/role-policy.tsisNodeRoleMethod(method)判定的方法只允许node角色调用其余默认归operator。作用域常量与方法归属映射在 src/gateway/method-scopes.tsexport const ADMIN_SCOPE operator.admin as const; export const READ_SCOPE operator.read as const; export const WRITE_SCOPE operator.write as const; export const APPROVALS_SCOPE operator.approvals as const; export const PAIRING_SCOPE operator.pairing as const;METHOD_SCOPE_GROUPS把每个方法精确归类例如status、logs.tail、sessions.list归operator.readsend、agent、chat.send、node.invoke归operator.writeconfig.*前缀匹配、sessions.reset、channels.logout归operator.adminexec.approval.*归operator.approvalsdevice.token.rotate/revoke、node.pair.*归operator.pairing。节点专属方法集合NODE_ROLE_METHODS包括node.invoke.result、node.event、node.pending.*、skills.bins等——对应文档中「节点可注册能力、可接收 invoke、可上报事件」的行为边界。授权判定函数authorizeOperatorScopesForMethodsrc/gateway/method-scopes.ts实现了最小权限逻辑持有operator.admin可放行一切operator.read方法对持有 read 或 write 的客户端放行未分类方法默认拒绝default-deny。CLI 默认作用域在 src/gateway/method-scopes.tsexport const CLI_DEFAULT_OPERATOR_SCOPES: OperatorScope[] [ ADMIN_SCOPE, READ_SCOPE, WRITE_SCOPE, APPROVALS_SCOPE, PAIRING_SCOPE, ];与文档中「CLI 恒为 operator 角色作用域由子命令推导」的设计一致见下文角色示例。四、统一认证与配对4.1 客户端身份声明每个客户端在connect时必须提供deviceId稳定由设备密钥派生displayName人类可读名rolescopecapscommands。在 docs/gateway/protocol.md 的 connect 示例中这一结构已经完全落地{ type: req, id: …, method: connect, params: { minProtocol: 3, maxProtocol: 3, client: { id: cli, version: 1.2.3, platform: macos, mode: operator }, role: operator, scopes: [operator.read, operator.write], caps: [], commands: [], permissions: {}, auth: { token: … }, locale: en-US, userAgent: openclaw-cli/1.2.3, device: { id: device_fingerprint, publicKey: …, signature: …, signedAt: 1737264000000, nonce: … } } }节点示例则携带caps如camera/canvas/screen/location/voice、commands如camera.snap、screen.record、location.get和细粒度permissions如camera.capture: true、screen.record: false对应文档中「节点注册能力」的行为。4.2 统一配对流程文档设计客户端未认证连接Gateway 为这个deviceId创建pairing requestOperator 收到提示并批准/拒绝Gateway 签发与以下内容绑定的凭据设备公钥角色role(s)作用域scope(s)能力/命令caps/commands客户端持久化 token之后以认证状态重连。4.3 设备绑定认证防 bearer token 重放首选方案是设备密钥对device keypair而非裸 token设备一次性生成密钥对deviceId fingerprint(publicKey)公钥哈希Gateway 下发 nonce设备签名Gateway 验证Token 签发给公钥proof-of-possession而不是签发一个字符串。备选方案mTLS客户端证书安全性最强但运维复杂度更高短期 bearer token仅作为过渡阶段需尽早轮换与吊销。源码印证设备身份src/infra/device-identity.ts 实现了完整的密钥对身份用crypto.generateKeyPairSync(ed25519)生成密钥对deviceId fingerprintPublicKey(publicKeyPem)即对 SPKI 原始公钥做 SHA-256 后取 hexsrc/infra/device-identity.ts身份持久化在状态目录identity/device.jsonresolveStateDir()/identity/device.json文件权限0600若存储的deviceId与从公钥重新推导的不一致会自动修正保证 deviceId 恒等于公钥指纹。源码印证设备配对存储src/infra/device-pairing.ts 定义了完整的配对状态机export type DevicePairingPendingRequest { requestId: string; deviceId: string; publicKey: string; displayName?: string; role?: string; roles?: string[]; scopes?: string[]; silent?: boolean; ts: number; }; export type PairedDevice { deviceId: string; publicKey: string; roles?: string[]; scopes?: string[]; approvedScopes?: string[]; tokens?: Recordstring, DeviceAuthToken; createdAtMs: number; approvedAtMs: number; };pending 请求 TTL 为 5 分钟PENDING_TTL_MS 5 * 60 * 1000对应 pairing.md 中「pending 请求 5 分钟自动过期」token 按role维度存储tokens?: Recordstring, DeviceAuthToken即文档开放问题 1 推荐的「同一 deviceId 不同角色持有不同 token」支持device.token.rotate/device.token.revoke方法归operator.pairingscope。4.4 静默审批SSH 启发式文档要求精确定义静默审批避免引入薄弱环节优先选择以下一种Local-only客户端经 loopback/Unix socket 连接时自动配对SSH challengeGateway 下发 nonce客户端通过 SSH 取回以证明持有 SSH物理在场窗口在网关主机 UI 本地批准后允许短时间窗口例如 10 分钟内自动配对。必须始终记录自动批准日志。源码印证message-handler.ts中通过isLocalDirectRequest、isLoopbackAddress、isTrustedProxyAddress判定连接是否本地shouldAllowSilentLocalPairingsrc/gateway/server/ws-connection/handshake-auth-helpers.ts实现本地静默配对判定。docs/gateway/protocol.md 也明确本地连接包括 loopback 与网关主机自身的 tailnet 地址同主机 tailnet 绑定也可自动批准。配对存储方面docs/gateway/pairing.md 说明 macOS 应用可在请求标记silent: true且能通过 SSH 验证网关主机同一用户时尝试静默批准失败则回退到普通「Approve/Reject」提示。4.5 与node.pair.*的区别重要澄清docs/gateway/pairing.md 特别强调WS 节点使用设备配对rolenode在connect时完成node.pair.*是另一套独立配对存储不参与 WS 握手门控只有显式调用node.pair.*的客户端才走该流程。别把两套配对混为一谈。五、TLS 全覆盖开发与生产一致5.1 复用现有 Bridge TLS文档要求复用现有的 bridge TLS 运行时与指纹钉扎逻辑src/infra/bridge/server/tls.tssrc/node-host/bridge-client.ts中的指纹验证逻辑。5.2 应用到 WSWS 服务器使用相同的证书/密钥 指纹WS 客户端可选钉扎指纹发现discovery对所有端点广播 TLS 指纹发现信息只是定位提示locator hints永远不是信任锚点trust anchor。5.3 为什么降低对 SSH/Tailscale 的机密性依赖让远程移动连接默认安全。源码印证src/infra/tls/gateway.ts已实现网关 TLS 配置与证书指纹计算fingerprintSha256src/infra/tls/gateway.ts并有配套测试 src/infra/tls/fingerprint.test.ts 与 src/infra/tls/gateway.test.ts。docs/gateway/protocol.md 说明 WS 已支持 TLS客户端可选钉扎配置gateway.remote.tlsFingerprint或 CLI 参数--tls-fingerprint见 docs/gateway/remote.md。六、审批重构网关托管、集中交付6.1 现状 vs 提案现状审批发生在节点宿主macOS 应用节点运行时提示出现在节点运行之处。提案审批由网关托管gateway-hostedUI 交付给 operator 客户端。6.2 新流程六步Gateway 收到system.run意图来自 agentGateway 创建审批记录approval.requestedOperator UI一个或多个展示提示审批决定发送给 Gatewayapproval.resolve若批准Gateway 向节点发起 invoke节点执行并返回invoke-res。6.3 审批语义硬化硬性规则广播给所有 operator只有当前活跃 UI 显示模态框其他客户端收到 toast 通知首次决议生效first resolution winsGateway 拒绝后续 resolve视为已定案默认超时拒绝N 秒例如 60 秒后自动拒绝并记录原因决议需要operator.approvals作用域。6.4 收益提示出现在用户所在处mac 或手机远程节点获得一致的审批体验节点运行时保持无头headless不依赖 UI。6.5 源码印证协议与实现均已落地协议侧docs/gateway/protocol.md 的「Exec approvals」小节写明需要审批时网关广播exec.approval.requestedoperator 客户端调用exec.approval.resolve要求operator.approvalsscopehostnode的请求必须携带systemRunPlan规范化的argv/cwd/rawCommand/session 元数据缺少则被拒绝。实现侧src/gateway/exec-approval-manager.ts 就是「first resolution wins 超时 幂等」的落地register()幂等重复注册返回同一 pending promise已决议的 id 禁止重新注册approval id ... already resolved记录带expiresAtMs超时并记录requestedByConnId/DeviceId/ClientId防止其他客户端重放审批 id。审批方法归属operator.approvalsscope在 src/gateway/method-scopes.ts 中可见exec.approval.request、exec.approval.waitDecision、exec.approval.resolve等。节点侧审批错误处理见 src/gateway/node-invoke-system-run-approval-errors.ts 与node-invoke-system-run-approval.ts说明system.run走节点时审批已由网关侧接管。七、角色清晰度示例文档原文iPhone 应用Node 角色mic、camera、voice chat、location、push-to-talk可选operator.read状态与聊天查看可选operator.write/admin仅显式开启时。macOS 应用默认operator 角色控制 UI启用「Mac node」后开node 角色system.run、screen、camera两条连接使用同一 deviceId→ 合并为一条 UI 条目。CLI恒为operator 角色作用域由子命令推导子命令作用域status、logsoperator.readagent、messageoperator.writeconfig、channelsoperator.admin审批 配对operator.approvals/operator.pairing这一「子命令推导作用域」的设计在 CLI 默认配置中有迹可循CLI_DEFAULT_OPERATOR_SCOPES默认授予全部五个 scope见 src/gateway/method-scopes.ts配合方法级 scope 映射即可实现按子命令/方法的最小权限授权。八、身份与昵称稳定 ID 可爱 slug8.1 稳定 ID认证必需永不变化首选密钥对指纹公钥哈希——已在 4.3 节印证deviceId SHA-256(publicKey)。8.2 可爱 slug龙虾主题仅作人类标签非安全要素示例scarlet-claw、saltwave、mantis-pinch存储在网关注册表中可编辑冲突处理追加-2、-3。8.3 UI 分组同一deviceId跨角色连接 → 合并为单个「Instance」行徽标operator/node显示能力 最后在线时间。源码印证docs/gateway/protocol.md 的 Presence 一节写明system-presence返回以设备身份为 key 的条目包含deviceId、roles、scopes因此即使同一设备同时以 operator 与 node 连接UI 也可按设备显示单行。九、迁移策略Phase 0 → 6阶段内容当前仓库状态对照Phase 0发布本文档盘点所有协议调用与审批流本文即文档本身Phase 1扩展connect参数role、scope、deviceId为 node 角色增加 allowlist 门控已落地connect 携带role/scopes/caps/commands/permissions/devicemethod-scopes.tsrole-policy.ts实现门控Phase 2保留 bridge 运行并行增加 WS 节点支持用配置开关门控新特性bridge 已退役docs/gateway/bridge-protocol.md 标注不再随构建发布Phase 3在 WS 中增加审批请求/决议事件macOS 应用 UI 提示与响应节点运行时停止弹 UI已落地exec.approval.requested/exec.approval.resolveExecApprovalManagerPhase 4用 bridge TLS 运行时为 WS 增加 TLS客户端增加钉扎已落地src/infra/tls/gateway.tsgateway.remote.tlsFingerprint/--tls-fingerprintPhase 5迁移 iOS/Android/mac 节点到 WS保留 bridge 作 fallback稳定后移除bridge 已移除节点统一走 WS见server-mobile-nodes.ts、server-node-events.ts等Phase 6所有非本地连接要求基于密钥的身份增加吊销与轮换 UI已落地device.token.rotate/device.token.revokeoperator.pairingscopeDEVICE_AUTH_*迁移诊断整体看Clawnet 文档提出的愿景在当前仓库中已完成大部分双协议收敛为单协议角色与作用域、设备级认证、集中式审批、TLS 钉扎均已实现迁移正处于尾声Phase 5 完成、Phase 6 已部分完成。十、安全注意事项文档原文要点角色/allowlist 在网关边界强制执行任何客户端没有 operator scope 就拿不到「完整」API所有连接都必须配对TLS 钉扎降低移动端 MITM 风险SSH 静默审批只是便利措施仍须记录且可撤销发现discovery永远不是信任锚点能力声明capability claims由服务器按平台/类型与 allowlist 校验。对照实现authorizeOperatorScopesForMethod对未分类方法默认拒绝default-denyroleCanSkipDeviceIdentitysrc/gateway/role-policy.ts仅允许 operator 在共享认证通过时跳过设备身份其他情况一律要求设备身份——正是「所有连接都必须配对」的代码形态。能力校验方面resolveNodeCommandAllowlistsrc/gateway/node-command-policy.ts与node-invoke-sanitize.ts说明节点上报的 caps/commands 作为 claims 由网关按服务器端 allowlist 校验后再放行 invoke。十一、流媒体与大负载节点媒体WS 控制面对小消息没问题但节点还要传输摄像头片段camera clips屏幕录制screen recordings音频流audio streams。文档给出三种选项并要求实现前选定其一避免漂移WS 二进制帧 分块 背压规则独立流媒体端点仍要求 TLS 认证媒体密集型命令继续保留 bridge最后再迁移。现状提示既然 bridge 已不再随构建发布媒体传输实际上已偏向选项 1 与 2WS/独立端点的组合但从文档设计角度这是实现前必须明确的决策点。十二、能力与命令策略Capability Command Policy节点上报的 caps/commands 视为claims声明不是事实网关按平台强制 allowlist任何新命令需要 operator 审批或显式 allowlist 变更变更必须带时间戳审计。十三、审计与速率限制记录配对请求、批准/拒绝、token 签发/轮换/吊销速率限制配对垃圾请求与审批提示轰炸。实现印证网关侧已有 src/gateway/auth-rate-limit.ts认证暴力破解防护、src/gateway/control-plane-rate-limit.ts控制面速率限制、src/gateway/control-plane-audit.ts控制面审计WS 连接侧还有 unauthorized-flood-guard.ts 防未认证洪泛。十四、协议卫生显式协议版本 错误码重连规则 心跳策略Presence TTL 与 last-seen 语义。实现印证PROTOCOL_VERSION位于 src/gateway/protocol/schema.ts客户端在connect中携带minProtocol/maxProtocol服务器拒绝不匹配版本schema 由 TypeBox 定义通过pnpm protocol:gen含 Swift 生成protocol:gen:swift与pnpm protocol:check生成与校验见 docs/gateway/protocol.md。心跳策略见 docs/gateway/heartbeat.mdhello-ok中的policy.tickIntervalMs示例 15000ms即为心跳间隔。十五、开放问题Open Questions单设备双角色下的 token 模型推荐按角色分别签发 tokennode 与 operator 各一个同一 deviceId、不同 scope吊销更清晰。→ 已在PairedDevice.tokens: Recordrole, DeviceAuthToken中落地。Operator scope 粒度read/write/admin approvals pairing 为最小可行集后续再考虑按特性细分 scope。Token 轮换与吊销 UX角色变更时自动轮换提供按 deviceId role 吊销的 UI。发现Discovery扩展当前 Bonjour TXT加入 WS TLS 指纹与角色提示仅作为定位提示。跨网络审批广播给所有 operator 客户端活跃 UI 显示模态首个响应生效网关保证原子性。十六、总结TL;DR今天文档写作时WS 控制面 Bridge 节点传输并存痛点审批错位、实例重复、两套协议栈提案Clawnet单一 WS 协议 显式角色与作用域、统一配对 TLS 钉扎、网关托管审批、稳定设备 ID 可爱 slug预期收益更简单的 UX、更强的安全性、更少重复代码、更好的移动端路由。而对照当前仓库docs/gateway/protocol.md、src/gateway/role-policy.ts、src/gateway/method-scopes.ts、src/infra/device-identity.ts、src/infra/device-pairing.ts、src/gateway/exec-approval-manager.ts、src/infra/tls/gateway.ts 等文件表明这份重构蓝图的核心内容已基本落地——Clawnet 不再只是一份设计文档而是 OpenClaw 当前网络层的真实形态。若你要开发新的 operator 或 node 客户端直接以 docs/gateway/protocol.md 为准实现 WS 连接即可若你是老 bridge 客户端维护者则需按 docs/gateway/pairing.md 的 WS 设备配对流程迁移。赞分享人工智能大模型LLM 网关AI Agent即时通讯【免费下载链接】openclaw-zero-tokenOpenClaw: Use All Major AI Models NO API Token! Claude/ChatGPT/Gemini/DeepSeek/Doubao/Grok/Qwen/Manus/Kimi项目地址https://gitcode.com/gh_mirrors/op/openclaw-zero-token点击查看免费下载相关推荐OpenClaw Gateway WebSocket 协议详解connect 握手、帧结构、角色权限与设备认证迁移OpenClaw Gateway WebSocket 协议详解connect 握手、帧结构、角色权限与设备认证迁移 本文以 OpenClaw 官方文档 doc人工智能大模型LLM 网关AI Agent即时通讯多协议网关架构Authelia协议转换与统一认证多协议网关架构Authelia协议转换与统一认证 引言现代应用认证的挑战 在当今复杂的微服务架构中应用认证面临着前所未有的挑战。不同服务可能使用不同的认证后端认证鉴权单点登录身份认证应用安全Agno Agent 输入输出全解9 个示例控制回复格式让结构化输出一次到位Agno Agent 输入输出全解9 个示例控制回复格式让结构化输出一次到位 你向 Agent 提了个问题答案却是一整段散文你想要列表还想要代码能读的人工智能大模型AI AgentAgent 框架多智能体工具调用RAGAgent 工作流Agent 记忆创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考