設定

モデルフェイルオーバー

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はラウンドロビン順序を使用します：

プライマリキー： プロファイルタイプ（APIキーよりOAuthを優先）。
セカンダリキー： usageStats.lastUsed（各タイプ内で最も古いものから順に）。
クールダウン中/無効化されたプロファイルは末尾に移動され、有効期限が最も早いものから順に並べられます。

セッションスティッキネス（キャッシュに優しい）

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

セッションがリセットされる（/new / /reset）
コンパクションが完了する（コンパクションカウントが増加する）
プロファイルがクールダウン中/無効化されている

/model …@<profileId>による手動選択は、そのセッションのユーザーオーバーライドを設定し、新しいセッションが開始されるまで自動ローテーションされません。自動固定プロファイル（セッションルーターによって選択されたもの）は優先設定として扱われます：最初に試行されますが、レート制限/タイムアウトが発生した場合、OpenClawは別のプロファイルにローテーションする可能性があります。ユーザー固定プロファイルはそのプロファイルにロックされ、それが失敗しモデルフォールバックが設定されている場合、OpenClawはプロファイルを切り替える代わりに次のモデルに移動します。

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

同じプロバイダーに対してOAuthプロファイルとAPIキープロファイルの両方を持っている場合、固定されていない限り、ラウンドロビンによってメッセージ間でそれらが切り替わる可能性があります。単一のプロファイルを強制するには：

auth.order[provider] = ["provider:profileId"]で固定する、または
プロファイルオーバーライド付きの/model …を使用してセッションごとのオーバーライドを使用する（UI/チャット画面でサポートされている場合）。

クールダウン

プロファイルが認証/レート制限エラー（またはレート制限のように見えるタイムアウト）で失敗した場合、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
    }
  }
}

課金無効化

課金/クレジット失敗（例：「クレジット不足」/「クレジット残高が少なすぎます」）はフェイルオーバー対象として扱われますが、通常は一時的なものではありません。短いクールダウンの代わりに、OpenClawはプロファイルを無効化（より長いバックオフ付き）としてマークし、次のプロファイル/プロバイダーにローテーションします。状態はauth-profiles.jsonに保存されます：

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

デフォルト：

課金バックオフは5時間から開始し、課金失敗ごとに倍増し、24時間で上限に達します。
バックオフカウンターは、プロファイルが24時間失敗していない場合にリセットされます（設定可能）。

モデルフォールバック

プロバイダーのすべてのプロファイルが失敗した場合、OpenClawはagents.defaults.model.fallbacksの次のモデルに移動します。これは、認証失敗、レート制限、およびプロファイルローテーションを枯渇させたタイムアウトに適用されます（他のエラーではフォールバックは進みません）。実行がモデルオーバーライド（フックまたはCLI）で開始された場合、フォールバックは設定されたフォールバックを試行した後、agents.defaults.model.primaryで終了します。