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 → 期待される gateway ターゲットに到達できる（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 などのプローブ/監査結果を返します。gateway に到達できない場合、コマンドは構成のみの要約にフォールバックします。
openclaw logs --follow → 安定したアクティビティがあり、致命的なエラーの繰り返しがない。

Assistant が制限されている、またはツールが見つからないように感じる

Assistant がファイルを検査できない、コマンドを実行できない、ブラウザ自動化を使用できない、または期待されるツールを確認できない場合は、まず有効なツールプロファイルを確認してください。

bash

openclaw statusopenclaw status --allopenclaw doctor

一般的な原因:

tools.profile: "messaging" はチャット専用エージェント向けに意図的に狭くなっています。
tools.profile: "coding" は、リポジトリ、ファイル、シェル、ランタイムワークフロー向けの通常のプロファイルです。
tools.profile: "full" は最も広いツールセットを公開するため、信頼できるオペレーター制御のエージェントに限定する必要があります。
エージェント別の agents.list[].tools オーバーライドにより、1 つのエージェントに対してルートプロファイルを狭めたり広げたりできます。

ルートまたはエージェント別のツールプロファイルを変更し、Gateway を再起動または再読み込みしてから openclaw status --all を再度実行します。プロファイルモデルと allow/deny オーバーライドについては、ツールを参照してください。

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 に進んでください。

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

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

エラーが messages[].content に文字列が期待されることを示している場合は、 models.providers.<provider>.models[].compat.requiresStringContent: true を設定します。
それでもバックエンドが OpenClaw のエージェントターンでのみ失敗する場合は、 models.providers.<provider>.models[].compat.supportsTools: false を設定して再試行します。
ごく小さな直接呼び出しは引き続き動作する一方で、より大きな OpenClaw プロンプトによりバックエンドがクラッシュする場合は、残りの問題を上流のモデル/サーバーの制限として扱い、詳細ランブックに進んでください: /gateway/troubleshooting#local-openai-compatible-backend-passes-direct-probes-but-agent-runs-fail

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

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

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

