コマンドの段階的確認
- ノードが接続され、ロール
nodeとしてペアリングされている。 nodes describeに呼び出そうとしている機能が含まれている。- 実行承認に、想定されるモード/許可リストが表示されている。
フォアグラウンド要件
canvas.*、camera.*、screen.* は、iOS/Android ノードではフォアグラウンド専用です。
簡単な確認と修正:
NODE_BACKGROUND_UNAVAILABLE が表示された場合は、ノードアプリをフォアグラウンドにして再試行してください。
権限マトリクス
| 機能 | iOS | Android | macOS ノードアプリ | 一般的な失敗コード |
|---|---|---|---|---|
camera.snap, camera.clip | カメラ（クリップ音声にはマイクも必要） | カメラ（クリップ音声にはマイクも必要） | カメラ（クリップ音声にはマイクも必要） | *_PERMISSION_REQUIRED |
screen.record | 画面収録（マイクは任意） | 画面キャプチャプロンプト（マイクは任意） | 画面収録 | *_PERMISSION_REQUIRED |
location.get | 使用中のみ、または常に許可（モードによる） | モードに基づくフォアグラウンド/バックグラウンド位置情報 | 位置情報権限 | LOCATION_PERMISSION_REQUIRED |
system.run | 該当なし（ノードホストパス） | 該当なし（ノードホストパス） | 実行承認が必要 | SYSTEM_RUN_DENIED |
ペアリングと承認
ノードコマンドが成功するかどうかは、3 つの別々のゲートで制御されます。- デバイスペアリング: このノードは Gateway に接続できるか？
- Gateway ノードコマンドポリシー: RPC コマンド ID は
gateway.nodes.allowCommands/denyCommandsとプラットフォーム既定値で許可されているか？ - 実行承認: このノードは特定のシェルコマンドをローカルで実行できるか？
system.run では、ノードごとのポリシーは Gateway のペアリングレコードではなく、そのノードの実行承認ファイル（openclaw approvals get --node ...）にあります。
簡単な確認:
- ペアリングがない: まずノードデバイスを承認します。
nodes describeにコマンドがない: Gateway ノードコマンドポリシーと、接続時にノードが実際にそのコマンドを宣言したかを確認します。- ペアリングは正常だが
system.runが失敗する: そのノードの実行承認/許可リストを修正します。
host=node 実行では、Gateway は実行を準備済みの正規 systemRunPlan にもバインドします。承認済みの実行が転送される前に、後続の呼び出し元がコマンド、cwd、またはセッションメタデータを変更した場合、Gateway は編集済みペイロードを信頼する代わりに、承認の不一致としてその実行を拒否します。
一般的なノードエラーコード
| コード | 意味 |
|---|---|
NODE_BACKGROUND_UNAVAILABLE | アプリがバックグラウンドにあります。フォアグラウンドにしてください。 |
CAMERA_DISABLED | ノード設定でカメラトグルが無効になっています。 |
*_PERMISSION_REQUIRED | OS 権限がない、または拒否されています。 |
LOCATION_DISABLED | 位置情報モードがオフです。 |
LOCATION_PERMISSION_REQUIRED | 要求された位置情報モードが許可されていません。 |
LOCATION_BACKGROUND_UNAVAILABLE | アプリがバックグラウンドにありますが、「使用中のみ」の権限しかありません。 |
SYSTEM_RUN_DENIED: approval required | 実行リクエストには明示的な承認が必要です。 |
SYSTEM_RUN_DENIED: allowlist miss | コマンドが許可リストモードでブロックされています。Windows ノードホストでは、cmd.exe /c ... のようなシェルラッパー形式は、ask フローで承認されない限り、許可リストモードで許可リストミスとして扱われます。 |
高速復旧ループ
- デバイスペアリングを再承認します。
- ノードアプリを再度開きます（フォアグラウンド）。
- OS 権限を再付与します。
- 実行承認ポリシーを再作成/調整します。