节点故障排查

节点在状态中可见，但工具调用失败时，参考这个页面。

排查流程

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 包含你要调用的能力。
执行审批显示预期的模式/白名单。

前台要求

canvas.*、camera.* 和 screen.* 在 iOS/Android 节点上仅限前台使用。

快速检查与修复：

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

如果看到 NODE_BACKGROUND_UNAVAILABLE，把节点应用切到前台再试。

权限矩阵

能力	iOS	Android	macOS 节点应用	典型错误码
`camera.snap`、`camera.clip`	摄像头（+ 录制视频时需要麦克风）	摄像头（+ 录制视频时需要麦克风）	摄像头（+ 录制视频时需要麦克风）	`*_PERMISSION_REQUIRED`
`screen.record`	屏幕录制（+ 可选麦克风）	屏幕录制提示（+ 可选麦克风）	屏幕录制	`*_PERMISSION_REQUIRED`
`location.get`	使用期间或始终（取决于模式）	前台/后台定位（取决于模式）	定位权限	`LOCATION_PERMISSION_REQUIRED`
`system.run`	不适用（走节点主机）	不适用（走节点主机）	需要执行审批	`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 包装器在白名单模式下视为白名单未命中，除非通过 ask 流程批准。

快速恢复流程

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

如果还是不行：

重新批准设备配对。
重新打开节点应用（保持前台）。
重新授予系统权限。
重新创建/调整执行审批策略。