OpenClaw 節點故障排除：快速修復常見連線與權限錯誤

當你在後台看到 Node 顯示為連線狀態，但實際執行工具時卻一直報錯，這種「看得到卻用不到」的情況真的很讓人抓狂。這通常是因為權限、前台限制或指令授權出了問題。

這份指南會幫你快速排查問題，從基礎的狀態檢查到權限細節，讓你一步步找出 Node 無法正常運作的原因。

Node troubleshooting

當 Node 在狀態列表中可見，但 Node 工具執行失敗時，請參考此頁面進行排查。

指令階梯 (Command ladder)

先從全域狀態開始檢查：

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

接著執行針對特定 Node 的檢查：

openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>
openclaw approvals get --node <idOrNameOrIp>

健康的訊號包括：

• Node 已連線並針對 node 角色完成配對。
• nodes describe 的結果包含你正在呼叫的 capability。
• Exec approvals 顯示符合預期的模式或白名單。

前台運行要求 (Foreground requirements)

在 iOS 或 Android 的 Node 上，canvas.*、camera.* 以及 screen.* 僅限於前台運行。

快速檢查與修復：

openclaw nodes describe --node <idOrNameOrIp>
openclaw nodes canvas snapshot --node <idOrNameOrIp>
openclaw logs --follow

如果你看到 NODE_BACKGROUND_UNAVAILABLE，請將 Node App 切換到前台並重試。

權限矩陣 (Permissions matrix)

Capability	iOS	Android	macOS node app	典型失敗代碼
camera.snap, camera.clip	Camera (+ 錄製影片需 mic)	Camera (+ 錄製影片需 mic)	Camera (+ 錄製影片需 mic)	*_PERMISSION_REQUIRED
screen.record	Screen Recording (+ 可選 mic)	Screen capture 提示 (+ 可選 mic)	Screen Recording	*_PERMISSION_REQUIRED
location.get	While Using 或 Always (取決於模式)	Foreground/Background location (取決於模式)	Location 權限	LOCATION_PERMISSION_REQUIRED
system.run	n/a (node host 路徑)	n/a (node host 路徑)	需要 Exec approvals	SYSTEM_RUN_DENIED

配對與授權的區別 (Pairing versus approvals)

這是不同的關卡：

1. 設備配對 (Device pairing)：這個 Node 可以連線到 Gateway 嗎？
2. Gateway node 指令策略：該 RPC 指令 ID 是否被 gateway.nodes.allowCommands / denyCommands 或平台預設值允許？
3. Exec approvals：這個 Node 可以在本地執行特定的 shell 指令嗎？

快速檢查：

openclaw devices list
openclaw nodes status
openclaw approvals get --node <idOrNameOrIp>
openclaw approvals allowlist add --node <idOrNameOrIp> "/usr/bin/uname"

如果缺少配對，請先核准該 Node 設備。 如果 nodes describe 缺少某個指令，請檢查 Gateway 的 Node 指令策略，以及該 Node 在連線時是否真的宣告了該指令。 如果配對正常但 system.run 失敗，請修正該 Node 上的 exec approvals 或白名單。

Node 配對是身份與信任的門檻，而不是針對單一指令的審核機制。對於 system.run，針對每個 Node 的策略存在於該 Node 的 exec approvals 檔案中（openclaw approvals get --node ...），而不是在 Gateway 的配對記錄裡。

常見 Node 錯誤代碼 (Common node error codes)

• NODE_BACKGROUND_UNAVAILABLE → App 處於後台；請將其切換至前台。
• CAMERA_DISABLED → Node 設定中的相機開關已關閉。
• *_PERMISSION_REQUIRED → 缺少或拒絕了 OS 權限。
• LOCATION_DISABLED → 定位模式已關閉。
• LOCATION_PERMISSION_REQUIRED → 未授予要求的定位模式權限。
• LOCATION_BACKGROUND_UNAVAILABLE → App 處於後台，但僅擁有「使用期間」權限。
• SYSTEM_RUN_DENIED: approval required → Exec 請求需要明確授權。
• SYSTEM_RUN_DENIED: allowlist miss → 指令被白名單模式阻擋。 在 Windows Node 主機上，除非透過詢問流程核准，否則 cmd.exe /c ... 等 shell 包裝形式在白名單模式下會被視為未命中。

快速恢復流程 (Fast recovery loop)

openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>
openclaw approvals get --node <idOrNameOrIp>
openclaw logs --follow

如果仍然卡住：

• 重新核准設備配對。
• 重新開啟 Node App（確保在前台）。
• 重新授予 OS 權限。
• 重新建立或調整 exec approval 策略。

下一步：

• /nodes/index
• /nodes/camera
• /nodes/location-command
• /tools/exec-approvals
• /gateway/pairing

如果你在排查過程中遇到任何問題，可以隨時諮詢 AI Setup Assistant。