OpenClaw 教程 OpenClaw Nodes 多节点 Pairing QR Troubleshooting

OpenClaw系列第23课：节点配对排错 - QR/手动连接失败怎么办

Kai2026-05-112026-05-12

这是「OpenClaw 教程课程」第 23 课。
前两课我们讲了多节点架构和 Tailscale 组网。这一课开始进入真正的排错现场：手机 / Mac / 树莓派 / headless node 配对不上，应该怎么查？

图：节点配对失败不要乱改配置，先按网络、认证、setup code、device pairing、node role、capabilities、permissions、approvals 分层排查。

多节点最折磨人的问题，往往不是“我不会搭”。

而是：

QR 扫了没反应
setup code 粘贴后连接失败
/pair 生成了，但手机连不上
openclaw devices list 看不到 pending
设备 approve 了，但 openclaw nodes status 没有
节点在线，但 camera / screen / location 调用失败
node host 连上了，但 exec host=node 跑不了

这类问题如果靠猜，会很痛苦。

正确方法是分层排查。

这一课我们不讲玄学。

就讲一个实用排错模型：

1	网络可达 → Gateway 认证 → setup code / bootstrap token → device pairing → node role → capabilities → command policy → 系统权限 / 前台状态 → exec approvals

只要按这个顺序查，大多数问题都能定位。

一、先记住：配对失败不要先重装

很多新手一遇到节点配对失败，第一反应是：

删除 App
重装 OpenClaw
重启 Gateway
清空配置
重置 Tailscale

不建议一上来这样做。

因为配对问题通常不是单点问题，而是链路里的某一层没通。

比如：

手机根本访问不到 Gateway
URL 是 ws://，但当前场景要求 wss://
setup code 过期
pending request 已经被新的请求替代
设备 paired 了，但请求的 role 不是 node
节点在线，但没声明目标 command
App 在后台，camera 被系统拒绝
system.run 被 exec approvals 拦住

所以第一原则是：

先定位卡在哪一层，再决定要不要重配。

图：OpenClaw 节点配对排错建议按层检查：网络、认证、setup code、device pairing、node role、capabilities、policy、权限和 approvals。

二、先区分三种“配对”

OpenClaw 里“pairing”这个词会出现在不同地方。

新手最容易混。

1）DM Pairing：谁能给 bot 发私聊

这是聊天入口权限。

比如 Telegram 私聊 bot 时，陌生用户可能需要 pairing code。

它回答的是：

这个聊天用户能不能和 bot 对话？

它不等于节点配对。

2）Device Pairing：这个设备能不能连接 Gateway

节点连接 Gateway 时，会带设备身份，并声明 role: node。

Gateway 会创建 device pairing request。

你需要 approve。

它回答的是：

这个设备能不能作为受信任设备加入 Gateway？

WS nodes 用的是这个。

3）Gateway-owned node pairing：历史/独立的 node pairing store

文档里提到：

openclaw nodes pending
openclaw nodes approve <requestId>
openclaw nodes reject <requestId>

属于 gateway-owned node pairing flow。

但要注意，当前 WS nodes 使用 device pairing。

文档也明确说：

node.pair.* 是 separate pairing store，不 gate WS connect handshake。

所以实操时，新手优先记这组命令：

openclaw devices list
openclaw devices approve <requestId>
openclaw devices reject <requestId>
openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>

一句话：

手机 / macOS / Android / headless WS nodes，先看 devices，再看 nodes。

三、正常节点配对流程长什么样？

先看一遍正常路径，排错才有参照物。

以手机节点为例：

Gateway 正常运行
Telegram 里给 bot 发 /pair
bot 返回 setup code 或 QR
手机 OpenClaw App 打开 Settings → Gateway
扫 QR 或粘贴 setup code
手机尝试连接 Gateway WebSocket
Gateway 收到新设备连接请求
Gateway 生成 pending device request
你执行：

