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

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 の両方が必要です。どちらかが欠けているエントリーは無視されます。

レート制限の応答が制限の解ける時刻を示している場合、メインはちょうどその時刻まで控えに回されます（何も示さないプロバイダーには、60 秒から 4 時間まで伸びていく指数的な待ち時間が適用されます）。必要なら、メインがすぐに使えるようになるときは切り替えないようにもできます。

fallback:
  min_switch_reset_seconds: 120   # 0 (default) = always switch

Gemini の控えのエントリーは gemini、google、google-gemini、google-ai-studio のどれでも書けます。 Google 純正の API エンドポイントでは、いずれも純正の Gemini クライアントを使い、 generationConfig.thinkingConfig の読み替えも行われます。OpenAI 互換の独自ベース URL を指定した場合は、 これまでどおり互換クライアントのほうを使います。

対応プロバイダー

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

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 が壊れた応答や空の応答を繰り返し返したとき。HTTP 200 で返ってきた本文でも、アシスタントの発言がルーターの Connect timeout, please try again later. だけで、生成したトークンが 0 なら、これも不正として数えます（ストリーミングかどうかを問わず、主となるやり取りでも、反復上限のまとめでも、補助的な呼び出しでも同じです）。そのため、そのまま答えとして見せずに再試行します。ストリーミング中の拒否（モデルが拒否用のチャンネルで理由を添えて断ること）は空の応答ではなく、最終結果の content_filter として扱われます。そのため再試行はせず、そのまま表示します。Anthropic 本来の通信では stop_reason: refusal が本文なしで届きます。Hermes はその応答の stop_details にある理由（区分と、あれば説明）を拒否のメッセージとログの行（native_stop_reason=… stop_details=…）に載せます。

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

1. 控えのプロバイダーの認証情報を解決します（key_cmd を使う名前付きの独自プロバイダーも含みます）
2. 新しい API クライアントを組み立てます。タイムアウトやリクエスト用クライアントの作り直しをまたいで、動的な認証情報の取得元は保たれます
3. モデル・プロバイダー・クライアントをその場で差し替えます
4. 控えのモデルに合わせて推論の深さを取り直します（そのモデルの agent.reasoning_overrides の項目、なければ全体の agent.reasoning_effort）
5. 再試行のカウンターをリセットし、会話を続けます

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

同じ取り直しは、最初のリクエストの前にメインのプロバイダーの認証が失敗して CLI が起動時にフォールバックしたときにも起きます。控えのモデルには、メイン側のものではなく、そのモデル自身に設定された深さが渡ります。hermes chat --reasoning <level> を明示している場合は、この起動時の切り替えをまたいでも保たれます。その実行についての利用者の意図だからです。

例

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.4

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

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

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

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

自動判定の連鎖

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

Main provider + main model → auxiliary.<task>.fallback_chain →
fallback_providers / fallback_model → skip the task (warn)

課金や使用量で失敗したときに一時的に外されるのは、失敗したその独自エンドポイントだけで、補助タスクの健全性のクールダウンの間だけです。custom として登録された経路がまとめて外れるわけではありません。ベース URL の違う健全なローカルのエンドポイントは、引き続き控えとしても、そのあとの自動の割り振りの先としても選ばれます。同じ独自エンドポイントの別名どうしは、健全性の状態を共有します。組み込みのプロバイダーは、これまでどおりアカウントを共有する形の健全性の確認を行います。

タスクごとの連鎖がいちばん的確なので、書かれていればそれが優先されます。トップレベルの 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

これらの組み込みの連鎖が動くのは、メインのプロバイダーが選ばれていないときだけです（model.provider: auto または未設定）。メインのプロバイダーを選んだあとは、メインの経路が使えず fallback_chain / fallback_providers も無い場合、補助タスクは警告を出して飛ばされます。たまたまログインしている別のプロバイダーを推測して使うことはしません。期限切れの xAI や Codex のセッションが、知らないうちに Nous Portal や OpenRouter の残高で課金されることがあってはならないからです。フォールバックが必要なら宣言してください。

補助プロバイダーの設定

タスクはそれぞれ独立に 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 はトップレベルの 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: ...）は容量の問題ではなくリクエスト側の制約として扱われます。明示的なプロバイダー指定が尊重され、フォールバックのはしごは動きません。明示指定の門をくぐり抜けるのは、日次・月次のクォータ枯渇、支払いエラー、接続失敗だけです。

明示したプロバイダーで認証エラー（HTTP 401）が起きた場合は、手順 2 だけをたどります。auxiliary.<task>.fallback_chain を書いていれば、その項目を順に試します（連鎖の途中の項目がリクエストの最中に落ちた場合は、次の項目へ引き継ぎます）。メインエージェントのモデルと自動判定の連鎖は参照しません。そのタスクをそれらに任せると宣言していないからです。連鎖がなければ、従来どおり認証エラーでそのタスクは失敗します。認証は認証情報の単位で効くので、同じプロバイダー名の連鎖の項目は飛ばされます。控えは別のプロバイダーに向けてください（providers: に別の項目を立てるのでも構いません）。

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.model / cron.model_provider でモデルを選びます。詳しくは定時タスク（cron）を参照してください。

まとめ