このページは詳細なランブックです。まず高速なトリアージフローを確認したい場合は、/help/troubleshooting から始めてください。Documentation Index
Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
コマンドの手順
まず次をこの順序で実行します。openclaw gateway statusにRuntime: running、Connectivity probe: ok、およびCapability: ...行が表示される。openclaw doctorが、ブロック要因となる設定やサービスの問題を報告しない。openclaw channels status --probeがアカウントごとのライブなトランスポート状態を表示し、対応している場合はworksやaudit okなどのプローブ/監査結果も表示する。
分断されたインストールと新しい設定ガード
更新後に Gateway サービスが予期せず停止する場合、またはログで、あるopenclaw バイナリが最後に openclaw.json を書き込んだバージョンより古いことが示される場合に使用します。
OpenClaw は設定の書き込みに meta.lastTouchedVersion を記録します。読み取り専用コマンドは新しい OpenClaw が書き込んだ設定を引き続き検査できますが、古いバイナリからのプロセスやサービスの変更は続行を拒否します。ブロックされる操作には、Gateway サービスの開始、停止、再起動、アンインストール、強制的なサービス再インストール、サービスモードの Gateway 起動、gateway --force によるポートクリーンアップが含まれます。
Skill のシンボリックリンクがパスエスケープとしてスキップされる
ログに次が含まれる場合に使用します。~/.agents/skills、<workspace>/.agents/skills、<workspace>/skills、または
~/.openclaw/skills 配下のシンボリックリンクは、ターゲットが明示的に信頼されていない限り、実際のターゲットがそのルートの外側に解決されるとスキップされます。
リンクを検査します。
~、/、同期プロジェクトフォルダー全体のような広いターゲットは使用しないでください。
allowSymlinkTargets は、信頼された SKILL.md ディレクトリを含む実際の skill ルートに限定してください。
関連:
Anthropic 429 長いコンテキストには追加利用が必要
ログ/エラーにHTTP 429: rate_limit_error: Extra usage is required for long context requests が含まれる場合に使用します。
- 選択された Anthropic Opus/Sonnet モデルに
params.context1m: trueがある。 - 現在の Anthropic 認証情報が長いコンテキストの使用対象ではない。
- 1M ベータパスを必要とする長いセッション/モデル実行でのみリクエストが失敗する。
関連:
ローカルの OpenAI 互換バックエンドは直接プローブを通過するが、エージェント実行が失敗する
次の場合に使用します。curl ... /v1/modelsが動作する- 小さな直接
/v1/chat/completions呼び出しが動作する - OpenClaw のモデル実行が通常のエージェントターンでのみ失敗する
- 小さな直接呼び出しは成功するが、OpenClaw の実行は大きなプロンプトでのみ失敗する
- 同じ素のモデル ID で直接
/v1/chat/completionsが動作するにもかかわらず、model_not_foundまたは 404 エラーが出る messages[].contentが文字列を期待しているというバックエンドエラー- OpenAI 互換のローカルバックエンドで、
incomplete turn detected ... stopReason=stop payloads=0警告が断続的に出る - 大きなプロンプトトークン数または完全なエージェントランタイムプロンプトでのみ発生するバックエンドクラッシュ
一般的なシグネチャ
一般的なシグネチャ
- ローカル MLX/vLLM スタイルのサーバーで
model_not_found→baseUrlに/v1が含まれていること、/v1/chat/completionsバックエンドではapiが"openai-completions"であること、models.providers.<provider>.models[].idが素のプロバイダーローカル ID であることを確認します。選択時は一度だけプロバイダープレフィックスを付けます。例:mlx/mlx-community/Qwen3-30B-A3B-6bit。カタログエントリはmlx-community/Qwen3-30B-A3B-6bitのままにします。 messages[...].content: invalid type: sequence, expected a string→ バックエンドが構造化された Chat Completions コンテンツパーツを拒否しています。修正:models.providers.<provider>.models[].compat.requiresStringContent: trueを設定します。validation.keysまたは["role","content"]のような許可済みメッセージキー → バックエンドが Chat Completions メッセージ上の OpenAI スタイルの再生メタデータを拒否しています。修正:models.providers.<provider>.models[].compat.strictMessageKeys: trueを設定します。incomplete turn detected ... stopReason=stop payloads=0→ バックエンドは Chat Completions リクエストを完了しましたが、そのターンでユーザーに表示されるアシスタントテキストを返しませんでした。OpenClaw は再生しても安全な空の OpenAI 互換ターンを一度だけ再試行します。失敗が継続する場合、通常はバックエンドが空/非テキストのコンテンツを出力しているか、最終回答テキストを抑制しています。- 小さな直接リクエストは成功するが、OpenClaw エージェント実行がバックエンド/モデルのクラッシュで失敗する（たとえば一部の
inferrsビルド上の Gemma）→ OpenClaw トランスポートはすでに正しい可能性が高く、バックエンドがより大きなエージェントランタイムプロンプト形状で失敗しています。 - ツールを無効化すると失敗が減るが、消えない → ツールスキーマは負荷要因の一部でしたが、残る問題は依然として上流モデル/サーバーの容量またはバックエンドのバグです。
修正オプション
修正オプション
- 文字列専用の Chat Completions バックエンドには
compat.requiresStringContent: trueを設定します。 - 各メッセージで
roleとcontentのみを受け付ける厳格な Chat Completions バックエンドにはcompat.strictMessageKeys: trueを設定します。 - OpenClaw のツールスキーマ面を安定して処理できないモデル/バックエンドには
compat.supportsTools: falseを設定します。 - 可能な範囲でプロンプト負荷を下げます。より小さいワークスペースブートストラップ、短いセッション履歴、軽量なローカルモデル、またはより強い長いコンテキスト対応を持つバックエンドを使用します。
- 小さな直接リクエストが通り続ける一方で、OpenClaw エージェントターンがバックエンド内でまだクラッシュする場合は、上流サーバー/モデルの制限として扱い、受け入れられたペイロード形状とともにそこで再現手順を報告します。
返信がない
チャンネルが起動しているのに何も応答しない場合は、何かを再接続する前にルーティングとポリシーを確認します。- DM 送信者の Pairing が保留中。
- グループメンションのゲート設定（
requireMention、mentionPatterns）。 - チャンネル/グループの許可リストの不一致。
drop guild message (mention required→ メンションされるまでグループメッセージは無視される。pairing request→ 送信者に承認が必要。blocked/allowlist→ 送信者/チャンネルがポリシーでフィルターされた。
ダッシュボード制御 UI の接続性
ダッシュボード/制御 UI が接続できない場合は、URL、認証モード、セキュアコンテキストの前提を検証します。- 正しいプローブ URL とダッシュボード URL。
- クライアントと Gateway の間の認証モード/トークンの不一致。
- デバイス ID が必要な場所で HTTP を使用している。
接続/認証シグネチャ
接続/認証シグネチャ
認証詳細コードのクイックマップ
失敗したconnect レスポンスの error.details.code を使って、次の操作を選択します。
| 詳細コード | 意味 | 推奨される対応 |
|---|---|---|
AUTH_TOKEN_MISSING | クライアントが必要な共有トークンを送信しませんでした。 | クライアントにトークンを貼り付けるか設定し、再試行します。ダッシュボードパスの場合: openclaw config get gateway.auth.token を実行してから Control UI 設定に貼り付けます。 |
AUTH_TOKEN_MISMATCH | 共有トークンが Gateway 認証トークンと一致しませんでした。 | canRetryWithDeviceToken=true の場合、信頼済みの再試行を 1 回許可します。キャッシュ済みトークンの再試行では保存済みの承認済みスコープが再利用されます。明示的な deviceToken / scopes 呼び出し元は要求されたスコープを維持します。それでも失敗する場合は、トークンドリフト復旧チェックリストを実行します。 |
AUTH_DEVICE_TOKEN_MISMATCH | キャッシュ済みのデバイスごとのトークンが古いか、取り消されています。 | devices CLI を使ってデバイストークンをローテーションまたは再承認し、再接続します。 |
AUTH_SCOPE_MISMATCH | デバイストークンは有効ですが、承認済みのロール/スコープがこの接続要求をカバーしていません。 | デバイスを再ペアリングするか、要求されたスコープ契約を承認します。これを共有トークンのドリフトとして扱わないでください。 |
PAIRING_REQUIRED | デバイス ID に承認が必要です。not-paired、scope-upgrade、role-upgrade、または metadata-upgrade について error.details.reason を確認し、存在する場合は requestId / remediationHint を使用します。 | 保留中の要求を承認します: openclaw devices list の後に openclaw devices approve <requestId> を実行します。スコープ/ロールのアップグレードは、要求されたアクセスを確認した後、同じフローを使用します。 |
共有 Gateway トークン/パスワードで認証された直接 loopback バックエンド RPC は、CLI のペアリング済みデバイススコープベースラインに依存すべきではありません。サブエージェントやその他の内部呼び出しが
scope-upgrade でまだ失敗する場合は、呼び出し元が client.id: "gateway-client" と client.mode: "backend" を使用しており、明示的な deviceIdentity またはデバイストークンを強制していないことを確認してください。openclaw devices rotate / revoke / remove が予期せず拒否される場合:
- ペアリング済みデバイストークンセッションは、呼び出し元が
operator.adminも持っていない限り、自身のデバイスのみ管理できます openclaw devices rotate --scope ...は、呼び出し元セッションがすでに保持している operator スコープのみ要求できます
- 設定 (Gateway 認証モード)
- Control UI
- デバイス
- リモートアクセス
- 信頼済みプロキシ認証
Gateway サービスが実行されていない
サービスはインストール済みだが、プロセスが起動したままにならない場合に使用します。- 終了ヒント付きの
Runtime: stopped。 - サービス設定の不一致 (
Config (cli)とConfig (service))。 - ポート/リスナーの競合。
--deep使用時の余分な launchd/systemd/schtasks インストール。Other gateway-like services detected (best effort)のクリーンアップヒント。
一般的なシグネチャ
一般的なシグネチャ
Gateway start blocked: set gateway.mode=localまたはexisting config is missing gateway.mode→ ローカル Gateway モードが有効になっていないか、設定ファイルが上書きされてgateway.modeが失われています。修正: 設定でgateway.mode="local"を設定するか、openclaw onboard --mode local/openclaw setupを再実行して期待されるローカルモード設定を再スタンプします。Podman 経由で OpenClaw を実行している場合、デフォルトの設定パスは~/.openclaw/openclaw.jsonです。refusing to bind gateway ... without auth→ 有効な Gateway 認証パス (トークン/パスワード、または設定されている場合は信頼済みプロキシ) なしで非 loopback にバインドしようとしています。another gateway instance is already listening/EADDRINUSE→ ポート競合です。Other gateway-like services detected (best effort)→ 古い、または並列の launchd/systemd/schtasks ユニットが存在します。ほとんどのセットアップでは、1 台のマシンにつき Gateway は 1 つにすべきです。複数必要な場合は、ポート + 設定/状態/ワークスペースを分離します。/gateway#multiple-gateways-same-host を参照してください。- doctor からの
System-level OpenClaw gateway service detected→ ユーザーレベルのサービスがない一方で、systemd システムユニットが存在します。doctor にユーザーサービスをインストールさせる前に重複を削除または無効化するか、システムユニットが意図した supervisor である場合はOPENCLAW_SERVICE_REPAIR_POLICY=externalを設定します。 Gateway service port does not match current gateway config→ インストール済み supervisor がまだ古い--portを固定しています。openclaw doctor --fixまたはopenclaw gateway install --forceを実行してから、Gateway サービスを再起動します。
Gateway が無効な設定を拒否した
Gateway 起動がInvalid config で失敗する場合、またはホットリロードログに
無効な編集をスキップしたと表示される場合に使用します。
Invalid config at ...config reload skipped (invalid config): ...Config write rejected: ...- アクティブな設定の横にあるタイムスタンプ付きの
openclaw.json.rejected.*ファイル doctor --fixが壊れた直接編集を修復した場合の、タイムスタンプ付きのopenclaw.json.clobbered.*ファイル
何が起きたか
何が起きたか
- 起動、ホットリロード、または OpenClaw 所有の書き込み中に設定が検証に通りませんでした。
- Gateway 起動は
openclaw.jsonを書き換えるのではなく、フェイルクローズします。 - ホットリロードは無効な外部編集をスキップし、現在のランタイム設定をアクティブに保ちます。
- OpenClaw 所有の書き込みは、コミット前に無効/破壊的なペイロードを拒否し、
.rejected.*を保存します。 openclaw doctor --fixが修復を担当します。非 JSON プレフィックスを削除したり、拒否されたペイロードを.clobbered.*として保持しながら last-known-good コピーを復元したりできます。
検査と修復
検査と修復
一般的なシグネチャ
一般的なシグネチャ
.clobbered.*が存在する → doctor がアクティブな設定を修復する間、壊れた外部編集を保持しました。.rejected.*が存在する → OpenClaw 所有の設定書き込みが、コミット前にスキーマまたは clobber チェックに失敗しました。Config write rejected:→ 書き込みが必要な形状を削除する、ファイルを急激に縮小する、または無効な設定を永続化しようとしました。config reload skipped (invalid config):→ 直接編集が検証に失敗し、実行中の Gateway に無視されました。Invalid config at ...→ Gateway サービスが起動する前に起動が失敗しました。missing-meta-vs-last-good、gateway-mode-missing-vs-last-good、またはsize-drop-vs-last-good:*→ OpenClaw 所有の書き込みが、last-known-good バックアップと比べてフィールドまたはサイズを失ったため拒否されました。Config last-known-good promotion skipped→ 候補に***などの伏せ字のシークレットプレースホルダーが含まれていました。
修正オプション
修正オプション
openclaw doctor --fixを実行して、doctor にプレフィックス付き/clobbered 設定を修復させるか、last-known-good を復元させます。.clobbered.*または.rejected.*から意図したキーのみをコピーし、openclaw config setまたはconfig.patchで適用します。- 再起動前に
openclaw config validateを実行します。 - 手動で編集する場合は、変更したい部分オブジェクトだけでなく、完全な JSON5 設定を保持してください。
Gateway probe 警告
openclaw gateway probe が何かに到達するものの、警告ブロックも表示する場合に使用します。
- JSON 出力内の
warnings[].codeとprimaryTargetId。 - 警告が SSH フォールバック、複数の Gateway、欠落したスコープ、または未解決の認証参照のどれに関するものか。
SSH tunnel failed to start; falling back to direct probes.→ SSH セットアップに失敗しましたが、コマンドは引き続き直接設定済み/loopback ターゲットを試行しました。multiple reachable gateways detected→ 複数のターゲットが応答しました。通常、これは意図的なマルチ Gateway セットアップ、または古い/重複したリスナーを意味します。Read-probe diagnostics are limited by gateway scopes (missing operator.read)→ 接続は成功しましたが、詳細 RPC はスコープ制限されています。デバイス ID をペアリングするか、operator.readを持つ認証情報を使用してください。Gateway accepted the WebSocket connection, but follow-up read diagnostics failed→ 接続は成功しましたが、完全な診断 RPC セットがタイムアウトまたは失敗しました。これは診断が劣化した到達可能な Gateway として扱い、--json出力のconnect.okとconnect.rpcOkを比較してください。Capability: pairing-pendingまたはgateway closed (1008): pairing required→ Gateway は応答しましたが、このクライアントは通常の operator アクセスの前にまだペアリング/承認が必要です。- 未解決の
gateway.auth.*/gateway.remote.*SecretRef 警告テキスト → 失敗したターゲットに対して、このコマンドパスでは認証素材を利用できませんでした。
チャネルは接続済みだが、メッセージが流れない
チャネル状態が接続済みなのにメッセージフローが止まっている場合は、ポリシー、権限、チャネル固有の配送ルールに注目してください。- DM ポリシー（
pairing、allowlist、open、disabled）。 - グループの許可リストとメンション要件。
- チャネル API の権限/スコープ不足。
mention required→ グループメンションポリシーによりメッセージが無視されています。pairing/ 承認待ちの痕跡 → 送信者が承認されていません。missing_scope、not_in_channel、Forbidden、401/403→ チャネル認証/権限の問題です。
Cron と Heartbeat の配送
Cron または Heartbeat が実行されなかった、または配送されなかった場合は、まずスケジューラーの状態を確認し、次に配送先を確認してください。- Cron が有効で、次回の起動が存在すること。
- ジョブ実行履歴の状態（
ok、skipped、error）。 - Heartbeat のスキップ理由（
quiet-hours、requests-in-flight、cron-in-progress、lanes-busy、alerts-disabled、empty-heartbeat-file、no-tasks-due）。
よくある兆候
よくある兆候
cron: scheduler disabled; jobs will not run automatically→ cron が無効です。cron: timer tick failed→ スケジューラーの tick に失敗しました。ファイル/ログ/ランタイムエラーを確認してください。heartbeat skippedでreason=quiet-hours→ アクティブ時間帯の外です。heartbeat skippedでreason=empty-heartbeat-file→HEARTBEAT.mdは存在しますが、空行または Markdown ヘッダーのみを含むため、OpenClaw はモデル呼び出しをスキップします。heartbeat skippedでreason=no-tasks-due→HEARTBEAT.mdにtasks:ブロックがありますが、この tick で期限を迎えるタスクがありません。heartbeat: unknown accountId→ Heartbeat 配送先のアカウント ID が無効です。heartbeat skippedでreason=dm-blocked→ Heartbeat の送信先が DM 形式の宛先に解決されましたが、agents.defaults.heartbeat.directPolicy（またはエージェント単位の上書き）がblockに設定されています。
Node はペアリング済みだが、ツールが失敗する
Node がペアリング済みでもツールが失敗する場合は、フォアグラウンド、権限、承認状態を切り分けてください。- Node がオンラインで、想定される機能を持っていること。
- カメラ/マイク/位置情報/画面に対する OS 権限の付与。
- Exec 承認と許可リストの状態。
NODE_BACKGROUND_UNAVAILABLE→ Node アプリをフォアグラウンドにする必要があります。*_PERMISSION_REQUIRED/LOCATION_PERMISSION_REQUIRED→ OS 権限が不足しています。SYSTEM_RUN_DENIED: approval required→ exec 承認が保留中です。SYSTEM_RUN_DENIED: allowlist miss→ コマンドが許可リストによりブロックされています。
ブラウザツールが失敗する
Gateway 自体は正常なのにブラウザツールのアクションが失敗する場合に使用します。plugins.allowが設定され、browserを含んでいるか。- 有効なブラウザ実行ファイルパス。
- CDP プロファイルへの到達性。
existing-session/userプロファイル向けのローカル Chrome の可用性。
Plugin / 実行ファイルの兆候
Plugin / 実行ファイルの兆候
unknown command "browser"またはunknown command 'browser'→ バンドルされたブラウザ plugin がplugins.allowにより除外されています。browser.enabled=trueなのにブラウザツールがない / 利用できない →plugins.allowがbrowserを除外しているため、plugin が読み込まれていません。Failed to start Chrome CDP on port→ ブラウザプロセスの起動に失敗しました。browser.executablePath not found→ 設定されたパスが無効です。browser.cdpUrl must be http(s) or ws(s)→ 設定された CDP URL がfile:やftp:などの未対応スキームを使用しています。browser.cdpUrl has invalid port→ 設定された CDP URL のポートが不正または範囲外です。Playwright is not available in this gateway build; '<feature>' is unsupported.→ 現在の Gateway インストールには、コアブラウザランタイム依存関係がありません。OpenClaw を再インストールまたは更新してから、Gateway を再起動してください。ARIA スナップショットと基本的なページスクリーンショットは引き続き動作しますが、ナビゲーション、AI スナップショット、CSS セレクター要素スクリーンショット、PDF エクスポートは利用できないままです。
Chrome MCP / 既存セッションの兆候
Chrome MCP / 既存セッションの兆候
Could not find DevToolsActivePort for chrome→ Chrome MCP 既存セッションは、選択されたブラウザデータディレクトリにまだアタッチできませんでした。ブラウザの検査ページを開き、リモートデバッグを有効にし、ブラウザを開いたままにして、最初のアタッチプロンプトを承認してから再試行してください。サインイン状態が不要な場合は、管理対象のopenclawプロファイルを優先してください。No Chrome tabs found for profile="user"→ Chrome MCP アタッチプロファイルに、開いているローカル Chrome タブがありません。Remote CDP for profile "<name>" is not reachable→ 設定されたリモート CDP エンドポイントに Gateway ホストから到達できません。Browser attachOnly is enabled ... not reachableまたはBrowser attachOnly is enabled and CDP websocket ... is not reachable→ アタッチ専用プロファイルに到達可能なターゲットがないか、HTTP エンドポイントは応答したものの CDP WebSocket を開けませんでした。
要素 / スクリーンショット / アップロードの兆候
要素 / スクリーンショット / アップロードの兆候
fullPage is not supported for element screenshots→ スクリーンショット要求で--full-pageと--refまたは--elementが混在しています。element screenshots are not supported for existing-session profiles; use ref from snapshot.→ Chrome MCP /existing-sessionのスクリーンショット呼び出しでは、CSS--elementではなく、ページキャプチャまたはスナップショット--refを使用する必要があります。existing-session file uploads do not support element selectors; use ref/inputRef.→ Chrome MCP アップロードフックには、CSS セレクターではなくスナップショット参照が必要です。existing-session file uploads currently support one file at a time.→ Chrome MCP プロファイルでは、呼び出しごとに 1 つのアップロードを送信してください。existing-session dialog handling does not support timeoutMs.→ Chrome MCP プロファイル上のダイアログフックは、タイムアウト上書きをサポートしていません。existing-session type does not support timeoutMs overrides.→profile="user"/ Chrome MCP 既存セッションプロファイルのact:typeではtimeoutMsを省略するか、カスタムタイムアウトが必要な場合は管理対象/CDP ブラウザプロファイルを使用してください。existing-session evaluate does not support timeoutMs overrides.→profile="user"/ Chrome MCP 既存セッションプロファイルのact:evaluateではtimeoutMsを省略するか、カスタムタイムアウトが必要な場合は管理対象/CDP ブラウザプロファイルを使用してください。response body is not supported for existing-session profiles yet.→responsebodyには引き続き、管理対象ブラウザまたは raw CDP プロファイルが必要です。- アタッチ専用またはリモート CDP プロファイルで viewport / ダークモード / ロケール / オフライン上書きが古い → Gateway 全体を再起動せずにアクティブな制御セッションを閉じ、Playwright/CDP エミュレーション状態を解放するには、
openclaw browser stop --browser-profile <name>を実行してください。
アップグレード後に何かが突然壊れた場合
アップグレード後の破損の多くは、設定のずれ、またはより厳格なデフォルトが現在適用されていることが原因です。1. 認証と URL 上書きの挙動が変更された
1. 認証と URL 上書きの挙動が変更された
gateway.mode=remoteの場合、ローカルサービスは正常でも、CLI 呼び出しがリモートを対象にしている可能性があります。- 明示的な
--url呼び出しは、保存された認証情報にフォールバックしません。
gateway connect failed:→ URL の対象が間違っています。unauthorized→ エンドポイントには到達できますが、認証が間違っています。
2. バインドと認証のガードレールがより厳格になった
2. バインドと認証のガードレールがより厳格になった
- 非ループバックバインド（
lan、tailnet、custom）には、有効な Gateway 認証パスが必要です。共有トークン/パスワード認証、または正しく設定された非ループバックtrusted-proxyデプロイです。 gateway.tokenのような古いキーはgateway.auth.tokenの代わりにはなりません。
refusing to bind gateway ... without auth→ 有効な Gateway 認証パスなしで非ループバックにバインドしています。- ランタイムは実行中なのに
Connectivity probe: failed→ Gateway は動作していますが、現在の認証/URL ではアクセスできません。
3. ペアリングとデバイス ID 状態が変更された
3. ペアリングとデバイス ID 状態が変更された
- ダッシュボード/Node の保留中のデバイス承認。
- ポリシーまたは ID の変更後の保留中の DM ペアリング承認。
device identity required→ デバイス認証が満たされていません。pairing required→ 送信者/デバイスを承認する必要があります。