节点管理

节点是什么

Node（节点） 是连接到 Gateway 的配套设备（macOS/iOS/watchOS/Android/无头 Linux），以 role: "node" 身份通过 WebSocket 连接，暴露设备能力供 Agent 调用。

能力	说明
canvas.*	画布渲染（展示 HTML/CSS/JS 页面）
camera.*	拍照、录像
screen.*	屏幕录制和截图
device.*	设备信息、安装应用列表
notifications.*	发送/读取系统通知
system.run	在节点上执行 shell 命令

关键概念

Node 是外围设备，不是网关。它不运行 Gateway 服务，通道消息始终落在 Gateway 上而非 Node 上。

节点架构

mermaid

graph LR
    subgraph Gateway 主机
        GW[Gateway<br/>127.0.0.1:18789]
        AG[Agent]
    end

    subgraph 节点设备
        N1[macOS 菜单栏 App]
        N2[iOS/Android App]
        N3[无头 Linux Node]
    end

    GW <-->|WebSocket| N1
    GW <-->|WebSocket| N2
    GW <-->|WebSocket| N3
    AG -->|node.invoke| GW
    GW -->|转发命令| N1 & N2 & N3

配对节点

节点使用设备配对机制。连接时节点出示签名设备身份，Gateway 创建配对请求，管理员批准后建立信任关系。

bash

# 查看待配对请求
openclaw devices list

# 批准配对
openclaw devices approve <requestId>

# 拒绝配对
openclaw devices reject <requestId>

# 查看已连接节点状态
openclaw nodes status

# 查看节点详情
openclaw nodes describe --node <idOrNameOrIp>

配对有效期

待处理的配对请求在设备最后一次重试后 5 分钟过期。持续重连的设备会保持其请求存活，不会每次重连都生成新的请求。

启动节点

macOS 菜单栏 App 模式

macOS 可直接运行菜单栏 App，作为单节点连接 Gateway，提供 Canvas、摄像头、屏幕、通知等命令。

命令行无头模式

bash

# 前台运行节点
openclaw node run --host <gateway-host> --port 18789 --display-name "Build Node"

# 安装为系统服务（Linux）
openclaw node install --host <gateway-host> --port 18789 --display-name "Build Node"
openclaw node start

通过 SSH 隧道连接远程 Gateway

bash

# Terminal A：建立 SSH 隧道
ssh -N -L 18790:127.0.0.1:18789 user@gateway-host

# Terminal B：节点通过隧道连接
export OPENCLAW_GATEWAY_TOKEN="<gateway-token>"
openclaw node run --host 127.0.0.1 --port 18790 --display-name "Remote Node"

节点配置文件

json5

// 节点机器上的 ~/.openclaw/openclaw.json
{
  nodeHost: {
    mcp: {
      servers: {
        localDocs: {
          command: "npx",
          args: ["-y", "@modelcontextprotocol/server-filesystem", "/srv/docs"],
          toolFilter: { include: ["read_*", "search"] },
        },
        internalApi: {
          url: "https://mcp.internal.example/mcp",
          transport: "streamable-http",
          headers: { Authorization: "Bearer ${INTERNAL_MCP_TOKEN}" },
        },
      },
    },
  },
}

文件传输

节点与 Gateway 之间可以通过文件传输工具操作文件：

工具	方向	用途
`file_fetch`	节点 → Gateway	从节点读取文件
`file_write`	Gateway → 节点	向节点写入文件
`dir_list`	节点 → Gateway	列出节点目录内容
`dir_fetch`	节点 → Gateway	打包下载节点目录树

bash

# Agent 可以这样操作节点上的文件
# file_fetch: node="MBP-Node", path="/Users/bob/projects/README.md"
# dir_list: node="MBP-Node", path="/Users/bob/projects/"

本地模型推理

节点上运行的 Ollama 模型可以通过 node_inference 工具供 Agent 调用：

bash

# 发现节点上的可用模型
# Agent 调用：node_inference action=discover

# 使用特定节点上的模型进行推理
# Agent 调用：node_inference action=run node="MBP-Node" model="qwen3:14b" prompt="..."

这允许 Agent 将任务分发到节点上执行，利用节点的 GPU 进行本地推理，数据不离开节点。

节点重命名与移除

bash

# 重命名节点
openclaw nodes rename --node <id|name|ip> --name "客厅 Mac Mini"

