Appearance
节点故障排查
当节点在状态中可见但节点工具调用失败时，请使用本文排查。
诊断命令
bash
openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe然后运行节点专项检查：
bash
openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>
openclaw approvals get --node <idOrNameOrIp>健康信号：
- 节点已连接并以
node角色配对。 nodes describe包含你正在调用的功能。- Exec 审批显示预期的模式/允许列表。
前台要求
iOS/Android 节点上的 canvas.*、camera.* 和 screen.* 仅在前台可用。
快速检查与修复：
bash
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 | 不适用（走节点主机路径） | 不适用（走节点主机路径） | 需要 Exec 审批 | SYSTEM_RUN_DENIED |
配对与审批的区别
这是两个不同的门控：
- 设备配对：该节点能否连接到网关？
- Exec 审批：该节点能否运行某个 shell 命令？
快速检查：
bash
openclaw devices list
openclaw nodes status
openclaw approvals get --node <idOrNameOrIp>
openclaw approvals allowlist add --node <idOrNameOrIp> "/usr/bin/uname"若缺少配对，先批准节点设备。若配对正常但 system.run 失败，修复 exec 审批/允许列表。
常见节点错误码
NODE_BACKGROUND_UNAVAILABLE→ 应用在后台；切到前台。CAMERA_DISABLED→ 节点设置中摄像头开关已关闭。*_PERMISSION_REQUIRED→ 操作系统权限缺失/被拒绝。LOCATION_DISABLED→ 位置模式已关闭。LOCATION_PERMISSION_REQUIRED→ 请求的位置模式未授权。LOCATION_BACKGROUND_UNAVAILABLE→ 应用在后台但仅有"使用时"权限。SYSTEM_RUN_DENIED: approval required→ exec 请求需要显式审批。SYSTEM_RUN_DENIED: allowlist miss→ 命令被允许列表模式阻止。 在允许列表模式下，Windows 节点主机的cmd.exe /c ...形式会被视为允许列表未命中，除非通过 ask 流程审批。
快速恢复流程
bash
openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>
openclaw approvals get --node <idOrNameOrIp>
openclaw logs --follow若仍卡住：
- 重新批准设备配对。
- 重新打开节点应用（切到前台）。
- 重新授予操作系统权限。
- 重新创建/调整 exec 审批策略。
相关文档：