OpenClaw Node 技术架构与核心概念

cxr8282026-03-29 15:16

1.1 Node 的定义与定位

1.1.1 什么是 OpenClaw Node？

OpenClaw Node（节点）是 OpenClaw 生态系统中的伴随设备执行层，它可以运行在 macOS、iOS、Android、Linux、Windows 等多种平台上，通过 WebSocket 连接到 OpenClaw Gateway（网关），暴露一系列设备能力命令接口，使 AI Agent 能够远程执行操作。

官方定义（来自 OpenClaw 文档）：

"A node is a companion device (macOS/iOS/Android/headless) that connects to the Gateway WebSocket (same port as operators) with role: "node" and exposes a command surface (e.g. canvas.*, camera.*, device.*, notifications.*, system.*) via node.invoke."

1.1.2 Node 的核心特征

特征 说明 与其他组件的区别
WebSocket 连接 使用与操作员相同的端口（默认 18789） 与 Gateway 共享通信基础设施
角色标识 role: "node" 区别于 role: "operator" 和 role: "agent"
命令表面 暴露标准化的命令接口 不是被动执行，而是主动提供能力
设备配对 首次连接需批准 类似蓝牙配对的信任机制
本地审批 Exec Approvals 在 Node 主机上执行 安全决策去中心化
图 1: Gateway-Node 架构关系图

Node Layer - 执行层
Communication - WebSocket:18789
Gateway Layer - 决策层
🧠 AI 模型推理

Gemini/Claude/GPT
📨 消息路由
💾 会话管理
🛠️ 工具调用协调
🔌 连接管理
🔐 设备配对
🎫 认证授权
💓 心跳检测
💻 Node 1

Mac/远程管理
🐧 Node 2

Linux/CI-CD
📦 Node 3

NAS/文件管理
📱 Node 4

iPhone/相机
🤖 Node 5

Android/屏幕

图注: Gateway 负责 AI 决策，Node 负责边缘执行，通过 WebSocket 在端口 18789 通信。

1.1.3 Node 不是 Gateway

这是一个常见的误解。让我们明确区分：

组件 职责 运行位置 关键能力
Gateway AI 模型推理、消息路由、决策制定 中央服务器（云端/本地） 理解自然语言、调用工具、管理会话
Node 在远程设备上执行命令 边缘设备（Mac/PC/手机/NAS） 执行 system.run、访问设备能力

关键洞察：

Gateway 是"大脑"，负责思考和决策；Node 是"手脚"，负责执行和操作。这种分离使得 AI 可以在云端思考，在边缘执行，实现了"集中决策、分布式执行"的理想架构。

1.1.4 Node 的典型部署模式

