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，请将节点应用切换到前台并重试。

权限矩阵

配对与授权的区别

这是两个不同的校验关卡：

1. 设备配对：该节点能否连接到网关？
2. 执行授权：该节点能否运行特定的 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

如果仍然卡住：

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

相关文档：

• 节点概述
• 相机节点
• 位置命令
• 执行授权
• 配对网关