SaaS・IT

Claude Code fallbackModel設定でAPI障害対策｜実装事例

Claude Code v2.1.166で追加されたfallbackModelの設定方法と、529 Overload時に自動でバックアップモデルへ切り替える障害対策を公式docs準拠で解説します。

Claude Code fallbackModel設定でAPI障害対策｜実装事例

結論：Claude Code v2.1.166から利用できるfallbackModel機能を設定すると、プライマリモデルの過負荷・利用不可時に自動でバックアップモデルへ切り替わり、エージェントの中断リスクを大幅に下げられます。

  • 要点1：fallbackModelは重複排除後で最大3モデルのチェーンを設定可能。設定ファイル（settings.json）またはCLIフラグ（--fallback-model）の2通りで有効化できる（Anthropic公式docs 2026年6月）。
  • 要点2：切り替えは「現在のターンのみ」有効で、次のメッセージではプライマリモデルを最初に再試行する設計。ユーザー操作不要で自動フォールバックする。
  • 要点3：認証・課金・レート制限・リクエストサイズ・トランスポートのエラーはフォールバック対象外。「過負荷・利用不可・再試行不可能なサーバーエラー」のみが切り替えをトリガーする。

対象読者：Claude Codeを社内自動化・CI/CDパイプラインに組み込んでいるエンジニア・SRE・DevOpsエンジニア。

今日やること：本記事の設定JSON例を手元の~/.claude/settings.jsonにコピーして、fallbackModelを有効化する。

背景：エンタープライズ導入で多い障害は「過負荷（Overload）」

Claude Codeを業務自動化・CI/CDに組み込む企業が増えるにつれて、「本番パイプラインが突然止まった」という相談が増えている。

原因のひとつが API過負荷（Overload） である。Anthropic APIは高負荷時に一時的に過負荷状態になり、リクエストを拒否することがある。従来のClaude Codeはこの場合にエラーを返してセッションを中断していた。

Claude Code v2.1.166（2026年6月・Week 24）で、fallbackModelが導入された（出典：Anthropic公式「Week 24・June 8–12, 2026」code.claude.com/docs/ja/whats-new/2026-w24）。

この機能により、プライマリモデルが過負荷・利用不可の場合に、あらかじめ定義したバックアップモデルチェーンへ自動で切り替えられるようになった。

fallbackModelの仕様（Anthropic公式docs準拠）

以下はAnthropicの公式ドキュメント（code.claude.com/docs/ja/model-config#fallback-model-chains）に基づく仕様の要約である。

仕様項目 内容
最大フォールバック数 重複排除後で3モデル（余分なエントリは無視）
切り替えスコープ 現在のターンのみ。次のメッセージではプライマリを最初に再試行
トリガー条件 過負荷・利用不可・再試行不可能なサーバーエラー
非トリガー条件 認証・課金・レート制限・リクエストサイズ・トランスポートエラー
切り替え通知 切り替え時にセッション内へ通知が表示される（自動・ユーザー操作不要）
エイリアス対応 "default"、"sonnet"、"haiku"等のエイリアスも使用可
到達不能モデルの挙動 スキップして次の要素に進む
availableModels連携 許可リスト外のモデルはチェーン読込時にドロップされ、試行されない

実装方法：2通りの設定

方法1：settings.jsonで永続設定（推奨）

// ~/.claude/settings.json（ユーザーレベル設定）
// または .claude/settings.json（プロジェクトレベル設定）
{
  "model": "claude-opus-4-8",
  "fallbackModel": [
    "claude-sonnet-4-6",
    "claude-haiku-4-5"
  ]
}

上記の設定では、claude-opus-4-8が過負荷・利用不可の場合にclaude-sonnet-4-6を試み、それも駄目ならclaude-haiku-4-5に切り替わる。

方法2：CLIフラグで1セッション限定（テスト・検証時）

# カンマ区切りで複数モデルを指定
claude --fallback-model sonnet,haiku

# または単一モデルを指定
claude --model opus --fallback-model sonnet

