nodes/troubleshooting.md¶
當節點在狀態中可見但節點工具失敗時，請使用此頁。
指令階梯¶
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 核准顯示預期的模式／允許清單。
前景需求¶
canvas.*、camera.* 與 screen.* 在 iOS／Android 節點上僅能於前景使用。
快速檢查與修正：
openclaw nodes describe --node <idOrNameOrIp>
openclaw nodes canvas snapshot --node <idOrNameOrIp>
openclaw logs --follow
如果你看到 NODE_BACKGROUND_UNAVAILABLE，請將節點 App 切換到前景後再試一次。
權限矩陣¶
| 能力 | iOS | Android | macOS 節點 App | 常見失敗代碼 |
|---|---|---|---|---|
camera.snap、camera.clip |
相機（剪輯音訊需麥克風） | 相機（剪輯音訊需麥克風） | 相機（剪輯音訊需麥克風） | *_PERMISSION_REQUIRED |
screen.record |
螢幕錄製（麥克風選用） | 螢幕擷取提示（+ 麥克風為選用） | 螢幕錄製 | *_PERMISSION_REQUIRED |
location.get |
使用期間或永遠（依模式而定） | 依模式為前景／背景位置 | 位置權限 | LOCATION_PERMISSION_REQUIRED |
system.run |
n/a (節點主機路徑) | n/a (節點主機路徑) | 需要 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"
If pairing is missing, approve the node device first.
如果缺少配對，請先核准節點裝置。
若配對正常但 system.run 失敗，請修正 exec 核准／允許清單。
常見節點錯誤代碼¶
NODE_BACKGROUND_UNAVAILABLE→ App 在背景；請切換到前景。CAMERA_DISABLED→ 節點設定中停用了相機切換。*_PERMISSION_REQUIRED→ 缺少／被拒絕的 OS 權限。LOCATION_DISABLED→ 位置模式已關閉。LOCATION_PERMISSION_REQUIRED→ 未授與請求的位置模式。LOCATION_BACKGROUND_UNAVAILABLE→ App 在背景，但僅有「使用期間」權限。SYSTEM_RUN_DENIED: approval required→ Exec 請求需要明確核准。SYSTEM_RUN_DENIED: allowlist miss→ 指令被允許清單模式阻擋。
快速復原流程¶
openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>
openclaw approvals get --node <idOrNameOrIp>
openclaw logs --follow
若仍卡住：
- 重新核准裝置配對。
- 重新開啟節點應用程式（前景）。
- 重新授與 OS 權限。
- 重新建立／調整 exec 核准政策。
相關內容：