多节点架构

概述

多节点架构使多台设备协同工作，实现**"A 设备对话、B 设备执行"**的分布式体验。Gateway 作为中央调度枢纽，管理所有节点的注册、发现和智能路由。

架构总览

                      
                      ┌─────────┐   WebSocket   ┌─────────────┐   WebSocket   ┌──────────┐
│ Web 端   │ ◄────────────► │   Gateway    │ ◄────────────► │ APP 节点 A│
│(Browser) │               │  (Node.js)   │               │ (macOS)  │
└─────────┘               │              │               └──────────┘
                          │  - 节点注册    │
                          │  - 智能路由    │               ┌──────────┐
                          │  - 消息转发    │ ◄────────────► │ APP 节点 B│
                          │  - 权限验证    │               │(Windows) │
                          └─────────────┘               └──────────┘

                    

节点类型

节点注册信息

每个节点连接 Gateway 时注册以下信息：

节点可见范围

account 级节点：用户在多台设备上登录，可以在任意设备间调度任务。

enterprise 级节点：组织内的共享执行资源，所有成员都可以通过 Gateway 使用。

Gateway 智能路由

当 Web 端用户发起对话时，Gateway 使用三级降级策略选择最合适的执行节点：

第一级：LLM 语义路由

使用 OpenAI API 分析用户意图，匹配最佳节点：

LLM 返回：{nodeId, confidence, reason}

安全措施：

• 节点描述作为 DATA 处理，不作为指令执行
• 防止通过节点描述进行提示注入

注意：当前 LLM 路由尚未配置模型，会自动降级到第二级。

第二级：BM25 关键词匹配

基于 BM25 算法对用户查询和节点描述进行关键词匹配：

返回得分最高的节点，或 null（无匹配）。

第三级：最近连接兜底

按 connectedAtMs 时间戳选择最近连接的节点，确保始终有兜底结果。

远程执行

对话流程

                      
                      1. Web 端发送 chat.send 到 Gateway
2. Gateway 执行智能路由，选择目标节点
3. Gateway 转发消息到 APP 节点
4. APP 节点启动 Agent Loop 执行任务
5. 执行过程中的流式事件通过 chat.event 回传
6. Web 端实时渲染执行过程

                    

远程工具调用

                      
                      1. 主 Agent 通过 dispatch_multi_node_agent 指定远程节点
2. Gateway 发送 node.invoke.request 到目标节点
3. 远程节点启动独立 Agent Loop
4. 完成后通过 node.invoke.result 返回结果

                    

附件 Hoisting（2026-04 更新）NEW

跨节点派发时，如果消息包含内联 base64 附件（图片、文档等），系统会自动上传到云存储并改为 URL 引用：

• 原因：避免 Gateway RPC 消息过大导致传输失败
• 时机：远程派发前自动执行，用户无感知
• OS 路径归一化：跨操作系统（macOS/Windows/Linux）派发时自动转换路径分隔符

权限弹窗分发规则

跨节点执行时，工具权限弹窗"在哪一端展示"是关键的产品决策 —— 需要在"用户能及时响应"和"防止越权触发敏感操作"之间取得平衡。

同账号场景（调用方与执行方为同一账号）

不同账号场景（enterprise node 跨账号调用）

• node-D 是 enterprise 类型节点（同组织内可被其他用户发现），当前登录 user001
• node-E（登录 user002，APP 或 Web 端均可）通过 Gateway 向 node-D 发送消息
• 若 node-D 执行中需要工具权限：
  • 弹窗仅在 node-D 本机界面显示，不跨端分发到 node-E
  • 无人响应超过 5 分钟默认拒绝

设计动机

实施提醒：node-A APP → node-B APP 的同账号跨端分发链路目前不存在。涉及该路径的需求需新增 Gateway 路由 + APP 端接收/展示逻辑，不要默认它已可用。

跨账号 Gateway 隔离 NEW

除了权限弹窗的位置规则外，数据访问本身也有隔离：

个人记忆隔离

当节点以 enterprise 范围被跨账号调用时：

• 账户级记忆（userId 绑定）：❌ 不可访问
• 企业级记忆（orgId 绑定）：✅ 可访问
• 会话级记忆（本次会话）：✅ 可访问

通过 isRemoteSession 标志在记忆查询时强制过滤 —— 跨账号调用者无法通过 memory_query 读取目标节点所有者的个人记忆。

为什么这样设计

• 隐私保护：你的个人偏好、工作习惯、账户信息不能被同事通过调用你的节点读取
• 企业共享：组织的技术栈、规范等企业知识仍正常共享，不影响协作
• 合规需求：满足 GDPR 等隐私法规对"最小权限"的要求

对话图标区分

会话列表中不同来源的对话显示不同图标：

基于 isLocalInitiated、targetNodeId 和 sourceChannel 字段判断。

WebSocket 协议

连接握手

                      
                      1. Client → Gateway: connect.challenge
2. Gateway → Client: challenge（含 nonce）
3. Client → Gateway: connect（含签名的 JWT）
4. Gateway → Client: hello-ok（确认连接）

                    

心跳保活

• tick 机制：定期心跳维持连接
• 断线重连：指数退避重试
• 过期清理：Gateway 定期清理过期节点会话

流量控制

• Delta 节流：SSE 流式事件 150ms 聚合，减少 WebSocket 帧数
• Run TTL：10 分钟超时，每小时清理过期 Run

对用户意味着什么

多节点架构让你可以在任何地方发起任务，让最合适的设备来执行。

典型场景：

• 在咖啡厅用手机浏览器（Web 端）发起一个需要访问办公室电脑文件的任务 → Gateway 自动把任务路由到办公室的 APP 节点执行
• 团队里一台高性能服务器（macOS Pro）始终开着 APP 设为 enterprise → 所有团队成员都可以从自己的浏览器把重活派发过去

你能感受到的体验：

• 在 Web 端发起对话时，系统自动选择一个在线的 APP 节点来执行
• 会话列表中会显示不同的图标，让你知道对话是本地执行还是远程执行
• 如果没有 APP 节点在线，Web 端会提示无法执行需要 Agent 能力的任务
• 多台电脑都安装了 APP 时，可以手动选择在哪台电脑上执行

你需要注意的：

• Web 端无法独立执行 Agent 任务，需要至少一个 APP 节点在线
• 远程执行的对话有网络延迟（取决于 Gateway 和节点间的网络质量）
• 设置节点为 enterprise 范围时，团队成员可以将任务派发到你的设备上 —— 但你的个人记忆不会被访问到

相关文档

• Claw 节点管理 — 管理界面查看在线节点
• 运行时安全 — 节点 — 节点安全配置
• 子代理 — 跨节点派发 — dispatch_multi_node_agent
• 三维记忆系统 — 跨账号记忆隔离