トラブルシューティング

• ローカル 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 トランスポートはすでに正しい可能性が高く、バックエンドがより大きなエージェントランタイムプロンプト形状で失敗しています。
• ツールを無効化すると失敗が減るが、消えない → ツールスキーマは負荷要因の一部でしたが、残る問題は依然として上流モデル/サーバーの容量またはバックエンドのバグです。

1. 文字列専用の Chat Completions バックエンドには compat.requiresStringContent: true を設定します。
2. 各メッセージで role と content のみを受け付ける厳格な Chat Completions バックエンドには compat.strictMessageKeys: true を設定します。
3. OpenClaw のツールスキーマ面を安定して処理できないモデル/バックエンドには compat.supportsTools: false を設定します。
4. 可能な範囲でプロンプト負荷を下げます。より小さいワークスペースブートストラップ、短いセッション履歴、軽量なローカルモデル、またはより強い長いコンテキスト対応を持つバックエンドを使用します。
5. 小さな直接リクエストが通り続ける一方で、OpenClaw エージェントターンがバックエンド内でまだクラッシュする場合は、上流サーバー/モデルの制限として扱い、受け入れられたペイロード形状とともにそこで再現手順を報告します。

• device identity required → 非セキュアコンテキスト、またはデバイス認証の欠落。
• origin not allowed → ブラウザーの Origin が gateway.controlUi.allowedOrigins に含まれていない（または明示的な許可リストなしに非ループバックのブラウザーオリジンから接続している）。
• device nonce required / device nonce mismatch → クライアントがチャレンジベースのデバイス認証フロー（connect.challenge + device.nonce）を完了していない。
• device signature invalid / device signature expired → クライアントが現在のハンドシェイクに対して誤ったペイロード（または古いタイムスタンプ）に署名した。
• AUTH_TOKEN_MISMATCH かつ canRetryWithDeviceToken=true → クライアントはキャッシュ済みデバイストークンで信頼済み再試行を一度だけ実行できる。
• そのキャッシュ済みトークン再試行は、ペアリング済みデバイストークンとともに保存されたキャッシュ済みスコープセットを再利用する。明示的な deviceToken / 明示的な scopes 呼び出し元は、代わりに要求したスコープセットを保持する。
• AUTH_SCOPE_MISMATCH → デバイストークンは認識されたが、その承認済みスコープがこの接続リクエストをカバーしていない。共有 Gateway トークンをローテーションするのではなく、再ペアリングするか、要求されたスコープ契約を承認する。
• その再試行パスの外では、接続認証の優先順位は、明示的な共有トークン/パスワードが最初、次に明示的な deviceToken、次に保存済みデバイストークン、最後にブートストラップトークン。
• 非同期 Tailscale Serve Control UI パスでは、同じ {scope, ip} に対する失敗試行は、リミッターが失敗を記録する前に直列化される。そのため、同じクライアントからの不正な同時再試行が 2 件ある場合、2 件の単純な不一致ではなく、2 回目の試行で retry later が表面化することがある。
• ブラウザーオリジンのループバッククライアントから too many failed authentication attempts (retry later) → 同じ正規化済み Origin からの失敗の繰り返しは一時的にロックアウトされる。別の localhost オリジンは別のバケットを使用する。
• その再試行後も unauthorized が繰り返される → 共有トークン/デバイストークンのずれ。必要に応じてトークン設定を更新し、デバイストークンを再承認/ローテーションする。
• gateway connect failed: → ホスト/ポート/URL ターゲットが誤っている。

• 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 サービスを再起動します。

• 起動、ホットリロード、または 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 → 候補に *** などの伏せ字のシークレットプレースホルダーが含まれていました。

1. openclaw doctor --fix を実行して、doctor にプレフィックス付き/clobbered 設定を修復させるか、last-known-good を復元させます。
2. .clobbered.* または .rejected.* から意図したキーのみをコピーし、openclaw config set または config.patch で適用します。
3. 再起動前に openclaw config validate を実行します。
4. 手動で編集する場合は、変更したい部分オブジェクトだけでなく、完全な JSON5 設定を保持してください。

• 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 に設定されています。

• 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 エクスポートは利用できないままです。

• 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> を実行してください。

openclaw gateway statusopenclaw config get gateway.modeopenclaw config get gateway.remote.urlopenclaw config get gateway.auth.mode

確認すること:

• gateway.mode=remote の場合、ローカルサービスは正常でも、CLI 呼び出しがリモートを対象にしている可能性があります。
• 明示的な --url 呼び出しは、保存された認証情報にフォールバックしません。

よくある兆候:

• gateway connect failed: → URL の対象が間違っています。
• unauthorized → エンドポイントには到達できますが、認証が間違っています。

openclaw config get gateway.bindopenclaw config get gateway.auth.modeopenclaw config get gateway.auth.tokenopenclaw gateway statusopenclaw logs --follow

確認すること:

• 非ループバックバインド（lan、tailnet、custom）には、有効な Gateway 認証パスが必要です。共有トークン/パスワード認証、または正しく設定された非ループバック trusted-proxy デプロイです。
• gateway.token のような古いキーは gateway.auth.token の代わりにはなりません。

よくある兆候:

• refusing to bind gateway ... without auth → 有効な Gateway 認証パスなしで非ループバックにバインドしています。
• ランタイムは実行中なのに Connectivity probe: failed → Gateway は動作していますが、現在の認証/URL ではアクセスできません。

openclaw devices listopenclaw pairing list --channel <channel> [--account <id>]openclaw logs --followopenclaw doctor

確認すること:

• ダッシュボード/Node の保留中のデバイス承認。
• ポリシーまたは ID の変更後の保留中の DM ペアリング承認。

よくある兆候:

• device identity required → デバイス認証が満たされていません。
• pairing required → 送信者/デバイスを承認する必要があります。