复制代码 
┌─────────────────────────────────────────────────────────────┐
│                    Gateway (云端/本地)                       │
│  ┌─────────────────────────────────────────────────────┐    │
│  │  AI 模型 (Gemini/Claude/GPT)                         │    │
│  │  消息路由                                            │    │
│  │  会话管理                                            │    │
│  │  工具调用协调                                        │    │
│  └─────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘
           │ WebSocket (ws://gateway:18789)
           │
    ┌──────┼──────┬──────────┬──────────┐
    │      │      │          │          │
┌───▼──┐ ┌─▼───┐ ┌─▼───┐ ┌──▼───┐ ┌──▼────┐
│Node 1│ │Node2│ │Node3│ │Node4 │ │Node5  │
│Mac   │ │Linux│ │NAS  │ │iPhone│ │Android│
│远程管理│ │CI/CD│ │文件 │ │相机 │ │屏幕  │
└──────┘ └─────┘ └─────┘ └──────┘ └───────┘

部署场景：

  1. Node 1 (Mac): 远程办公室的 Mac，用于执行系统命令和浏览器自动化
  2. Node 2 (Linux): 构建服务器，用于 CI/CD 自动化
  3. Node 3 (NAS): 文件服务器，用于智能文件管理
  4. Node 4 (iPhone): 移动设备，用于拍照和屏幕录制
  5. Node 5 (Android): 平板设备，用于演示和监控

1.2 与 Gateway 的关系

1.2.1 连接模型

OpenClaw Node 与 Gateway 的连接遵循WebSocket 对等模型，这意味着：

  1. 相同端口: Node 和 Operator（操作员）使用相同的 WebSocket 端口（默认 18789）
  2. 不同角色 : 连接时通过 role 字段区分身份
  3. 双向通信: Gateway 可以向 Node 发送命令，Node 也可以主动向 Gateway 报告状态

连接流程：

复制代码 
1. Node 启动 → 创建 WebSocket 连接
2. 发送握手消息 → { role: "node", deviceId: "xxx", capabilities: [...] }
3. Gateway 验证 → 检查设备配对状态
4. 如果已配对 → 建立连接，注册能力
5. 如果未配对 → 创建配对请求，等待批准
6. 连接建立 → Node 进入待命状态
图 2: 设备配对流程序列图

操作员 Gateway Node 操作员 Gateway Node role: "node" 开始正常通信 1. WebSocket 连接请求 2. 检测到未配对设备 3. 创建配对请求 requestId: "abc123" deviceName: "Build-Node" 4. 通知"新设备请求配对" 5. 审查并批准 openclaw devices approve abc123 6. 保存配对信息 ~/.openclaw/node.json 7. 连接建立

图注: 设备配对类似蓝牙配对，确保只有授权节点可以接入。

1.2.2 设备配对机制

设备配对是 OpenClaw Node 的第一道安全防线。其设计灵感来自蓝牙配对，但针对 AI Agent 场景进行了优化。

配对流程：

复制代码 
┌─────────────┐                    ┌─────────────┐
│    Node     │                    │   Gateway   │
│  (未配对)   │                    │  (操作员)   │
└──────┬──────┘                    └──────┬──────┘
       │                                  │
       │  1. WebSocket 连接请求            │
       │────────────────────────────────>│
       │                                  │
       │  2. 检测到未配对设备              │
       │                                  │
       │  3. 创建配对请求                  │
       │     requestId: "abc123"          │
       │     deviceName: "Build-Node"     │
       │     capabilities: ["system.run"] │
       │                                  │
       │  4. 通知操作员                    │
       │     "新设备请求配对"              │
       │                                  │
       │  5. 操作员审查并批准              │
       │     openclaw devices approve abc123
       │                                  │
       │  6. 保存配对信息                  │
       │     ~/.openclaw/node.json        │
       │                                  │
       │  7. 连接建立                      │
       │<────────────────────────────────│
       │                                  │

配对信息存储：

json 复制代码 
// ~/.openclaw/node.json
{
  "nodeId": "node-abc123",
  "displayName": "Build-Node",
  "gatewayHost": "gateway.example.com",
  "gatewayPort": 18789,
  "pairedAt": "2026-03-27T10:30:00Z",
  "capabilities": ["system.run", "canvas.*", "camera.snap"]
}

1.2.3 命令路由机制

当 AI Agent 需要执行远程命令时，命令是如何从 Gateway 传递到 Node 的？

路由流程：

复制代码 
1. Agent 决定执行命令
   └─> "在 Build-Node 上运行 npm test"

2. Gateway 解析意图
   └─> 目标 Node: "Build-Node"
   └─> 命令：system.run
   └─> 参数：{ cmd: "npm", args: ["test"], cwd: "/project" }

3. Gateway 查找 Node 连接
   └─> 遍历已连接的 Node 列表
   └─> 匹配 displayName 或 nodeId

4. Gateway 通过 WebSocket 发送命令
   └─> { type: "node.invoke", command: "system.run", params: {...} }

5. Node 接收命令
   └─> 检查 Exec Approvals
   └─> 如果批准 → 执行命令
   └─> 如果拒绝 → 返回错误

6. Node 返回结果
   └─> { status: "success", output: "...", exitCode: 0 }

7. Gateway 转发结果给 Agent
   └─> Agent 继续后续操作

关键点：

  • Gateway 不直接执行命令，而是路由到合适的 Node
  • Node 有最终决定权，可以拒绝任何命令
  • 所有通信都通过单一的 WebSocket 连接，无需额外端口

1.3 技术实现原理

1.3.1 Node 主机架构

OpenClaw Node 的核心是一个轻量级 WebSocket 客户端，它负责：

  1. 建立并维护与 Gateway 的连接
  2. 注册设备能力
  3. 接收并执行命令
  4. 返回执行结果

简化架构图：

复制代码 
┌─────────────────────────────────────────────────────────┐
│                    Node Host                            │
│  ┌─────────────────────────────────────────────────┐   │
│  │  WebSocket Client                                │   │
│  │  ├─ 连接管理（重连、心跳）                       │   │
│  │  ├─ 消息编码/解码                                │   │
│  │  └─ 认证（Token/密码）                           │   │
│  └─────────────────────────────────────────────────┘   │
│  ┌─────────────────────────────────────────────────┐   │
│  │  Command Dispatcher                              │   │
│  │  ├─ 命令路由（canvas/camera/system/...）         │   │
│  │  ├─ Exec Approvals 检查                          │   │
│  │  └─ 并发控制                                     │   │
│  └─────────────────────────────────────────────────┘   │
│  ┌─────────────────────────────────────────────────┐   │
│  │  Command Implementations                         │   │
│  │  ├─ system.run → child_process.spawn             │   │
│  │  ├─ canvas.* → Puppeteer/Playwright              │   │
│  │  ├─ camera.* → AVFoundation/CameraX              │   │
│  │  └─ device.* → Platform-specific APIs            │   │
│  └─────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘

1.3.2 system.run 执行机制

system.run 是 Node 最核心、最强大的命令，它允许 AI Agent 在远程设备上执行任意 shell 命令。

执行流程：

复制代码 
1. 接收命令
   └─> { command: "system.run", params: { cmd: "npm", args: ["test"] } }

2. Exec Approvals 检查
   └─> 读取 ~/.openclaw/exec-approvals.json
   └─> 检查 "npm" 是否在白名单
   └─> 如果不在 → 请求人工审批（如果 ask=on-miss）
   └─> 如果在 → 继续执行

3. 环境准备
   └─> 设置工作目录（cwd）
   └─> 设置环境变量（过滤危险变量）
   └─> 创建子进程

4. 执行命令
   └─> child_process.spawn("npm", ["test"], { cwd, env, stdio: "pipe" })
   └─> 捕获 stdout/stderr
   └─> 监控超时（默认 300 秒）

5. 返回结果
   └─> { status: "success", output: "✓ 42 tests passed", exitCode: 0 }
图 3: 命令表面分类图

Command Surface
system
system.run
system.which
canvas
canvas.present
canvas.navigate
canvas.eval
canvas.snapshot
camera
camera.snap
camera.clip
screen
screen.record
device
device.status
device.permissions
notifications
notifications.send
location
location.get

图注: Node 暴露 7 大类命令接口，覆盖系统执行、浏览器自动化、媒体采集等。

安全机制：

json 复制代码 
// ~/.openclaw/exec-approvals.json
{
  "version": 1,
  "defaults": {
    "security": "allowlist",  // deny | allowlist | full
    "ask": "on-miss",         // off | on-miss | always
    "askFallback": "deny"     // 如果无法提示，默认拒绝
  },
  "agents": {
    "main": {
      "allowlist": [
        {
          "id": "abc123",
          "pattern": "/opt/homebrew/bin/npm",
          "lastUsedAt": 1711526400000,
          "lastUsedCommand": "npm test"
        }
      ]
    }
  }
}

1.3.3 文件绑定机制

为了防止"批准后文件被篡改"的攻击，OpenClaw 实现了文件绑定机制：

问题场景：

复制代码 
1. Agent 请求执行：node script.js
2. 用户审查 script.js 内容，确认安全，批准
3. 攻击者在批准后立即篡改 script.js
4. Agent 执行被篡改的 script.js，造成损害

文件绑定解决方案：

复制代码 
1. Agent 请求执行：node script.js
2. Exec Approvals 计算 script.js 的哈希：sha256("script.js") = "abc123..."
3. 批准时记录哈希值
4. 执行前重新计算哈希
5. 如果哈希不匹配 → 拒绝执行
6. 如果哈希匹配 → 继续执行

限制：

  • 仅适用于单个文件 的场景（如 node script.js）
  • 对于复杂命令（如 npm test 依赖数百个文件），无法完全绑定
  • 最佳实践：结合沙箱和最小权限原则

1.4 通信协议详解

1.4.1 WebSocket 消息格式

OpenClaw Node 与 Gateway 之间的通信基于自定义 WebSocket 协议，所有消息都是 JSON 格式。

连接建立消息：

json 复制代码 
{
  "type": "connect",
  "payload": {
    "role": "node",
    "deviceId": "node-abc123",
    "deviceName": "Build-Node",
    "capabilities": ["system.run", "canvas.*", "camera.snap"],
    "platform": "darwin",
    "platformVersion": "14.2",
    "appVersion": "2026.3.24"
  }
}

命令调用消息：

json 复制代码 
{
  "type": "node.invoke",
  "payload": {
    "command": "system.run",
    "params": {
      "cmd": "npm",
      "args": ["test"],
      "cwd": "/project",
      "env": { "NODE_ENV": "test" },
      "timeout": 300000
    },
    "requestId": "req-xyz789"
  }
}

命令响应消息：

json 复制代码 
{
  "type": "node.invoke.response",
  "payload": {
    "requestId": "req-xyz789",
    "status": "success",
    "output": "✓ 42 tests passed in 12.3s",
    "exitCode": 0,
    "duration": 12345
  }
}

1.4.2 心跳与重连

为了保持连接的可靠性，Node 实现了心跳机制 和自动重连：

心跳消息（每 30 秒）：

json 复制代码 
{
  "type": "ping",
  "payload": {
    "timestamp": 1711526400000
  }
}

心跳响应：

json 复制代码 
{
  "type": "pong",
  "payload": {
    "timestamp": 1711526400030,
    "latency": 30
  }
}

重连策略：

复制代码 
1. 连接断开 → 等待 1 秒
2. 重连失败 → 等待 2 秒
3. 重连失败 → 等待 4 秒
4. 重连失败 → 等待 8 秒
5. ... 指数退避，最大 60 秒
6. 重连成功 → 恢复心跳

1.4.3 认证机制

OpenClaw Node 支持两种认证方式：

1. Token 认证（推荐）：

json 复制代码 
{
  "type": "auth",
  "payload": {
    "method": "token",
    "token": "OPENCLAW_GATEWAY_TOKEN"
  }
}

2. 密码认证（不推荐，仅用于测试）：

json 复制代码 
{
  "type": "auth",
  "payload": {
    "method": "password",
    "password": "gateway-password"
  }
}

安全建议：

  • 生产环境必须使用 Token 认证
  • Token 应通过环境变量传递，不要硬编码
  • 定期轮换 Token（建议每 90 天）
  • 使用 OPENCLAW_GATEWAY_TOKEN 环境变量

1.5 命令表面（Command Surface）

1.5.1 命令分类

OpenClaw Node 暴露的命令分为以下几类：

类别 前缀 功能 平台支持
系统命令 system.* 执行 shell 命令、查询系统信息 全平台
浏览器自动化 canvas.* 打开网页、截图、执行 JS macOS/iOS/Android
相机控制 camera.* 拍照、录像 macOS/iOS/Android
屏幕录制 screen.* 录制屏幕视频 macOS/iOS/Android
设备管理 device.* 查询设备状态、权限 iOS/Android
通知 notifications.* 发送系统通知 macOS/iOS/Android/Windows
位置 location.* 获取地理位置 iOS/Android

1.5.2 常用命令示例

system.run - 执行 shell 命令：

json 复制代码 
{
  "command": "system.run",
  "params": {
    "cmd": "git",
    "args": ["status"],
    "cwd": "/project"
  }
}

canvas.present - 打开网页：

json 复制代码 
{
  "command": "canvas.present",
  "params": {
    "target": "https://example.com",
    "width": 1200,
    "height": 800
  }
}

camera.snap - 拍照：

json 复制代码 
{
  "command": "camera.snap",
  "params": {
    "facing": "back",
    "quality": 0.9
  }
}

screen.record - 录屏：

json 复制代码 
{
  "command": "screen.record",
  "params": {
    "duration": "10s",
    "fps": 10
  }
}

1.5.3 命令可用性检测

Node 在连接时会向 Gateway 报告其支持的能力：

json 复制代码 
{
  "type": "connect",
  "payload": {
    "capabilities": [
      "system.run",
      "system.which",
      "canvas.present",
      "canvas.navigate",
      "canvas.eval",
      "canvas.snapshot",
      "camera.snap",
      "camera.clip",
      "screen.record",
      "notifications.send"
    ]
  }
}

Gateway 根据这些能力决定哪些命令可以路由到该 Node。例如，如果 Node 不支持 camera.*，Agent 尝试调用时会收到错误提示。

小结

本章详细介绍了 OpenClaw Node 的技术架构和核心概念：

  1. Node 的定义：Node 是 OpenClaw 生态系统中的伴随设备执行层，通过 WebSocket 连接到 Gateway，暴露标准化的命令接口。

  2. 与 Gateway 的关系：Gateway 是"大脑"，负责决策；Node 是"手脚"，负责执行。两者通过 WebSocket 对等连接，使用设备配对机制建立信任。

  3. 技术实现 ：Node 主机由 WebSocket 客户端、命令分发器、命令实现三部分组成。system.run 通过子进程执行，受 Exec Approvals 保护。

  4. 通信协议：基于 WebSocket 的自定义 JSON 协议，支持心跳、重连、Token 认证等机制。

  5. 命令表面：Node 暴露 7 大类命令，涵盖系统执行、浏览器自动化、相机控制、屏幕录制、设备管理、通知、位置等功能。

参考文献：

  1. OpenClaw Official Documentation. "Nodes." https://docs.openclaw.ai/nodes/
  2. OpenClaw Official Documentation. "Exec Approvals." https://docs.openclaw.ai/tools/exec-approvals/
  3. OpenClaw Official Documentation. "Gateway Protocol." https://docs.openclaw.ai/gateway/protocol/
  4. Hostinger. "OpenClaw Use Cases: 25 Ways to Automate Work and Life." https://www.hostinger.com/tutorials/openclaw-use-cases
  5. Meta-Intelligence. "OpenClaw Hooks Guide." https://www.meta-intelligence.tech/en/insight-openclaw-hooks-guide
相关推荐
1941s2 小时前
OpenClaw 每日新玩法 | 多 Agent 协作系统 - 让 AI 员工 24小时自主工作
人工智能·agent·openclaw
步步为营DotNet2 小时前
深入剖析.NET 11 中 Microsoft.Extensions.AI 在 AI 驱动后端开发的进阶应用
人工智能·microsoft·.net
Ulyanov2 小时前
Python GUI工程化实战：从tkinter/ttk到可复用的现代化组件架构
开发语言·python·架构·gui·tkinter
空空潍2 小时前
Spring AI 实战系列（三）：多模型共存+双版本流式输出
java·人工智能·spring
gaozhiyong08132 小时前
提示词的解剖学：Gemini 3.1 Pro 提示工程高级策略与国内实战
人工智能·算法·机器学习
Langchain2 小时前
2026 年 AI 最值得关注的方向：上下文工程！
人工智能·python·自然语言处理·llm·agent·大模型开发·rag
学习者0072 小时前
大模型之VLLMA
人工智能
iThinkAi智能体2 小时前
1个运营带4个实习生，周产350篇笔记：小红书图文矩阵真的没那么玄乎
人工智能·经验分享·笔记
chaofan9802 小时前
深度实战：2026年大模型应用如何解决“接口抖动”？五大主流平台横向测评
人工智能·自动化·api·claude opus
热门推荐
012026年3月AI领域大事件：DeepSeek引领开源风暴02GitHub 镜像站点03围棋-html版本04小黑课堂计算机二级WPSoffice题库软件下载安装教程（2026年3月最新版）05班级宠物园部署指南06【计算机一级WPSoffice】小黑课堂题库软件下载安装教程（2026年3月最新版）07UV安装并设置国内源08“wsl --install -d Ubuntu-22.04”下载慢，中国地区离线安装 Ubuntu 22.04 WSL方法（亲测2025年5月6日）09中国象棋-html版本10Qwen3.5 开源全解析：从 0.8B 到 397B，代际升级 + 全场景选型指南