​

モデルフェイルオーバー

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

​

認証ストレージ（キー + OAuth）

• シークレットは ~/.openclaw/agents/<agentId>/agent/auth-profiles.json（レガシー: ~/.openclaw/agent/auth-profiles.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:[email protected]）。

​

ローテーション順

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

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

​

セッションのスティッキー化（キャッシュフレンドリー）

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

​

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

• auth.order[provider] = ["provider:profileId"] で固定する、または
• UI/チャット画面でサポートされている場合、/model … によるセッション単位のオーバーライドでプロファイルを指定する。

​

クールダウン

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

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

​

課金による無効化

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

• 請求バックオフは5時間、請求失敗ごとに2倍、24時間で始まります。
• プロファイルが 24 時間 失敗していない場合、バックオフカウンターはリセットされます（設定可能）。

​

モデルフォールバック

​

関連設定

• auth.profiles / auth.order
• auth.cooldowns.billingBackoffHours / auth.cooldowns.billingBackoffHoursByProvider
• auth.cooldowns.billingMaxHours / auth.cooldowns.failureWindowHours
• agents.defaults.model.primary / agents.defaults.model.fallbacks
• agents.defaults.imageModel のルーティング