トラブルシューティング

• ローカル 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 を設定します。
• incomplete turn detected ... stopReason=stop payloads=0 → バックエンドは Chat Completions リクエストを完了したものの、そのターンでユーザーに表示されるアシスタントテキストを返していません。OpenClaw はリプレイ安全な空の OpenAI 互換ターンを 1 回再試行します。失敗が続く場合は通常、バックエンドが空/非テキストコンテンツを出力しているか、最終回答テキストを抑制していることを意味します。
• 直接の小さなリクエストは成功するが、OpenClaw エージェント実行がバックエンド/モデルクラッシュで失敗する（一部の inferrs ビルド上の Gemma など）→ OpenClaw トランスポートはすでに正しい可能性が高く、バックエンドがより大きなエージェントランタイムプロンプト形状で失敗しています。
• ツールを無効化すると失敗が減るが消えない → ツールスキーマも負荷の一部でしたが、残る問題は依然として上流のモデル/サーバー容量またはバックエンドのバグです。

1. 文字列のみの Chat Completions バックエンドには compat.requiresStringContent: true を設定します。
2. OpenClaw のツールスキーマ面を安定して処理できないモデル/バックエンドには compat.supportsTools: false を設定します。
3. 可能な範囲でプロンプト負荷を下げます。より小さなワークスペースブートストラップ、より短いセッション履歴、より軽いローカルモデル、または長いコンテキストのサポートが強いバックエンドを使用します。
4. 直接の小さなリクエストが成功し続ける一方で、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 → クライアントはキャッシュ済みデバイストークンを使って信頼された再試行を 1 回実行できます。
• そのキャッシュ済みトークンの再試行では、ペアリング済みデバイストークンとともに保存されたキャッシュ済みスコープセットを再利用します。明示的な deviceToken / 明示的な scopes 呼び出し元は、代わりに要求したスコープセットを保持します。
• その再試行パス以外では、接続認証の優先順位は、明示的な共有トークン/パスワードが最初、次に明示的な 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 認証パス（トークン/パスワード、または設定済みの場合は trusted-proxy）なしの非 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 にユーザーサービスのインストールを許可する前に重複を削除または無効化するか、そのシステムユニットが意図したスーパーバイザーである場合は OPENCLAW_SERVICE_REPAIR_POLICY=external を設定します。
• Gateway service port does not match current gateway config → インストール済みのスーパーバイザーがまだ古い --port を固定しています。openclaw doctor --fix または openclaw gateway install --force を実行し、その後 Gateway サービスを再起動します。

• 起動、ホットリロード、または OpenClaw 所有の書き込み中に設定が検証に通りませんでした。
• Gateway 起動は openclaw.json を書き換える代わりにフェイルクローズします。
• ホットリロードは無効な外部編集をスキップし、現在のランタイム設定をアクティブなままにします。
• OpenClaw 所有の書き込みは、コミット前に無効/破壊的なペイロードを拒否し、.rejected.* を保存します。
• openclaw doctor --fix が修復を担当します。非 JSON プレフィックスを削除したり、拒否されたペイロードを .clobbered.* として保持しながら最後に正常だったコピーを復元したりできます。

CONFIG="$(openclaw config file)"
ls -lt "$CONFIG".clobbered.* "$CONFIG".rejected.* 2>/dev/null | head
diff -u "$CONFIG" "$(ls -t "$CONFIG".clobbered.* 2>/dev/null | head -n 1)"
openclaw config validate
openclaw doctor

• .clobbered.* が存在する → doctor がアクティブ設定を修復する間、壊れた外部編集を保持しました。
• .rejected.* が存在する → OpenClaw 所有の設定書き込みが、コミット前にスキーマまたは上書きチェックに失敗しました。
• 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 所有の書き込みが、最後に正常だったバックアップと比較してフィールドまたはサイズを失ったため拒否されました。
• Config last-known-good promotion skipped → 候補に *** などのマスク済みシークレットプレースホルダーが含まれていました。

1. openclaw doctor --fix を実行し、doctor にプレフィックス付き/上書きされた設定の修復、または最後に正常だった設定の復元を任せます。
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 の existing-session は、選択されたブラウザデータディレクトリにまだアタッチできなかった。ブラウザの inspect ページを開き、リモートデバッグを有効にし、ブラウザを開いたままにし、最初のアタッチプロンプトを承認してから再試行する。サインイン状態が不要な場合は、管理対象の 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 existing-session プロファイルで act:type に timeoutMs を指定しない。カスタムタイムアウトが必要な場合は、管理対象/CDP ブラウザプロファイルを使用する。
• existing-session evaluate does not support timeoutMs overrides. → profile="user" / Chrome MCP existing-session プロファイルで act:evaluate に timeoutMs を指定しない。カスタムタイムアウトが必要な場合は、管理対象/CDP ブラウザプロファイルを使用する。
• response body is not supported for existing-session profiles yet. → responsebody にはまだ管理対象ブラウザまたは raw CDP プロファイルが必要。
• アタッチ専用またはリモート CDP プロファイルで viewport / dark-mode / locale / offline のオーバーライドが古い → Gateway 全体を再起動せずに、openclaw browser stop --browser-profile <name> を実行してアクティブな制御セッションを閉じ、Playwright/CDP エミュレーション状態を解放する。

openclaw gateway status
openclaw config get gateway.mode
openclaw config get gateway.remote.url
openclaw config get gateway.auth.mode

確認すること:

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

よくある特徴:

• gateway connect failed: → URL ターゲットが誤っている。
• unauthorized → エンドポイントには到達できるが、認証が誤っている。

openclaw config get gateway.bind
openclaw config get gateway.auth.mode
openclaw config get gateway.auth.token
openclaw gateway status
openclaw logs --follow

確認すること:

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

よくある特徴:

• refusing to bind gateway ... without auth → 有効な Gateway 認証経路なしで local loopback 以外に bind しようとしている。
• ランタイムは実行中だが Connectivity probe: failed → Gateway は稼働しているが、現在の認証/URL ではアクセスできない。

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

確認すること:

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

よくある特徴:

• device identity required → デバイス認証が満たされていない。
• pairing required → 送信者/デバイスの承認が必要。