節點疑難排解
當節點在狀態中可見但工具執行失敗時，請參考本頁。
檢查步驟
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，將節點應用程式切到前景後重試。
權限矩陣
| 功能 | iOS | Android | macOS 節點應用程式 | 常見失敗碼 |
|---|---|---|---|---|
camera.snap、camera.clip | 相機（+ 錄影含音訊時需麥克風） | 相機（+ 錄影含音訊時需麥克風） | 相機（+ 錄影含音訊時需麥克風） | *_PERMISSION_REQUIRED |
screen.record | 螢幕錄製（+ 麥克風可選） | 螢幕擷取提示（+ 麥克風可選） | 螢幕錄製 | *_PERMISSION_REQUIRED |
location.get | 使用中或始終（依模式而定） | 前景/背景定位（依模式而定） | 定位權限 | LOCATION_PERMISSION_REQUIRED |
system.run | 不適用（節點主機路徑） | 不適用（節點主機路徑） | 需要 Exec 核准 | SYSTEM_RUN_DENIED |
配對與核准的差異
這是兩個不同的閘門：
- 裝置配對：此節點能否連接到 gateway？
- Exec 核准：此節點能否執行特定的 shell 指令？
快速檢查：
openclaw devices list
openclaw nodes status
openclaw approvals get --node <idOrNameOrIp>
openclaw approvals allowlist add --node <idOrNameOrIp> "/usr/bin/uname"如果缺少配對，先核准節點裝置。
如果配對正常但 system.run 失敗，修正 exec 核准/允許清單。
常見節點錯誤碼
NODE_BACKGROUND_UNAVAILABLE→ 應用程式在背景；切到前景。CAMERA_DISABLED→ 節點設定中的相機開關已停用。*_PERMISSION_REQUIRED→ 作業系統權限缺少/被拒絕。LOCATION_DISABLED→ 定位模式為關閉。LOCATION_PERMISSION_REQUIRED→ 請求的定位模式未被授權。LOCATION_BACKGROUND_UNAVAILABLE→ 應用程式在背景，但只有「使用中」權限。SYSTEM_RUN_DENIED: approval required→ exec 請求需要明確核准。SYSTEM_RUN_DENIED: allowlist miss→ 指令被允許清單模式阻擋。 在 Windows 節點主機上，cmd.exe /c ...等 shell 包裝器形式在允許清單模式下被視為未命中，除非透過 ask 流程核准。
快速恢復流程
openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>
openclaw approvals get --node <idOrNameOrIp>
openclaw logs --follow若仍無法解決：
- 重新核准裝置配對。
- 重新開啟節點應用程式（前景）。
- 重新授予作業系統權限。
- 重新建立/調整 exec 核准策略。
相關文件：