​

モデルフェイルオーバー

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

​

ランタイムフロー

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

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

• providerOverride
• modelOverride
• authProfileOverride
• authProfileOverrideSource
• authProfileOverrideCompactionCount

​

認証ストレージ（キー + 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へインポートされます）。

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

​

プロファイルID

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

​

ローテーション順序

1. 明示的な設定: auth.order[provider]（設定されている場合）。
2. 設定済みプロファイル: プロバイダーでフィルタしたauth.profiles。
3. 保存済みプロファイル: そのプロバイダー向けのauth-profiles.json内エントリ。

• 主キー: プロファイル種別（APIキーよりOAuthを優先）
• 副キー: usageStats.lastUsed（各種別内で最も古いものが先）
• クールダウン中/無効化されたプロファイルは末尾へ移動し、最も早く期限切れになる順に並べられます。

​

セッションのスティッキネス（キャッシュにやさしい）

• セッションがリセットされたとき（/new / /reset）
• compactionが完了したとき（compaction countが増加）
• プロファイルがクールダウン中/無効化されているとき

​

OAuthが「消えたように見える」理由

• auth.order[provider] = ["provider:profileId"]で固定する、または
• /model …でプロファイルオーバーライド付きのセッション単位オーバーライドを使う（UI/チャット面が対応している場合）。

​

クールダウン

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

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

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

​

請求による無効化

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

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

​

モデルフォールバック

​

候補チェーンのルール

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

​

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

• 認証失敗
• レート制限とクールダウン枯渇
• 過負荷/プロバイダー多忙エラー
• タイムアウト系のフェイルオーバーエラー
• 請求による無効化
• 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）
• 候補が残っていないときの最終的な未知のエラー

​

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

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

​

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

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

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

​

可観測性と失敗サマリー

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

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

​

関連する設定

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