1	openclaw devices list

找到对应 requestId，批准：

1	openclaw devices approve <requestId>

节点重新连接或完成握手
查看节点：

1 2	openclaw nodes status openclaw nodes describe --node <idOrNameOrIp>

如果一切正常，你应该看到：

设备 pending 出现过
approve 后设备角色包含 node
nodes status 显示 connected / paired
nodes describe 里能看到 capabilities / commands

图：正常节点配对从 setup code 开始，节点连接 Gateway，Gateway 生成 pending request，用户 approve 后节点成为 paired node。

四、第一层：网络是否可达？

如果节点连不到 Gateway，后面都不用查。

先问：

这个设备真的能访问 Gateway URL 吗？

常见场景：

Gateway 在 VPS
手机在移动网络
树莓派在家里局域网
Mac 在公司网络

这时要靠第 22 课讲过的：

Tailscale Serve
Tailscale tailnet
SSH tunnel
LAN
wss:// 安全端点

检查 Gateway 本身

在 Gateway 主机上：

1 2	openclaw status openclaw gateway status

如果 Gateway 都没起来，节点肯定连不上。

检查 Tailscale

如果你走 Tailscale：

1	tailscale status

看：

Gateway 主机是否在线
手机 / Mac / 树莓派是否在同一个 tailnet
MagicDNS 是否能解析
ACL 是否限制访问

检查路径类型

新手常见错误是：

1	公网 / tailnet 场景用了 ws://

文档里提到，Tailscale / public / non-loopback mobile pairing 建议使用：

Tailscale Serve
Funnel
其他 wss:// Gateway URL

而直接 non-loopback ws:// setup URL 可能会被拒绝。

所以如果你看到“连接失败”，先确认 setup code 里的 URL 类型。

五、第二层：Gateway auth 是否通过？

网络通了，不代表认证通过。

Gateway auth 可能是：

token
password
trusted-proxy
Tailscale identity
none，仅私有入口场景

如果你手动连 Gateway，常见问题是：

token 没传
token 传错
password 配在错误机器上
以为 gateway.remote.token 等于服务端 auth token
URL override 时没有显式带 token

文档里有个重要提醒：

CLI 传 --url 时，不会自动复用隐式 config/env credentials，需要显式带 --token 或 --password。

所以排错时，不要只看“地址对不对”。

还要看“凭据是不是按当前调用路径传进去了”。

六、第三层：setup code / QR 是否有效？

/pair 返回的 setup code 不是永久通行证。

文档里说，setup code 是 base64 编码的 JSON payload，里面包含：

url: Gateway WebSocket URL
bootstrapToken: 短期单设备 bootstrap token

要点：

setup code 有效期内要像密码一样对待。

常见失败原因：

setup code 过期
复制时少了一段
二维码对应的是旧 Gateway URL
Gateway 重启后环境变化
手机扫描的是旧聊天记录里的 QR
你重新生成了 code，但手机还在用旧的

建议：

重新发 /pair
使用最新 setup code / QR
不要用截图里很久以前的二维码
确认 code 里的 URL 是你当前可访问的 Gateway

如果你在 Telegram 里用 /pair qr，也要确认扫的是最新图。

七、第四层：devices list 有没有 pending？

手机扫完 QR 或粘贴 setup code 后，Gateway 应该出现 pending device request。

检查：

1	openclaw devices list

如果没有 pending，说明请求可能根本没到 Gateway，或者被前面某层拒绝了。

按顺序查：

Gateway 是否在线
手机是否能访问 Gateway URL
URL 是不是安全路径
setup code 是否过期
token / password 是否正确
Gateway 日志里有没有拒绝记录

可以同时看日志：

1	openclaw logs --follow

如果 pending 出现了，要仔细看：

requestId
role
scopes
platform
display name
是否是你刚刚连接的设备

不要看到 pending 就直接 approve。

先确认它是你自己的设备。

