モデルのフェイルオーバー

OpenClaw は障害を 2 段階で処理します。

1. 現在のプロバイダー内での 認証プロファイルのローテーション。
2. agents.defaults.model.fallbacks 内の次のモデルへの モデルフォールバック。

ランタイムフロー

これは意図的に「セッション全体を保存して復元する」よりも限定的です。応答ランナーがフォールバック用に永続化するのは、自身が所有するモデル選択フィールドだけです。対象は 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 で失敗した非プライマリ候補も含め、設定済みの各フォールバック候補を再試行します。

認証失敗の繰り返しを抑制するには、次を設定して有効にします。

OPENCLAW_FALLBACK_SKIP_TTL_MS=60000

有効にすると、非プライマリのフォールバック候補で認証クラスの失敗が発生した後、OpenClaw はセッション ID、プロバイダー、モデルをキーとして、メモリ内かつセッション単位のスキップマーカーを記録します。プライマリ候補は決してスキップされないため、ユーザーが明示的にモデルを選択した場合は、実際の認証エラーが引き続き表示されます。このキャッシュはプロセスローカルであり、Gateway の再起動時に消去されます。

値はミリ秒単位の TTL です。0 または未設定の場合、キャッシュは無効です。正の値は 1 秒から 10 分の範囲に制限されます。

ユーザーに表示されるフォールバック通知

セッションが自動選択されたフォールバックへ移行すると、OpenClaw は同じ応答サーフェスにステータス通知を送信します。

↪️ モデルフォールバック：<fallback>（選択済み <primary>、<reason>）

後続のプローブが成功し、セッションが選択済みのプライマリへ戻ると、OpenClaw は次を送信します。

↪️ モデルフォールバック解除：<primary>（以前は <fallback>）

これらの通知は運用メッセージであり、アシスタントのコンテンツではありません。可能な場合は副作用のみのターンも含め、状態変更ごとに 1 回配信されますが、固定されたフォールバックでのターンでは繰り返されません。配信では通常の送信元応答抑制を回避し、スレッド対応チャンネルにおける最初のアシスタント応答枠を消費せず、テキスト読み上げおよびコミットメント抽出の対象にもなりません。

認証ストレージ（キー + OAuth）

OpenClaw は、API キーと OAuth トークンの両方に 認証プロファイルを使用します。

• シークレットおよびランタイムの認証ルーティング状態は ~/.openclaw/agents/<agentId>/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

認証情報の種類：

• 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:<email>（例：google-antigravity:user@gmail.com）。

プロファイルは、エージェント単位の openclaw-agent.sqlite 認証プロファイルストアに保存されます。

ローテーション順序

プロバイダーに複数のプロファイルがある場合、OpenClaw は次の順序で選択します。

明示的な順序が設定されていない場合、OpenClaw はラウンドロビン順序を使用します。

• プライマリキー： プロファイルの種類（OAuth、静的トークン、API キーの順）。
• セカンダリキー： usageStats.lastUsed（種類ごとに古いものから）。
• クールダウン中または無効なプロファイルは末尾へ移動し、終了時刻が早い順に並べられます。

セッション固定性（キャッシュ効率を重視）

OpenClaw は、プロバイダーのキャッシュをウォーム状態に保つため、選択した認証プロファイルをセッションごとに固定します。リクエストごとにはローテーションしません。固定されたプロファイルは、次のいずれかが発生するまで再利用されます。

• セッションがリセットされた（/new / /reset）
• Compaction が完了した（Compaction カウントが増加）
• プロファイルがクールダウン中または無効である

/model …@<profileId> による手動選択では、そのセッションに ユーザーオーバーライドが設定され、新しいセッションが開始されるまで自動ローテーションされません。

OpenAI Codex サブスクリプションと API キーのバックアップ

OpenAI エージェントモデルでは、認証とランタイムは別々です。openai/gpt-* は Codex ハーネス上で動作したまま、認証は Codex サブスクリプションプロファイルと OpenAI API キーのバックアップとの間でローテーションできます。

ユーザー向けの順序には auth.order.openai を使用します。

{  auth: {    order: {      openai: ["openai:user@example.com", "openai:api-key-backup"],    },  },}

ChatGPT/Codex OAuth プロファイルと OpenAI API キープロファイルの両方に openai:* を使用します。サブスクリプションが Codex の使用量上限に達すると、Codex から正確なリセット時刻が提供された場合、OpenClaw はその時刻を記録し、順序内の次の認証プロファイルを試行し、実行を Codex ハーネス内に維持します。リセット時刻を過ぎると、サブスクリプションプロファイルが再び使用可能になり、次回の自動選択でそのプロファイルへ戻ることができます。

そのセッションで 1 つのアカウントまたはキーを強制的に使用したい場合にのみ、ユーザー固定プロファイルを使用してください。ユーザー固定プロファイルは意図的に厳密であり、暗黙に別のプロファイルへ切り替わることはありません。

クールダウン

認証エラー、レート制限エラー、またはレート制限とみなされるタイムアウトによってプロファイルが失敗すると、OpenClaw はそのプロファイルをクールダウン状態にし、次のプロファイルへ移動します。

通常の（課金および永続的な認証エラー以外の）クールダウンは、プロファイルの直近のエラー回数に応じて増加します。

• 1 回目の失敗: 30 秒
• 2 回目の失敗: 1 分
• 3 回目以降の失敗: 5 分（上限）

プロファイルの失敗期間が経過すると、カウンターはリセットされます（auth.cooldowns.failureWindowHours、デフォルトは 24）。

状態は、エージェントごとの SQLite 認証状態の usageStats に保存されます。

{  "usageStats": {    "provider:profile": {      "lastUsed": 1736160000000,      "cooldownUntil": 1736160600000,      "errorCount": 2    }  }}

課金による無効化

課金またはクレジットのエラー（たとえば「クレジット不足」や「クレジット残高が少なすぎる」）はフェイルオーバーの対象として扱われますが、通常は一時的なものではありません。短いクールダウンを設定する代わりに、OpenClaw はプロファイルを無効としてマークし（より長いバックオフを設定）、次のプロファイルまたはプロバイダーに切り替えます。

確度の高い永続的な認証エラー（取り消されたキー、無効化されたキー、無効化されたワークスペース）は同様の無効化分類になりますが、一部のプロバイダーでは障害発生中に認証エラーに見えるペイロードが一時的に返されるため、課金エラーよりも大幅に早く復旧します。

状態は、エージェントごとの SQLite 認証状態に保存されます。

{  "usageStats": {    "provider:profile": {      "disabledUntil": 1736178000000,      "disabledReason": "billing"    }  }}

デフォルト値（auth.cooldowns.*）:

過負荷およびレート制限エラーは、課金クールダウンよりも積極的に処理されます。デフォルトでは、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 はそのプロバイダーを永久に自動スキップするわけではありません。候補ごとに判断します。

セッションオーバーライドとライブモデル切り替え

セッションのモデル変更は共有状態です。アクティブなランナー、/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 の設定を参照してください。

• 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 のルーティング

モデル選択とフォールバックの全般的な概要については、モデルを参照してください。