Nodes and media
Node のトラブルシューティング
ステータスに Node が表示されているのに Node ツールが失敗する場合は、このページを参照してください。
コマンドの実行手順
openclaw statusopenclaw gateway statusopenclaw logs --followopenclaw doctoropenclaw channels status --probe続いて、Node 固有のチェックを実行します。
openclaw nodes statusopenclaw nodes describe --node <idOrNameOrIp>openclaw approvals get --node <idOrNameOrIp>正常性を示す状態:
- Node が接続され、ロール
nodeとしてペアリングされている。 nodes describeに、呼び出そうとしているケイパビリティが含まれている。- 実行承認に、想定したモードと許可リストが表示されている。
フォアグラウンド要件
iOS/Android Node では、canvas.*、camera.*、screen.* はフォアグラウンドでのみ利用できます。
簡易チェックと修正:
openclaw nodes describe --node <idOrNameOrIp>openclaw nodes canvas snapshot --node <idOrNameOrIp>openclaw logs --followNODE_BACKGROUND_UNAVAILABLE が表示された場合は、Node アプリをフォアグラウンドに移して再試行してください。
権限マトリクス
| ケイパビリティ | iOS | Android | macOS Node アプリ | 一般的なエラーコード |
|---|---|---|---|---|
camera.snap, camera.clip |
カメラ（クリップ音声にはマイクも必要） | カメラ（クリップ音声にはマイクも必要） | カメラ（クリップ音声にはマイクも必要） | *_PERMISSION_REQUIRED |
screen.record |
画面収録（マイクは任意） | 画面キャプチャの確認（マイクは任意） | 画面収録 | *_PERMISSION_REQUIRED |
computer.act |
該当なし | 該当なし | アクセシビリティ + 画面収録 | COMPUTER_DISABLED, ACCESSIBILITY_REQUIRED |
location.get |
使用中のみ、または常に（モードによる） | モードに応じたフォアグラウンド/バックグラウンド位置情報 | 位置情報の権限 | LOCATION_PERMISSION_REQUIRED |
system.run |
該当なし（Node ホストのパス） | 該当なし（Node ホストのパス） | 実行承認が必要 | SYSTEM_RUN_DENIED |
ペアリングと承認の違い
Node コマンドが成功するかどうかは、次の 3 つの独立したゲートによって制御されます。
- デバイスのペアリング: この Node は Gateway に接続できるか？
- Gateway の Node コマンドポリシー: RPC コマンド ID は
gateway.nodes.allowCommands/denyCommandsとプラットフォームのデフォルトによって許可されているか？ - 実行承認: この Node は特定のシェルコマンドをローカルで実行できるか？
Node のペアリングは ID と信頼性を確認するゲートであり、コマンドごとの承認機構ではありません。system.run の Node ごとのポリシーは、Gateway のペアリングレコードではなく、その Node の実行承認ファイル（openclaw approvals get --node ...）にあります。
簡易チェック:
openclaw devices listopenclaw nodes statusopenclaw approvals get --node <idOrNameOrIp>openclaw approvals allowlist add --node <idOrNameOrIp> "/usr/bin/uname"- ペアリングがない場合: まず Node デバイスを承認します。
nodes describeにコマンドがない場合: Gateway の Node コマンドポリシーと、接続時に Node が実際にそのコマンドを宣言したかどうかを確認します。- ペアリングに問題はないが
system.runが失敗する場合: その Node の実行承認または許可リストを修正します。
承認を必要とする host=node の実行では、Gateway は準備済みの正規 systemRunPlan にも実行を関連付けます。承認済みの実行が転送される前に、後続の呼び出し元がコマンド、cwd、またはセッションメタデータを変更した場合、Gateway は編集されたペイロードを信頼せず、承認内容の不一致として実行を拒否します。
一般的な Node エラーコード
| コード | 意味 |
|---|---|
NODE_BACKGROUND_UNAVAILABLE |
アプリがバックグラウンドにあります。フォアグラウンドに移してください。 |
CAMERA_DISABLED |
Node 設定でカメラの切り替えが無効になっています。 |
*_PERMISSION_REQUIRED |
OS の権限がないか、拒否されています。 |
LOCATION_DISABLED |
位置情報モードがオフになっています。 |
LOCATION_PERMISSION_REQUIRED |
要求された位置情報モードが許可されていません。 |
LOCATION_BACKGROUND_UNAVAILABLE |
アプリがバックグラウンドにありますが、「使用中のみ」の権限しかありません。 |
COMPUTER_DISABLED |
macOS アプリで Allow Computer Control を有効にしてから、ペアリングの更新を承認してください。 |
ACCESSIBILITY_REQUIRED |
macOS System Settings で、現在の OpenClaw アプリバンドルにアクセシビリティ権限を付与してください。 |
SYSTEM_RUN_DENIED: approval required |
実行要求には明示的な承認が必要です。 |
SYSTEM_RUN_DENIED: allowlist miss |
許可リストモードによってコマンドがブロックされました。Windows Node ホストでは、cmd.exe /c ... のようなシェルラッパー形式は、確認フローで承認されていない限り、許可リストモードで許可リスト不一致として扱われます。 |
簡易復旧ループ
openclaw nodes statusopenclaw nodes describe --node <idOrNameOrIp>openclaw approvals get --node <idOrNameOrIp>openclaw logs --followそれでも解決しない場合:
- デバイスのペアリングを再承認します。
- Node アプリを再度開きます（フォアグラウンド）。
- OS の権限を再付与します。
- 実行承認ポリシーを再作成または調整します。
コンピューター制御については、視覚機能に対応したエージェントが computer ツールを公開していること、画面収録権限を付与した状態で screen.snapshot が成功すること、/phone status に意図した一時的または永続的な Gateway 承認が表示されることも確認してください。gateway.nodes.denyCommands のエントリは常に allowCommands より優先されます。