八、第五层：approve 的是不是当前 requestId？

有一个非常常见的问题：

同一个设备重复连接后，旧 pending request 被新的 request 替代。

文档里说，如果同一设备用不同 auth details 重试，比如 role / scopes / public key 变化，之前的 pending request 会被 superseded，新 requestId 会生成。

所以你可能遇到：

1	openclaw devices approve <旧requestId>

然后失败，或者批准了不是当前请求。

正确做法：

1	openclaw devices list

确认最新 requestId，再 approve：

1	openclaw devices approve <最新requestId>

如果你不确定，宁可 reject 旧请求，再重新连一次。

1	openclaw devices reject <requestId>

九、第六层：role 是不是 node？

设备 approve 后，不代表它一定是 node。

节点连接 Gateway 时应该声明：

1	role: node

如果 role 不对，就不会按 node 出现在 nodes status 里。

检查：

1 2	openclaw devices list openclaw nodes status

如果设备已经 approved，但 nodes status 没看到它，可能原因：

它不是 node role
它是 operator / browser / Control UI 类设备
它配对过，但当前没连接
它连接到另一个 Gateway 了
它用的是旧 token 或旧配置

这时候不要只盯 nodes status。

要回到 device pairing 看它批准的角色。

十、第七层：nodes status 是否 connected？

approve 之后，查看：

1 2	openclaw nodes status openclaw nodes list --connected

你要区分两种状态：

paired：这个设备被批准过
connected：这个节点现在在线

可能出现：

1	paired 了，但不 connected

这通常说明：

节点 App 退出了
手机 App 在后台被系统挂起
node host 进程没运行
网络断了
Gateway 重启后节点没重连
设备连接到了旧 Gateway 地址

对 headless node host，可以在节点机器上重新运行：

1	openclaw node run --host <gateway-host> --port 18789 --display-name "Build Node"

如果 Gateway 是 loopback-only，远程 node host 不能直接连，要按第 22 课用 Tailscale Serve / tailnet / SSH tunnel。

十一、第八层：nodes describe 里有没有目标能力？

节点在线，不代表它能做你想做的事。

查看节点详情：

1	openclaw nodes describe --node <idOrNameOrIp>

重点看：

capabilities
commands
permissions
platform
display name
connected 状态

比如你想调用 camera，但 describe 里没有 camera.* 或相关 command，那就不是权限问题，而是节点没有声明这个能力。

可能原因：

节点平台不支持
App 版本太旧
节点设置里关闭了
连接时没有声明该 command
Gateway command policy 过滤了
你连到的不是你以为的那个节点

一句话：

调用能力前，先看 describe。

图：排查节点时，先用 devices list 看配对，再用 nodes status 看在线状态，最后用 nodes describe 看能力和权限。

十二、第九层：Gateway node command policy 是否允许？

OpenClaw 的节点命令要过两个 gate：

节点自己声明了这个 command
Gateway node command policy 允许这个 command

文档里说，安全命令可能有平台默认允许。

但隐私重或危险命令，比如：

camera.snap
camera.clip
screen.record

通常需要显式 opt-in。

如果 describe 里能看到能力，但调用被拒绝，可能就是 policy 没放开。

不要为了省事直接全放。

建议按最小权限配置，只允许当前需要的命令。

十三、第十层：App 是否在前台？

移动端节点有一个常见坑：

iOS / Android 上，canvas.*、camera.*、screen.* 通常要求 App 在前台。

文档里的典型错误是：

1	NODE_BACKGROUND_UNAVAILABLE

解决方法很朴素：

打开手机上的 OpenClaw App
保持在前台
重新调用能力

这不是 OpenClaw 故障。

这是移动系统权限和后台限制。

所以看到这类错误，不要先改 Gateway。

先把 App 切到前台。

十四、第十一层：系统权限有没有给？

节点连接正常，能力声明正常，policy 也允许，但调用还是失败。

