> ## Documentation Index
> Fetch the complete documentation index at: https://openclaw.veiseule.ai/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

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

1. 現在のプロバイダー内での **認証プロファイルのローテーション**。
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](/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 は次の順序で選択します。

1. **明示的な設定**: `auth.order[provider]`（設定されている場合）。
2. **設定済みプロファイル**: プロバイダーでフィルタされた `auth.profiles`。
3. **保存済みプロファイル**: プロバイダーに対応する `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
検証失敗)は、フェイルオーバーに値するものとして扱われ、同じクールダウンを使用します。
フォーマット/無効要求エラー(例えば、Cloud Code Assist ツールコール ID
検証失敗)は、フェイルオーバーに値するものとして扱われ、同じクールダウンを使用します。

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

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

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

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "usageStats": {
    "provider:profile": {
      "lastUsed": 1736160000000,
      "cooldownUntil": 1736160600000,
      "errorCount": 2
    }
  }
}
```

## 課金による無効化

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

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

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "usageStats": {
    "provider:profile": {
      "disabledUntil": 1736178000000,
      "disabledReason": "billing"
    }
  }
}
```

デフォルト:

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

## モデルフォールバック

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

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

## 関連設定

次については [Gateway 設定](/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` のルーティング

モデル選択とフォールバックの全体像については [Models](/concepts/models) を参照してください。