Node 故障排查

当节点在 status 中可见，但 node tools 调用失败时，请使用本页。

命令排查顺序

  1. openclaw status
  2. openclaw gateway status
  3. openclaw logs --follow
  4. openclaw doctor
  5. openclaw channels status --probe

然后执行节点专项检查：

  1. openclaw nodes status
  2. openclaw nodes describe --node <idOrNameOrIp>
  3. openclaw approvals get --node <idOrNameOrIp>

健康信号：

  • 节点已连接，并且以 node 角色完成配对。
  • nodes describe 中包含你正在调用的 capability。
  • Exec approvals 显示为符合预期的 mode/allowlist。

前台运行要求

在 iOS/Android 节点上，canvas.*、camera.* 和 screen.* 只能在前台使用。

快速检查与修复：

  1. openclaw nodes describe --node <idOrNameOrIp>
  2. openclaw nodes canvas snapshot --node <idOrNameOrIp>
  3. openclaw logs --follow

如果你看到 NODE_BACKGROUND_UNAVAILABLE，请将节点 app 切到前台后再重试。

权限矩阵

Capability iOS Android macOS node app 常见失败代码
camera.snap, camera.clip Camera（clip 音频还需要 mic） Camera（clip 音频还需要 mic） Camera（clip 音频还需要 mic） *_PERMISSION_REQUIRED
screen.record Screen Recording（mic 可选） screen capture prompt（mic 可选） Screen Recording *_PERMISSION_REQUIRED
location.get While Using 或 Always（取决于 mode） 前台/后台 location，取决于 mode Location permission LOCATION_PERMISSION_REQUIRED
system.run n/a（node host path） n/a（node host path） 需要 Exec approvals SYSTEM_RUN_DENIED

Pairing 与 approvals 的区别

这是两个不同的关卡：

  1. Device pairing：这个节点能否连接到 gateway？
  2. Exec approvals：这个节点能否执行某条特定 shell command？

快速检查：

  1. openclaw devices list
  2. openclaw nodes status
  3. openclaw approvals get --node <idOrNameOrIp>
  4. openclaw approvals allowlist add --node <idOrNameOrIp> "/usr/bin/uname"

如果缺少 pairing，请先批准该 node device。 如果 pairing 正常但 system.run 失败，请修复 exec approvals/allowlist。

常见 node 错误码

  • NODE_BACKGROUND_UNAVAILABLE → app 在后台；请切到前台。
  • CAMERA_DISABLED → 节点设置中 camera 开关被禁用。
  • *_PERMISSION_REQUIRED → 缺少或被拒绝了系统权限。
  • LOCATION_DISABLED → location mode 已关闭。
  • LOCATION_PERMISSION_REQUIRED → 请求的 location mode 未获授权。
  • LOCATION_BACKGROUND_UNAVAILABLE → app 在后台，但当前只有 While Using 权限。
  • SYSTEM_RUN_DENIED: approval required → exec 请求需要显式批准。
  • SYSTEM_RUN_DENIED: allowlist miss → 命令被 allowlist mode 拦截。 在 Windows node hosts 上，像 cmd.exe /c ... 这类 shell-wrapper 形式，在 allowlist mode 下如果没有通过 ask flow 批准，也会被视为 allowlist miss。

快速恢复循环

  1. openclaw nodes status
  2. openclaw nodes describe --node <idOrNameOrIp>
  3. openclaw approvals get --node <idOrNameOrIp>
  4. openclaw logs --follow

如果仍然卡住：

  • 重新批准 device pairing。
  • 重新打开 node app（切到前台）。
  • 重新授予系统权限。
  • 重新创建或调整 exec approval policy。