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に、呼び出している機能が含まれている。- 実行承認に、想定されるモード／許可リストが表示されている。
フォアグラウンド要件
canvas.*、camera.*、screen.* は、iOS／Android の Node ではフォアグラウンドでのみ動作します。
簡易チェックと修正：
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 |
While Using または Always（モードによる） | モードに応じたフォアグラウンド／バックグラウンド位置情報 | 位置情報の権限 | LOCATION_PERMISSION_REQUIRED |
system.run |
該当なし（Node ホストのパス） | 該当なし（Node ホストのパス） | 実行承認が必要 | SYSTEM_RUN_DENIED |
ペアリングと承認の違い
Node コマンドが成功するかどうかは、3 つの独立したゲートによって制御されます。
- デバイスのペアリング：この Node は Gateway に接続できるか？
- Gateway の Node コマンドポリシー：RPC コマンド ID は、
gateway.nodes.commands.allow／gateway.nodes.commands.denyとプラットフォームのデフォルト設定で許可されているか？ - 実行承認：この 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 |
アプリがバックグラウンドになっていますが、While Using 権限しかありません。 |
COMPUTER_DISABLED |
macOS アプリで Allow Computer Control を有効にしてから、ペアリングの更新を承認してください。 |
ACCESSIBILITY_REQUIRED |
macOS の System Settings で、現在の OpenClaw アプリバンドルに Accessibility を許可してください。 |
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.commands.deny エントリは常に gateway.nodes.commands.allow より優先されます。
