节点故障排查

当节点在 openclaw status 中可见，但节点工具（camera/screen/location/canvas/system.run 等）调用失败时，用本页排查。

命令阶梯（从全局到节点）

先把全局链路跑通：

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>

健康信号：

节点已连接且已配对（role 为 node）。
nodes describe 里包含你正在调用的 capability。
执行审批（exec approvals）策略与允许列表符合预期。

前台限制（Foreground requirements）

canvas.*、camera.*、screen.* 在 iOS/Android 节点上通常只能前台运行。

快速验证：

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

如果你看到 NODE_BACKGROUND_UNAVAILABLE，把节点 App 切到前台再重试。

权限矩阵（Permissions matrix）

能力（Capability）	iOS	Android	macOS 节点 App	常见失败码（Typical code）
`camera.snap`, `camera.clip`	相机（clip 还需要麦克风）	相机（clip 还需要麦克风）	相机（clip 还需要麦克风）	`*_PERMISSION_REQUIRED`
`screen.record`	屏幕录制（麦克风可选）	屏幕捕获授权（麦克风可选）	屏幕录制	`*_PERMISSION_REQUIRED`
`location.get`	使用期间/始终（取决于模式）	前台/后台位置（取决于模式）	位置权限	`LOCATION_PERMISSION_REQUIRED`
`system.run`	n/a（走 node host 路径）	n/a（走 node host 路径）	需要 exec approvals	`SYSTEM_RUN_DENIED`

配对（pairing）vs 执行审批（approvals）

这两道门是不一样的：

设备配对：节点是否允许连接到 Gateway？
执行审批：节点是否允许执行某个特定命令（system.run / exec）？

快速检查：

openclaw devices list
openclaw nodes status
openclaw approvals get --node <idOrNameOrIp>
openclaw approvals allowlist add --node <idOrNameOrIp> "/usr/bin/uname"

如果是“配对没过”，先批准设备配对。如果配对已通过但 system.run 失败，优先修 exec approvals / allowlist。

常见节点错误码

NODE_BACKGROUND_UNAVAILABLE → App 在后台；切前台再试。
CAMERA_DISABLED → 节点设置里相机开关关闭了。
*_PERMISSION_REQUIRED → 系统权限未授权/被拒绝。
LOCATION_DISABLED → 位置服务开关关闭。
LOCATION_PERMISSION_REQUIRED → 请求的定位权限等级不满足（例如需要“始终”）。
LOCATION_BACKGROUND_UNAVAILABLE → App 在后台，但只有“使用期间”权限。
SYSTEM_RUN_DENIED: approval required → 需要明确审批。
SYSTEM_RUN_DENIED: allowlist miss → 允许列表未命中，命令被阻止。

快速恢复闭环

openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>
openclaw approvals get --node <idOrNameOrIp>
openclaw logs --follow

仍卡住时：

重新批准设备配对。
重启/重新打开节点 App（确保前台）。
重新授予系统权限。
调整/重建 exec approvals 策略。