Model failover

OpenClaw は 2 つの段階で failure を処理します：

  1. 現在の provider 内での Auth profile rotation（認証プロファイルローテーション）。
  2. agents.defaults.model.fallbacks の次の model への Model fallback（モデルフォールバック）。

このドキュメントでは、runtime rule とそれを支えるデータについて説明します。

Auth storage（key + OAuth）

OpenClaw は API key と OAuth token の両方に auth profile を使用します。

  • Secret は ~/.openclaw/agents/<agentId>/agent/auth-profiles.json（legacy：~/.openclaw/agent/auth-profiles.json）に保存されます。
  • Config auth.profiles / auth.order は metadata + routing のみ（secret なし）です。
  • Legacy import-only OAuth file：~/.openclaw/credentials/oauth.json（初回使用時に auth-profiles.json にインポート）。

詳細：/concepts/oauth

Credential type：

  • type: "api_key" → { provider, key }
  • type: "oauth" → { provider, access, refresh, expires, email? }（+ 一部の provider では projectId/enterpriseUrl）

Profile ID

OAuth login は distinct profile を作成するため、複数のアカウントが共存できます。

  • デフォルト：email が利用できない場合は provider:default。
  • Email 付き OAuth：provider:<email>（例：google-antigravity:[email protected]）。

Profile は ~/.openclaw/agents/<agentId>/agent/auth-profiles.json の profiles 下に保存されます。

Rotation order（ローテーション順序）

Provider に複数の profile がある場合、OpenClaw は次のような順序を選択します：

  1. Explicit config：auth.order[provider]（設定されている場合）。
  2. Configured profile：provider でフィルタリングされた auth.profiles。
  3. Stored profile：auth-profiles.json 内の provider のエントリ。

明示的な order が設定されていない場合、OpenClaw は round-robin order を使用します：

  • Primary key：profile type（OAuth が API key より前）。
  • Secondary key：usageStats.lastUsed（各 type 内で最も古いものが先）。
  • Cooldown/disabled profile は最後に移動し、最も早い expiry で order されます。

Session stickiness（cache-friendly）

OpenClaw は session ごとに選択された auth profile を pin して、provider cache を warm に保ちます。 すべてのリクエストで rotate しません。Pin された profile は次まで再利用されます：

  • session がリセットされる（/new / /reset）
  • compaction が完了する（compaction count が増加）
  • profile が cooldown/disabled になる

/model …@<profileId> による手動選択は、その session の user override を設定し、新しい session が開始されるまで auto-rotate されません。

Auto-pin された profile（session router によって選択）は preference として扱われます： 最初に試行されますが、rate limit/timeout で OpenClaw が別の profile に rotate する場合があります。 User-pin された profile はその profile にロックされたままです。失敗し、model fallback が設定されている場合、OpenClaw は profile を切り替える代わりに次の model に移動します。

Why OAuth can "look lost"（なぜ OAuth が「失われたように見える」か）

同じ provider に OAuth profile と API key profile の両方がある場合、pin されていない限り、round-robin がメッセージ間で切り替わることがあります。単一の profile を強制するには：

  • auth.order[provider] = ["provider:profileId"] で pin するか、
  • /model … を介した per-session override を使用します（UI/chat surface でサポートされている場合）。

Cooldown

Profile が auth/rate-limit error（または rate limiting に見える timeout）で失敗すると、OpenClaw はそれを cooldown にマークし、次の profile に移動します。 Format/invalid-request error（例：Cloud Code Assist tool call ID validation failure）は failover-worthy として扱われ、同じ cooldown を使用します。

Cooldown は exponential backoff を使用します：

  • 1 分
  • 5 分
  • 25 分
  • 1 時間（cap）

State は auth-profiles.json の usageStats 下に保存されます：

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

Billing disable

Billing/credit failure（例：「insufficient credits」/「credit balance too low」）は failover-worthy として扱われますが、通常は transient ではありません。短い cooldown の代わりに、OpenClaw は profile を disabled（より長い backoff 付き）としてマークし、次の profile/provider に rotate します。

State は auth-profiles.json に保存されます：

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

デフォルト：

  • Billing backoff は 5 時間から開始し、billing failure ごとに 2 倍になり、24 時間で cap されます。
  • Profile が 24 時間失敗していない場合、backoff counter がリセットされます（設定可能）。

Model fallback

Provider のすべての profile が失敗すると、OpenClaw は agents.defaults.model.fallbacks の次の model に移動します。これは auth failure、rate limit、profile rotation を使い果たした timeout に適用されます（他の error は fallback を進めません）。

Run が model override（hook または CLI）で開始される場合、fallback は設定された fallback を試行した後、agents.defaults.model.primary で終了します。

Related config

以下については 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 routing

より広範な model selection と fallback overview については Models を参照してください。

← ドキュメントに戻る