モデルフェイルオーバー

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:[email protected]）。

プロファイルは ~/.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はプロファイル切り替えではなく次のモデルに移動します。

OAuthが「見失われた」ように見える理由

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

auth.order[provider] = ["provider:profileId"] で固定するか、
UI/チャットサーフェスがサポートしている場合、/model … でプロファイルオーバーライド付きのセッション単位オーバーライドを使用。

クールダウン

認証/レート制限エラー（またはレート制限と思われるタイムアウト）でプロファイルが失敗すると、OpenClawはクールダウン状態にしてフォーマットし次のプロファイルに移行します。フォーマット/無効なリクエストエラー（例: Cloud Code Assistツール呼び出しIDの検証失敗）もフェイルオーバー対象として扱われ、同じクールダウンが使用されます。Unhandled stop reason: error、stop reason: error、reason: error などのOpenAI互換停止理由エラーもタイムアウト/フェイルオーバーシグナルとして分類されます。

クールダウンは指数バックオフを使用:

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

状態は auth-profiles.json の usageStats 配下に保存:

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

課金による無効化

課金/クレジット失敗（例: “insufficient credits” / “credit balance too low”）はフェイルオーバー対象として扱われますが、通常は一時的ではありません。短いクールダウンの代わりに、OpenClawはプロファイルを無効化（より長いバックオフ付き）し、次のプロファイル/プロバイダーにローテーションします。

状態は auth-profiles.json に保存:

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

デフォルト:

課金バックオフは5時間から開始、課金失敗ごとに倍増、24時間で上限。
バックオフカウンターは24時間（設定可能）失敗がなければリセット。

モデルフォールバック

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

モデルオーバーライド（フックまたはCLI）でランが開始された場合も、設定されたフォールバックを試行した後、フォールバックは agents.defaults.model.primary で終了します。