モデルフェイルオーバー

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

​

ランタイムフロー

​

選択ソースポリシー

• 設定済みデフォルト: agents.defaults.model.primary は agents.defaults.model.fallbacks を使用します。
• エージェントプライマリ: agents.list[].model は、そのエージェントのモデルオブジェクトに独自の fallbacks が含まれていない限り厳密です。厳密な動作を明示するには fallbacks: [] を使用し、そのエージェントをモデルフォールバックにオプトインするには空でないリストを使用します。
• 自動フォールバックオーバーライド: ランタイムフォールバックは、再試行前に providerOverride, modelOverride, modelOverrideSource: "auto" と、選択された元のモデルを書き込みます。このオーバーライドは、メッセージごとにプライマリをプローブせずに、設定済みフォールバックチェーンを歩き続けます。ただし OpenClaw は設定済みの元モデルを5分ごとにプローブし（設定不可）、回復するとオーバーライドをクリアします。/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 実行を厳密にします。

​

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

OPENCLAW_FALLBACK_SKIP_TTL_MS=60000

​

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

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

↪️ Model Fallback cleared: <primary> (was <fallback>)

​

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

• type: "api_key" → { provider, key }
• type: "oauth" → { provider, access, refresh, expires, email? }（一部のプロバイダーでは + projectId/enterpriseUrl）
• type: "token" → 静的なベアラー形式のトークン。任意で期限切れを設定できます。OpenClaw は更新しません（aws-sdk やその他の認証情報チェーン認証モードで使用）

​

プロファイル ID

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

​

ローテーション順序

• プライマリキー: プロファイルタイプ（OAuth、次に静的トークン、次に API キー）。
• セカンダリキー: usageStats.lastUsed（各タイプ内で古いものが先）。
• クールダウン中/無効化されたプロファイルは末尾に移動され、最も早い期限順に並べられます。

​

セッションのスティッキネス（キャッシュに適した動作）

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

​

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

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

​

クールダウン

• 1 回目の失敗: 30 秒
• 2 回目の失敗: 1 分
• 3 回目以降の失敗: 5 分（上限）

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

​

請求による無効化

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

​

モデルフォールバック

​

候補チェーンのルール

​

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

​

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

​

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

• 明示的なユーザー主導のモデル変更だけが、保留中のライブ切り替えをマークします。これには /model、session_status(model=...)、sessions.patch が含まれます。
• フォールバックローテーション、Heartbeat オーバーライド、Compaction などのシステム主導のモデル変更は、それ自体では保留中のライブ切り替えをマークしません。
• ユーザー主導のモデルオーバーライドは、フォールバックポリシーでは正確な選択として扱われるため、到達不能な選択済みプロバイダーは agents.defaults.model.fallbacks によって隠されるのではなく、失敗として表面化します。
• フォールバック再試行が開始される前に、返信ランナーは選択されたフォールバックオーバーライドフィールドをセッションエントリに永続化します。
• 自動フォールバックオーバーライドは後続ターンでも選択されたままになるため、OpenClaw は既知の不良プライマリをメッセージごとにプローブしません。OpenClaw は設定済みの起点を定期的に再プローブし、回復したら自動オーバーライドをクリアします。/new、/reset、sessions.reset は自動由来のオーバーライドを即座にクリアします。
• ユーザーへの返信では、フォールバック遷移とフォールバック解除による回復を、状態変更ごとに 1 回通知します。固定されたフォールバックのターンでは通知を繰り返しません。
• /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.authPermanentBackoffMinutes / auth.cooldowns.authPermanentMaxMinutes
• auth.cooldowns.overloadedProfileRotations / auth.cooldowns.overloadedBackoffMs
• auth.cooldowns.rateLimitedProfileRotations
• agents.defaults.model.primary / agents.defaults.model.fallbacks
• agents.defaults.imageModel ルーティング