OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Nodes and media

节点故障排查

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

命令排查顺序

bash
openclaw statusopenclaw gateway statusopenclaw logs --followopenclaw doctoropenclaw channels status --probe

然后运行节点专用检查：

bash
openclaw nodes statusopenclaw 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 相机（录制片段音频还需麦克风） 相机（录制片段音频还需麦克风） 相机（录制片段音频还需麦克风） *_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 网关配对记录中。

快速检查：

bash
openclaw devices listopenclaw nodes statusopenclaw 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 required Exec 请求需要明确审批。
SYSTEM_RUN_DENIED: allowlist miss 命令被允许列表模式阻止。在 Windows 节点主机上，除非通过询问流程获得批准，否则在允许列表模式下，类似 cmd.exe /c ... 的 shell 包装器形式会被视为未命中允许列表。

快速恢复流程

bash
openclaw nodes statusopenclaw 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。

相关内容

Was this useful?
On this page

On this page