这时看系统权限。

常见权限矩阵：

能力	iOS	Android	macOS	常见错误
`camera.snap` / `camera.clip`	Camera，clip audio 可能需要 Mic	Camera，clip audio 可能需要 Mic	Camera，clip audio 可能需要 Mic	`*_PERMISSION_REQUIRED`
`screen.record`	Screen Recording，可能需要 Mic	Screen capture prompt，可能需要 Mic	Screen Recording	`*_PERMISSION_REQUIRED`
`location.get`	While Using 或 Always	前台 / 后台定位取决于模式	Location permission	`LOCATION_PERMISSION_REQUIRED`
`system.run`	不适用	不适用	node host approvals	`SYSTEM_RUN_DENIED`

常见错误：

CAMERA_DISABLED
*_PERMISSION_REQUIRED
LOCATION_DISABLED
LOCATION_PERMISSION_REQUIRED
LOCATION_BACKGROUND_UNAVAILABLE

排查建议：

去系统设置里确认 Camera / Microphone / Location / Screen Recording 权限
在 OpenClaw App 内确认对应能力开关
Android 上注意前台定位限制
iOS 上注意 While Using / Always / Precise Location

十五、第十二层：exec host=node 为什么失败？

node host 和 camera / screen 不一样。

它主要提供：

system.run
system.which

也就是让命令跑在节点机器上。

但远程命令执行非常敏感，所以还有 exec approvals。

如果你看到：

1 2	SYSTEM_RUN_DENIED: approval required SYSTEM_RUN_DENIED: allowlist miss

说明问题不在 pairing，而在 exec approvals。

检查：

1	openclaw approvals get --node <idOrNameOrIp>

添加只读命令 allowlist 示例：

1	openclaw approvals allowlist add --node <idOrNameOrIp> "/usr/bin/uname"

不要为了解决问题直接 full 放开。

建议：

1
2
3

优先 allowlist
必要时 ask
非常明确的私有环境才考虑 full

而且要记住：

Node pairing 是设备信任，不是 shell 命令授权。

十六、一个最快排错命令梯子

遇到节点问题，可以先按这个梯子跑。

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

然后跑节点相关：

openclaw devices list
openclaw nodes status
openclaw nodes list --connected
openclaw nodes describe --node <idOrNameOrIp>
openclaw approvals get --node <idOrNameOrIp>

健康信号是：

Gateway 正常
设备已 paired
角色包含 node
节点 connected
describe 里有目标 capability / command
command policy 允许
OS 权限允许
node exec approvals 符合预期

图：节点排错不要跳步骤，先查 Gateway，再查 devices，再查 nodes status，再查 describe，最后查 permissions 和 approvals。

十七、场景一：QR 扫了没反应

按这个顺序查：

QR 是否最新
setup code 是否过期
手机是否能访问 Gateway URL
URL 是否是 wss:// 或 Tailscale Serve 路径
Gateway 是否在线
Tailscale 是否在线
openclaw devices list 有没有 pending
openclaw logs --follow 有没有拒绝原因

常见修复：

重新发 /pair
使用最新 QR
确认手机在同一个 tailnet
不要使用旧截图
使用 Tailscale Serve 而不是公网 ws://

十八、场景二：setup code 粘贴后失败

常见原因：

复制不完整
多了空格或换行
code 已过期
code 里 URL 不是当前 Gateway
bootstrap token 失效
Gateway auth 不匹配
移动端拒绝 non-loopback 明文 ws://

修复建议：

重新生成 setup code
复制完整内容
确认 URL 类型
确认 Gateway 和 Tailscale 正常
再看 devices list

十九、场景三：devices list 看不到 pending

这说明 Gateway 没收到有效 pairing 请求。

按顺序查：

1
2
3

openclaw gateway status
tailscale status
openclaw logs --follow

然后确认：

