モデルフェイルオーバー

OpenClaw は失敗を2段階で処理します。

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

このドキュメントでは、ランタイムルールと、それを支えるデータについて説明します。

ランタイムフロー

通常のテキスト実行では、OpenClaw は次の順序で候補を評価します。

これは意図的に「セッション全体を保存して復元する」よりも狭い範囲です。返信ランナーは、フォールバック用に自身が所有するモデル選択フィールドだけを永続化します。

• providerOverride
• modelOverride
• modelOverrideSource
• authProfileOverride
• authProfileOverrideSource
• authProfileOverrideCompactionCount

これにより、失敗したフォールバックリトライが、試行の実行中に発生した手動の /model 変更やセッションローテーション更新など、より新しい無関係なセッション変更を上書きすることを防ぎます。

選択元ポリシー

OpenClaw は、選択されたプロバイダー/モデルと、それが選択された理由を分離します。そのソースによって、フォールバックチェーンが許可されるかどうかが決まります。

• 設定済みデフォルト: agents.defaults.model.primary は agents.defaults.model.fallbacks を使用します。
• エージェントプライマリ: agents.list[].model は、そのエージェントモデルオブジェクトに独自の fallbacks が含まれていない限り厳密です。厳密な動作を明示するには fallbacks: [] を使用し、そのエージェントをモデルフォールバックに参加させるには空でないリストを指定します。
• 自動フォールバック上書き: ランタイムフォールバックは、リトライ前に providerOverride、modelOverride、modelOverrideSource: "auto"、および選択元モデルを書き込みます。この自動上書きにより、毎回のメッセージでプライマリを探査せずに設定済みフォールバックチェーンを進み続けられますが、OpenClaw は設定済みの選択元を定期的に再探査し、復旧したら自動上書きをクリアします。/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 実行を厳密にします。

自動フォールバックのプライマリ探査間隔は5分で、設定できません。OpenClaw はセッションおよびプライマリモデルごとに最近の探査を記憶するため、失敗中のプライマリを毎ターン再試行しません。OpenClaw は、セッションがフォールバックへ移動したときに可視通知を送信し、選択されたプライマリへ戻ったときに別の通知を送信します。固定されたフォールバックターンごとに通知を繰り返すことはありません。

認証失敗スキップキャッシュ

デフォルトでは、新しいターンごとに既存のフォールバックリトライ動作が維持されます。OpenClaw は、最近 auth または auth_permanent で失敗した非プライマリ候補を含め、設定済みの各フォールバック候補を再試行します。

これらの認証失敗の繰り返しを抑制したい運用者は、次でオプトインできます。

OPENCLAW_FALLBACK_SKIP_TTL_MS=60000

有効にすると、OpenClaw は認証クラスの失敗後、非プライマリフォールバック候補に対して、インメモリでセッションスコープのスキップマーカーを記録します。マーカーはセッション ID、プロバイダー、モデルでキー指定されます。プライマリ候補は決してスキップされないため、明示的なユーザーモデル選択では実際の認証エラーが引き続き表面化します。キャッシュはプロセスローカルで、Gateway の再起動時にクリアされます。

値はミリ秒単位の TTL です。0 または未設定の値はキャッシュを無効にします。正の値は1秒から10分の間にクランプされます。

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

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

↪️ Model Fallback: <fallback> (selected <primary>; <reason>)

後続の探査が成功し、セッションが選択されたプライマリへ戻ると、OpenClaw は次を送信します。

↪️ Model Fallback cleared: <primary> (was <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 を追加）

プロファイル ID

OAuth ログインは、複数アカウントが共存できるように個別のプロファイルを作成します。

• デフォルト: メールアドレスが利用できない場合は provider:default。
• メールアドレス付き OAuth: provider:<email>（例: google-antigravity:user@gmail.com）。

プロファイルは、エージェントごとの openclaw-agent.sqlite 認証プロファイルストアにあります。

ローテーション順序

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

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

• プライマリキー: プロファイルタイプ（API キーより OAuth が先）。
• セカンダリキー: 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 分
• 5 分
• 25 分
• 1 時間（上限）

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

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

請求による無効化

請求/クレジットの失敗（たとえば「insufficient credits」/「credit balance too low」）はフェイルオーバー対象として扱われますが、通常は一時的なものではありません。短いクールダウンの代わりに、OpenClaw はプロファイルを disabled（より長いバックオフ付き）としてマークし、次のプロファイル/プロバイダーへローテーションします。

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

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

デフォルト:

• 請求バックオフは 5 時間 から始まり、請求失敗ごとに倍増し、24 時間 で上限に達します。
• プロファイルが 24 時間 失敗していない場合、バックオフカウンターはリセットされます（設定可能）。
• 過負荷の再試行では、モデルフォールバックの前に 同一プロバイダー内のプロファイルローテーション 1 回 が許可されます。
• 過負荷の再試行は、デフォルトで 0 ms バックオフ を使用します。

モデルフォールバック

あるプロバイダーのすべてのプロファイルが失敗した場合、OpenClaw は agents.defaults.model.fallbacks 内の次のモデルへ移動します。これは、プロファイルローテーションを使い切った認証失敗、レート制限、タイムアウトに適用されます（その他のエラーではフォールバックは進みません）。十分な詳細を公開しないプロバイダーエラーも、フォールバック状態では正確にラベル付けされます。empty_response はプロバイダーが使用可能なメッセージまたはステータスを返さなかったことを意味し、no_error_details はプロバイダーが明示的に Unknown error (no error details in response) を返したことを意味し、unclassified は OpenClaw が未加工のプレビューを保持したものの、まだどの分類器にも一致しなかったことを意味します。

過負荷エラーとレート制限エラーは、請求クールダウンより積極的に処理されます。デフォルトでは、OpenClaw は同一プロバイダー内の認証プロファイル再試行を 1 回許可し、その後待機せずに次に設定されたモデルフォールバックへ切り替えます。ModelNotReadyException などのプロバイダー混雑シグナルは、その過負荷バケットに入ります。これは auth.cooldowns.overloadedProfileRotations、auth.cooldowns.overloadedBackoffMs、auth.cooldowns.rateLimitedProfileRotations で調整できます。

実行が、設定されたデフォルトのプライマリ、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.overloadedProfileRotations / auth.cooldowns.overloadedBackoffMs
• auth.cooldowns.rateLimitedProfileRotations
• agents.defaults.model.primary / agents.defaults.model.fallbacks
• agents.defaults.imageModel ルーティング

より広範なモデル選択とフォールバックの概要については、Models を参照してください。