# 节点故障排查 > 排查节点配对、前台运行要求、权限和工具故障 - 网址：https://funcoding.ai/agents/openclaw/nodes/troubleshooting/ - 来源：OpenClaw 官方文档原文（中文），MIT 许可，同步于 2026-10-11 - 官方原文：https://docs.openclaw.ai/zh-CN/nodes/troubleshooting --- 当节点在状态中可见，但节点工具运行失败时，请使用此页面。 ## 命令排查顺序 ```bash openclaw status openclaw gateway status openclaw logs --follow openclaw doctor openclaw channels status --probe ``` 然后运行节点专用检查： ```bash openclaw nodes status openclaw nodes describe --node openclaw approvals get --node ``` 健康状态信号： - 节点已连接并完成角色 `node` 的配对。 - `nodes describe` 包含你正在调用的能力。 - Exec 审批显示预期的模式/允许列表。 ## 前台运行要求 在 iOS/Android 节点上，`canvas.*`、`camera.*` 和 `screen.*` 仅能在前台运行。 快速检查并修复： ```bash openclaw nodes describe --node openclaw nodes canvas snapshot --node 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 list openclaw nodes status openclaw approvals get --node openclaw approvals allowlist add --node "/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 status openclaw nodes describe --node openclaw approvals get --node openclaw logs --follow ``` 如果问题仍未解决： - 重新批准设备配对。 - 重新打开节点应用（保持前台运行）。 - 重新授予操作系统权限。 - 重新创建/调整 Exec 审批策略。 对于计算机控制，还要确认支持视觉能力的智能体公开了 `computer` 工具，`screen.snapshot` 在获得屏幕录制权限后成功，并且 `/phone status` 显示了你预期的临时或永久 Gateway 网关授权。`gateway.nodes.commands.deny` 条目始终会覆盖 `gateway.nodes.commands.allow`。 ## 相关内容 - [节点概览](https://funcoding.ai/agents/openclaw/nodes/) - [相机节点](https://funcoding.ai/agents/openclaw/nodes/camera/) - [位置命令](https://funcoding.ai/agents/openclaw/nodes/location-command/) - [计算机使用](https://funcoding.ai/agents/openclaw/nodes/computer-use/) - [Exec 审批](https://funcoding.ai/agents/openclaw/tools/exec-approvals/) - [Gateway 网关配对](https://funcoding.ai/agents/openclaw/gateway/pairing/) - [Gateway 网关故障排查](https://funcoding.ai/agents/openclaw/gateway/troubleshooting/) - [渠道故障排查](https://funcoding.ai/agents/openclaw/channels/troubleshooting/)