OpenClawのモデルフェイルオーバー設定：自動切り替えを最適化する

開発中に API のレート制限に遭遇したり、モデルが突然ダウンしたりするのは、エンジニアにとって最も避けたい事態の一つです。作業のフローが途切れる上に、手動で設定を切り替える手間も発生します。OpenClaw は、こうしたエラーを自動的に検知し、スムーズに復旧するための仕組みを提供しています。

OpenClaw は、エラーが発生した際に 2 つのステップで対応します。

1. 現在のプロバイダー内での Auth profile のローテーション。
2. agents.defaults.model.fallbacks に指定された次のモデルへの Model fallback。

このドキュメントでは、実行時のルールとそれを支えるデータについて解説します。

認証ストレージ (キー + OAuth)

OpenClaw は、API キーと OAuth トークンの両方に auth profiles を使用します。

• シークレットは ~/.openclaw/agents/<agentId>/agent/auth-profiles.json（レガシー環境では ~/.openclaw/agent/auth-profiles.json）に保存されます。また、設定ファイルの auth.profiles や auth.order は、メタデータとルーティングのみを扱い、シークレットは含みません。
• レガシーなインポート専用の OAuth ファイル ~/.openclaw/credentials/oauth.json は、初回使用時に auth-profiles.json へインポートされます。

詳細はこちら：/concepts/oauth

認証情報の種類：

• type: "api_key" → { provider, key }
• type: "oauth" → { provider, access, refresh, expires, email? }（一部のプロバイダーでは projectId や enterpriseUrl も含まれます）

プロファイル ID

OAuth ログインでは、複数のアカウントを共存させるために個別のプロファイルが作成されます。

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

プロファイルは ~/.openclaw/agents/<agentId>/agent/auth-profiles.json の profiles セクションに保存されます。

ローテーションの順序

プロバイダーに複数のプロファイルがある場合、OpenClaw は以下の優先順位で順序を決定します。

1. 明示的な設定：auth.order[provider] が設定されている場合。
2. 構成済みおよび保存済みのプロファイル：auth.profiles でフィルタリングされたもの、または auth-profiles.json にあるプロバイダーごとのエントリ。

明示的な順序が設定されていない場合、OpenClaw はラウンドロビン方式を採用します。

• プロファイルの種類（API キーより OAuth を優先）と、usageStats.lastUsed に基づく使用順序（古いものから優先）を組み合わせて

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

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