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

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"、および選択された起点モデルを書き込みます。その自動オーバーライドは、設定済みフォールバックチェーンを引き続き進めることができ、/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 実行を厳密にします。

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

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

• シークレットは ~/.openclaw/agents/<agentId>/agent/auth-profiles.json にあります（レガシー: ~/.openclaw/agent/auth-profiles.json）。
• ランタイム認証ルーティング状態は ~/.openclaw/agents/<agentId>/agent/auth-state.json にあります。
• 設定 auth.profiles / auth.order はメタデータ + ルーティングのみです（シークレットなし）。
• レガシーのインポート専用 OAuth ファイル: ~/.openclaw/credentials/oauth.json（初回使用時に auth-profiles.json へインポートされます）。

詳細: OAuth

認証情報の種類:

• type: "api_key" → { provider, key }
• type: "oauth" → { provider, access, refresh, expires, email? }（一部のプロバイダーでは projectId/enterpriseUrl も含む）

プロファイル ID

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

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

プロファイルは ~/.openclaw/agents/<agentId>/agent/auth-profiles.json 内の profiles の下にあります。

ローテーション順序

プロバイダーに複数のプロファイルがある場合、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-codex:[email protected]", "openai:api-key-backup"],    },  },}

既存の Codex サブスクリプションプロファイルは、引き続きレガシーの openai-codex:* プロファイル ID を使用する場合があります。順序付けされた API キーバックアップは通常の openai:* API キープロファイルにできます。サブスクリプションが Codex 使用量制限に達すると、 Codex が提供する場合、OpenClaw は正確なリセット時刻を記録し、次に 順序付けされた認証プロファイルを試し、実行を Codex ハーネス内に保ちます。リセット時刻を 過ぎると、サブスクリプションプロファイルは再び対象になり、次の自動 選択でそこへ戻ることができます。

そのセッションで 1 つのアカウント/キーを強制したい場合にのみ、ユーザー固定プロファイルを使用します。ユーザー固定プロファイルは意図的に厳密であり、黙って 別のプロファイルへ移動しません。

クールダウン

認証/レート制限エラー（またはレート制限のように見えるタイムアウト）によってプロファイルが失敗した場合、OpenClaw はそれをクールダウンにマークし、次のプロファイルへ移動します。

クールダウンは指数バックオフを使用します。

• 1 分
• 5 分
• 25 分
• 1 時間（上限）

状態は auth-state.json 内の usageStats に保存されます。

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

請求による無効化

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

状態は auth-state.json に保存されます。

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

デフォルト:

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

モデルフォールバック

プロバイダーのすべてのプロファイルが失敗すると、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 はメッセージごとに既知の不良プライマリをプローブしません。/new、/reset、sessions.reset は自動由来のオーバーライドをクリアし、セッションを設定済みデフォルトに戻します。
• /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 のルーティング

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