Gateway 节点配对

Gateway 是节点准入的唯一来源。UI（macOS app 等）只是审批/拒绝待处理请求的前端。

重要：WS 节点在 connect 时使用设备配对（role node）。node.pair.* 是独立的配对存储，不控制 WS 握手。

配对流程

1. 节点连接到 Gateway WS 并请求配对
2. Gateway 存储待处理请求并发出 node.pair.requested 事件
3. 通过 CLI 或 UI 审批或拒绝请求
4. 审批后 Gateway 签发新 token（重新配对时 token 轮换）
5. 节点用 token 重新连接，状态变为”已配对”

待处理请求在 5 分钟后自动过期。

CLI 工作流

openclaw nodes pending                          # 查看待处理请求
openclaw nodes approve <requestId>              # 审批
openclaw nodes reject <requestId>              # 拒绝
openclaw nodes status                          # 查看已配对/已连接节点
openclaw nodes remove --node <id|name|ip>      # 移除节点
openclaw nodes rename --node <id|name|ip> --name "Living Room iPad"

节点命令门控（2026.3.31+）

重大变更：节点命令在配对审批前被禁用，仅设备配对不足以暴露声明的节点命令。

• 首次连接时自动请求配对
• 审批前所有待处理节点命令被过滤，不执行
• 审批前排队的命令被丢弃（不延迟执行）

可信 CIDR 自动审批

对于私有节点网络，可配置自动审批：

{
  gateway: {
    nodes: {
      pairing: {
        autoApproveCidrs: ["192.168.1.0/24"],
      },
    },
  },
}

安全边界：

• 仅适用于无请求 scope 的首次 role: node 设备配对
• Operator、浏览器、Control UI、WebChat 客户端仍需手动审批
• 角色/scope/元数据/公钥升级仍需手动审批

存储位置

~/.openclaw/nodes/paired.json   # 已配对节点（含 token，敏感）
~/.openclaw/nodes/pending.json  # 待处理请求

覆盖 OPENCLAW_STATE_DIR 时，nodes/ 目录随之移动。

相关链接

• gateway-discovery — 节点发现与传输
• gateway-troubleshooting — 故障排查