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

OpenClaw は障害を 2 段階で処理します。

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

ランタイムフロー

フォールバックの実行はターンローカルです。返信ランナーが永続化するのはフォールバック通知の状態のみです。これにより、/status と遷移通知で、選択されたモデルと実際に応答したモデルを区別できます。次のターンのモデル選択としてフォールバックを永続化することはありません。

選択元ポリシー

選択元によって、フォールバックチェーンを使用できるかどうかが決まります。

• 設定済みのデフォルト: 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 はユーザーに見える通知を送信し、その後のターンで選択されたプライマリが成功すると、別の通知を送信します。通知状態を永続化することで、連続するターンで同じ選択済みモデルとアクティブモデルの組み合わせが使われた場合の通知の繰り返しを防ぎますが、モデル選択自体は変更されません。

認証失敗スキップキャッシュ

デフォルトでは、新しい各ターンで既存のフォールバック再試行動作が維持されます。OpenClaw は、最近 auth または auth_permanent で失敗した非プライマリ候補を含め、設定された各フォールバック候補を再び試行します。

繰り返される認証失敗を抑制するには、次を設定してオプトインします。

OPENCLAW_FALLBACK_SKIP_TTL_MS=60000

有効にすると、OpenClaw は認証クラスの障害後に、非プライマリのフォールバック候補に対するインメモリかつセッションスコープのスキップマーカーを記録します。キーにはセッション ID、プロバイダー、モデルを使用します。プライマリ候補はスキップされないため、ユーザーが明示的に選択したモデルでは実際の認証エラーが引き続き表示されます。キャッシュはプロセスローカルであり、Gateway の再起動時にクリアされます。

値はミリ秒単位の TTL です。0 または未設定の場合、キャッシュは無効になります。正の値は 1 秒から 10 分の範囲に制限されます。

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

セッションが自動選択されたフォールバックへ移行すると、OpenClaw は同じ返信画面にステータス通知を送信します。

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

後続のプローブが成功し、セッションが選択済みのプライマリに戻ると、OpenClaw は次を送信します。

↪️ モデルフォールバックを解除: <primary>（以前: <fallback>）

これらの通知は運用メッセージであり、アシスタントのコンテンツではありません。可能な場合は副作用のみのターンも含め、状態の変更ごとに 1 回配信されますが、ターンローカルのフォールバック遷移が繰り返されても再送されません。配信は通常の送信元返信抑制をバイパスし、スレッド形式のチャンネルにおける最初のアシスタント返信枠を消費せず、テキスト読み上げとコミットメント抽出の対象外です。

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

OpenClaw は API キーと 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 によってインポートされます。

詳細: OAuth

認証情報の種類:

• type: "api_key" → { provider, key }
• type: "oauth" → { provider, access, refresh, expires, email? }（一部のプロバイダーではさらに projectId/enterpriseUrl）
• type: "token" → 静的な Bearer 形式のトークン。有効期限は任意です。OpenClaw はこれを更新しません（aws-sdk およびその他の認証情報チェーン認証モードで使用）

プロファイル ID

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

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

プロファイルは、エージェントごとの openclaw-agent.sqlite 認証プロファイルストアに保存されます。

ローテーション順序

プロバイダーに複数のプロファイルがある場合、OpenClaw は次の順序で選択します。

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

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

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

OpenClaw は、プロバイダーのキャッシュをウォーム状態に保つため、セッションごとに選択した認証プロファイルを固定します。リクエストごとにはローテーションしません。固定されたプロファイルは、次のいずれかが発生するまで再利用されます。

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

/model …@<profileId> による手動選択は、そのセッションにユーザーオーバーライドを設定します。新しいセッションが開始されるまで自動ローテーションされません。

OpenAI Codex サブスクリプションと API キーのバックアップ

OpenAI エージェントモデルでは、認証とランタイムは分離されています。認証では Codex サブスクリプションプロファイルと OpenAI API キーのバックアップ間をローテーションできますが、openai/gpt-* は Codex ハーネス上に維持されます。

ユーザー向けの順序には auth.order.openai を使用します。

{  auth: {    order: {      openai: ["openai:user@example.com", "openai:api-key-backup"],    },  },}

