フォールバックプロバイダー

Hermes Agent には、プロバイダー側で問題が起きてもセッションを止めないための仕組みが 3 層あります。

1. 認証情報プール — *同じ*プロバイダーの複数の API キーを順に使い回します（最初に試されます）
2. メインモデルのフォールバック — メインのモデルが失敗したときに、*別の* provider:model へ自動で切り替えます
3. 補助タスクのフォールバック — 画像認識や圧縮といった脇のタスクについて、独立にプロバイダーを解決します

認証情報プールは同一プロバイダー内でのキーの持ち回り（たとえば OpenRouter のキーを複数持つ場合）を担当します。このページで扱うのは、プロバイダーをまたぐフォールバックです。どちらも任意の機能で、互いに独立して動きます。

メインモデルのフォールバック

メインの LLM プロバイダーでエラーが起きたとき — レート制限、サーバー過負荷、認証失敗、接続断など — Hermes は会話を失うことなく、セッションの途中で控えの provider:model のペアへ自動的に切り替えられます。

設定

いちばん簡単なのは、対話式のマネージャーを使う方法です。

hermes fallback

hermes fallback は hermes model と同じプロバイダー選択画面をそのまま使います。プロバイダーの一覧も、認証情報の入力も、検証のしかたも同じです。連鎖の管理には add、list（別名 ls）、remove（別名 rm）、clear のサブコマンドを使います。変更内容は config.yaml のトップレベルにある fallback_providers: のリストへ保存されます。

YAML を直接書きたい場合は、~/.hermes/config.yaml のトップレベルに fallback_providers のリストを追加します。

fallback_providers:
  - provider: openrouter
    model: anthropic/claude-sonnet-4

各エントリーには provider と model の両方が必要です。どちらかが欠けているエントリーは無視されます。

対応プロバイダー

独自エンドポイントへのフォールバック

OpenAI 互換の独自エンドポイントを使う場合は、base_url と、必要に応じて key_env を追加します。

fallback_providers:
  - provider: custom
    model: my-local-model
    base_url: http://localhost:8000/v1
    key_env: MY_LOCAL_KEY            # env var name containing the API key

フォールバックが働く条件

メインのモデルが次のかたちで失敗したとき、フォールバックが自動的に動きます。

• レート制限（HTTP 429） — 再試行を使い切ったあと
• サーバーエラー（HTTP 500、502、503） — 再試行を使い切ったあと
• 認証失敗（HTTP 401、403） — ただちに（再試行しても意味がないため）
• 見つからない（HTTP 404） — ただちに
• 不正な応答 — API が壊れた応答や空の応答を繰り返し返したとき

作動すると、Hermes は次の順に処理します。

1. 控えのプロバイダーの認証情報を解決します
2. 新しい API クライアントを組み立てます
3. モデル・プロバイダー・クライアントをその場で差し替えます
4. 再試行のカウンターをリセットし、会話を続けます

切り替えは途切れません。会話の履歴もツール呼び出しもコンテキストもそのまま保たれます。エージェントは中断したところから、モデルだけを変えて続きを進めます。

例

Anthropic ネイティブの控えに OpenRouter を置く:

model:
  provider: anthropic
  default: claude-sonnet-4-6

fallback_providers:
  - provider: openrouter
    model: anthropic/claude-sonnet-4

OpenRouter の控えに Nous Portal を置く:

model:
  provider: openrouter
  default: anthropic/claude-opus-4

fallback_providers:
  - provider: nous
    model: nous-hermes-3

クラウドの控えにローカルのモデルを置く:

fallback_providers:
  - provider: custom
    model: llama-3.1-70b
    base_url: http://localhost:8000/v1
    key_env: LOCAL_API_KEY

控えに Codex OAuth を置く:

fallback_providers:
  - provider: openai-codex
    model: gpt-5.3-codex

フォールバックが効く場所

補助タスクのフォールバック

Hermes は脇のタスクに、別の軽量なモデルを使います。タスクごとに独自のプロバイダー解決の連鎖があり、それがそのまま組み込みのフォールバックとして働きます。

独立にプロバイダーを解決するタスク

自動判定の連鎖

タスクのプロバイダーが "auto"（既定値）になっている場合、Hermes はまずその補助タスクにメインのプロバイダーとメインのモデルを試します。その経路が使えないか、あとで容量系のエラーで失敗した場合、Hermes は組み込みの探索連鎖を使う前に、利用者が設定したフォールバックの方針を尊重します。

