OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Start here

一般的なトラブルシューティング

トリアージの入口。2分で診断し、その後、詳細ページに進みます。

最初の60秒

次の手順を順番に実行します。

bash
openclaw statusopenclaw status --allopenclaw gateway probeopenclaw gateway statusopenclaw doctoropenclaw channels status --probeopenclaw logs --follow

正常な出力（各項目1行）：

  • openclaw status に設定済みのチャンネルが表示され、認証エラーがない。
  • openclaw status --all により、共有可能な完全なレポートが生成される。
  • openclaw gateway probe に Reachable: yes と表示される。Capability: ... はプローブで確認された認証レベルです。Read probe: limited - missing scope: operator.read は診断機能の制限であり、接続失敗ではありません。
  • openclaw gateway status に Runtime: running、Connectivity probe: ok、および妥当な Capability: ... が表示される。読み取りスコープのRPC確認も必須にするには、--require-rpc を追加します。
  • openclaw doctor から、処理を妨げる設定またはサービスのエラーが報告されない。
  • openclaw channels status --probe は、Gatewayに到達できる場合、アカウントごとの現在の転送状態（works / audit ok）を返す。到達できない場合は、設定のみの概要にフォールバックする。
  • openclaw logs --follow に安定した動作が表示され、致命的なエラーが繰り返されていない。

アシスタントの機能が制限されている、またはツールが見つからない

有効なツールプロファイルを確認します。

bash
openclaw statusopenclaw status --allopenclaw doctor

一般的な原因：

  • tools.profile: "minimal" では、session_status のみが許可される。
  • tools.profile: "messaging" は、チャット専用エージェント向けの限定的なプロファイルです。
  • tools.profile: "coding" は、新しいローカル設定のデフォルトです（リポジトリ、ファイル、シェル、ランタイムの操作）。
  • tools.profile: "full" はプロファイルによる制限を解除する。信頼できるオペレーター管理下のエージェントに限定してください。
  • エージェント単位の agents.list[].tools は、1つのエージェントについてルートプロファイルを制限または拡張する。

プロファイルを変更し、Gatewayを再起動または再読み込みしてから、openclaw status --all でもう一度確認します。プロファイルとグループの完全な表：ツールプロファイル。

Anthropicの長いコンテキストでの429

HTTP 429: rate_limit_error: Extra usage is required for long context requests → Anthropicの長いコンテキストで追加使用量が必要となる429。

ローカルのOpenAI互換バックエンドは直接実行では動作するが、OpenClawでは失敗する

ローカルまたはセルフホストの /v1 バックエンドは、直接の /v1/chat/completions プローブには応答するものの、openclaw infer model run または通常のエージェントターンでは失敗します。

  1. エラーに、messages[].content は文字列である必要があると示されている場合：models.providers.<provider>.models[].compat.requiresStringContent: true を設定します。
  2. 引き続きOpenClawのエージェントターンでのみ失敗する場合：models.providers.<provider>.models[].compat.supportsTools: false を設定して再試行します。
  3. 小さな直接呼び出しは動作するが、より大きなOpenClawプロンプトでバックエンドがクラッシュする場合：これは上流のモデルまたはサーバーの制限であり、OpenClawのバグではありません。ローカルのOpenAI互換バックエンドは直接プローブに成功するが、エージェント実行は失敗するに進んでください。

openclaw extensionsの欠落によりPluginのインストールが失敗する

package.json missing openclaw.extensions は、PluginパッケージがOpenClawでサポートされなくなった形式を使用していることを意味します。

Pluginパッケージで修正します。

  1. package.json に openclaw.extensions を追加し、ビルド済みのランタイムファイル（通常は ./dist/index.js）を指定します。
  2. 再公開してから、openclaw plugins install <package> をもう一度実行します。
json
{  "name": "@openclaw/my-plugin",  "version": "1.2.3",  "openclaw": {    "extensions": ["./dist/index.js"]  }}

参照：Pluginアーキテクチャ

インストールポリシーによってPluginのインストールまたは更新がブロックされる

更新は完了するものの、Pluginが古い、無効になっている、または blocked by install policy、install policy failed closed、Disabled "<plugin>" after plugin update failure と表示される場合：security.installPolicy を確認します。

