トラブルシューティング

2 分しかない場合は、このページをトリアージの入口として使ってください。

最初の 60 秒

以下のコマンドを順番に実行してください：

openclaw status
openclaw status --all
openclaw gateway probe
openclaw gateway status
openclaw doctor
openclaw channels status --probe
openclaw logs --follow

正常時の出力のポイント：

openclaw status → 設定済みチャンネルが表示され、明らかな認証エラーがない。
openclaw status --all → 完全なレポートが生成され、共有可能。
openclaw gateway probe → 期待されるゲートウェイターゲットに到達可能。
openclaw gateway status → Runtime: running かつ RPC probe: ok。
openclaw doctor → ブロッキングな設定/サービスエラーがない。
openclaw channels status --probe → チャンネルが connected または ready を報告。
openclaw logs --follow → 安定した動作、繰り返される致命的エラーがない。

Anthropic ロングコンテキスト 429

以下が表示される場合： HTTP 429: rate_limit_error: Extra usage is required for long context requests、 /gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context を参照してください。

プラグインインストール失敗：openclaw extensions が見つからない

package.json missing openclaw.extensions でインストールが失敗する場合、そのプラグインパッケージは OpenClaw が受け付けなくなった古い形式を使用しています。

プラグインパッケージでの修正方法：

package.json に openclaw.extensions を追加。
エントリをビルド済みのランタイムファイル（通常 ./dist/index.js）に向ける。
プラグインを再公開し、openclaw plugins install <npm-spec> を再実行。

例：

{
  "name": "@openclaw/my-plugin",
  "version": "1.2.3",
  "openclaw": {
    "extensions": ["./dist/index.js"]
  }
}

参照：/tools/plugin#distribution-npm

判断フローチャート

flowchart TD
  A[OpenClaw が動作しない] --> B{最初に何が壊れたか}
  B --> C[返信がない]
  B --> D[ダッシュボードまたはコントロール UI が接続できない]
  B --> E[ゲートウェイが起動しない、またはサービスが実行されていない]
  B --> F[チャンネルは接続されているがメッセージが流れない]
  B --> G[Cron またはハートビートが発火しない、または配信されない]
  B --> H[ノードはペアリング済みだがカメラ/キャンバス/画面/exec が失敗]
  B --> I[ブラウザツールが失敗]

  C --> C1[/返信なしセクション/]
  D --> D1[/コントロール UI セクション/]
  E --> E1[/ゲートウェイセクション/]
  F --> F1[/チャンネルフローセクション/]
  G --> G1[/自動化セクション/]
  H --> H1[/ノードツールセクション/]
  I --> I1[/ブラウザセクション/]

返信がない

```bash
openclaw status
openclaw gateway status
openclaw channels status --probe
openclaw pairing list --channel <channel> [--account <id>]
openclaw logs --follow
```

正常な出力：

- `Runtime: running`
- `RPC probe: ok`
- `channels status --probe` でチャンネルが connected/ready と表示
- 送信者が承認済み（または DM ポリシーが open/allowlist）

よくあるログの特徴：

- `drop guild message (mention required` → Discord のメンション制限がメッセージをブロック。
- `pairing request` → 送信者が未承認で DM ペアリング承認待ち。
- `blocked` / `allowlist` がチャンネルログに出現 → 送信者、ルーム、またはグループがフィルタリングされている。

詳細ページ：

