Node 故障排除

�?node 在状态中可见�?node 工具失败时使用此页面�?

命令阶梯

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

然后运行 node 特定检查：

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

健康信号�?

Node 已连接并�?node 角色配对�?
nodes describe 包含你调用的功能�?
Exec 批准显示预期的模�?白名单�?

前台要求

canvas.*、camera.* �?screen.* �?iOS/Android nodes 上仅限前台�?

快速检查和修复�?

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

如果你看�?NODE_BACKGROUND_UNAVAILABLE，将 node 应用带到前台重试�?

权限矩阵

功能	iOS	Android	macOS node 应用	典型失败代码
`camera.snap`、`camera.clip`	相机�? 片段音频的麦克风�?	相机�? 片段音频的麦克风�?	相机�? 片段音频的麦克风�?	`*_PERMISSION_REQUIRED`
`screen.record`	屏幕录制�? 可选麦克风�?	屏幕捕获提示�? 可选麦克风�?	屏幕录制	`*_PERMISSION_REQUIRED`
`location.get`	取决于模式的”使用�?�?始终”	取决于模式的前台/后台位置	位置权限	`LOCATION_PERMISSION_REQUIRED`
`system.run`	n/a（node host 路径�?	n/a（node host 路径�?	需�?Exec 批准	`SYSTEM_RUN_DENIED`

配对 vs 批准

这些是不同的门控�?

设备配对：此 node 能否连接�?Gateway�?
Exec 批准：此 node 能否运行特定 shell 命令�?

快速检查：

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

如果缺少配对，首先批�?node 设备�? 如果配对正常�?system.run 失败，修�?exec 批准/白名单�?

常见 node 错误代码

NODE_BACKGROUND_UNAVAILABLE �?应用在后台；将其带到前台�?
CAMERA_DISABLED �?相机开关在 node 设置中禁用�?
*_PERMISSION_REQUIRED �?操作系统权限缺失/被拒绝�?
LOCATION_DISABLED �?位置模式关闭�?
LOCATION_PERMISSION_REQUIRED �?请求的位置模式未授予�?
LOCATION_BACKGROUND_UNAVAILABLE �?应用在后台但仅存�?使用�?权限�?
SYSTEM_RUN_DENIED: approval required �?exec 请求需要明确批准�?
SYSTEM_RUN_DENIED: allowlist miss �?命令被白名单模式阻止�? �?Windows node hosts 上，白名单模式下�?shell-wrapper 形式�?cmd.exe /c ... 被视为白名单缺失，除非通过询问流程批准�?

快速恢复循�?

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

如果仍然卡住�?

重新批准设备配对�?
重新打开 node 应用（前台）�?
重新授予操作系统权限�?
重新创建/调整 exec 批准策略�?