OpenClawノードのトラブルシューティング：接続とエラーを解決
Nodeがステータス画面には表示されているのに、いざツールを使おうとすると動かない……。そんな状況は開発者なら誰でも経験があるはずです。設定は正しいはずなのに、なぜかコマンドが通らない時のもどかしさは、トラブルシューティングの明確な指針があれば解消できます。
この記事では、Nodeの問題を素早く特定し、正常な状態に戻すための実践的なステップをまとめました。
Nodeのトラブルシューティング
Section titled “Nodeのトラブルシューティング”Nodeがステータス画面で確認できるにもかかわらず、Nodeツールが失敗する場合は、このページの手順を確認してください。
コマンドの優先順位
Section titled “コマンドの優先順位”まずは、以下のコマンドを順番に実行して、全体の状況を把握するのがベストな方法です。
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の結果に、呼び出そうとしている機能（capability）が含まれている。- Exec approvals（実行承認）に、期待通りのモードや allowlist が表示されている。
フォアグラウンドでの実行要件
Section titled “フォアグラウンドでの実行要件”iOSやAndroidのNodeでは、canvas.*、camera.*、screen.* はフォアグラウンドでしか動作しません。
クイックチェックと修正の手順は以下の通りです。
openclaw nodes describe --node <idOrNameOrIp>openclaw nodes canvas snapshot --node <idOrNameOrIp>openclaw logs --followもし NODE_BACKGROUND_UNAVAILABLE というエラーが表示された場合は、Nodeアプリをフォアグラウンド（最前面）に移動させてから再試行してください。
権限マトリックス
Section titled “権限マトリックス”OSごとの権限設定と、それに対応するエラーコードをまとめました。
| Capability | iOS | Android | macOS node app | Typical failure code |
|---|---|---|---|---|
camera.snap, camera.clip | Camera (+ mic for clip audio) | Camera (+ mic for clip audio) | Camera (+ mic for clip audio) | *_PERMISSION_REQUIRED |
screen.record | Screen Recording (+ mic optional) | Screen capture prompt (+ mic optional) | Screen Recording | *_PERMISSION_REQUIRED |
location.get | While Using or Always (depends on mode) | Foreground/Background location based on mode | Location permission | LOCATION_PERMISSION_REQUIRED |
system.run | n/a (node host path) | n/a (node host path) | Exec approvals required | SYSTEM_RUN_DENIED |
ペアリングと承認（Approvals）の違い
Section titled “ペアリングと承認（Approvals）の違い”これらは異なるゲートウェイ（制限）であることを理解しておくのが重要です。
- デバイスのペアリング: このNodeは Gateway に接続できるか？
- Gateway Nodeコマンドポリシー: そのRPCコマンドIDは、
gateway.nodes.allowCommands/denyCommandsやプラットフォームのデフォルト設定で許可されているか？ - Exec approvals（実行承認）: この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の Exec approvals または allowlist を修正してください。
Nodeのペアリングは「IDと信頼」を確認するためのものであり、コマンドごとの承認を行う場所ではありません。system.run に関しては、各Nodeの Exec approvals ファイル（openclaw approvals get --node ...）でポリシーを管理します。Gateway のペアリングレコードではない点に注意してください。
よくあるNodeエラーコード
Section titled “よくあるNodeエラーコード”NODE_BACKGROUND_UNAVAILABLE→ アプリがバックグラウンドにあります。フォアグラウンドに移動させてください。CAMERA_DISABLED→ Nodeの設定でカメラがオフになっています。*_PERMISSION_REQUIRED→ OSの権限が不足しているか、拒否されています。LOCATION_DISABLED→ 位置情報モードがオフです。LOCATION_PERMISSION_REQUIRED→ 要求された位置情報モードが許可されていません。LOCATION_BACKGROUND_UNAVAILABLE→ アプリがバックグラウンドにあり、「このAppの使用中のみ」の権限しか付与されていません。SYSTEM_RUN_DENIED: approval required→ 実行リクエストに対して明示的な承認が必要です。SYSTEM_RUN_DENIED: allowlist miss→ allowlist モードによってコマンドがブロックされました。 WindowsのNodeホストでは、cmd.exe /c ...のようなシェルラッパー形式は、承認フロー経由で許可されない限り、allowlist モードではブロック対象として扱われます。
迅速な復旧手順
Section titled “迅速な復旧手順”問題が解決しない場合は、以下のループを試してください。
openclaw nodes statusopenclaw nodes describe --node <idOrNameOrIp>openclaw approvals get --node <idOrNameOrIp>openclaw logs --followそれでも解決しない場合のチェックリストです。
- デバイスのペアリングを再度承認する。
- Nodeアプリを再度開く（フォアグラウンドにする）。
- OSの権限を再度付与する。
- Exec approval ポリシーを再作成または調整する。
次のステップ
Section titled “次のステップ”解決しない場合は、AI Setup Assistant に相談してください。
OpenClaw Expert
まだ解決しませんか？
このページで解決しない場合は、OpenClaw Expertに直接質問してください。