节点是否真的点了 connect
Gateway URL 是否写对
token/password 是否正确
setup code 是否过期
手机是不是扫了旧 QR
设备是不是连接到了另一个 Gateway

如果是 headless node host，确认 node run 是否真的启动：

1	openclaw node run --host <gateway-host> --port 18789 --display-name "Build Node"

二十、场景四：approve 后 nodes status 没有

可能原因：

approve 的 requestId 不是最新
设备 role 不是 node
节点没有重新连接
App 在后台或被系统杀掉
node host 进程退出
连接的是另一个 Gateway
paired 在 device store，但 node command surface 没上线

排查：

openclaw devices list
openclaw nodes status
openclaw nodes list --connected
openclaw logs --follow

如果 requestId 不确定，重新 devices list，再 approve 最新请求。

二十一、场景五：nodes status 有，但 camera 失败

检查：

1	openclaw nodes describe --node <idOrNameOrIp>

然后看：

是否有 camera command
Gateway policy 是否允许 camera.snap / camera.clip
App 是否在前台
Camera 权限是否给了
Camera toggle 是否关闭
clip 是否需要 microphone 权限

常见错误：

NODE_BACKGROUND_UNAVAILABLE
CAMERA_DISABLED
CAMERA_PERMISSION_REQUIRED
MICROPHONE_PERMISSION_REQUIRED

修复：

打开 App 并保持前台
系统设置里允许 Camera / Microphone
App 设置里开启 camera
按最小权限允许对应 node command

二十二、场景六：screen / canvas 失败

检查：

1
2
3

openclaw nodes describe --node <idOrNameOrIp>
openclaw nodes canvas snapshot --node <idOrNameOrIp>
openclaw logs --follow

常见原因：

App 在后台
Screen Recording 权限没给
macOS 没开 Screen Recording
Android 屏幕捕获 prompt 没确认
Gateway policy 没允许

看到：

1 2	NODE_BACKGROUND_UNAVAILABLE *_PERMISSION_REQUIRED

先处理前台和系统权限。

二十三、场景七：location 失败

常见错误：

LOCATION_DISABLED
LOCATION_PERMISSION_REQUIRED
LOCATION_BACKGROUND_UNAVAILABLE
LOCATION_TIMEOUT
LOCATION_UNAVAILABLE

排查：

OpenClaw App 里的 location mode 是否 off
系统定位权限是否给了
iOS 是否允许 While Using / Always
Precise Location 是否符合需求
Android App 是否在前台
GPS / Wi-Fi / 蜂窝定位是否可用

location.get 属于敏感能力。

不要为了排错长期打开高精度位置。

二十四、场景八：node host 连上了，但 exec 失败

先确认 node 在线：

1 2	openclaw nodes status openclaw nodes describe --node <idOrNameOrIp>

再查 approvals：

1	openclaw approvals get --node <idOrNameOrIp>

如果是 allowlist miss，就添加明确路径：

1	openclaw approvals allowlist add --node <idOrNameOrIp> "/usr/bin/uname"

如果你想让当前会话默认走 node：

1	/exec host=node security=allowlist node=<id-or-name>

注意：

host=auto 不会自动替你选择 node。

要显式设置 host=node。

二十五、什么时候该删除并重新配对？

不要一开始就删。

但以下情况可以考虑重新配对：

设备换了系统或重装 App
设备公钥 / role / scopes 变化
旧 requestId 混乱
paired 记录明显是旧设备
节点名称和平台对不上
token 轮换失败
设备长期显示 stale

删除前先确认你删的是正确设备。

可用：

1 2	openclaw devices list openclaw nodes status

如果是旧 gateway-owned node pairing store，也可能用：

1	openclaw nodes remove --node <id\|name\|ip>

但要注意前面讲过的区别：WS nodes 主要看 device pairing。

二十六、不要做的危险操作

排错时，下面这些操作要谨慎：

1）不要把 Gateway 端口裸露公网

不要为了让手机连上，就直接开放：

