Nodes and media
Node のトラブルシューティング
Node が status では見えているのに Node ツールが失敗する場合は、このページを使ってください。
コマンドラダー
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 が接続されており、role
nodeとしてペアリング済みである。 nodes describeに、呼び出そうとしている capability が含まれている。- Exec approvals に、期待する mode/allowlist が表示されている。
フォアグラウンド要件
canvas.*、camera.*、screen.* は iOS/Android Node ではフォアグラウンド専用です。
簡易チェックと修正:
openclaw nodes describe --node <idOrNameOrIp>
openclaw nodes canvas snapshot --node <idOrNameOrIp>
openclaw logs --follow
NODE_BACKGROUND_UNAVAILABLE が出た場合は、Node アプリをフォアグラウンドにして再試行してください。
権限マトリクス
| Capability | iOS | Android | macOS Node アプリ | 典型的な失敗コード |
|---|---|---|---|---|
camera.snap, camera.clip |
Camera（clip 音声用に mic も） | Camera（clip 音声用に mic も） | Camera（clip 音声用に mic も） | *_PERMISSION_REQUIRED |
screen.record |
Screen Recording（mic は任意） | Screen capture プロンプト（mic は任意） | Screen Recording | *_PERMISSION_REQUIRED |
location.get |
While Using または Always（mode に依存） | mode に応じた Foreground/Background location | Location permission | LOCATION_PERMISSION_REQUIRED |
system.run |
n/a（Node ホスト経路） | n/a（Node ホスト経路） | Exec approvals が必要 | SYSTEM_RUN_DENIED |
ペアリング vs 承認
これらは別のゲートです。
- デバイスペアリング: この Node は gateway に接続できるか？
- Gateway Node コマンドポリシー: RPC コマンド ID は
gateway.nodes.allowCommands/denyCommandsとプラットフォームデフォルトで許可されているか？ - Exec approvals: この Node は特定のシェルコマンドをローカル実行できるか？
簡易チェック:
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/allowlist を修正してください。
Node ペアリングは identity/trust ゲートであり、コマンドごとの承認サーフェスではありません。system.run の Node ごとのポリシーは、その Node の exec approvals file（openclaw approvals get --node ...）にあり、gateway のペアリング記録にはありません。
承認に支えられた host=node 実行では、gateway は実行を
準備済みの正規 systemRunPlan にも結び付けます。承認済み実行が転送される前に、
後続の呼び出し元が command/cwd やセッションメタデータを変更した場合、gateway は
編集済みペイロードを信頼する代わりに approval mismatch として拒否します。
よくある Node エラーコード
NODE_BACKGROUND_UNAVAILABLE→ アプリがバックグラウンドです。フォアグラウンドにしてください。CAMERA_DISABLED→ Node 設定で camera トグルが無効です。*_PERMISSION_REQUIRED→ OS 権限がない/拒否されています。LOCATION_DISABLED→ location mode がオフです。LOCATION_PERMISSION_REQUIRED→ 要求された location mode が付与されていません。LOCATION_BACKGROUND_UNAVAILABLE→ アプリがバックグラウンドですが、While Using 権限しかありません。SYSTEM_RUN_DENIED: approval required→ exec リクエストには明示的承認が必要です。SYSTEM_RUN_DENIED: allowlist miss→ コマンドが allowlist mode によってブロックされました。 Windows Node ホストでは、cmd.exe /c ...のような shell-wrapper 形式は、 allowlist mode では ask フローで承認されない限り allowlist miss として扱われます。
高速復旧ループ
openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>
openclaw approvals get --node <idOrNameOrIp>
openclaw logs --follow
それでも詰まる場合:
- デバイスペアリングを再承認する。
- Node アプリを再オープンする（フォアグラウンド）。
- OS 権限を再付与する。
- Exec approval ポリシーを再作成/調整する。
関連: