OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Nodes and media

節點疑難排解

當節點顯示於狀態中，但節點工具執行失敗時，請參閱此頁面。

命令階梯

bash
openclaw statusopenclaw gateway statusopenclaw logs --followopenclaw doctoropenclaw channels status --probe

接著執行節點專屬檢查：

bash
openclaw nodes statusopenclaw nodes describe --node <idOrNameOrIp>openclaw approvals get --node <idOrNameOrIp>

正常訊號：

  • 節點已連線，且已針對角色 node 完成配對。
  • nodes describe 包含你正在呼叫的功能。
  • 執行核准顯示預期的模式／允許清單。

前景要求

在 iOS／Android 節點上，canvas.*、camera.* 和 screen.* 只能在前景執行。

快速檢查與修正：

bash
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
computer.act 不適用 不適用 輔助使用 + 螢幕錄製 COMPUTER_DISABLED、ACCESSIBILITY_REQUIRED
location.get 使用 App 期間或永遠（取決於模式） 依模式使用前景／背景位置 位置權限 LOCATION_PERMISSION_REQUIRED
system.run 不適用（節點主機路徑） 不適用（節點主機路徑） 需要執行核准 SYSTEM_RUN_DENIED

配對與核准的差異

節點命令是否成功由三個獨立關卡控制：

  1. 裝置配對：此節點能否連線至閘道？
  2. 閘道節點命令原則：RPC 命令 ID 是否獲 gateway.nodes.commands.allow／gateway.nodes.commands.deny 和平台預設值允許？
  3. 執行核准：此節點能否在本機執行特定的 Shell 命令？

節點配對是身分／信任關卡，而非個別命令的核准介面。對於 system.run，個別節點原則位於該節點的執行核准檔案（openclaw approvals get --node ...）中，而非閘道配對記錄中。

快速檢查：

bash
openclaw devices listopenclaw nodes statusopenclaw approvals get --node <idOrNameOrIp>openclaw approvals allowlist add --node <idOrNameOrIp> "/usr/bin/uname"
  • 缺少配對：請先核准節點裝置。
  • nodes describe 缺少命令：請檢查閘道節點命令原則，以及節點連線時是否確實宣告了該命令。
  • 配對正常但 system.run 失敗：請修正該節點上的執行核准／允許清單。

對於以核准為依據的 host=node 執行作業，閘道也會將執行繫結至已準備好的標準 systemRunPlan。如果後續呼叫者在轉送已核准的執行作業前修改命令、目前工作目錄或工作階段中繼資料，閘道會將該執行作業視為核准不符並予以拒絕，而不會信任經過編輯的承載資料。

常見節點錯誤代碼

代碼 意義
NODE_BACKGROUND_UNAVAILABLE 應用程式在背景中；請將其切換至前景。
CAMERA_DISABLED 節點設定中的相機切換開關已停用。
*_PERMISSION_REQUIRED 缺少作業系統權限或權限遭拒。
LOCATION_DISABLED 位置模式已關閉。
LOCATION_PERMISSION_REQUIRED 要求的位置模式尚未獲得授權。
LOCATION_BACKGROUND_UNAVAILABLE 應用程式在背景中，但只有「使用 App 期間」權限。
COMPUTER_DISABLED 在 macOS 應用程式中啟用 Allow Computer Control，然後核准配對更新。
ACCESSIBILITY_REQUIRED 在 macOS「系統設定」中，將輔助使用權限授予目前的 OpenClaw App 套件。
SYSTEM_RUN_DENIED: approval required 執行要求需要明確核准。
SYSTEM_RUN_DENIED: allowlist miss 命令遭允許清單模式封鎖。在 Windows 節點主機上，除非透過詢問流程核准，否則 cmd.exe /c ... 之類的 Shell 包裝函式形式，在允許清單模式中會被視為未命中允許清單。

快速復原迴圈

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

如果仍然無法解決：

  • 重新核准裝置配對。
  • 重新開啟節點應用程式（保持在前景）。
  • 重新授予作業系統權限。
  • 重新建立／調整執行核准原則。

對於電腦控制，也請確認具備視覺能力的代理程式有提供 computer 工具、screen.snapshot 能在具備螢幕錄製權限的情況下成功執行，以及 /phone status 顯示你預期的暫時或持續性閘道授權。gateway.nodes.commands.deny 項目一律優先於 gateway.nodes.commands.allow。

相關內容

Was this useful?
On this page

On this page