1	0.0.0.0:18789

优先 Tailscale Serve / SSH tunnel / 安全 WSS。

2）不要把 autoApproveCidrs 写太大

尤其不要：

1	autoApproveCidrs: ["0.0.0.0/0"]

这会让节点自动批准边界变得很危险。

3）不要为了 exec 省事直接 full

node exec 是远程命令执行。

优先：

allowlist
ask
最小权限

4）不要 approve 看不懂的 pending

pending 里要看 role、platform、display name、requestId。

不确定就 reject。

5）不要把 setup code 发给别人

setup code 有 bootstrap token。

有效期内要像密码一样保管。

图：排错时不要为了省事扩大暴露面。不要裸露 Gateway，不要滥用 auto approve，不要随便 full exec，不要 approve 陌生 pending。

二十七、适合新手的排错提问模板

下面这些可以直接复制给 OpenClaw。

1）QR 扫码失败

1	我的 OpenClaw 手机节点扫 QR 后没有 pending。请按网络可达、Gateway auth、setup code 是否过期、devices list、gateway logs 的顺序排查，只做只读检查。

2）setup code 粘贴失败

1	我用 setup code 连接 OpenClaw Gateway 失败。请帮我判断是 code 过期、URL 类型、token/password、还是 Tailscale/WSS 路径问题，不要修改配置。

3）approve 后 nodes status 没有

1	我已经 approve 设备，但 openclaw nodes status 看不到节点。请帮我区分 device pairing、role=node、connected 状态和是否连到错误 Gateway。

4）节点在线但能力失败

1	节点在线，但 camera/screen/location 调用失败。请先查看 nodes describe，再按 command policy、App 前台、系统权限、节点设置排查。

5）node exec 失败

1	node host 已连接，但 exec host=node 失败。请检查 system.run capability、exec approvals、allowlist miss，不要直接改成 full 权限。

6）安全检查

请帮我检查当前 OpenClaw 节点配对和远程访问是否有安全风险：是否裸露 Gateway、是否滥用 autoApproveCidrs、是否有陌生 pending、是否 node exec 权限过宽。只读检查。

二十八、这一课最值得记住的一句话

如果今天只记一句话：

节点排错不要猜，按层查：网络、认证、setup code、device pairing、node role、connected、capability、policy、系统权限、approvals。

再记一句安全原则：

排错不是放开所有权限，而是找到卡住的那一层。

二十九、总结

今天这节课，我们把节点配对排错拆成了一套方法：

先区分 DM pairing、device pairing、gateway-owned node pairing。
WS nodes 优先看 openclaw devices list。
扫码失败先查网络和 setup code，不要先重装。
跨网络移动节点优先用 Tailscale Serve / WSS。
pending 不出现，说明请求可能没到 Gateway 或被前置认证拒绝。
approve 要确认最新 requestId。
paired 不等于 connected。
connected 不等于具备目标能力。
capability 存在，还要看 command policy。
手机 camera / screen / canvas 常常要求 App 前台。
系统权限缺失会导致 *_PERMISSION_REQUIRED。
node exec 失败多半要查 exec approvals。
不要为了排错扩大安全暴露面。

排错的核心不是记住每个错误码。

而是建立一个稳定的顺序：

1	先看 Gateway，再看网络，再看 pairing，再看 node，再看 capability，再看权限。

这样你以后遇到 QR 失败、setup code 失败、节点不在线、能力调用失败，都不会慌。

下一课预告

下一课我们会讲：

第 24 课：摄像头 / 音频 / 媒体节点实战

会重点讲：

手机摄像头怎么给 Agent 提供现场画面
camera.snap 和 camera.clip 怎么用
音频 / TTS / 媒体文件在节点里怎么流转
为什么相机、麦克风、屏幕录制要特别注意隐私
如何把节点能力做成安全的日常工作流

🦞 本文由八条撰写，持续更新中。