跳到正文
FunCoding

搜索

搜索文档、文章、Skill 和 MCP

节点故障排查

排查节点配对、前台运行要求、权限和工具故障

当节点在状态中可见，但节点工具运行失败时，请使用此页面。

命令排查顺序

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 包含你正在调用的能力。
  • Exec 审批显示预期的模式/允许列表。

前台运行要求

在 iOS/Android 节点上，canvas.*、camera.* 和 screen.* 仅能在前台运行。

快速检查并修复：

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

如果看到 NODE_BACKGROUND_UNAVAILABLE，请将节点应用切换到前台，然后重试。

权限矩阵

能力iOSAndroidmacOS 节点应用典型失败代码
camera.snap、camera.clip相机（录制片段音频还需麦克风）相机（录制片段音频还需麦克风）相机（录制片段音频还需麦克风）*_PERMISSION_REQUIRED
screen.record屏幕录制（麦克风可选）屏幕捕获提示（麦克风可选）屏幕录制*_PERMISSION_REQUIRED
computer.act不适用不适用辅助功能 + 屏幕录制COMPUTER_DISABLED、ACCESSIBILITY_REQUIRED
location.get使用 App 时或始终（取决于模式）根据模式使用前台/后台位置权限位置权限LOCATION_PERMISSION_REQUIRED
system.run不适用（节点主机路径）不适用（节点主机路径）需要 Exec 审批SYSTEM_RUN_DENIED

配对与审批

节点命令能否成功由三个独立的关卡控制：

  1. 设备配对：此节点能否连接到 Gateway 网关？
  2. Gateway 网关节点命令策略：gateway.nodes.commands.allow / gateway.nodes.commands.deny 和平台默认设置是否允许此 RPC 命令 ID？
  3. Exec 审批：此节点能否在本地运行特定的 shell 命令？

节点配对是身份/信任关卡，并非针对每条命令的审批界面。对于 system.run，每个节点的策略位于该节点的 Exec 审批文件（openclaw approvals get --node ...）中，而不是 Gateway 网关配对记录中。

快速检查：

openclaw devices list
openclaw nodes status
openclaw approvals get --node <idOrNameOrIp>
openclaw approvals allowlist add --node <idOrNameOrIp> "/usr/bin/uname"
  • 缺少配对：请先批准节点设备。
  • nodes describe 缺少命令：检查 Gateway 网关节点命令策略，并确认节点在连接时是否实际声明了该命令。
  • 配对正常，但 system.run 失败：修复该节点上的 Exec 审批/允许列表。

对于由审批支持的 host=node 运行，Gateway 网关还会将执行绑定到准备好的规范 systemRunPlan。如果后续调用方在转发已审批的运行之前修改了命令、cwd 或会话元数据，Gateway 网关会以审批不匹配为由拒绝运行，而不会信任修改后的载荷。

常见节点错误代码

代码含义
NODE_BACKGROUND_UNAVAILABLE应用在后台运行；请将其切换到前台。
CAMERA_DISABLED节点设置中的相机开关已禁用。
*_PERMISSION_REQUIRED缺少操作系统权限或权限被拒绝。
LOCATION_DISABLED位置模式已关闭。
LOCATION_PERMISSION_REQUIRED请求的位置模式未获授权。
LOCATION_BACKGROUND_UNAVAILABLE应用在后台运行，但只有“使用 App 时”权限。
COMPUTER_DISABLED在 macOS 应用中启用 Allow Computer Control，然后批准配对更新。
ACCESSIBILITY_REQUIRED在 macOS 系统设置中，向当前 OpenClaw 应用程序包授予辅助功能权限。
SYSTEM_RUN_DENIED: approval requiredExec 请求需要明确审批。
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

如果问题仍未解决：

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

对于计算机控制，还要确认支持视觉能力的智能体公开了 computer 工具，screen.snapshot 在获得屏幕录制权限后成功，并且 /phone status 显示了你预期的临时或永久 Gateway 网关授权。gateway.nodes.commands.deny 条目始终会覆盖 gateway.nodes.commands.allow。

相关内容