- [/gateway/troubleshooting#no-replies](/docs/gateway/troubleshooting#no-replies)
- [/channels/troubleshooting](/docs/channels/troubleshooting)
- [/channels/pairing](/docs/channels/pairing)

ダッシュボードまたはコントロール UI が接続できない

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

正常な出力：

- `openclaw gateway status` に `Dashboard: http://...` が表示
- `RPC probe: ok`
- ログに認証ループがない

よくあるログの特徴：

- `device identity required` → HTTP/非セキュアコンテキストでデバイス認証を完了できない。
- `AUTH_TOKEN_MISMATCH` とリトライヒント（`canRetryWithDeviceToken=true`）→ 信頼されたデバイストークンによる自動リトライが 1 回発生する可能性あり。
- リトライ後も `unauthorized` が繰り返される → トークン/パスワードの不一致、認証モードの不一致、またはデバイストークンの期限切れ。
- `gateway connect failed:` → UI が誤った URL/ポートを指しているか、ゲートウェイに到達できない。

詳細ページ：

- [/gateway/troubleshooting#dashboard-control-ui-connectivity](/docs/gateway/troubleshooting#dashboard-control-ui-connectivity)
- [/web/control-ui](/docs/web/control-ui)
- [/gateway/authentication](/docs/gateway/authentication)

ゲートウェイが起動しない、またはサービスがインストールされているが実行されていない

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

正常な出力：

- `Service: ... (loaded)`
- `Runtime: running`
- `RPC probe: ok`

よくあるログの特徴：

- `Gateway start blocked: set gateway.mode=local` → ゲートウェイモードが未設定または remote。
- `refusing to bind gateway ... without auth` → 非ループバックバインドでトークン/パスワードが未設定。
- `another gateway instance is already listening` または `EADDRINUSE` → ポートが既に使用中。

詳細ページ：

- [/gateway/troubleshooting#gateway-service-not-running](/docs/gateway/troubleshooting#gateway-service-not-running)
- [/gateway/background-process](/docs/gateway/background-process)
- [/gateway/configuration](/docs/gateway/configuration)

チャンネルは接続されているがメッセージが流れない

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

正常な出力：

- チャンネルトランスポートが接続済み。
- ペアリング/許可リストのチェックが通過。
- 必要な場所でメンションが検出されている。

よくあるログの特徴：

- `mention required` → グループのメンション制限が処理をブロック。
- `pairing` / `pending` → DM 送信者がまだ承認されていない。
- `not_in_channel`、`missing_scope`、`Forbidden`、`401/403` → チャンネル権限トークンの問題。

詳細ページ：

- [/gateway/troubleshooting#channel-connected-messages-not-flowing](/docs/gateway/troubleshooting#channel-connected-messages-not-flowing)
- [/channels/troubleshooting](/docs/channels/troubleshooting)

Cron またはハートビートが発火しない、または配信されない

```bash
openclaw status
openclaw gateway status
openclaw cron status
openclaw cron list
openclaw cron runs --id <jobId> --limit 20
openclaw logs --follow
```

正常な出力：

- `cron.status` が有効で次のウェイク時間が表示。
- `cron runs` に最近の `ok` エントリが表示。
- ハートビートが有効でアクティブ時間外ではない。

よくあるログの特徴：

- `cron: scheduler disabled; jobs will not run automatically` → cron が無効。
- `heartbeat skipped` かつ `reason=quiet-hours` → 設定されたアクティブ時間外。
- `requests-in-flight` → メインレーンがビジー。ハートビートウェイクが延期された。
- `unknown accountId` → ハートビートの配信先アカウントが存在しない。

詳細ページ：

- [/gateway/troubleshooting#cron-and-heartbeat-delivery](/docs/gateway/troubleshooting#cron-and-heartbeat-delivery)
- [/automation/troubleshooting](/docs/automation/troubleshooting)
- [/gateway/heartbeat](/docs/gateway/heartbeat)

ノードはペアリング済みだがツールが失敗（カメラ/キャンバス/画面/exec）

```bash
openclaw status
openclaw gateway status
openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>
openclaw logs --follow
```

正常な出力：

- ノードが接続済みかつペアリング済みでロール `node` として表示。
- 呼び出そうとしているコマンドのケイパビリティが存在。
- ツールの権限状態が granted。

よくあるログの特徴：

- `NODE_BACKGROUND_UNAVAILABLE` → ノードアプリをフォアグラウンドに。
- `*_PERMISSION_REQUIRED` → OS 権限が拒否/未付与。
- `SYSTEM_RUN_DENIED: approval required` → exec 承認が保留中。
- `SYSTEM_RUN_DENIED: allowlist miss` → コマンドが exec 許可リストにない。

詳細ページ：

- [/gateway/troubleshooting#node-paired-tool-fails](/docs/gateway/troubleshooting#node-paired-tool-fails)
- [/nodes/troubleshooting](/docs/nodes/troubleshooting)
- [/tools/exec-approvals](/docs/tools/exec-approvals)

ブラウザツールが失敗

```bash
openclaw status
openclaw gateway status
openclaw browser status
openclaw logs --follow
openclaw doctor
```

正常な出力：

- ブラウザステータスが `running: true` でブラウザ/プロファイルが選択されている。
- `openclaw` プロファイルが起動、または `chrome` リレーにタブが接続されている。

よくあるログの特徴：

- `Failed to start Chrome CDP on port` → ローカルブラウザの起動に失敗。
- `browser.executablePath not found` → 設定されたバイナリパスが誤り。
- `Chrome extension relay is running, but no tab is connected` → 拡張機能が未接続。
- `Browser attachOnly is enabled ... not reachable` → アタッチ専用プロファイルにライブの CDP ターゲットがない。

詳細ページ：

- [/gateway/troubleshooting#browser-tool-fails](/docs/gateway/troubleshooting#browser-tool-fails)
- [/tools/browser-linux-troubleshooting](/docs/tools/browser-linux-troubleshooting)
- [/tools/browser-wsl2-windows-remote-cdp-troubleshooting](/docs/tools/browser-wsl2-windows-remote-cdp-troubleshooting)
- [/tools/chrome-extension](/docs/tools/chrome-extension)