CLIフラグ（--fallback-model）はsettings.jsonのfallbackModel設定より優先される。

エンタープライズ向け設定パターン

パターンA：コスト重視（Sonnet中心・Haikuへ降下）

日常的な自動化タスク（書類生成・コードレビュー補助など）で、コストを抑えたい場合。

{
  "model": "claude-sonnet-4-6",
  "fallbackModel": [
    "claude-haiku-4-5",
    "default"
  ]
}

"default"エイリアスは、アカウントタイプに応じたデフォルトモデルに展開される（Max・Team Premium・Enterprise従量課金・Anthropic APIはOpus 4.8、Pro・Team Standard・Enterpriseサブスク席はSonnet 4.6 など。出典：code.claude.com/docs/ja/model-config#default-model-setting）。

パターンB：品質重視（Opus中心・Sonnetへ降下）

複雑なリファクタリング・アーキテクチャ設計タスクで品質を優先し、障害時はSonnetで継続する場合。

{
  "model": "claude-opus-4-8",
  "fallbackModel": [
    "claude-sonnet-4-6",
    "claude-haiku-4-5"
  ]
}

パターンC：マネージドデプロイ（Enterprise管理者設定）

エンタープライズ管理者がavailableModelsとfallbackModelを組み合わせて、ユーザーの利用モデルを制限しつつ冗長性を確保する場合。

// 管理設定（managed / policy settings）
{
  "availableModels": ["claude-sonnet-4-6", "claude-haiku-4-5"],
  "enforceAvailableModels": true,
  "fallbackModel": ["claude-haiku-4-5"]
}

注意：availableModelsで許可されていないモデルがfallbackModelに含まれる場合、チェーン読込時にドロップされる（Anthropic公式docs準拠）。なおenforceAvailableModelsはClaude Code v2.1.175以降で利用できる。

パターンD：CI/CDパイプライン組み込み

GitHub Actions等のCI/CD環境では、--fallback-modelフラグをワークフロー設定に含める。

# .github/workflows/claude-review.yml（例）
name: Claude Code Review
on: [pull_request]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run Claude Code Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          claude -p "このPRの変更をレビューして、バグと改善点を指摘してください。" \
            --model sonnet \
            --fallback-model haiku \
            --output-format text

実装コード：fallbackModel設定を検証するスクリプト

#!/usr/bin/env python3
"""
fallbackModel設定確認スクリプト
Claude Code v2.1.166以降 / 想定シナリオ
実際の過負荷を意図的に発生させることは推奨しないため、
settings.json の設定確認と軽量な動作確認に使用する
"""
import subprocess
import json
import os
from pathlib import Path

def check_fallback_config(settings_file: str = None) -> dict:
    """現在の fallbackModel 設定を確認する"""
    if settings_file is None:
        settings_file = os.path.expanduser("~/.claude/settings.json")

    path = Path(settings_file)
    if not path.exists():
        return {"status": "file_not_found", "fallbackModel": []}

    with open(path, "r", encoding="utf-8") as f:
        settings = json.load(f)

    return {
        "status": "ok",
        "model": settings.get("model", "default"),
        "fallbackModel": settings.get("fallbackModel", []),
        "settings_path": str(path),
    }

def run_with_fallback_test(prompt: str, model: str, fallback: list) -> dict:
    """
    --fallback-model フラグ付きで Claude Code を実行し、
    標準出力とリターンコードを確認する。
    本番運用では環境変数で API キーを安全に管理すること。
    """
    fallback_str = ",".join(fallback)
    cmd = [
        "claude", "-p", prompt,
        "--model", model,
        "--fallback-model", fallback_str,
        "--output-format", "text",
    ]
    result = subprocess.run(cmd, capture_output=True, text=True, timeout=120)
    return {
        "returncode": result.returncode,
        "stdout": result.stdout[:500],
        "stderr": result.stderr[:200],
        "cmd": " ".join(cmd),
    }

