​

Model failover

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

​

実行時フロー

1. 現在選択されているセッションモデル。
2. 設定された agents.defaults.model.fallbacks を順番に。
3. 実行がオーバーライドから始まった場合は、最後に設定済みのプライマリモデル。

1. アクティブなセッションモデルと auth-profile の優先設定を解決する。
2. モデル候補チェーンを構築する。
3. auth-profile のローテーション / クールダウンルールで現在のプロバイダーを試す。
4. そのプロバイダーがフォールバックに値するエラーで使い尽くされたら、次の モデル候補に移動する。
5. リトライ開始前に選択されたフォールバックオーバーライドを永続化し、他の セッション読み取り側がランナーがこれから使用するのと同じプロバイダー / モデルを見るようにする。
6. フォールバック候補が失敗した場合、その失敗した候補とまだ一致しているときに限り、 フォールバック所有のセッションオーバーライドフィールドだけをロールバックする。
7. すべての候補が失敗した場合、各試行の詳細と、判明している場合は最も早い クールダウン満了時刻を含む FallbackSummaryError を投げる。

• providerOverride
• modelOverride
• authProfileOverride
• authProfileOverrideSource
• authProfileOverrideCompactionCount

​

Auth ストレージ（キー + OAuth）

• シークレットは ~/.openclaw/agents/<agentId>/agent/auth-profiles.json に保存されます（レガシー: ~/.openclaw/agent/auth-profiles.json）。
• config の auth.profiles / auth.order は メタデータ + ルーティングのみ です（シークレットは含みません）。
• レガシーのインポート専用 OAuth ファイル: ~/.openclaw/credentials/oauth.json（初回利用時に auth-profiles.json にインポートされます）。

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

​

Profile ID

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

​

ローテーション順序

1. 明示的な config: auth.order[provider]（設定されている場合）
2. 設定済み profile: プロバイダーで絞り込んだ auth.profiles
3. 保存済み profile: そのプロバイダーの auth-profiles.json 内のエントリー

• 主キー: profile のタイプ（API キーより OAuth を優先）
• 副キー: usageStats.lastUsed（各タイプ内で最も古いものから）
• クールダウン中 / 無効化済み profile は末尾に移動され、最も早い満了時刻順に並べられます。

​

セッション固定性（キャッシュに優しい）

• セッションがリセットされる（/new / /reset）
• compaction が完了する（compaction 回数が増える）
• profile がクールダウン中または無効化される

​

OAuth が「失われたように見える」理由

• auth.order[provider] = ["provider:profileId"] で固定する、または
• /model … に profile オーバーライドを付けたセッションごとのオーバーライドを使用する （UI / チャットサーフェスが対応している場合）。

​

クールダウン

• OpenClaw は、失敗したモデル ID が分かっている場合、レート制限失敗に対して cooldownModel を記録します。
• 同じプロバイダー上の兄弟モデルは、クールダウンが別のモデルにスコープされている場合でも試行できます。
• 課金 / 無効化ウィンドウは、引き続きその profile を全モデルでブロックします。

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

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

​

課金による無効化

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

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

​

モデルフォールバック

​

候補チェーンのルール

• 要求されたモデルは常に先頭です。
• 明示的に設定されたフォールバックは重複排除されますが、モデルの allowlist ではフィルタリングされません。これらは明示的な運用者の意図として扱われます。
• 現在の実行がすでに同じプロバイダーファミリー内の設定済みフォールバック上にある場合、 OpenClaw は設定済みチェーン全体を使い続けます。
• 現在の実行が config と異なるプロバイダー上にあり、その現在の モデルが設定済みフォールバックチェーンの一部でない場合、OpenClaw は 別プロバイダーの無関係な設定済みフォールバックを追加しません。
• 実行がオーバーライドから始まった場合、設定済みのプライマリが末尾に追加されるため、 先行候補を使い切った後にチェーンは通常のデフォルトへ戻ることができます。

​

どのエラーでフォールバックが進むか

• auth 失敗
• レート制限とクールダウン枯渇
• 過負荷 / プロバイダー多忙エラー
• タイムアウト型のフォールバックエラー
• 課金による無効化
• LiveSessionModelSwitchError。これは古い永続化モデルが外側のリトライループを作らないよう、 フォールバックパスに正規化されます
• 他に候補が残っている場合の、その他の未認識エラー

• タイムアウト / フォールバック型でない明示的な中断
• compaction / リトライロジック内にとどまるべきコンテキストオーバーフローエラー （たとえば request_too_large、INVALID_ARGUMENT: input exceeds the maximum number of tokens、input token count exceeds the maximum number of input tokens、The input is too long for the model、または ollama error: context length exceeded）
• 候補が残っていない最終的な未知のエラー

​

クールダウン時のスキップとプローブの動作

• 永続的な auth 失敗では、そのプロバイダー全体を即座にスキップします。
• 課金による無効化では通常スキップしますが、再起動なしで回復可能にするため、 プライマリ候補はスロットル付きでなおプローブされることがあります。
• プライマリ候補は、プロバイダーごとのスロットル付きで、クールダウン満了近くにプローブされる場合があります。
• 同一プロバイダーの兄弟フォールバックは、失敗が一時的に見える場合 （rate_limit、overloaded、または unknown）には、クールダウン中でも試行されることがあります。 これは、レート制限がモデルスコープで、兄弟モデルがすぐに回復する可能性がある場合に特に重要です。
• 一時的なクールダウンプローブは、単一のプロバイダーがクロスプロバイダーのフォールバックを停滞させないよう、 フォールバック実行ごとにプロバイダーあたり 1 回に制限されます。

​

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

• 保留中のライブ切り替えをマークするのは、明示的なユーザー主導のモデル変更だけです。 これには /model、session_status(model=...)、sessions.patch が含まれます。
• フォールバックローテーション、heartbeat オーバーライド、 compaction のようなシステム主導のモデル変更は、それ自体では保留中のライブ切り替えをマークしません。
• フォールバックリトライが始まる前に、reply ランナーは選択された フォールバックオーバーライドフィールドをセッションエントリーに永続化します。
• ライブセッション再調整は、古い実行時モデルフィールドよりも 永続化されたセッションオーバーライドを優先します。
• フォールバック試行が失敗した場合、ランナーは自分が書いたオーバーライドフィールドのみを、 しかもそれがその失敗した候補とまだ一致している場合にのみロールバックします。

1. プライマリが失敗する。
2. フォールバック候補がメモリ内で選択される。
3. セッションストアにはまだ古いプライマリが記録されている。
4. ライブセッション再調整がその古いセッション状態を読み取る。
5. フォールバック試行が始まる前に、リトライが古いモデルに戻される。

​

可観測性と失敗サマリー

• 試行した provider/model
• reason（rate_limit、overloaded、billing、auth、model_not_found、 および類似のフォールバック理由）
• 任意の status/code
• 人間が読めるエラーサマリー

• 試行された provider/model チェーンに無関係なモデルスコープのレート制限は無視されます
• 残っているブロックがそのモデルに一致するモデルスコープのレート制限である場合、 OpenClaw はそのモデルをまだブロックしている最後の一致する満了時刻を報告します

​

関連する config

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