ChatGPT/Codex OAuth プロファイルと OpenAI API キープロファイルの両方に openai:* を使用します。サブスクリプションが Codex の使用量上限に達すると、Codex からリセット時刻が提供される場合、OpenClaw はその正確な時刻を記録し、順序内の次の認証プロファイルを試行して、実行を Codex ハーネス内に維持します。リセット時刻を過ぎるとサブスクリプションプロファイルが再び候補となり、次の自動選択でそのプロファイルに戻ることができます。

そのセッションで 1 つのアカウントまたはキーを強制的に使用する場合にのみ、ユーザー固定プロファイルを使用してください。ユーザー固定プロファイルは意図的に厳密であり、暗黙に別のプロファイルへ切り替わることはありません。

クールダウン

認証エラーやレート制限エラー（またはレート制限のように見えるタイムアウト）が原因でプロファイルが失敗すると、OpenClaw はそのプロファイルをクールダウン状態にして、次のプロファイルへ移動します。

通常の（請求関連でも永続的な認証関連でもない）クールダウンは、プロファイルの直近のエラー数に応じて延長されます。

• 1 回目の失敗: 30 秒
• 2 回目の失敗: 1 分
• 3 回目以降の失敗: 5 分（上限）

プロファイルに組み込まれた失敗ウィンドウが経過すると、カウンターはリセットされます。

状態は、usageStats のエージェント単位の SQLite 認証状態に保存されます。

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

請求による無効化

請求／クレジットの失敗（たとえば「クレジット不足」／「クレジット残高が低すぎる」）はフェイルオーバーの対象として扱われますが、通常は一時的なものではありません。OpenClaw は短いクールダウンを設定する代わりに、プロファイルを無効としてマークし（より長いバックオフを設定）、次のプロファイル／プロバイダーへローテーションします。

確度の高い永続的な認証失敗（取り消された／無効化されたキー、無効化されたワークスペース）には同様の無効化レーンが適用されますが、一部のプロバイダーは障害発生時に認証エラーに見えるペイロードを一時的に返すため、請求関連よりもはるかに早く回復します。

状態は、エージェント単位の SQLite 認証状態に保存されます。

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

過負荷およびレート制限エラーは、請求関連のクールダウンより積極的に処理されます。デフォルトでは、OpenClaw は同一プロバイダー内で認証プロファイルの再試行を 1 回許可した後、待機せずに次の設定済みモデルフォールバックへ切り替えます。

モデルフォールバック

あるプロバイダーのすべてのプロファイルが失敗すると、OpenClaw は agents.defaults.model.fallbacks 内の次のモデルへ移動します。これは、プロファイルのローテーションを使い切った認証失敗、レート制限、タイムアウトに適用されます（その他のエラーではフォールバックは進みません）。十分な詳細を提示しないプロバイダーエラーも、フォールバック状態では正確にラベル付けされます。empty_response はプロバイダーが使用可能なメッセージもステータスも返さなかったことを、no_error_details はプロバイダーが明示的に Unknown error (no error details in response) を返したことを、unclassified は OpenClaw が未加工のプレビューを保持したものの、まだどの分類器にも一致していないことを意味します。

ModelNotReadyException などのプロバイダーがビジー状態であることを示すシグナルは過負荷バケットに分類され、レート制限と同じく、1 回ローテーションしてからフォールバックするポリシーに従います（上記のデフォルト表を参照）。

候補チェーン全体が過負荷による失敗のみで使い切られた場合、応答ランナーは同じターン内でチェーンを最大 10 回再試行します。ターン全体の再試行は、ツールの実行またはアシスタントの出力が開始される前にのみ許可されます。これにより、観測可能な処理の後に過負荷が発生した場合の変更やメッセージの重複を回避します。バックオフは 2.5 秒から始まり、倍増して上限の 30 秒に達します。ターンの待機時間が 30 秒に達すると、OpenClaw は一時的なステータス通知を 1 回送信します: The AI service is temporarily overloaded. I’m still retrying; this may take a few minutes. 再試行と、フォールバックで最終的に選ばれた候補は、そのターン内にのみ有効です。通常の一時的なサーバーエラーには、別途 1 回の再試行ポリシーが適用されます。