if __name__ == "__main__":
    config = check_fallback_config()
    print("=== 現在の fallbackModel 設定 ===")
    print(json.dumps(config, ensure_ascii=False, indent=2))

    print("\n=== 動作確認テスト ===")
    result = run_with_fallback_test(
        prompt="「こんにちは」と返してください。",
        model="sonnet",
        fallback=["haiku"],
    )
    print(f"returncode: {result['returncode']}")
    print(f"応答: {result['stdout'][:100]}")
    if result["returncode"] != 0:
        print(f"エラー: {result['stderr']}")

fallbackModelの落とし穴と回避策

❌ 落とし穴1：認証エラー・レート制限はフォールバックしない

レート制限（Too Many Requests）や認証エラー（Unauthorized）はフォールバックのトリガーにならない。これらはユーザー側のAPI設定・クォータの問題であり、別モデルに切り替えても解決しない。

⭕ 回避策：レート制限対策はExponential Backoffを実装する。認証エラーはAPIキーの設定を確認する。fallbackModelはあくまで「Anthropic側の一時的な過負荷・利用不可」への対応策と理解する。

❌ 落とし穴2：availableModelsとfallbackModelの組み合わせでモデルがドロップされる

エンタープライズ管理者がavailableModels: ["haiku"]のみを許可している環境でfallbackModel: ["sonnet", "haiku"]を設定すると、sonnetがドロップされチェーンが["haiku"]のみになる。

⭕ 回避策：管理者はfallbackModelチェーンで使用したいモデルをすべてavailableModelsに含める。ユーザーは自分のチェーン設定が管理者の制限に引っかかっていないかを/modelコマンドで確認する。

❌ 落とし穴3：フォールバック先モデルの品質差を考慮していない

Opusで動かす前提で設計したプロンプトが、Haikuへのフォールバック時に品質が落ちることがある。「とりあえず動いた」状態で誤った出力を下流処理に渡してしまうリスクがある。

⭕ 回避策：フォールバック先モデルでも最低限のアウトプット品質を確認するバリデーション処理を実装する。出力JSONのスキーマ検証や、必須フィールドの存在チェックを自動化する。

❌ 落とし穴4：CLIフラグがsettings.jsonを上書きすることを知らない

--fallback-modelフラグはsettings.jsonのfallbackModelより優先される。CI/CDで--fallback-modelを指定していると、ローカルのsettings.jsonの設定が反映されない。

⭕ 回避策：環境別の設定を明文化する。CIではCLIフラグ、ローカルではsettings.json、という使い分けルールをチームで共有する。

定量効果の試算（想定シナリオ・参考値）

以下は1日100回Claude Codeを呼び出す自動化パイプラインを持つ開発チームの想定試算である。実際の効果はAPI利用状況・Anthropic側の負荷状況によって異なる。

シナリオ fallbackModel未設定 fallbackModel設定後（試算）
過負荷発生時の対応 手動再起動・アラート対応が必要 自動フォールバックで継続
パイプライン中断リスク 高（過負荷頻度に依存） 低（フォールバックチェーンが機能する間）
担当者の対応工数（目安） 1回あたり15〜30分 設定のみで継続的な過負荷対応

注意：Anthropic側の過負荷頻度・継続時間は予測できない。fallbackModelはあくまで一時的な切り替えであり、長期的な過負荷に対してはキャッシュ戦略や非同期リトライの実装も検討すること。

よくある質問（FAQ）

Q1. fallbackModelはどのバージョンから使えますか？
A. Claude Code v2.1.166以降で利用できます（2026年6月・Week 24）。古いバージョンを使用している場合はclaude updateでアップデートしてください（出典：Anthropic公式「Week 24・June 8–12, 2026」）。

Q2. フォールバックが発生したことを確認できますか？
A. インタラクティブセッションでは切り替え時にセッション内へ通知が表示されます。非インタラクティブモード（-pフラグ）では--output-format jsonで出力し、実際に使われたモデルを確認する運用が便利です（出力フィールドの詳細は手元のバージョンで確認してください）。

