> ## Documentation Index > Fetch the complete documentation index at: https://openclawdoc.org/llms.txt > Use this file to discover all available pages before exploring further. # モデルフェイルオーバー > 1. 認証プロファイルのローテーション: 同じプロバイダー内で別のアカウント（プロファイル）に切り替える。2. モデルフォールバック: agents.defaults.model.fallbacks で指定された次のモデルへ切り替える。 OpenClaw は、以下の 2 段階でエラー発生時の処理（フェイルオーバー）を行います: 1. **認証プロファイルのローテーション**: 同じプロバイダー内で別のアカウント（プロファイル）に切り替える。 2. **モデルフォールバック**: `agents.defaults.model.fallbacks` で指定された次のモデルへ切り替える。 このドキュメントでは、実行時のルールとそれを支えるデータの仕組みについて説明します。 ## 認証情報の保存 (キーと OAuth) OpenClaw は、API キーと OAuth トークンの両方を **認証プロファイル** として管理します。 * シークレット情報（秘密鍵など）は `~/.openclaw/agents//agent/auth-profiles.json` に保存されます（旧パス: `~/.openclaw/agent/auth-profiles.json`）。 * 構成ファイル (`openclaw.json`) の `auth.profiles` や `auth.order` には、**メタデータとルーティング設定のみ**が含まれます（シークレットは含まれません）。 * 以前の OAuth インポート用ファイル `~/.openclaw/credentials/oauth.json` は、初回使用時に `auth-profiles.json` へインポートされます。 詳細は [/concepts/oauth](/concepts/oauth) を参照してください。 認証情報の種類: * `type: "api_key"` → `{ provider, key }` * `type: "oauth"` → `{ provider, access, refresh, expires, email? }` (プロバイダーによって `projectId` や `enterpriseUrl` が追加されます) ## プロファイル ID OAuth によるログインではアカウントごとに固有のプロファイルが作成されるため、複数のアカウントを共存させることができます。 * デフォルト: メールアドレスが取得できない場合は `provider:default`。 * メールアドレスありの OAuth: `provider:` (例: `google-antigravity:user@gmail.com`)。 プロファイル情報は、各エージェントのディレクトリにある `auth-profiles.json` 内の `profiles` セクションに保持されます。 ## ローテーションの順序 1 つのプロバイダーに対して複数のプロファイルがある場合、OpenClaw は以下の優先順位で順序を決定します: 1. **明示的な構成**: `auth.order[provider]` 設定がある場合。 2. **構成済みのプロファイル**: `auth.profiles` 内の該当プロバイダーの設定。 3. **保存済みのプロファイル**: `auth-profiles.json` 内の該当プロバイダーのエントリ。 明示的な順序指定がない場合は、以下のラウンドロビン方式で選択されます: * **第一基準**: プロファイルの種類 (**API キーよりも OAuth を優先**)。 * **第二基準**: `usageStats.lastUsed` (同じ種類の中では、最終使用日時が古いものから順に)。 * **例外**: クールダウン中または無効化されたプロファイルは、期限切れが近い順に最後尾へ移動されます。 ### セッションの固定 (スティッキーセッション) OpenClaw はプロバイダー側のキャッシュを有効活用するため、**セッションごとに選択された認証プロファイルを固定**します。 リクエストごとにローテーションすることはありません。固定されたプロファイルは、以下のいずれかの条件を満たすまで再利用され続けます: * セッションがリセットされたとき (`/new` または `/reset`)。 * 圧縮（コンパクション）が完了したとき。 * そのプロファイルがクールダウン状態または無効化されたとき。 `/model …@` コマンドによる手動選択は、そのセッションに対する **ユーザーによる上書き** として扱われ、新しいセッションが開始されるまで自動ローテーションの対象外となります。 自動で固定されたプロファイル（セッションルーターによる選択）は「優先設定」として扱われます。まずそのプロファイルが試行されますが、レート制限やタイムアウトが発生した場合は別のプロファイルへローテーションすることがあります。一方、ユーザーが明示的に固定したプロファイルの場合、エラー発生時にはプロファイルの切り替えは行わず、モデルのフォールバック設定があれば次のモデルへと移行します。 ### OAuth が「見失われた」ように見える理由 同じプロバイダーに対して OAuth プロファイルと API キープロファイルの両方がある場合、固定されていない限り、メッセージをまたいでラウンドロビンで切り替わることがあります。常に特定のプロファイルを使用したい場合は以下のいずれかを行ってください: * `auth.order[provider] = ["provider:profileId"]` で固定する。 * チャット UI などで `/model …` コマンドを使用してセッションごとにプロファイルを上書きする。 ## クールダウン (一時停止) 認証エラー、レート制限エラー、またはレート制限に近い挙動（タイムアウトなど）によりリクエストが失敗した場合、OpenClaw はそのプロファイルを「クールダウン」状態としてマークし、次のプロファイルへ移行します。フォーマットエラーやリクエスト不正（例：Cloud Code Assist のツール呼び出し ID 検証失敗）も、フェイルオーバー対象として同様にクールダウンが適用されます。また、OpenAI 互換エンドポイントからの `Unhandled stop reason: error` などの停止理由エラーも、タイムアウトやフェイルオーバーの信号として扱われます。 クールダウンには指数バックオフが適用されます: * 1 分 * 5 分 * 25 分 * 1 時間 (上限) この状態は `auth-profiles.json` の `usageStats` セクションに保存されます。 ## 支払い関連による無効化 支払い情報の不足やクレジット残高不足によるエラーは、一時的なネットワークエラーとは異なり、すぐには解消されません。そのため、OpenClaw はそのプロファイルを（より長い待機期間を設けて） **無効化** し、次のプロファイルやプロバイダーへとローテーションします。 この状態も `auth-profiles.json` 内で管理されます。 デフォルト設定: * 無効化の待機期間は **5 時間** から始まり、失敗を繰り返すごとに倍増し、最大 **24 時間** となります。 * 該当のプロファイルで **24 時間**（設定可能）エラーが発生しなければ、カウンターはリセットされます。 ## モデルフォールバック プロバイダー内のすべてのプロファイルが失敗（認証エラー、レート制限、タイムアウトなど）した場合、OpenClaw は `agents.defaults.model.fallbacks` で指定された次のモデルへと移行します（その他の予期せぬエラーではフォールバックは進行しません）。 フックや CLI からモデルの上書き指定を行って実行を開始した場合でも、最終的には構成済みのフォールバックをすべて試した後に `agents.defaults.model.primary` へと辿り着きます。 ## 関連する構成設定 [ゲートウェイ構成](/gateway/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` ルーティング モデル選択とフォールバックの全体像については [モデル](/concepts/models) を参照してください。