节点概览

Node（节点）是 OpenClaw 中用于扩展 Agent 感知与交互能力的边缘设备。通过节点，你的 Agent 可以获得语音、视觉、定位等硬件能力，真正实现与物理世界的交互。

什么是节点

节点是运行在各类设备上的轻量客户端，通过 WebSocket（长连接协议）与 Gateway（网关）实时通信。每个节点为 Agent 提供一种或多种设备能力。

核心思想

Agent 运行在网关上处理逻辑，Node 运行在终端设备上提供硬件能力，两者通过网络协同工作。

节点类型

节点类型	设备	提供能力
Audio（音频节点）	麦克风/扬声器	语音采集、语音播放、STT/TTS
Camera（摄像头节点）	摄像头设备	图像采集、视频流、视觉分析
Mobile（移动节点）	iOS / Android 手机	位置、传感器、通知、语音
Desktop（桌面节点）	macOS / Linux / Windows	系统音频、屏幕截图、文件访问

架构关系

节点在 OpenClaw 整体架构中的位置：

┌─────────────┐     WebSocket      ┌─────────────┐     API      ┌─────────────┐
│   Node      │ ◄────────────────► │   Gateway   │ ◄──────────► │   Agent     │
│  (边缘设备)  │    实时双向通信      │   (网关)     │   工具调用    │  (智能体)    │
└─────────────┘                    └─────────────┘              └─────────────┘
  音频/摄像头/GPS                     路由 & 调度                   LLM 推理

节点生命周期

每个节点连接到网关时，会经历以下状态：

pair（配对） → connect（连接） → ready（就绪） → active（活跃）

1. pair：通过配对码或 QR Code（二维码）完成身份绑定
2. connect：建立 WebSocket 连接
3. ready：完成能力协商，等待指令
4. active：正在执行任务（如录音、拍照）

自动重连

节点断开后会自动尝试重连，默认重试间隔为 5 秒，最多重试 60 次。

常用命令

查看所有已注册节点

openclaw nodes

输出示例：

ID          TYPE     STATUS    DEVICE          LAST SEEN
node-a1b2   audio    active    MacBook Pro     2s ago
node-c3d4   camera   ready     Raspberry Pi    15s ago
node-e5f6   mobile   offline   iPhone 15       2h ago

启动本机节点

openclaw node --type audio

权限要求

启动音频节点需要操作系统授予麦克风权限；启动摄像头节点需要授予摄像头权限。首次运行时系统会弹出权限请求。

配对远程节点

openclaw pairing --generate

生成一个一次性配对码，在远程设备上输入即可完成配对。

节点能力一览

通过节点，Agent 可以获得以下能力：

• 音频采集：实时录音、语音识别（STT）
• 语音输出：文字转语音（TTS）、音频播放
• 摄像头：拍照、连续帧采集、运动检测
• 定位：GPS 坐标、地理围栏
• 传感器：加速度计、陀螺仪（移动设备）
• 通知：推送通知到移动设备

配置文件

节点的全局配置在网关配置文件中的 nodes 部分：

config.yaml

nodes:
  auto_accept: false          # 是否自动接受新节点配对
  heartbeat_interval: 30      # 心跳间隔（秒）
  reconnect_attempts: 60      # 最大重连次数
  capabilities:
    audio: true
    camera: true
    location: true

下一步

你想要...	请阅读
添加语音交互	音频与语音
添加视觉能力	摄像头捕获
处理图片媒体	图片与媒体
使用位置功能	位置命令
解析多模态内容	媒体理解
语音对话	对话模式
设置唤醒词	语音唤醒
排查节点问题	故障排查