当节点在状态中可见但节点工具失败时，使用此页面。Documentation Index
Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
命令阶梯
- 节点已连接，并已按
node角色配对。 nodes describe包含你正在调用的能力。- 执行批准显示预期的模式/允许列表。
前台要求
canvas.*、camera.* 和 screen.* 在 iOS/Android 节点上只能在前台使用。
快速检查和修复：
NODE_BACKGROUND_UNAVAILABLE，请将节点应用切到前台后重试。
权限矩阵
| 能力 | iOS | Android | macOS 节点应用 | 典型失败代码 |
|---|---|---|---|---|
camera.snap, camera.clip | 摄像头（+ 用于片段音频的麦克风） | 摄像头（+ 用于片段音频的麦克风） | 摄像头（+ 用于片段音频的麦克风） | *_PERMISSION_REQUIRED |
screen.record | 屏幕录制（+ 可选麦克风） | 屏幕捕获提示（+ 可选麦克风） | 屏幕录制 | *_PERMISSION_REQUIRED |
location.get | 使用期间或始终（取决于模式） | 基于模式的前台/后台位置 | 位置权限 | LOCATION_PERMISSION_REQUIRED |
system.run | 不适用（节点主机路径） | 不适用（节点主机路径） | 需要执行批准 | SYSTEM_RUN_DENIED |
配对与批准
这些是不同的门禁：- 设备配对：此节点能否连接到 Gateway 网关？
- Gateway 网关节点命令策略：RPC 命令 ID 是否被
gateway.nodes.allowCommands/denyCommands和平台默认值允许？ - 执行批准：此节点能否在本地运行特定 shell 命令？
nodes describe 缺少某个命令，请检查 Gateway 网关节点命令策略，以及该节点连接时是否实际声明了该命令。
如果配对正常但 system.run 失败，请修复该节点上的执行批准/允许列表。
节点配对是身份/信任门禁，不是按命令批准的表面。对于 system.run，每个节点的策略位于该节点的执行批准文件中（openclaw approvals get --node ...），不在 Gateway 网关配对记录中。
对于由批准支持的 host=node 运行，Gateway 网关还会将执行绑定到
已准备好的规范 systemRunPlan。如果后续调用方在已批准运行转发之前更改命令/cwd 或
会话元数据，Gateway 网关会将该运行作为批准不匹配而拒绝，而不是信任被编辑的载荷。
常见节点错误代码
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 包装形式在 允许列表模式下会被视为允许列表未命中，除非通过询问流程批准。
快速恢复循环
- 重新批准设备配对。
- 重新打开节点应用（前台）。
- 重新授予操作系统权限。
- 重新创建/调整执行批准策略。