命令階梯
- 節點已連線，並已配對為
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 |
配對與核准
有三個獨立關卡控制節點命令是否成功：- 裝置配對：此節點能否連線到閘道？
- 閘道節點命令政策：RPC 命令 ID 是否被
gateway.nodes.allowCommands/denyCommands和平台預設值允許？ - 執行核准：此節點能否在本機執行特定 shell 命令？
system.run，逐節點政策位於該節點的執行核准檔案（openclaw approvals get --node ...），而不是閘道配對記錄。
快速檢查：
- 缺少配對：先核准節點裝置。
nodes describe缺少命令：檢查閘道節點命令政策，以及節點連線時是否實際宣告該命令。- 配對正常但
system.run失敗：修正該節點上的執行核准/允許清單。
host=node 執行，閘道也會將執行綁定到已準備的標準 systemRunPlan。如果後續呼叫端在已核准的執行被轉送前，變更命令、cwd 或工作階段中繼資料，閘道會因核准不符而拒絕該執行，而不是信任被編輯的負載。
常見節點錯誤代碼
| 代碼 | 意義 |
|---|---|
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 包裝形式在允許清單模式中會被視為允許清單未命中，除非透過詢問流程核准。 |
快速復原迴圈
- 重新核准裝置配對。
- 重新開啟節點應用程式（前景）。
- 重新授予作業系統權限。
- 重新建立/調整執行核准政策。