Q3. Bedrock/Vertex AI経由でもfallbackModelは機能しますか？
A. これらのプロバイダーではモデルIDがプロバイダー固有の形式（ARNやデプロイメント名）になります。エイリアス（"sonnet"など）ではなく完全なモデルIDの指定が必要になる場合があるため、各プロバイダー向けのモデル指定方法を公式docsで確認してください。

Q4. 過負荷時のfallbackModelと、Fable 5の安全分類器フォールバックは別物ですか？
A. はい、別物です。fallbackModelは「過負荷・利用不可」という可用性ベースの切り替えを制御します。一方、Anthropic公式docsでいう「自動モデルフォールバック」は、Fable 5の安全分類器がリクエストをフラグした際にOpusへ切り替えるコンテンツベースの挙動です。両者は独立して動作します（出典：code.claude.com/docs/ja/model-config）。

Q5. フォールバック後に元のモデルに戻るのはいつですか？
A. フォールバックは現在のターンのみ有効です。次のメッセージ送信時には、Claude Codeがプライマリモデルを最初に再試行します。プライマリが回復していれば自動で元に戻ります（Anthropic公式docs準拠）。

まとめ：今日から始める3つのアクション

  1. settings.jsonにfallbackModelを追加する：claude updateでv2.1.166以降に更新してから、~/.claude/settings.jsonに"fallbackModel": ["sonnet", "haiku"]を追記する（1分で完了）。
  2. CIパイプラインに--fallback-modelを追加する：自動化スクリプト・GitHub Actionsのclaudeコマンドに--fallback-model sonnet,haikuを追加する。
  3. フォールバック先モデルでのアウトプット品質を確認する：本番前にHaikuフォールバック時のアウトプットが下流処理に問題を起こさないかを検証する。

著者プロフィール

佐藤傑（さとう・すぐる）。株式会社Uravation代表取締役。X（@SuguruKun_ai）フォロワー約10万人。100社以上の企業向けAI研修・導入支援。著書『AIエージェント仕事術』（SBクリエイティブ）。

Uravation Claude Code 個別指導・導入支援

Claude Codeのエンタープライズ導入・自動化設計でお困りの方へ。fallbackModel設定・CI/CD組み込み・セキュリティ設計まで、個別相談を承っています。

無料相談はこちら →

関連して読む記事

参照・確認ソース

  1. Anthropic公式「Week 24・June 8–12, 2026（v2.1.166〜v2.1.176）」— fallbackModel、–safe-mode、/cd、サブエージェントネストの仕様（code.claude.com/docs/ja/whats-new/2026-w24）
  2. Anthropic公式「モデル設定 — フォールバックモデルチェーン」— fallbackModelの詳細仕様・設定例・トリガー条件・availableModelsとの連携（code.claude.com/docs/ja/model-config#fallback-model-chains）
  3. Anthropic公式「モデル設定 — デフォルトモデル設定」— プランごとのデフォルトモデル（Opus 4.8 / Sonnet 4.6）の確認（code.claude.com/docs/ja/model-config#default-model-setting）

あわせて読みたい

Next Step

この事例を、自社の業務に置き換える。

対象業務、利用データ、評価基準、社内展開の順番まで整理すると、AI開発ツール導入の失敗を減らせます。

導入を相談する

Related Cases

Claude Codeでモノリス分割・マイクロサービス移行【2026年最新】
SaaS・IT

Claude Codeでモノリス分割・マイクロサービス移行【2026年最新】

Claude Codeでモノリスの依存関係を可視化し、Strangler Figパターンで段階的にマイクロサービス化する手順をコード例付きで解説（想定シナリオ）。

読む
【2026年最新】旅行代理店Claude Code活用5ステップ
SaaS・IT

【2026年最新】旅行代理店Claude Code活用5ステップ

旅行代理店 Claude Codeで行程表・見積書・旅行条件書の作成負担を減らす設計を、法令確認と5ステップで解説。

読む
【2026年最新】引越し業Claude Code実務7選
SaaS・IT

【2026年最新】引越し業Claude Code実務7選

引越し業 Claude Codeで訪問見積書、作業指示書、繁忙期の配車・シフト調整を効率化する実装手順を解説。

読む