--- read_when: - 認証プロファイルのローテーション、クールダウン、またはモデルのフォールバック動作の診断 - 認証プロファイルまたはモデルのフェイルオーバールールの更新 - セッションのモデルオーバーライドとフォールバック再試行の相互作用を理解する sidebarTitle: Model failover summary: OpenClaw が認証プロファイルをローテーションし、モデル間でフォールバックする仕組み title: モデルのフェイルオーバー x-i18n: generated_at: "2026-07-11T22:06:43Z" model: gpt-5.6 postprocess_version: locale-links-v1 provider: openai source_hash: 2da6399c8f5c6d9ab40486b553a41600a3c8eb64efa09e72784b81e42edbba61 source_path: concepts/model-failover.md workflow: 16 --- OpenClaw は障害を 2 段階で処理します。 1. 現在のプロバイダー内での **認証プロファイルのローテーション**。 2. `agents.defaults.model.fallbacks` 内の次のモデルへの **モデルフォールバック**。 ## ランタイムフロー アクティブなセッションモデルと認証プロファイルの優先設定を解決します。 現在のモデル選択と、その選択元に対するフォールバックポリシーから、モデル候補チェーンを構築します。設定済みのデフォルト、Cron ジョブのプライマリ、自動選択されたフォールバックモデルでは、設定済みのフォールバックを使用できます。ユーザーが明示的に選択したセッションモデルは厳密に適用されます。 認証プロファイルのローテーションとクールダウンのルールに従って、現在のプロバイダーを試行します。 そのプロバイダーでフェイルオーバー対象のエラーが発生し、すべての試行候補を使い切った場合は、次のモデル候補に進みます。 再試行を開始する前に、選択したフォールバックオーバーライドを永続化します。これにより、他のセッションリーダーにも、ランナーがこれから使用するものと同じプロバイダーとモデルが表示されます。永続化されたモデルオーバーライドには `modelOverrideSource: "auto"` が設定されます。 フォールバック候補が失敗した場合、その候補とまだ一致している、フォールバックが所有するセッションオーバーライドフィールドだけをロールバックします。 すべての候補が失敗した場合は、各試行の詳細と、判明している場合は最も早いクールダウン終了時刻を含む `FallbackSummaryError` をスローします。 これは意図的に「セッション全体を保存して復元する」よりも限定的です。応答ランナーがフォールバック用に永続化するのは、自身が所有するモデル選択フィールドだけです。対象は `providerOverride`、`modelOverride`、`modelOverrideSource`、`authProfileOverride`、`authProfileOverrideSource`、`authProfileOverrideCompactionCount` です。これにより、フォールバックの再試行が失敗しても、試行中に行われた手動の `/model` 変更やセッションローテーションの更新など、より新しく無関係なセッション変更が上書きされることを防ぎます。 ## 選択元ポリシー 選択元によって、フォールバックチェーンの使用可否が決まります。 - **設定済みのデフォルト**：`agents.defaults.model.primary` は `agents.defaults.model.fallbacks` を使用します。 - **エージェントのプライマリ**：`agents.list[].model` は、そのエージェントのモデルオブジェクトに独自の `fallbacks` が含まれていない限り、厳密に適用されます。厳密な動作を明示するには `fallbacks: []` を使用し、そのエージェントでモデルフォールバックを有効にするには空でないリストを使用します。 - **自動フォールバックオーバーライド**：ランタイムフォールバックは、再試行前に `providerOverride`、`modelOverride`、`modelOverrideSource: "auto"`、および選択元モデルを書き込みます。このオーバーライドにより、メッセージごとにプライマリを試すことなく、設定済みのフォールバックチェーンを引き続き進められます。ただし、OpenClaw は設定済みの選択元を 5 分ごとにプローブし（設定変更不可）、復旧するとオーバーライドを解除します。`/new`、`/reset`、`sessions.reset` も、自動設定されたオーバーライドを解除します。明示的な `heartbeat.model` を指定せずに Heartbeat を実行した場合、その選択元が現在設定されているデフォルトと一致しなくなった直接の自動オーバーライドを解除します。 - **ユーザーのセッションオーバーライド**：`/model`、モデルピッカー、`session_status(model=...)`、`sessions.patch` は `modelOverrideSource: "user"` を書き込みます。これはセッションに対する厳密な選択です。選択したプロバイダーまたはモデルが応答生成前に失敗した場合、OpenClaw は無関係な設定済みフォールバックから応答せず、失敗を報告します。 - **従来のセッションオーバーライド**：古いセッションエントリには、`modelOverrideSource` のない `modelOverride` が含まれている場合があります。OpenClaw はこれをユーザーオーバーライドとして扱うため、以前の明示的な選択が暗黙にフォールバック動作へ変換されることはありません。 - **Cron ペイロードモデル**：Cron ジョブの `payload.model` / `--model` はジョブのプライマリであり、ユーザーのセッションオーバーライドではありません。ジョブに `payload.fallbacks` が指定されていない限り、設定済みのフォールバックを使用します。`payload.fallbacks: []` を指定すると、Cron の実行が厳密になります。 OpenClaw は、失敗しているプライマリをターンごとに再試行しないよう、セッションおよびプライマリモデルごとに最近のプライマリプローブを記憶します。セッションがフォールバックへ移行したときに通知を表示し、選択したプライマリに戻ったときにも別の通知を表示します。固定されたフォールバックでのターンごとに通知を繰り返すことはありません。 ## 認証失敗スキップキャッシュ デフォルトでは、新しい各ターンで既存のフォールバック再試行動作が維持されます。OpenClaw は、直近に `auth` または `auth_permanent` で失敗した非プライマリ候補も含め、設定済みの各フォールバック候補を再試行します。 認証失敗の繰り返しを抑制するには、次を設定して有効にします。 ```bash OPENCLAW_FALLBACK_SKIP_TTL_MS=60000 ``` 有効にすると、非プライマリのフォールバック候補で認証クラスの失敗が発生した後、OpenClaw はセッション ID、プロバイダー、モデルをキーとして、メモリ内かつセッション単位のスキップマーカーを記録します。プライマリ候補は決してスキップされないため、ユーザーが明示的にモデルを選択した場合は、実際の認証エラーが引き続き表示されます。このキャッシュはプロセスローカルであり、Gateway の再起動時に消去されます。 値はミリ秒単位の TTL です。`0` または未設定の場合、キャッシュは無効です。正の値は 1 秒から 10 分の範囲に制限されます。 ## ユーザーに表示されるフォールバック通知 セッションが自動選択されたフォールバックへ移行すると、OpenClaw は同じ応答サーフェスにステータス通知を送信します。 ```text ↪️ モデルフォールバック：（選択済み 、） ``` 後続のプローブが成功し、セッションが選択済みのプライマリへ戻ると、OpenClaw は次を送信します。 ```text ↪️ モデルフォールバック解除：（以前は ） ``` これらの通知は運用メッセージであり、アシスタントのコンテンツではありません。可能な場合は副作用のみのターンも含め、状態変更ごとに 1 回配信されますが、固定されたフォールバックでのターンでは繰り返されません。配信では通常の送信元応答抑制を回避し、スレッド対応チャンネルにおける最初のアシスタント応答枠を消費せず、テキスト読み上げおよびコミットメント抽出の対象にもなりません。 ## 認証ストレージ（キー + OAuth） OpenClaw は、API キーと OAuth トークンの両方に **認証プロファイル**を使用します。 - シークレットおよびランタイムの認証ルーティング状態は `~/.openclaw/agents//agent/openclaw-agent.sqlite` に保存されます。 - 設定の `auth.profiles` / `auth.order` は **メタデータとルーティング専用**です（シークレットは含みません）。 - インポート専用の従来の OAuth ファイル：`~/.openclaw/credentials/oauth.json`（初回使用時にエージェント単位の認証ストアへインポートされます）。 - 従来の `auth-profiles.json`、`auth-state.json`、エージェント単位の `auth.json` ファイルは、`openclaw doctor --fix` によってインポートされます。 詳細：[OAuth](/ja-JP/concepts/oauth) 認証情報の種類： - `type: "api_key"` → `{ provider, key }` - `type: "oauth"` → `{ provider, access, refresh, expires, email? }`（一部のプロバイダーでは `projectId` / `enterpriseUrl` も含む） - `type: "token"` → 静的なベアラー形式のトークン。任意で有効期限を設定できます。OpenClaw はこれを更新しません（`aws-sdk` などの認証情報チェーン方式で使用されます） ## プロファイル ID OAuth ログインでは、複数のアカウントを共存させるために個別のプロファイルが作成されます。 - デフォルト：メールアドレスを取得できない場合は `provider:default`。 - メールアドレス付き OAuth：`provider:`（例：`google-antigravity:user@gmail.com`）。 プロファイルは、エージェント単位の `openclaw-agent.sqlite` 認証プロファイルストアに保存されます。 ## ローテーション順序 プロバイダーに複数のプロファイルがある場合、OpenClaw は次の順序で選択します。 `auth.order[provider]`（設定されている場合）。 プロバイダーで絞り込んだ `auth.profiles`。 そのプロバイダーに対する、エージェント単位の SQLite 認証プロファイルエントリ。 明示的な順序が設定されていない場合、OpenClaw はラウンドロビン順序を使用します。 - **プライマリキー：** プロファイルの種類（**OAuth、静的トークン、API キー**の順）。 - **セカンダリキー：** `usageStats.lastUsed`（種類ごとに古いものから）。 - **クールダウン中または無効なプロファイル**は末尾へ移動し、終了時刻が早い順に並べられます。 ### セッション固定性（キャッシュ効率を重視） OpenClaw は、プロバイダーのキャッシュをウォーム状態に保つため、**選択した認証プロファイルをセッションごとに固定**します。リクエストごとにはローテーション**しません**。固定されたプロファイルは、次のいずれかが発生するまで再利用されます。 - セッションがリセットされた（`/new` / `/reset`） - Compaction が完了した（Compaction カウントが増加） - プロファイルがクールダウン中または無効である `/model …@` による手動選択では、そのセッションに **ユーザーオーバーライド**が設定され、新しいセッションが開始されるまで自動ローテーションされません。 セッションルーターによって選択された自動固定プロファイルは、**優先設定**として扱われます。最初に試行されますが、レート制限またはタイムアウト時には、OpenClaw が別のプロファイルへローテーションする場合があります。元のプロファイルが再び利用可能になると、選択済みのモデルやランタイムを変更することなく、新しい実行で再度そのプロファイルを優先できます。ユーザーが固定したプロファイルは、そのプロファイルにロックされたままです。失敗し、モデルフォールバックが設定されている場合、OpenClaw はプロファイルを切り替えずに次のモデルへ進みます。 ### OpenAI Codex サブスクリプションと API キーのバックアップ OpenAI エージェントモデルでは、認証とランタイムは別々です。`openai/gpt-*` は Codex ハーネス上で動作したまま、認証は Codex サブスクリプションプロファイルと OpenAI API キーのバックアップとの間でローテーションできます。 ユーザー向けの順序には `auth.order.openai` を使用します。 ```json5 { auth: { order: { openai: ["openai:user@example.com", "openai:api-key-backup"], }, }, } ``` ChatGPT/Codex OAuth プロファイルと OpenAI API キープロファイルの両方に `openai:*` を使用します。サブスクリプションが Codex の使用量上限に達すると、Codex から正確なリセット時刻が提供された場合、OpenClaw はその時刻を記録し、順序内の次の認証プロファイルを試行し、実行を Codex ハーネス内に維持します。リセット時刻を過ぎると、サブスクリプションプロファイルが再び使用可能になり、次回の自動選択でそのプロファイルへ戻ることができます。 そのセッションで 1 つのアカウントまたはキーを強制的に使用したい場合にのみ、ユーザー固定プロファイルを使用してください。ユーザー固定プロファイルは意図的に厳密であり、暗黙に別のプロファイルへ切り替わることはありません。 ## クールダウン 認証エラー、レート制限エラー、またはレート制限とみなされるタイムアウトによってプロファイルが失敗すると、OpenClaw はそのプロファイルをクールダウン状態にし、次のプロファイルへ移動します。 このレート制限区分は、単なる `429` よりも広い範囲を含みます。`Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded`、`throttled`、`resource exhausted` などのプロバイダーメッセージに加え、`weekly limit reached` や `monthly limit exhausted` など、定期的な使用量ウィンドウの上限も含まれます。 形式エラーや無効なリクエストのエラーは、通常、同じペイロードを再試行しても同じように失敗するため終端エラーとして扱われます。そのため、OpenClaw は認証プロファイルをローテーションせず、エラーを表示します。既知の再試行修復経路では、明示的に有効化できます。たとえば、Cloud Code Assist のツール呼び出し ID 検証エラーはサニタイズされ、`allowFormatRetry` ポリシーによって 1 回再試行されます。`Unhandled stop reason: error`、`stop reason: error`、`reason: error` などの OpenAI 互換の停止理由エラーは、タイムアウトまたはフェイルオーバーのシグナルとして分類されます。 送信元が既知の一時的なパターンと一致する場合、一般的なサーバーテキストもこのタイムアウト区分に分類されることがあります。たとえば、モデルランタイムのストリームラッパーが出力する単独のメッセージ `An unknown error occurred` は、すべてのプロバイダーでフェイルオーバー対象として扱われます。これは、共有モデルランタイムが、プロバイダーのストリームを具体的な詳細なしに `stopReason: "aborted"` または `stopReason: "error"` で終了したときに、このメッセージを生成するためです。`internal server error`、`unknown error, 520`、`upstream error`、`backend error` などの一時的なサーバーテキストを含む JSON の `api_error` ペイロードも、フェイルオーバー対象のタイムアウトとして扱われます。 OpenRouter 固有の一般的なアップストリームテキスト（単独の `Provider returned error` など）は、プロバイダーのコンテキストが実際に OpenRouter である場合に限り、タイムアウトとして扱われます。`LLM request failed with an unknown error.` のような一般的な内部フォールバックテキストは保守的に扱われ、それだけではフェイルオーバーを引き起こしません。 一部のプロバイダー SDK は、OpenClaw に制御を戻す前に、長い `Retry-After` 期間にわたってスリープすることがあります。Anthropic や OpenAI などの Stainless ベースの SDK では、OpenClaw はデフォルトで SDK 内部の `retry-after-ms` / `retry-after` 待機時間を 60 秒に制限し、それより長い再試行可能なレスポンスを即座に表面化させることで、このフェイルオーバーパスを実行できるようにします。上限を調整または無効化するには `OPENCLAW_SDK_RETRY_MAX_WAIT_SECONDS` を使用します。[再試行動作](/ja-JP/concepts/retry)を参照してください。 レート制限のクールダウンは、モデル単位にすることもできます。 - 失敗したモデル ID が判明している場合、OpenClaw はレート制限エラーについて `cooldownModel` を記録します。 - クールダウンの対象が別のモデルである場合、同じプロバイダーの別モデルを引き続き試行できます。 - 課金または無効化による停止期間は、引き続きすべてのモデルにわたってプロファイル全体をブロックします。 通常の（課金および永続的な認証エラー以外の）クールダウンは、プロファイルの直近のエラー回数に応じて増加します。 - 1 回目の失敗: 30 秒 - 2 回目の失敗: 1 分 - 3 回目以降の失敗: 5 分（上限） プロファイルの失敗期間が経過すると、カウンターはリセットされます（`auth.cooldowns.failureWindowHours`、デフォルトは 24）。 状態は、エージェントごとの SQLite 認証状態の `usageStats` に保存されます。 ```json { "usageStats": { "provider:profile": { "lastUsed": 1736160000000, "cooldownUntil": 1736160600000, "errorCount": 2 } } } ``` ## 課金による無効化 課金またはクレジットのエラー（たとえば「クレジット不足」や「クレジット残高が少なすぎる」）はフェイルオーバーの対象として扱われますが、通常は一時的なものではありません。短いクールダウンを設定する代わりに、OpenClaw はプロファイルを**無効**としてマークし（より長いバックオフを設定）、次のプロファイルまたはプロバイダーに切り替えます。 課金に見えるレスポンスがすべて `402` とは限らず、HTTP `402` がすべてここに分類されるわけでもありません。プロバイダーが代わりに `401` または `403` を返した場合でも、OpenClaw は明示的な課金関連テキストを課金分類として扱いますが、プロバイダー固有のマッチャーは、それを所有するプロバイダーのスコープ内に限定されます（たとえば OpenRouter の `403 Key limit exceeded`）。 一方、一時的な `402` の使用期間上限エラーや、組織またはワークスペースの利用額上限エラーは、メッセージが再試行可能に見える場合、`rate_limit` に分類されます（たとえば `weekly usage limit exhausted`、`daily limit reached, resets tomorrow`、`organization spending limit exceeded`）。これらは長期の課金無効化パスではなく、短期のクールダウンおよびフェイルオーバーパスに留まります。 確度の高い永続的な認証エラー（取り消されたキー、無効化されたキー、無効化されたワークスペース）は同様の無効化分類になりますが、一部のプロバイダーでは障害発生中に認証エラーに見えるペイロードが一時的に返されるため、課金エラーよりも大幅に早く復旧します。 状態は、エージェントごとの SQLite 認証状態に保存されます。 ```json { "usageStats": { "provider:profile": { "disabledUntil": 1736178000000, "disabledReason": "billing" } } } ``` デフォルト値（`auth.cooldowns.*`）: | キー | デフォルト | 目的 | | ----------------------------- | ---------- | --------------------------------------------------------------------------- | | `billingBackoffHours` | 5 | 課金バックオフの基本値。課金エラーごとに倍増 | | `billingMaxHours` | 24 | 課金バックオフの上限 | | `authPermanentBackoffMinutes` | 10 | 確度の高い永続的な認証エラーに対するバックオフの基本値 | | `authPermanentMaxMinutes` | 60 | そのバックオフの上限 | | `failureWindowHours` | 24 | この期間内に失敗が発生しなければ、失敗カウンターをリセット | | `overloadedProfileRotations` | 1 | 過負荷時にモデルフォールバックする前に許可される同一プロバイダー内のプロファイル切り替え回数 | | `overloadedBackoffMs` | 0 | 過負荷による切り替えを再試行する前の固定遅延 | | `rateLimitedProfileRotations` | 1 | レート制限時にモデルフォールバックする前に許可される同一プロバイダー内のプロファイル切り替え回数 | 過負荷およびレート制限エラーは、課金クールダウンよりも積極的に処理されます。デフォルトでは、OpenClaw は同じプロバイダーの認証プロファイルで 1 回再試行し、その後は待機せず、次に設定されているモデルフォールバックへ切り替えます。 ## モデルフォールバック あるプロバイダーのすべてのプロファイルが失敗した場合、OpenClaw は `agents.defaults.model.fallbacks` 内の次のモデルへ移動します。これは、認証エラー、レート制限、およびプロファイル切り替えを使い切ったタイムアウトに適用されます（その他のエラーではフォールバックを進めません）。十分な詳細が公開されないプロバイダーエラーも、フォールバック状態では正確にラベル付けされます。`empty_response` は、プロバイダーから利用可能なメッセージもステータスも返されなかったことを意味します。`no_error_details` は、プロバイダーが明示的に `Unknown error (no error details in response)` を返したことを意味します。`unclassified` は、OpenClaw が未加工のプレビューを保持したものの、まだどの分類器にも一致していないことを意味します。 `ModelNotReadyException` など、プロバイダーが使用中であることを示すシグナルは過負荷分類となり、レート制限と同じく、1 回切り替えてからフォールバックするポリシーに従います（上記のデフォルト値の表を参照）。 実行が、設定されたデフォルトのプライマリ、Cron ジョブのプライマリ、明示的なフォールバックを持つエージェントのプライマリ、または自動選択されたフォールバックオーバーライドから開始された場合、OpenClaw は対応する設定済みフォールバックチェーンを順に試行できます。明示的なフォールバックを持たないエージェントのプライマリ、およびユーザーによる明示的な選択（たとえば `/model ollama/qwen3.5:27b`、モデルピッカー、`sessions.patch`、または一時的な CLI プロバイダー／モデルオーバーライド）は厳密に扱われます。そのプロバイダーまたはモデルに到達できないか、応答を生成する前に失敗した場合、OpenClaw は無関係なフォールバックから応答するのではなく、失敗を報告します。 ### 候補チェーンのルール OpenClaw は、現在要求されている `provider/model` と設定済みのフォールバックから候補リストを構築します。 - 要求されたモデルが常に最初になります。 - 明示的に設定されたフォールバックは重複排除されますが、モデル許可リストではフィルタリングされません。これはオペレーターの明示的な意図として扱われます。 - 現在の実行が、同じプロバイダーファミリー内の設定済みフォールバックをすでに使用している場合、OpenClaw は設定済みチェーン全体を引き続き使用します。 - 明示的なフォールバックオーバーライドが指定されていない場合、要求されたモデルが別のプロバイダーを使用していても、設定済みフォールバックは設定済みプライマリより先に試行されます。 - フォールバックランナーに明示的なフォールバックオーバーライドが指定されていない場合、設定済みプライマリは末尾に追加されます。これにより、それ以前の候補を使い切った後、チェーンは通常のデフォルトに戻れます。 - 呼び出し元が `fallbacksOverride` を指定した場合、ランナーは要求されたモデルとそのオーバーライドリストだけを使用します。空のリストを指定するとモデルフォールバックが無効になり、設定済みプライマリが隠れた再試行対象として追加されることもありません。 ### フォールバックを進めるエラー - 認証エラー - レート制限およびクールダウン切れ - 過負荷およびプロバイダー使用中エラー - タイムアウト形式のフェイルオーバーエラー - 課金による無効化 - `LiveSessionModelSwitchError`。古い永続化モデルによって外側の再試行ループが発生しないよう、フェイルオーバーパスに正規化されます - 候補がまだ残っている場合の、その他の認識されないエラー - タイムアウトまたはフェイルオーバー形式ではない明示的な中止 - Compaction／再試行ロジック内に留めるべきコンテキスト超過エラー（たとえば `request_too_large`、`input token count exceeds the maximum number of input tokens`、`input exceeds the maximum number of tokens`、`input too long for the model`、`ollama error: context length exceeded`） - 候補が残っていない場合の最終的な不明エラー - Claude Fable 5 の安全性に基づく拒否。API キーを直接使用するリクエストでは、代わりに Anthropic のサーバー側フォールバックによってプロバイダーレベルで `claude-opus-4-8` に切り替えて処理します（[Anthropic](/ja-JP/providers/anthropic#safety-refusal-fallback-claude-fable-5)を参照） ### クールダウンのスキップとプローブの動作 あるプロバイダーのすべての認証プロファイルがすでにクールダウン中であっても、OpenClaw はそのプロバイダーを永久に自動スキップするわけではありません。候補ごとに判断します。 - 永続的な認証エラーでは、プロバイダー全体を即座にスキップします。 - 課金による無効化では通常スキップしますが、再起動せずに復旧できるよう、プライマリ候補をスロットル付きでプローブする場合があります。 - プライマリ候補は、プロバイダー単位のスロットルを適用したうえで、クールダウンの期限近くにプローブされる場合があります。 - 失敗が一時的に見える場合（`rate_limit`、`overloaded`、または不明）、クールダウン中でも同じプロバイダーの別フォールバックを試行できます。これは特に、レート制限がモデル単位であり、別モデルなら即座に復旧できる可能性がある場合に重要です。 - 単一のプロバイダーがプロバイダー間フォールバックを停滞させないよう、一時的なクールダウンのプローブは、フォールバック実行ごとに各プロバイダー 1 回までに制限されます。 ## セッションオーバーライドとライブモデル切り替え セッションのモデル変更は共有状態です。アクティブなランナー、`/model` コマンド、Compaction／セッション更新、およびライブセッション調整はすべて、同じセッションエントリの一部を読み書きします。 そのため、フォールバックの再試行はライブモデル切り替えと連携する必要があります。 - 明示的にユーザーが行ったモデル変更だけが、保留中のライブ切り替えとしてマークされます。これには `/model`、`session_status(model=...)`、`sessions.patch` が含まれます。 - フォールバック切り替え、Heartbeat オーバーライド、Compaction など、システムによるモデル変更は、それ自体では保留中のライブ切り替えとしてマークされません。 - ユーザーによるモデルオーバーライドは、フォールバックポリシー上の厳密な選択として扱われます。そのため、選択したプロバイダーに到達できない場合、`agents.defaults.model.fallbacks` で失敗を覆い隠さず、失敗として表面化します。 - フォールバックの再試行を開始する前に、応答ランナーは選択したフォールバックのオーバーライドフィールドをセッションエントリに永続化します。 - 自動フォールバックのオーバーライドは後続ターンでも選択されたままになるため、OpenClaw はメッセージごとに失敗が既知のプライマリをプローブしません。OpenClaw は設定済みの元モデルを定期的に再プローブし、復旧すると自動オーバーライドをクリアします。`/new`、`/reset`、`sessions.reset` は、自動設定されたオーバーライドを即座にクリアします。 - ユーザーへの応答では、フォールバックへの移行と、フォールバック解除による復旧を、状態変化ごとに 1 回通知します。フォールバックが継続するターンでは、通知を繰り返しません。 - `/status` には選択されたモデルが表示され、フォールバック状態が異なる場合は、アクティブなフォールバックモデルと理由も表示されます。 - ライブセッション調整では、古いランタイムモデルフィールドよりも、永続化されたセッションオーバーライドを優先します。 - ライブ切り替えエラーがアクティブなフォールバックチェーン内の後続候補を指している場合、OpenClaw は無関係な候補を先に順番に試すのではなく、その選択されたモデルへ直接移動します。 - フォールバックの試行が失敗した場合、ランナーは自身が書き込んだオーバーライドフィールドだけを、かつそれらが失敗した候補とまだ一致している場合にのみロールバックします。 これにより、次の典型的な競合を防ぎます。 選択されたプライマリモデルが失敗します。 フォールバック候補がメモリ内で選択されます。 セッションストアには、引き続き古いプライマリが反映されています。 ライブセッション調整が、古いセッション状態を読み取ります。 フォールバックの試行が開始される前に、再試行が古いモデルへ戻されます。 永続化されたフォールバックオーバーライドによってこの隙間が解消され、限定的なロールバックによって、より新しい手動またはランタイムのセッション変更が維持されます。 ## 可観測性と失敗の概要 `runWithModelFallback(...)` は、ログとユーザー向けのクールダウンメッセージに使用される試行ごとの詳細を記録します。 - 試行されたプロバイダー/モデル - 理由（`rate_limit`、`overloaded`、`billing`、`auth`、`model_not_found`、および同様のフェイルオーバー理由） - 任意のステータス/コード - 人が読めるエラー概要 構造化された `model_fallback_decision` ログには、候補が失敗した場合、スキップされた場合、または後続のフォールバックが成功した場合に、フラットな `fallbackStep*` フィールドも含まれます。これらのフィールドは、試行された遷移（`fallbackStepFromModel`、`fallbackStepToModel`、`fallbackStepFromFailureReason`、`fallbackStepFromFailureDetail`、`fallbackStepFinalOutcome`）を明示するため、最終的なフォールバックも失敗した場合でも、ログおよび診断エクスポーターは最初の失敗を再構成できます。 すべての候補が失敗すると、OpenClaw は `FallbackSummaryError` をスローします。外側の応答ランナーはこれを使用して、「すべてのモデルが一時的にレート制限されています」のような、より具体的なメッセージを生成し、判明している場合は最も早いクールダウンの終了時刻を含めることができます。 このクールダウン概要はモデルを考慮します。 - 試行されたプロバイダー/モデルのチェーンに関係のないモデルスコープのレート制限は無視されます - 残っているブロックが一致するモデルスコープのレート制限である場合、OpenClaw はそのモデルを引き続きブロックしている最後の一致する終了時刻を報告します ## 関連設定 以下については、[Gateway の設定](/ja-JP/gateway/configuration)を参照してください。 - `auth.profiles` / `auth.order` - `auth.cooldowns.billingBackoffHours` / `auth.cooldowns.billingBackoffHoursByProvider` - `auth.cooldowns.billingMaxHours` / `auth.cooldowns.failureWindowHours` - `auth.cooldowns.authPermanentBackoffMinutes` / `auth.cooldowns.authPermanentMaxMinutes` - `auth.cooldowns.overloadedProfileRotations` / `auth.cooldowns.overloadedBackoffMs` - `auth.cooldowns.rateLimitedProfileRotations` - `agents.defaults.model.primary` / `agents.defaults.model.fallbacks` - `agents.defaults.imageModel` のルーティング モデル選択とフォールバックの全般的な概要については、[モデル](/ja-JP/concepts/models)を参照してください。