実行が、設定済みのデフォルトプライマリ、Cron ジョブのプライマリ、明示的なフォールバックを持つエージェントプライマリ、または自動選択されたフォールバックオーバーライドから開始された場合、OpenClaw は対応する設定済みフォールバックチェーンを順に試行できます。明示的なフォールバックを持たないエージェントプライマリ、および明示的なユーザー選択（たとえば /model ollama/qwen3.5:27b、モデルピッカー、sessions.patch、または一時的な CLI プロバイダー／モデルオーバーライド）は厳密に扱われます。そのプロバイダー／モデルに到達できない、または応答を生成する前に失敗した場合、OpenClaw は無関係なフォールバックで応答する代わりに失敗を報告します。

候補チェーンのルール

OpenClaw は、現在要求されている provider/model と設定済みフォールバックから候補リストを構築します。

フォールバックを進めるエラー

クールダウン時のスキップとプローブの動作

あるプロバイダーのすべての認証プロファイルがすでにクールダウン中であっても、OpenClaw はそのプロバイダーを永続的に自動スキップするわけではありません。候補ごとに判断します。

セッションオーバーライドと実行中のモデル切り替え

セッションのモデル変更は共有状態です。アクティブなランナー、/model コマンド、Compaction／セッション更新、および実行中セッションの整合処理は、すべて同じセッションエントリの一部を読み書きします。フォールバックの実行はモデル選択フィールドを書き込まないため、再試行中に新しい手動選択を置き換えることはありません。

実行中のモデル切り替えは、次のルールに従います。

• 明示的なユーザー操作によるモデル変更のみが、保留中の実行中切り替えとしてマークされます。これには /model、session_status(model=...)、および sessions.patch が含まれます。
• フォールバックのローテーション、Heartbeat オーバーライド、Compaction などのシステムによるモデル変更は、それ自体では保留中の実行中切り替えとしてマークされません。
• ユーザーによるモデルオーバーライドは、フォールバックポリシー上、厳密な選択として扱われます。そのため、選択されたプロバイダーに到達できない場合、agents.defaults.model.fallbacks によって隠されるのではなく、失敗として表面化します。
• ランタイムのフォールバック候補は、そのターン内にのみ有効です。次のターンは、前回の実行中に行われた手動選択を含む、現在選択されているモデルから開始されます。
• 以前に保存された自動フォールバックオーバーライドは引き続きサポートされます。OpenClaw は設定された元の候補を定期的にプローブし、回復するとオーバーライドを解除します。/new、/reset、および sessions.reset は、自動設定されたオーバーライドを直ちに解除します。
• ユーザーへの応答では、フォールバックへの移行と、フォールバック解除後の回復を、状態変化ごとに 1 回通知します。選択済みモデルとアクティブモデルの組み合わせが同じままのターンが繰り返されても、通知は繰り返されません。
• /status は選択されたモデルを表示し、フォールバック状態が異なる場合は、アクティブなフォールバックモデルと理由も表示します。
• 実行中セッションの整合処理では、古いランタイムモデルフィールドよりも永続化されたセッションオーバーライドが優先されます。
• 実行中切り替えのエラーがアクティブなフォールバックチェーン内の後続候補を指している場合、OpenClaw は無関係な候補を先に順番に試すのではなく、選択されたそのモデルへ直接移動します。

アクティブな実行は、選択した候補を直接保持します。実行中の整合処理がその候補を変更するのは、明示的に保留中となっているユーザー切り替えの場合のみです。そのため、一時的なフォールバックオーバーライドやロールバックは不要です。

可観測性と失敗の要約

runWithModelFallback(...) は、ログおよびユーザー向けのクールダウンメッセージに使用される試行ごとの詳細を記録します。

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

構造化された model_fallback_decision ログには、候補が失敗した場合、スキップされた場合、または後続のフォールバックが成功した場合に、フラットな fallbackStep* フィールドも含まれます。これらのフィールドは、試行された遷移（fallbackStepFromModel、fallbackStepToModel、fallbackStepFromFailureReason、fallbackStepFromFailureDetail、fallbackStepFinalOutcome）を明示するため、最終的なフォールバックも失敗した場合でも、ログおよび診断エクスポーターはプライマリの失敗を再構築できます。

すべての候補が失敗すると、OpenClaw は FallbackSummaryError をスローします。外側の応答ランナーはこれを使用して、「すべてのモデルが一時的にレート制限されています」のような、より具体的なメッセージを作成し、判明している場合は最も早いクールダウン終了時刻を含めることができます。

このクールダウンの概要はモデルを考慮します。

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

関連設定

以下については、Gateway の設定を参照してください。

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

より広範なモデル選択とフォールバックの概要については、モデルを参照してください。