Main provider + main model → auxiliary.<task>.fallback_chain →
fallback_providers / fallback_model → built-in auxiliary discovery chain

タスクごとの連鎖がいちばん的確なので、書かれていればそれが優先されます。トップレベルの fallback_providers の連鎖はメインのエージェントが使うのと同じ方針なので、無料のみ・同一プロバイダーのみといったフォールバックの決まりごとも、auto の補助タスクにそのまま適用されます。

組み込みのテキスト用探索連鎖（圧縮、Web 抽出、タイトル生成など）:

OpenRouter → Nous Portal → Custom endpoint → Codex OAuth →
API-key providers (z.ai, Kimi, MiniMax, Xiaomi MiMo, Hugging Face, Anthropic) → give up

組み込みの画像認識用探索連鎖:

Main provider (if vision-capable) → OpenRouter → Nous Portal →
Codex OAuth → Anthropic → Custom endpoint → give up

これらの組み込みの連鎖は、タスクごとの方針もメインのフォールバック方針も宣言していない人のための、便宜的な受け皿です。

補助プロバイダーの設定

タスクはそれぞれ独立に config.yaml で設定できます。

auxiliary:
  vision:
    provider: "auto"              # auto | openrouter | nous | codex | main | anthropic
    model: ""                     # e.g. "openai/gpt-4o"
    base_url: ""                  # direct endpoint (takes precedence over provider)
    api_key: ""                   # API key for base_url

  compression:
    provider: "auto"
    model: ""
    fallback_chain:              # optional, task-specific fallback policy
      - provider: openrouter
        model: inclusionai/ring-2.6-1t:free

  skills_hub:
    provider: "auto"
    model: ""

  mcp:
    provider: "auto"
    model: ""

上のタスクはどれも同じ provider / model / base_url のかたちに従います。各タスクは自前の fallback_chain を宣言することもできます。省略した場合、provider: auto は Hermes の組み込みの補助用探索連鎖より前に、トップレベルの fallback_providers の連鎖を使います。

コンテキスト圧縮は auxiliary.compression の下で設定します。

auxiliary:
  compression:
    provider: main                                    # Same provider options as other auxiliary tasks
    model: google/gemini-3-flash-preview
    base_url: null                                    # Custom OpenAI-compatible endpoint

メインのフォールバック連鎖はこう書きます。

fallback_providers:
  - provider: openrouter
    model: anthropic/claude-sonnet-4
    # base_url: http://localhost:8000/v1             # Optional custom endpoint

補助・圧縮・フォールバックの 3 つは、どれも同じ考え方で動きます。provider で誰にリクエストを処理させるかを選び、model でどのモデルを使うかを選び、base_url で独自のエンドポイントを指す（こちらはプロバイダーの指定を上書きします）というかたちです。

補助タスクで指定できるプロバイダー

ここに挙げる選択肢が使えるのは auxiliary:、compression:、fallback_providers: のエントリーだけです。トップレベルの model.provider に "main" を指定することはできません。独自エンドポイントを使いたい場合は、model: のセクションで provider: custom を指定してください（AI プロバイダーを参照）。

エンドポイントの直接指定

どの補助タスクでも、base_url を設定するとプロバイダーの解決を丸ごと飛ばして、そのエンドポイントへ直接リクエストを送ります。

auxiliary:
  vision:
    base_url: "http://localhost:1234/v1"
    api_key: "local-key"
    model: "qwen2.5-vl"

base_url は provider より優先されます。認証には設定された api_key が使われ、未設定なら OPENAI_API_KEY が使われます。独自エンドポイントに OPENROUTER_API_KEY が流用されることはありません。

補助タスクの容量エラーによるフォールバック

補助タスクのプロバイダーを明示的に指定した場合（たとえば auxiliary.vision.provider: glm）、Hermes はそれを利用者の希望として扱います。ただし、そのプロバイダーが容量エラー（HTTP 402 の支払い要求、HTTP 429 の日次クォータ枯渇、接続失敗）によってリクエストを物理的に処理できないときは、黙って失敗するのではなく、次の層をたどってフォールバックします。

