OpenClaw 节点故障排查：节点配对、前台要求、权限与工具失败的排查步骤
OpenClaw 节点故障排查
当节点在状态中可见，但节点工具运行失败时，可以使用本页面进行排查。
命令阶梯
openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe然后运行节点专属检查：
openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>
openclaw approvals get --node <idOrNameOrIp>健康的信号：
- 节点已连接，且以
node角色完成配对。 nodes describe包含你正在调用的能力。- 执行授权显示预期的模式 / 白名单。
前台要求
在 iOS/Android 节点上，canvas.*、camera.* 和 screen.* 仅支持前台运行。 快速检查与修复：
openclaw nodes describe --node <idOrNameOrIp>
openclaw nodes canvas snapshot --node <idOrNameOrIp>
openclaw logs --follow
如果你看到 NODE_BACKGROUND_UNAVAILABLE，请将节点应用切换到前台并重试。
权限矩阵
| 能力 | iOS | Android | macOS 节点应用 | 典型错误码 |
|---|---|---|---|---|
camera.snap、camera.clip |
相机（clip 音频还需要麦克风） | 相机（clip 音频还需要麦克风） | 相机（clip 音频还需要麦克风） | *_PERMISSION_REQUIRED |
screen.record |
屏幕录制（麦克风可选） | 屏幕捕获提示（麦克风可选） | 屏幕录制 | *_PERMISSION_REQUIRED |
location.get |
使用期间或始终（取决于模式） | 基于模式的前台 / 后台位置 | 位置权限 | LOCATION_PERMISSION_REQUIRED |
system.run |
n/a（节点主机路径） | n/a（节点主机路径） | 需要执行授权 | SYSTEM_RUN_DENIED |
配对与授权的区别
这是两个不同的校验关卡：
- 设备配对：该节点能否连接到网关？
- 执行授权：该节点能否运行特定的 shell 命令？ 快速检查：
openclaw devices list
openclaw nodes status
openclaw approvals get --node <idOrNameOrIp>
openclaw approvals allowlist add --node <idOrNameOrIp> "/usr/bin/uname"
如果配对缺失，请先批准节点设备。 如果配对正常但 system.run 失败，请修复执行授权 / 白名单。
常见节点错误码
NODE_BACKGROUND_UNAVAILABLE→ 应用已后台运行；请将它切换到前台。CAMERA_DISABLED→ 节点设置中禁用了相机开关。*_PERMISSION_REQUIRED→ 系统权限缺失 / 被拒绝。LOCATION_DISABLED→ 位置模式已关闭。LOCATION_PERMISSION_REQUIRED→ 请求的位置模式未被授予。LOCATION_BACKGROUND_UNAVAILABLE→ 应用已后台运行，但仅拥有 “使用期间” 权限。SYSTEM_RUN_DENIED: approval required→ 执行请求需要显式批准。SYSTEM_RUN_DENIED: allowlist miss→ 命令被白名单模式阻止。 在 Windows 节点主机上，类似cmd.exe /c ...这样的 shell 包装形式，在白名单模式下会被视为白名单未命中，除非通过询问流程完成批准。
快速恢复流程
openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>
openclaw approvals get --node <idOrNameOrIp>
openclaw logs --follow如果仍然卡住：
- 重新批准设备配对。
- 重新打开节点应用（前台）。
- 重新授予系统权限。
- 重新创建 / 调整执行授权策略。
相关文档：