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

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

​

ランタイムフロー

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

​

選択ソースポリシー

• 設定済みデフォルト: 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/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）。

​

ローテーション順序

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

​

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

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

​

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

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

​

クールダウン

• 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 backoff を使用します。

​

モデルフォールバック

​

候補チェーンのルール

​

フォールバックを進めるエラー

​

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

​

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

• 明示的なユーザー駆動のモデル変更だけが、保留中のライブ切り替えをマークします。これには /model、session_status(model=...)、sessions.patch が含まれます。
• フォールバックローテーション、Heartbeat オーバーライド、Compaction などのシステム駆動のモデル変更は、それだけで保留中のライブ切り替えをマークすることはありません。
• ユーザー駆動のモデルオーバーライドはフォールバックポリシー上の正確な選択として扱われるため、選択されたプロバイダーに到達できない場合、agents.defaults.model.fallbacks によって覆い隠されるのではなく失敗として表面化します。
• フォールバックリトライが開始する前に、返信ランナーは選択されたフォールバックオーバーライドフィールドをセッションエントリに永続化します。
• 自動フォールバックオーバーライドは後続ターンでも選択されたままになるため、OpenClaw はメッセージごとに既知の不良プライマリをプローブしません。/new、/reset、sessions.reset は自動由来のオーバーライドをクリアし、セッションを設定済みデフォルトに戻します。
• /status は選択されたモデルを表示し、フォールバック状態が異なる場合はアクティブなフォールバックモデルと理由も表示します。
• ライブセッションの照合では、古いランタイムモデルフィールドよりも永続化されたセッションオーバーライドを優先します。
• ライブ切り替えエラーがアクティブなフォールバックチェーン内の後続候補を指している場合、OpenClaw は無関係な候補を先にたどらず、その選択されたモデルへ直接ジャンプします。
• フォールバック試行が失敗した場合、ランナーは自分が書き込んだオーバーライドフィールドだけをロールバックし、しかもそれらがその失敗候補とまだ一致している場合に限ります。

​

可観測性と失敗サマリー

• 試行されたプロバイダー/モデル
• 理由（rate_limit、overloaded、billing、auth、model_not_found、および同様のフェイルオーバー理由）
• 任意のステータス/コード
• 人間が読めるエラーサマリー

• 試行されたプロバイダー/モデルチェーンに関係しないモデルスコープのレート制限は無視されます
• 残っているブロックが一致するモデルスコープのレート制限である場合、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 のルーティング