1. 一次の補助プロバイダー — 利用者が設定したもの（常に最初に試されます）
2. auxiliary.<task>.fallback_chain — タスクごとの上書きリスト（書いていれば）
3. メインエージェントのプロバイダーとモデル — 最後の安全網（連鎖を書いていなくても常に試されます）
4. 警告して再送出 — すべての層が失敗した場合、Hermes は WARNING レベルで Auxiliary <task>: ... all fallbacks exhausted を記録し、元のエラーを再送出します

一時的な HTTP 429 のレート制限（Retry-After: ...）は容量の問題ではなくリクエスト側の制約として扱われます。明示的なプロバイダー指定が尊重され、フォールバックのはしごは動きません。明示指定の門をくぐり抜けるのは、日次・月次のクォータ枯渇、支払いエラー、接続失敗だけです。

provider: auto を使っている（補助プロバイダーを明示していない）場合は、手順 2〜3 の代わりに従来の自動判定の連鎖が走ります。その最初の一歩がすでにメインエージェントのモデルなので、auto の利用者は設定ゼロで同じ結果を得られます。

任意: タスクごとのフォールバック連鎖

「まずメインエージェントのモデル」とは違う順番にしたい場合は、fallback_chain を明示的に設定します。各エントリーには少なくとも provider が必要で、model、base_url、api_key は任意です。

auxiliary:
  vision:
    provider: glm
    model: glm-4v-flash
    fallback_chain:
      - provider: openrouter
        model: google/gemini-3-flash-preview
      - provider: nous
        model: anthropic/claude-sonnet-4

  compression:
    provider: openrouter
    fallback_chain:
      - provider: openai
        model: gpt-4o-mini
        timeout: 240            # optional — this candidate's own deadline (seconds)

フォールバックを効かせるために fallback_chain を設定する必要はありません。メインエージェントによる安全網は設定の有無にかかわらず動きます。既定とは違う順番にしたいときにだけ使ってください。

fallback_chain の各エントリーは、自分の timeout（秒）を宣言することもできます。宣言しない場合、控えの候補はタスク全体のタイムアウトを引き継ぎますが、その値は一次のプロバイダーに合わせて調整されているかもしれません。エントリーごとに timeout を書けば、遅くても確実な控え（たとえば大きなコンテキストを扱う要約器）に、一次側の時計で打ち切られることなく必要な時間を与えられます。

フォールバックを引き起こすプロバイダーのクォータエラー

Hermes は次のものを、402 のクレジット枯渇と同等の容量問題として扱います（一時的なレート制限としては扱いません）。

• Bedrock / LiteLLM: Too many tokens per day、daily limit、tokens per day
• Vertex AI / GCP: quota exceeded、resource exhausted、RESOURCE_EXHAUSTED
• 汎用: daily quota、quota_exceeded

使っているプロバイダーが日次クォータ枯渇を別の文言で返していて、Hermes がフォールバックしない場合、それは不具合です。エラー文字列をそのまま添えて issue を立ててください。

コンテキスト圧縮のフォールバック

コンテキスト圧縮は、要約をどのモデルとプロバイダーに任せるかを auxiliary.compression の設定ブロックで決めます。

auxiliary:
  compression:
    provider: "auto"                              # auto | openrouter | nous | main
    model: "google/gemini-3-flash-preview"

圧縮に使えるプロバイダーが 1 つもない場合、Hermes はセッションを落とすのではなく、要約を作らずに会話の途中のターンを捨てます。

委任時のプロバイダー上書き

delegate_task で立ち上がったサブエージェントは、親エージェントのメインのフォールバック連鎖を引き継ぎます。そのうえで、コストを抑えるためにサブエージェントだけ別の provider:model のペアへ回すこともできます。

delegation:
  provider: "openrouter"                      # override provider for all subagents
  model: "google/gemini-3-flash-preview"      # override model
  # base_url: "http://localhost:1234/v1"      # or use a direct endpoint
  # api_key: "local-key"

設定の詳細はサブエージェントへの委任を参照してください。

cron ジョブのプロバイダー

cron ジョブはエージェントを作るとき、設定された fallback_providers の連鎖（または旧来の fallback_model）を引き継ぎます。cron ジョブだけ別のプロバイダーをメインにしたい場合は、そのジョブ自身に provider と model の上書きを設定します。

cronjob(
    action="create",
    schedule="every 2h",
    prompt="Check server status",
    provider="openrouter",
    model="google/gemini-3-flash-preview"
)

設定の詳細は定時タスク（cron）を参照してください。

まとめ