OpenClaw Troubleshooting ガイド

開発を進めていると、昨日まで動いていたものが突然動かなくなったり、原因不明のエラーに直面したりすることがあります。複雑なシステムであればあるほど、どこから手をつければいいか迷ってしまうものです。

そんな時は、闇雲に設定を変更するのではなく、まずは現状を正しく把握することが解決への近道です。OpenClaw の状態を素早く診断するためのベストな手順を紹介します。

必要なもの

OpenClaw CLI

Quick Start: 最初の 60 秒でやるべきこと

問題が発生したら、まず以下のコマンドを順番に実行してください。これが最も効率的な診断フローです。

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

正常な状態であれば、以下のような結果が得られます。

openclaw status: 設定済みの channels が表示され、認証エラーがない。
openclaw status --all: 完全なレポートが表示され、共有可能な状態である。
openclaw gateway probe: ターゲットとなる gateway に到達できる。
openclaw gateway status: Runtime: running および RPC probe: ok と表示される。
openclaw doctor: ブロック要素となる config やサービスのエラーがない。
openclaw channels status --probe: 各 channels が connected または ready と報告されている。
openclaw logs --follow: ログが安定して出力され、致命的なエラーが繰り返されていない。

トラブルシューティング

何が起きているかに応じて、以下のデシジョンツリーを参考にしてください。

flowchart TD
  A[OpenClaw is not working] --> B{What breaks first}
  B --> C[No replies]
  B --> D[Dashboard or Control UI will not connect]
  B --> E[Gateway will not start or service not running]
  B --> F[Channel connects but messages do not flow]
  B --> G[Cron or heartbeat did not fire or did not deliver]
  B --> H[Node is paired but camera canvas screen exec fails]
  B --> I[Browser tool fails]

  C --> C1[/No replies section/]
  D --> D1[/Control UI section/]
  E --> E1[/Gateway section/]
  F --> F1[/Channel flow section/]
  G --> G1[/Automation section/]
  H --> H1[/Node tools section/]
  I --> I1[/Browser section/]

1. 返信が来ない場合 (No replies)

まずは以下のコマンドで状態を確認します。

openclaw status
openclaw gateway status
openclaw channels status --probe
openclaw pairing list <channel>
openclaw logs --follow

正常な出力の目安:

Runtime: running
RPC probe: ok
channels status --probe で該当 channel が connected/ready になっている。
送信者が承認されている（または DM ポリシーが open/allowlist になっている）。

よくあるログのサイン:

drop guild message (mention required: Discord でメンションがないためブロックされました。
pairing request: 送信者が未承認で、DM pairing の承認待ちです。
blocked / allowlist: channel ログにて送信者やルームがフィルタリングされています。

2. Dashboard や Control UI が接続できない

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

正常な出力の目安:

openclaw gateway status で Dashboard: http://... が表示されている。
RPC probe: ok
ログに認証ループ（auth loop）が発生していない。

よくあるログのサイン:

device identity required: HTTP または非セキュアなコンテキストのため、デバイス認証が完了できません。
unauthorized / reconnect loop: トークンやパスワードの間違い、または認証モードの不一致です。
gateway connect failed:: UI が間違った URL/port を参照しているか、gateway に到達できません。

3. Gateway が起動しない、またはサービスが実行されない

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: gateway mode が未設定または remote になっています。
refusing to bind gateway ... without auth: ループバック以外のアドレスに、トークンやパスワードなしでバインドしようとしています。
another gateway instance is already listening または EADDRINUSE: ポートが既に使用されています。

4. Channel は接続されているがメッセージが流れない

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

正常な出力の目安:

Channel のトランスポートが接続されている。
Pairing や allowlist のチェックをパスしている。
必要な場所でメンションが検知されている。

よくあるログのサイン:

mention required: グループ内でのメンションが必要な設定によりブロックされました。
pairing / pending: DM の送信者がまだ承認されていません。
not_in_channel, missing_scope, Forbidden, 401/403: channel のパーミッショントークンに問題があります。

5. Cron や heartbeat が実行されない、または配信されない

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

正常な出力の目安:

cron.status が enabled で、次回の実行予定が表示されている。
cron runs で最近の実行が ok になっている。
Heartbeat が有効で、アクティブ時間外になっていない。

よくあるログのサイン:

cron: scheduler disabled; jobs will not run automatically: cron が無効設定になっています。
heartbeat skipped (reason=quiet-hours): 設定されたアクティブ時間外です。
requests-in-flight: メインレーンが混雑しているため、heartbeat の実行が延期されました。
unknown accountId: heartbeat の配信先アカウントが存在しません。

6. Node はペアリング済みだがツール（camera/canvas/screen exec）が失敗する

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

正常な出力の目安:

Node が接続済みで、役割（role）が node としてペアリングされている。
実行しようとしているコマンドの capability が存在する。
ツールに対するパーミッションが許可されている。

よくあるログのサイン:

NODE_BACKGROUND_UNAVAILABLE: node アプリをフォアグラウンドにする必要があります。
*_PERMISSION_REQUIRED: OS の権限が拒否されているか不足しています。
SYSTEM_RUN_DENIED: approval required: 実行の承認待ちです。
SYSTEM_RUN_DENIED: allowlist miss: コマンドが実行許可リスト（exec allowlist）にありません。

7. Browser tool が失敗する

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

正常な出力の目安:

Browser status が 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: attach-only プロファイルに有効な CDP ターゲットがありません。

困ったときは、AI Setup Assistant も活用してみてください。

次のステップ

OpenClaw Expert

まだ解決しませんか？

このページで解決しない場合は、OpenClaw Expertに直接質問してください。