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

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

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

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

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

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

詳細: /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 は次の順序で選択します。

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

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

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

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

OpenClaw は、プロバイダーのキャッシュを温めたままにするため、セッションごとに選択された認証プロファイルを固定します。 すべてのリクエストごとにローテーションすることはありません。固定されたプロファイルは、次の場合まで再利用されます。リクエストごとに回転しません**。ピン留めされたプロファイルは次のまで再利用されます:

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

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

自動で固定されたプロファイル（セッションルーターによって選択）は 優先設定 として扱われます。最初に試行されますが、レート制限やタイムアウト時には OpenClaw が別のプロファイルにローテーションする場合があります。ユーザー固定のプロファイルはそのプロファイルにロックされたままです。失敗し、モデルフォールバックが設定されている場合、 OpenClaw はプロファイルを切り替えるのではなく、次のモデルに移動します。ユーザー固定プロファイルは、そのプロファイルにロックされたままです。失敗し、モデルフォールバックが設定されている場合、OpenClawはプロファイルを切り替える代わりに次のモデルに移動します。

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

同一プロバイダーに OAuth プロファイルと API キープロファイルの両方がある場合、固定されていないと、ラウンドロビンによりメッセージ間で切り替わることがあります。単一のプロファイルを強制するには次のいずれかを行います。単一のプロファイルを強制するには:

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

クールダウン¶

認証/レート制限エラー（またはレート制限に見えるタイムアウト）によりプロファイルが失敗した場合、 OpenClaw はそのプロファイルをクールダウンに設定し、次のプロファイルに移動します。フォーマット/無効リクエストエラー（例: Cloud Code Assist のツール呼び出し ID 検証失敗）もフェイルオーバー対象として扱われ、同じクールダウンが適用されます。フォーマット/無効要求エラー(例えば、Cloud Code Assist ツールコール ID 検証失敗)は、フェイルオーバーに値するものとして扱われ、同じクールダウンを使用します。

クールダウンは指数バックオフを使用します。

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

状態は auth-profiles.json の usageStats 配下に保存されます。

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

課金による無効化¶

請求/クレジットの失敗（例えば「クレジット不足」や「クレジット残高が低すぎる」など）は、フェイルオーバー価値として扱われますが、通常は一時的ではありません。短いクールダウンの代わりに、OpenClawはプロファイルを無効化(バックオフ時間が長い)としてマークし、次のプロファイル/プロバイダに回転します。

状態は auth-profiles.json に保存されます。

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

デフォルト:

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

モデルフォールバック¶

あるプロバイダーのすべてのプロファイルが失敗した場合、OpenClaw は agents.defaults.model.fallbacks 内の次のモデルに移動します。これは、認証失敗、レート制限、およびプロファイルローテーションを使い切ったタイムアウトに適用されます（その他のエラーではフォールバックは進みません）。これは、プロファイルの回転を使い果たした認証失敗、レート制限、およびタイムアウトに適用されます(他のエラーはフォールバックを進めません)。

フックや CLI によるモデルオーバーライドで実行が開始された場合でも、設定されたフォールバックを試行した後、フォールバックの終了点は agents.defaults.model.primary になります。

Overview

Model concepts

Configuration

Providers

Model Failover