モデルフェイルオーバー
OpenClaw が認証プロファイルをローテーションし、モデル間でフェイルオーバーする方法。
OpenClaw は 2 段階で障害を処理します：
1. 現在のプロバイダー内での認証プロファイルのローテーション。
2. ''モデルフェイルオーバー''から ''agents.defaults.model.fallbacks'' の次のモデルへ。
このドキュメントでは、実行時ルールとそれをサポートするデータについて説明します。
認証ストレージ（キー + OAuth）
OpenClaw は API キーと OAuth トークンに認証プロファイルを使用します。
- Secrets live in ''~/.openclaw/agents/<agentId>/agent/auth-profiles.json'' (legacy: ''~/.openclaw/agent/auth-profiles.json'').
- 設定 ''auth.profiles'' / ''auth.order'' は''メタデータ + ルーティング''です（シークレットは含まれません）。
- レガシー OAuth 専用インポート：''~/.openclaw/credentials/oauth.json''（初回使用時に ''auth-profiles.json'' にインポートされます）。
More details: ''/concepts/oauth''
認証情報タイプ：
- ''type: "api_key"'' → ''{ provider, key }''
- ''type: "oauth"'' → ''{ provider, access, refresh, expires, email? }'' （一部のプロバイダーでは、+ ''projectId''/''enterpriseUrl''）
プロファイル ID
OAuth ログインは複数のアカウントが共存できるように個別のプロファイルを作成します。
- デフォルト：''provider:default''（メールアドレスが利用できない場合）。
- OAuth with email: ''provider:<email>'' (e.g., ''google-antigravity:[email protected]'').
Profiles live under ''profiles'' in ''~/.openclaw/agents/<agentId>/agent/auth-profiles.json''.
ローテーション順序
プロバイダーに複数のプロファイルがある場合、OpenClaw はこの順序で選択します：
1. ''明示的な設定''：''auth.order[provider]''（設定されている場合）。
2. ''設定されたプロファイル''：''auth.profiles'' をプロバイダーでフィルタリング。
3. ''保存されたプロファイル''：プロバイダーの ''auth-profiles.json'' のエントリ。
明示的な順序が設定されていない場合、OpenClaw はラウンドロビン順序を使用します：
- 主キー：プロファイルタイプ（API キーの前の OAuth）。
- ''副キー：'' ''usageStats.lastUsed''（各タイプ内で最も古いものが先）。
- クールダウン/無効化されたプロファイルは最後に移動し、有効期限が最も早い順にソートされます。
#
セッションスティッキネス（キャッシュフレンドリー）
OpenClaw はプロバイダーキャッシュを温めるために、セッションごとに選択された認証プロファイルを固定します。
リクエストごとにローテーションしません。固定されたプロファイルは次の状況まで再利用されます：
- セッションリセット (''/new'' / ''/reset'')
- 圧縮の完了（圧縮カウントの増分）
- プロファイルがクールダウン/無効化状態
Manual selection via ''/model …@<profileId>'' sets a ''user override'' for that session
新しいセッションが開始するまで自動ローテーションしません。
自動固定されたプロファイル（セッションルーターによって選択）は優先事項として扱われます：
最初に試されますが、OpenClaw はレート制限/タイムアウトで別のプロファイルにローテーションする場合があります。
ユーザー固定のプロファイルはそのプロファイルにロックされたままです。失敗してモデルフェイルオーバー
が完了すると、OpenClaw はプロファイルを切り替えるのではなく、次のモデルに移動します。
OAuth が「見失われる」理由
同じプロバイダーの OAuth プロファイルと API キープロファイルの両方がある場合、固定されていない限り、メッセージ間でそれらを切り替えることができます。単一のプロファイルを強制するには：
- ''auth.order[provider] = ["provider:profileId"]'' で固定するか、
- ''/model …'' を介してセッションごとのオーバーライドとプロファイルオーバーライドを使用する（UI/チャットインターフェースがサポートしている場合）。
クールダウン時間
認証/レート制限エラー（またはタイムアウトのように見えるもの
レート制限のように）でプロファイルが失敗した場合、OpenClaw はそれをクールダウンとしてマークし、次のプロファイルに移動します。
形式/無効なリクエストエラー（例：Cloud Code Assist ツール呼び出し ID
検証の失敗）はフェイルオーバーの価値があると見なされ、同じクールダウンを使用します。
クールダウンは指数バックオフを使用します：
- 1 minute
- 5 minutes
- 25 minutes
- 1 hour (capped)
{
"usageStats": {
"provider:profile": {
"lastUsed": 1736160000000,
"cooldownUntil": 1736160600000,
"errorCount": 2
}
}
}請求の無効化
請求/クレジットの失敗（例：「クレジット不足」/「クレジット残高が低すぎる」）はフェイルオーバーの価値があると見なされますが、通常は一時的ではありません。短いクールダウンの代わりに、OpenClaw はプロファイルを無効化としてマークし（より長いバックオフ時間で）、次のプロファイル/プロバイダーにローテーションします。
ステータスは ''auth-profiles.json'' に保存されます：
{
"usageStats": {
"provider:profile": {
"disabledUntil": 1736178000000,
"disabledReason": "billing"
}
}
}デフォルト：
- 請求バックオフは5 時間から始まり、請求の失敗ごとに倍増し、24 時間で上限になります。
- プロファイルが 24 時間以内に失敗しない場合、バックオフカウンターはリセットされます（設定可能）。
モデルフェイルオーバー
プロバイダーのすべてのプロファイルが失敗した場合、OpenClaw は
''agents.defaults.model.fallbacks'' の次のモデルに移動します。これは認証の失敗、レート制限、および
プロファイルローテーションを使い果たすタイムアウトに適用されます（他のエラーはフェイルオーバーを進めません）。
モデルオーバーライド（フックまたは CLI）で実行が開始された場合、フェイルオーバーは引き続き
設定されたフェイルオーバーの後に ''agents.defaults.model.primary'' を試します。
Related Configuration
''ゲートウェイ設定''を参照してください：
- ''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'' ルーティング
モデル選択とフェイルオーバーの広範な概要については、''モデル''を参照してください。