package.json に openclaw.extensions を追加します。
エントリをビルド済みランタイムファイル（通常は ./dist/index.js）に向けます。
plugin を再公開し、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 の更新では更新後同期中に一致する @openclaw/* plugin の更新も必要になる場合があります。

対応するアップグレードルールも保守していない限り、次のような広範なポリシー形状は避けてください。

OpenClaw 所有の plugin を、たとえば @openclaw/*@2026.5.3 のみを許可するような、単一の厳密な古いバージョンに固定する。
npm、ネットワーク、または request.mode: "update" の plugin リクエストすべてなど、ソース種別だけでブロックする。
ポリシーコマンドを任意として扱う。security.installPolicy が有効な場合、ポリシー実行ファイルが存在しない、遅い、読み取れない、または権限でブロックされていると fail closed になります。
ポリシーリクエストの openclawVersion と plugin 候補メタデータを考慮せずに plugin バージョンを承認する。

より安全なポリシールールでは、単一のリリースに永続的に固定するのではなく、候補が現在の OpenClaw ホストと互換性がある場合に、信頼された OpenClaw 所有 plugin の更新を許可します。 npm をデフォルトでブロックする場合は、使用している信頼済み @openclaw/* plugin パッケージまたは plugin id に限定的な例外を設けます。インストールリクエストと更新リクエストを区別する場合は、同じ信頼ルールを request.mode: "update" に適用します。

復旧:

bash

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

ポリシーが意図的に厳格な場合は、信頼済み OpenClaw アップグレード期間中だけ緩和し、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) として実行されます。デフォルトのDockerセットアップでは、ホストのバインドマウントを修復します:

bash

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

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

bash

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

詳細なドキュメント:

判断ツリー

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/]

返信がない

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ターゲットで許可されていません。
再試行ヒント (canRetryWithDeviceToken=true) 付きの AUTH_TOKEN_MISMATCH → 信頼済みデバイストークンによる再試行が1回、自動的に行われる場合があります。
そのキャッシュ済みトークンの再試行では、ペアリング済みデバイストークンと一緒に保存されたキャッシュ済みスコープセットを再利用します。明示的な deviceToken / 明示的な scopes の呼び出し元は、代わりに要求したスコープセットを維持します。
非同期のTailscale Serve Control UIパスでは、同じ {scope, ip} に対する失敗した試行は、リミッターが失敗を記録する前に直列化されるため、2つ目の同時の不正な再試行ですでに retry later が表示されることがあります。
localhostブラウザオリジンからの too many failed authentication attempts (retry later) → 同じ Origin からの失敗が繰り返されたため、一時的にロックアウトされています。別のlocalhostオリジンは別のバケットを使用します。
その再試行後も unauthorized が繰り返される → トークン/パスワードが誤っている、認証モードが一致しない、またはペアリング済みデバイストークンが古くなっています。
gateway connect failed: → UIが誤ったURL/ポートを指しているか、Gatewayに到達できません。

詳細ページ:

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モードがremoteであるか、設定ファイルにlocal-modeスタンプがなく、修復する必要があります。
refusing to bind gateway ... without auth → 有効なGateway認証パス（トークン/パスワード、または設定済みの場合はtrusted-proxy）なしで非ループバックにバインドしようとしています。
another gateway instance is already listening または EADDRINUSE → ポートはすでに使用されています。

詳細ページ:

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

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 with reason=quiet-hours → 設定されたアクティブ時間外です。
heartbeat skipped with reason=empty-heartbeat-file → HEARTBEAT.md は存在しますが、空白、コメント、ヘッダー、フェンス、または空のチェックリストの足場のみを含んでいます。
heartbeat skipped with reason=no-tasks-due → HEARTBEAT.md のタスクモードは有効ですが、まだ期限に達したタスク間隔がありません。
heartbeat skipped with reason=alerts-disabled → すべての heartbeat 表示が無効です（showOk、showAlerts、useIndicator がすべてオフです）。
requests-in-flight → メインレーンがビジーです。heartbeat の起動は延期されました。
unknown accountId → 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 → ノードアプリをフォアグラウンドに移動してください。
*_PERMISSION_REQUIRED → OS 権限が拒否されたか不足しています。
SYSTEM_RUN_DENIED: approval required → exec 承認が保留中です。
SYSTEM_RUN_DENIED: allowlist miss → コマンドが 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 です。
host=auto は、サンドボックスランタイムがアクティブな場合は sandbox、それ以外の場合は gateway に解決されます。
host=auto はルーティングのみです。プロンプトなしの「YOLO」動作は、gateway/node 上の security=full と ask=off によって発生します。
gateway と node では、未設定の tools.exec.security はデフォルトで 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 → 暗黙的/明示的なサンドボックス選択ですが、サンドボックスモードがオフです。

詳細ページ:

ブラウザツールが失敗する

bash

openclaw statusopenclaw gateway statusopenclaw browser statusopenclaw logs --followopenclaw doctor

良好な出力は次のようになります。

ブラウザステータスに running: true と選択されたブラウザ/プロファイルが表示されています。
openclaw が起動する、または user がローカルの Chrome タブを確認できます。

よくあるログシグネチャ:

unknown command "browser" or 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 or Browser attachOnly is enabled and CDP websocket ... is not reachable → アタッチ専用プロファイルに稼働中の CDP ターゲットがありません。
attach-only またはリモート CDP プロファイルで古いビューポート / ダークモード / ロケール / オフラインのオーバーライドが残っている → Gateway を再起動せずに、openclaw browser stop --browser-profile <name> を実行してアクティブな制御セッションを閉じ、エミュレーション状態を解放してください。

詳細ページ:

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

最初の 60 秒

Assistant が制限されている、またはツールが見つからないように感じる

Anthropic 長いコンテキスト 429

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

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

インストールポリシーが plugin のインストールまたは更新をブロックする

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

判断ツリー

関連

On this page

Molty