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

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

​

ランタイムフロー

​

選択元ポリシー

• 設定済みのデフォルト: agents.defaults.model.primary は agents.defaults.model.fallbacks を使用します。
• エージェントのプライマリ: そのエージェントのモデルオブジェクトに独自の fallbacks が含まれていない限り、agents.entries.*.model には厳密に従います。厳密な動作を明示するには fallbacks: [] を使用し、そのエージェントでモデルフォールバックを有効にするには空でないリストを使用します。
• ランタイムフォールバック: フォールバック候補は現在のターンにのみ適用されます。次のターンは、選択されたプライマリから再び開始します。OpenClaw は以前に保存された modelOverrideSource: "auto" エントリも引き続き認識し、設定された元の候補を 5 分ごとにプローブして、回復するとエントリをクリアします。/new、/reset、および sessions.reset でも、これらのエントリがクリアされます。
• ユーザーのセッションオーバーライド: /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

​

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

↪️ モデルフォールバック: <fallback>（選択済み: <primary>; <reason>）

↪️ モデルフォールバックを解除: <primary>（以前: <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" → 静的な Bearer 形式のトークン。有効期限は任意です。OpenClaw はこれを更新しません（aws-sdk およびその他の認証情報チェーン認証モードで使用）

​

プロファイル ID

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

​

ローテーション順序

• プライマリキー: プロファイルの種類（OAuth、静的トークン、API キーの順）。
• OAuth のセカンダリキー: 現在使用可能なアクセストークンを持つプロファイルを、 アクセストークンの有効期限が切れたプロファイルより先にします。使用可能な同等プロファイルがない場合に ランタイムが更新できるよう、有効期限切れの OAuth プロファイルも候補として維持されます。
• 次のキー: usageStats.lastUsed（各種類および状態階層内で古いものから順）。
• クールダウン中または無効なプロファイルは末尾へ移動し、終了時刻が早い順に並べられます。

​

セッション固定（キャッシュ効率を考慮）

• セッションがリセットされた場合（/new / /reset）
• Compaction が完了した場合（Compaction 回数が増加）
• プロファイルがクールダウン中または無効な場合

​

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 は設定された元の候補を定期的にプローブし、回復するとオーバーライドを解除します。/new、/reset、および sessions.reset は、自動設定されたオーバーライドを直ちに解除します。
• ユーザーへの応答では、フォールバックへの移行と、フォールバック解除後の回復を、状態変化ごとに 1 回通知します。選択済みモデルとアクティブモデルの組み合わせが同じままのターンが繰り返されても、通知は繰り返されません。
• /status は選択されたモデルを表示し、フォールバック状態が異なる場合は、アクティブなフォールバックモデルと理由も表示します。
• 実行中セッションの整合処理では、古いランタイムモデルフィールドよりも永続化されたセッションオーバーライドが優先されます。
• 実行中切り替えのエラーがアクティブなフォールバックチェーン内の後続候補を指している場合、OpenClaw は無関係な候補を先に順番に試すのではなく、選択されたそのモデルへ直接移動します。

​

可観測性と失敗の要約

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

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

​

関連設定

• auth.profiles / auth.order
• agents.defaults.model.primary / agents.defaults.model.fallbacks
• agents.defaults.imageModel ルーティング