---
read_when:
    - Node は接続されていますが、カメラ／キャンバス／画面／実行ツールが失敗する
    - Node のペアリングと承認の違いに関するメンタルモデルを理解する必要があります
summary: Node のペアリング、フォアグラウンド要件、権限、ツールの障害をトラブルシューティングする
title: Node のトラブルシューティング
x-i18n:
    generated_at: "2026-07-26T09:28:47Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: 4a7ee9e48985805e91cd5acfa1b9f6b676b7e67236ce29fe91e2c8d03002e5c4
    source_path: nodes/troubleshooting.md
    workflow: 16
---

ステータスに Node が表示されているものの、Node ツールが失敗する場合は、このページを参照してください。

## コマンドの実行順序

```bash
openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe
```

次に、Node 固有のチェックを実行します。

```bash
openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>
openclaw approvals get --node <idOrNameOrIp>
```

正常性を示すシグナル：

- Node が接続され、ロール `node` 用にペアリングされている。
- `nodes describe` に、呼び出している機能が含まれている。
- 実行承認に、想定されるモード／許可リストが表示されている。

## フォアグラウンド要件

`canvas.*`、`camera.*`、`screen.*` は、iOS／Android の Node ではフォアグラウンドでのみ動作します。

簡易チェックと修正：

```bash
openclaw nodes describe --node <idOrNameOrIp>
openclaw nodes canvas snapshot --node <idOrNameOrIp>
openclaw logs --follow
```

`NODE_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 つの独立したゲートによって制御されます。

1. **デバイスのペアリング**：この Node は Gateway に接続できるか？
2. **Gateway の Node コマンドポリシー**：RPC コマンド ID は、`gateway.nodes.commands.allow`／`gateway.nodes.commands.deny` とプラットフォームのデフォルト設定で許可されているか？
3. **実行承認**：この Node は特定のシェルコマンドをローカルで実行できるか？

Node のペアリングは、コマンド単位の承認機能ではなく、ID／信頼性のゲートです。`system.run` の Node 単位のポリシーは、Gateway のペアリングレコードではなく、その Node の実行承認ファイル（`openclaw approvals get --node ...`）に保存されます。

簡易チェック：

```bash
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 の実行承認／許可リストを修正してください。

承認に基づく `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 ...` のようなシェルラッパー形式は、確認フローで承認されない限り、許可リストモードで許可リスト不一致として扱われます。 |

## 高速復旧ループ

```bash
openclaw nodes status
openclaw 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` より優先されます。

## 関連項目

- [Node の概要](/ja-JP/nodes)
- [カメラ Node](/ja-JP/nodes/camera)
- [位置情報コマンド](/ja-JP/nodes/location-command)
- [コンピューター操作](/ja-JP/nodes/computer-use)
- [実行承認](/ja-JP/tools/exec-approvals)
- [Gateway のペアリング](/ja-JP/gateway/pairing)
- [Gateway のトラブルシューティング](/ja-JP/gateway/troubleshooting)
- [チャンネルのトラブルシューティング](/ja-JP/channels/troubleshooting)