# 移除节点配对
# 对于仅 node 角色的设备 → 完整删除行
# 对于混合角色设备 → 仅移除 node 角色，保留其他角色
openclaw nodes remove --node <id|name|ip>

排故：常见节点问题

节点失连

bash

# 1. 检查 Gateway 状态
openclaw gateway status

# 2. 查看节点状态
openclaw nodes status

# 3. 检查防火墙
# Gateway 端口 18789 需要可达

# 4. 查看日志
openclaw logs --follow

配对失败

症状	可能原因	解决方法
配对请求过期	5 分钟超时	重新发起连接，快速批准
`protocol mismatch`	版本不兼容	先升级 Gateway，再升级节点
认证失败	Token 错误	确认 `OPENCLAW_GATEWAY_TOKEN` 正确
连接拒绝	防火墙/网络	检查节点能否 telnet 到 Gateway 端口

升级顺序

升级时先升级 Gateway，再升级各节点。N-1 协议窗口保证 v4 Gateway 可接受 v3 节点，Operator/UI 会话仍需当前协议版本。

排故命令速查

bash

openclaw nodes status                # 查看所有节点
openclaw nodes describe --node <id>  # 节点详细信息
openclaw devices list                # 待配对设备
openclaw logs --follow               # 实时日志
openclaw gateway status --deep       # 深度状态检查

Node-Hosted Skills

已连接的无头节点可以发布其本地 Skills，这些 Skills 在节点连接时出现在 Agent 的 Skill 列表中，断开后自动消失。本地或 Gateway Skill 同名时保留本地/Gateway 版本，节点 Skill 会获得确定性的节点前缀名称。

节点 Skill 的文件、相对引用和二进制文件都存在于节点上，执行时需指定 host=node node=<node-id>。

节点上的 MCP Server

节点机器上可以配置 MCP Server，无需在 Gateway 端重复配置：

json5

// 节点机器上的 ~/.openclaw/openclaw.json
{
  nodeHost: {
    mcp: {
      servers: {
        localDocs: {
          command: "npx",
          args: ["-y", "@modelcontextprotocol/server-filesystem", "/srv/docs"],
          toolFilter: { include: ["read_*"] },
        },
      },
    },
  },
}

无头节点主机启动这些 Server、列出工具并发布描述符。工具调用通过 mcp.tools.call.v1 路由回节点执行。

版本适配与升级

Gateway 的 WebSocket 接受 N-1 协议窗口内的已认证节点客户端：

v4 Gateway 可接受 v3 节点
Operator 和 UI 会话必须使用当前协议版本
节点升级期间，N-1 节点保持可见和可管理
插件拥有的能力和命令在节点升级到当前协议前保持隐藏
早于 N-1 的节点需要在重连前离线升级

节点安全

node run 的所有执行审批在节点上通过 ~/.openclaw/exec-approvals.json 强制执行
审批绑定的节点运行会绑定精确的请求上下文：执行路径在批准前准备规范化的 systemRunPlan，批准后 Gateway 转发该存储的计划
共享密钥认证通过 OPENCLAW_GATEWAY_TOKEN 环境变量或配置中 gateway.auth.token 提供
建议为节点使用专用系统用户并配置最小权限

下一步

掌握了节点管理后，继续学习通道配置 →

加载练习题中...

🎯 本章要点

Node 是连接 Gateway 的配套设备，暴露设备能力供 Agent 调用
提供 canvas 渲染、camera 拍照、system.run 执行命令等设备能力

节点管理 ​

节点是什么 ​

节点架构 ​

配对节点 ​

启动节点 ​

macOS 菜单栏 App 模式 ​

命令行无头模式 ​

通过 SSH 隧道连接远程 Gateway ​

节点配置文件 ​

文件传输 ​

本地模型推理 ​

节点重命名与移除 ​

排故：常见节点问题 ​

节点失连 ​

配对失败 ​

排故命令速查 ​

Node-Hosted Skills ​

节点上的 MCP Server ​

版本适配与升级 ​

节点安全 ​

下一步 ​

🎯 本章要点 ​

有问题或补充？欢迎留言

节点管理

节点是什么

节点架构

配对节点

启动节点

macOS 菜单栏 App 模式

命令行无头模式

通过 SSH 隧道连接远程 Gateway

节点配置文件

文件传输

本地模型推理

节点重命名与移除

排故：常见节点问题

节点失连

配对失败

排故命令速查

Node-Hosted Skills

节点上的 MCP Server

版本适配与升级

节点安全

下一步

🎯 本章要点