インストールポリシーは、Pluginのインストールおよび更新時に実行されます。@openclaw/* Pluginのバージョンは通常、OpenClawのリリースとともに更新されるため、OpenClawの更新後の同期中に、対応するPluginの更新が必要になる場合があります。

対応するアップグレード規則も管理していない限り、次のようなポリシーは避けてください。

  • OpenClaw所有のPluginを特定の古いバージョンに固定する（たとえば、@openclaw/*@2026.5.3 のみを許可する）。
  • ソースの種類だけでブロックする（すべてのnpm、ネットワーク、または request.mode: "update" リクエスト）。
  • ポリシーコマンドを省略可能なものとして扱う：security.installPolicy が有効な場合、ポリシーの実行ファイルが存在しない、遅い、読み取れない、または権限によってブロックされていると、フェイルクローズになります。
  • リクエストの openclawVersion とPlugin候補のメタデータを照合せずに、バージョンを承認する。

1つのリリースに永久に固定するのではなく、現在のホストと互換性がある、信頼済みの @openclaw/* 更新を許可する規則を推奨します。npmをデフォルトでブロックする場合は、使用するPlugin IDに限定した例外を追加し、インストールと同じ信頼規則を request.mode: "update" にも適用します。

復旧手順：

bash
openclaw doctor --deepopenclaw plugins update --allopenclaw status --all

意図的に厳格なポリシーを使用している場合は、信頼済みのアップグレード期間中のみ緩和し、openclaw plugins update --all を再実行してから、より厳格な規則に戻します。更新の失敗によりPluginが無効になった場合は、再度有効にする前に調査します。

bash
openclaw plugins inspect <plugin-id> --runtime --jsonopenclaw plugins enable <plugin-id>

参照：オペレーターのインストールポリシー

Pluginは存在するが、不審な所有権によりブロックされる

openclaw doctor、セットアップ、または起動時の警告に次のように表示されます。

text
blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root)plugin present but blocked

Pluginファイルが、それを読み込むプロセスとは異なるUnixユーザーによって所有されています。Plugin設定を削除しないでください。ファイルの所有権を修正するか、状態ディレクトリを所有するユーザーとしてOpenClawを実行します。

Dockerのインストールでは、node（uid 1000）として実行されます。ホストのバインドマウントを修復します。

bash
sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspaceopenclaw doctor --fix

意図的にrootとしてOpenClawを実行する場合は、代わりに管理対象のPluginルートを修復します。

bash
sudo chown -R root:root /path/to/openclaw-config/npmopenclaw doctor --fix

詳細なドキュメント：ブロックされたPluginパスの所有権、Docker：権限とEACCES

判断フロー

flowchart TD
  A[OpenClawが動作しない] --> B{最初に問題が発生する箇所}
  B --> C[返信がない]
  B --> D[ダッシュボードまたはControl UIが接続できない]
  B --> E[Gatewayが起動しない、またはサービスが実行されていない]
  B --> F[チャンネルは接続するがメッセージが流れない]
  B --> G[CronまたはHeartbeatが実行されない、または配信されない]
  B --> H[Nodeはペアリング済みだが、カメラ、キャンバス、画面、コマンド実行が失敗する]
  B --> I[ブラウザーツールが失敗する]

  C --> C1[/返信がないセクション/]
  D --> D1[/Control UIセクション/]
  E --> E1[/Gatewayセクション/]
  F --> F1[/チャンネルフローセクション/]
  G --> G1[/自動化セクション/]
  H --> H1[/Nodeツールセクション/]
  I --> I1[/ブラウザーセクション/]
返信がない
bash
openclaw statusopenclaw gateway statusopenclaw channels status --probeopenclaw pairing list --channel <channel> [--account <id>]openclaw logs --follow

正常な出力：

  • Runtime: running
  • Connectivity probe: ok
  • Capability: read-only、write-capable、または admin-capable
  • チャンネルの転送が接続済みと表示され、サポートされている場合は channels status --probe に works または audit ok と表示される
  • 送信者が承認されている（またはDMポリシーがオープンまたは許可リスト方式である）

ログの特徴：

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

詳細ページ：返信がない、チャンネルのトラブルシューティング、ペアリング

ダッシュボードまたはControl UIが接続できない
bash
openclaw statusopenclaw gateway statusopenclaw logs --followopenclaw doctoropenclaw channels status --probe

正常な出力：

  • openclaw gateway status に Dashboard: http://... が表示される
  • Connectivity probe: ok
  • Capability: read-only、write-capable、または admin-capable
  • ログに認証ループがない

ログの特徴：

  • device identity required → HTTPまたは非セキュアなコンテキストでは、デバイス認証を完了できない。
  • origin not allowed → ブラウザーの Origin が、Control UIのGateway接続先で許可されていない。
  • AUTH_TOKEN_MISMATCH と canRetryWithDeviceToken=true → ペアリング済みトークンにキャッシュされたスコープを再利用し、信頼済みデバイストークンによる再試行が1回、自動的に行われる場合がある。
  • その再試行後も unauthorized が繰り返される → トークンまたはパスワードが誤っている、認証モードが一致していない、またはペアリング済みデバイストークンが古い。
  • too many failed authentication attempts (retry later) → そのブラウザーの Origin から失敗が繰り返されたため、一時的にロックアウトされている。他のlocalhostオリジンには別のバケットが使用される。Tailscale Serveの同時再試行に関する注意点は、ダッシュボード／Control UIの接続を参照してください。
  • gateway connect failed: → UIが誤ったURLまたはポートを接続先にしているか、Gatewayに到達できない。

詳細ページ：ダッシュボード／Control UIの接続、Control UI、認証

Gatewayが起動しない、またはサービスはインストール済みだが実行されていない
bash
openclaw statusopenclaw gateway statusopenclaw logs --followopenclaw doctoropenclaw channels status --probe

正常な出力：

  • Service: ... (loaded)
  • Runtime: running
  • Connectivity probe: ok
  • Capability: read-only、write-capable、または admin-capable

ログの特徴：

  • Gateway start blocked: set gateway.mode=local または existing config is missing gateway.mode → Gatewayモードがリモートになっているか、設定にローカルモードを示す情報がなく、修復が必要。
  • refusing to bind gateway ... without auth → 有効な認証経路（トークン／パスワード、または設定済みの場合は信頼済みプロキシ）がない状態で、ループバック以外にバインドしようとしている。
  • another gateway instance is already listening または EADDRINUSE → ポートがすでに使用されている。

詳細ページ：Gatewayサービスが実行されていない、バックグラウンドプロセス、設定

チャンネルは接続するがメッセージが流れない
bash
openclaw statusopenclaw gateway statusopenclaw logs --followopenclaw doctoropenclaw channels status --probe

正常な出力：

  • チャンネルの転送が接続済み。
  • ペアリングおよび許可リストの確認に合格している。
  • 必要な箇所でメンションが検出されている。

ログの特徴：

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

詳細ページ：チャンネルは接続済みだがメッセージが流れない、チャンネルのトラブルシューティング

CronまたはHeartbeatが実行されない、または配信されない
bash
openclaw statusopenclaw gateway statusopenclaw cron statusopenclaw cron listopenclaw cron runs --id <jobId> --limit 20openclaw logs --follow

正常な出力：

  • cron status に、スケジューラーが有効であり、次回の起動時刻が設定されていることが表示される。
  • cron runs に最近の ok エントリが表示される。
  • Heartbeatが有効であり、アクティブ時間内である。

ログの特徴：

  • cron: scheduler disabled; jobs will not run automatically → cron は無効です。
  • heartbeat skipped の理由が quiet-hours → 設定されたアクティブ時間外です。
  • heartbeat skipped の理由が empty-heartbeat-file → HEARTBEAT.md は存在しますが、空白、コメント、見出し、フェンス、または空のチェックリストのひな形しか含まれていません。
  • heartbeat skipped の理由が no-tasks-due → タスクモードは有効ですが、まだ実行時刻に達したタスク間隔がありません。
  • heartbeat skipped の理由が alerts-disabled → showOk、showAlerts、useIndicator がすべてオフです。
  • requests-in-flight → メインレーンが処理中のため、Heartbeat の起動が延期されています。
  • unknown accountId → Heartbeat の配信先アカウントが存在しません。

詳細ページ: Cron と Heartbeat の配信、スケジュール済みタスク: トラブルシューティング、Heartbeat

Node はペアリング済みだが camera canvas screen exec ツールが失敗する
bash
openclaw statusopenclaw gateway statusopenclaw nodes statusopenclaw nodes describe --node <idOrNameOrIp>openclaw logs --follow

正常な出力:

  • Node がロール node として接続済みかつペアリング済みと表示されます。
  • 呼び出しているコマンドに必要なケイパビリティが存在します。
  • ツールの権限状態が許可済みです。

ログの特徴:

  • NODE_BACKGROUND_UNAVAILABLE → Node アプリをフォアグラウンドに移動してください。
  • *_PERMISSION_REQUIRED → OS の権限が拒否されているか、付与されていません。
  • SYSTEM_RUN_DENIED: approval required → exec の承認待ちです。
  • SYSTEM_RUN_DENIED: allowlist miss → コマンドが exec の許可リストにありません。

詳細ページ: Node はペアリング済みだがツールが失敗する、Node のトラブルシューティング、Exec の承認

Exec が突然承認を求める
bash
openclaw config get tools.exec.hostopenclaw config get tools.exec.securityopenclaw config get tools.exec.askopenclaw gateway restart

変更された点:

  • tools.exec.host が未設定の場合、デフォルトは auto です。これはサンドボックスランタイムが有効な場合は sandbox、それ以外の場合は gateway として解決されます。
  • host=auto はルーティングのみを行います。プロンプトなしの動作は、Gateway/Node 上の security=full と ask=off の組み合わせによるものです。
  • tools.exec.security が未設定の場合、gateway/node ではデフォルトが full です。
  • tools.exec.ask が未設定の場合、デフォルトは off です。
  • 承認が表示される場合は、ホストローカルまたはセッション単位のポリシーによって、exec がこれらのデフォルトより厳しく制限されています。

現在の承認不要のデフォルトを復元します:

bash
openclaw config set tools.exec.host gatewayopenclaw config set tools.exec.security fullopenclaw config set tools.exec.ask offopenclaw gateway restart

より安全な代替策:

  • ホストのルーティングを安定させるには、tools.exec.host=gateway のみを設定します。
  • ホストでの exec に security=allowlist と ask=on-miss を使用し、許可リストにない場合に確認します。
  • サンドボックスモードを有効にして、host=auto が再び sandbox として解決されるようにします。

ログの特徴:

  • Approval required. → コマンドは /approve ... を待っています。
  • SYSTEM_RUN_DENIED: approval required → Node ホストでの exec の承認待ちです。
  • exec host=sandbox requires a sandbox runtime for this session → 暗黙的または明示的にサンドボックスが選択されていますが、サンドボックスモードはオフです。

詳細ページ: Exec、Exec の承認、セキュリティ: 監査で確認される項目

ブラウザーツールが失敗する
bash
openclaw statusopenclaw gateway statusopenclaw browser statusopenclaw logs --followopenclaw doctor

正常な出力:

  • ブラウザーの状態に running: true と、選択されたブラウザー/プロファイルが表示されます。
  • openclaw プロファイルが起動するか、user プロファイルからローカルの Chrome タブを認識できます。

ログの特徴:

  • unknown command "browser" → plugins.allow が設定されており、browser が除外されています。
  • Failed to start Chrome CDP on port → ローカルブラウザーの起動に失敗しました。
  • browser.executablePath not found → 設定されたバイナリーパスが誤っています。
  • browser.cdpUrl must be http(s) or ws(s) → 設定された CDP URL がサポートされていないスキームを使用しています。
  • browser.cdpUrl has invalid port → 設定された CDP URL のポートが不正か、範囲外です。
  • No Chrome tabs found for profile="user" → Chrome MCP 接続プロファイルに、開いているローカル Chrome タブがありません。
  • Remote CDP for profile "<name>" is not reachable → 設定されたリモート CDP エンドポイントに、このホストから到達できません。
  • Browser attachOnly is enabled ... not reachable → 接続専用プロファイルに稼働中の CDP ターゲットがありません。
  • 接続専用またはリモート CDP プロファイルに古いビューポート/ダークモード/ロケール/オフラインのオーバーライドが残っている → openclaw browser stop --browser-profile <name> を実行すると、Gateway を再起動せずに制御セッションを終了し、エミュレーション状態を解除できます。

詳細ページ: ブラウザーツールが失敗する、ブラウザーのコマンドまたはツールが見つからない、ブラウザー: Linux のトラブルシューティング、ブラウザー: WSL2/Windows リモート CDP のトラブルシューティング

関連項目

Was this useful?
On this page

On this page