From 175885218e82f99fb3cb58335640b7d4f4b7c2f8 Mon Sep 17 00:00:00 2001 From: aqilaziz Date: Fri, 15 May 2026 07:29:42 +0700 Subject: [PATCH] fix(docs): align fallback provider config examples Use the current top-level fallback_providers list in fallback docs and keep fallback_model documented only as the legacy compatibility shape. Also align cron and delegation fallback coverage with current runtime behavior. Closes #19691 Co-authored-by: Codex --- website/docs/user-guide/configuration.md | 6 +- .../user-guide/features/fallback-providers.md | 74 +++++++++---------- 2 files changed, 40 insertions(+), 40 deletions(-) diff --git a/website/docs/user-guide/configuration.md b/website/docs/user-guide/configuration.md index ecde153a9d..d74587432d 100644 --- a/website/docs/user-guide/configuration.md +++ b/website/docs/user-guide/configuration.md @@ -864,7 +864,7 @@ Available providers for auxiliary tasks: `auto`, `main`, plus any provider in th ::: :::warning `"main"` is for auxiliary tasks only -The `"main"` provider option means "use whatever provider my main agent uses" — it's only valid inside `auxiliary:`, `compression:`, and `fallback_model:` configs. It is **not** a valid value for your top-level `model.provider` setting. If you use a custom OpenAI-compatible endpoint, set `provider: custom` in your `model:` section. See [AI Providers](/integrations/providers) for all main model provider options. +The `"main"` provider option means "use whatever provider my main agent uses" — it's only valid inside `auxiliary:`, `compression:`, and primary fallback entries (`fallback_providers:` or legacy `fallback_model:`). It is **not** a valid value for your top-level `model.provider` setting. If you use a custom OpenAI-compatible endpoint, set `provider: custom` in your `model:` section. See [AI Providers](/integrations/providers) for all main model provider options. ::: ### Full auxiliary config reference @@ -934,7 +934,7 @@ Each auxiliary task has a configurable `timeout` (in seconds). Defaults: vision ::: :::info -Context compression has its own `compression:` block for thresholds and an `auxiliary.compression:` block for model/provider settings — see [Context Compression](#context-compression) above. The fallback model uses a `fallback_model:` block — see [Fallback Model](/integrations/providers#fallback-providers). All three follow the same provider/model/base_url pattern. +Context compression has its own `compression:` block for thresholds and an `auxiliary.compression:` block for model/provider settings — see [Context Compression](#context-compression) above. The primary fallback chain uses a top-level `fallback_providers:` list — see [Fallback Providers](/integrations/providers#fallback-providers). All three follow the same provider/model/base_url pattern. ::: ### OpenRouter routing & Pareto Code for auxiliary tasks @@ -977,7 +977,7 @@ AUXILIARY_VISION_MODEL=openai/gpt-4o ### Provider Options -These options apply to **auxiliary task configs** (`auxiliary:`, `compression:`, `fallback_model:`), not to your main `model.provider` setting. +These options apply to **auxiliary task configs** (`auxiliary:`, `compression:`) and primary fallback entries (`fallback_providers:` or legacy `fallback_model:`), not to your main `model.provider` setting. | Provider | Description | Requirements | |----------|-------------|-------------| diff --git a/website/docs/user-guide/features/fallback-providers.md b/website/docs/user-guide/features/fallback-providers.md index 0dc972e27a..7eaab0ea8a 100644 --- a/website/docs/user-guide/features/fallback-providers.md +++ b/website/docs/user-guide/features/fallback-providers.md @@ -29,18 +29,18 @@ hermes fallback `hermes fallback` reuses the provider picker from `hermes model` — same provider list, same credential prompts, same validation. Use the subcommands `add`, `list` (alias `ls`), `remove` (alias `rm`), and `clear` to manage the chain. Changes persist under the top-level `fallback_providers:` list in `config.yaml`. -If you'd rather edit the YAML directly, add a `fallback_model` section to `~/.hermes/config.yaml`: +If you'd rather edit the YAML directly, add a top-level `fallback_providers` list to `~/.hermes/config.yaml`: ```yaml -fallback_model: - provider: openrouter - model: anthropic/claude-sonnet-4 +fallback_providers: + - provider: openrouter + model: anthropic/claude-sonnet-4 ``` -Both `provider` and `model` are **required**. If either is missing, the fallback is disabled. +Each entry requires both `provider` and `model`. Entries missing either field are ignored. :::note `fallback_model` vs `fallback_providers` -`fallback_model` (singular) is the legacy single-fallback key — Hermes still honors it for back-compat. `fallback_providers` (plural, list) supports multiple fallbacks tried in order; `hermes fallback` writes to this key. When both are set, Hermes merges them with `fallback_providers` taking priority. +`fallback_providers` (plural, list) is the current config shape and supports multiple fallbacks tried in order. `fallback_model` (singular) is the legacy single-fallback key — Hermes still honors it for back-compat, but `hermes fallback` writes the current `fallback_providers` key and migrates legacy config on write. When both are set, `fallback_providers` takes priority. ::: ### Supported Providers @@ -90,11 +90,11 @@ Both `provider` and `model` are **required**. If either is missing, the fallback For a custom OpenAI-compatible endpoint, add `base_url` and optionally `key_env`: ```yaml -fallback_model: - provider: custom - model: my-local-model - base_url: http://localhost:8000/v1 - key_env: MY_LOCAL_KEY # env var name containing the API key +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 ``` ### When Fallback Triggers @@ -128,9 +128,9 @@ model: provider: anthropic default: claude-sonnet-4-6 -fallback_model: - provider: openrouter - model: anthropic/claude-sonnet-4 +fallback_providers: + - provider: openrouter + model: anthropic/claude-sonnet-4 ``` **Nous Portal as fallback for OpenRouter:** @@ -139,25 +139,25 @@ model: provider: openrouter default: anthropic/claude-opus-4 -fallback_model: - provider: nous - model: nous-hermes-3 +fallback_providers: + - provider: nous + model: nous-hermes-3 ``` **Local model as fallback for cloud:** ```yaml -fallback_model: - provider: custom - model: llama-3.1-70b - base_url: http://localhost:8000/v1 - key_env: LOCAL_API_KEY +fallback_providers: + - provider: custom + model: llama-3.1-70b + base_url: http://localhost:8000/v1 + key_env: LOCAL_API_KEY ``` **Codex OAuth as fallback:** ```yaml -fallback_model: - provider: openai-codex - model: gpt-5.3-codex +fallback_providers: + - provider: openai-codex + model: gpt-5.3-codex ``` ### Where Fallback Works @@ -166,12 +166,12 @@ fallback_model: |---------|-------------------| | CLI sessions | ✔ | | Messaging gateway (Telegram, Discord, etc.) | ✔ | -| Subagent delegation | ✘ (subagents do not inherit fallback config) | -| Cron jobs | ✘ (run with a fixed provider) | +| Subagent delegation | ✔ (subagents inherit the parent fallback chain) | +| Cron jobs | ✔ (cron agents inherit configured fallback providers) | | Auxiliary tasks (vision, compression) | ✘ (use their own provider chain — see below) | :::tip -There are no environment variables for `fallback_model` — it is configured exclusively through `config.yaml`. This is intentional: fallback configuration is a deliberate choice, not something a stale shell export should override. +There are no environment variables for the primary fallback chain — configure it exclusively through `config.yaml` or `hermes fallback`. This is intentional: fallback configuration is a deliberate choice, not something a stale shell export should override. ::: --- @@ -252,20 +252,20 @@ auxiliary: base_url: null # Custom OpenAI-compatible endpoint ``` -And the fallback model uses: +And the primary fallback chain uses: ```yaml -fallback_model: - provider: openrouter - model: anthropic/claude-sonnet-4 - # base_url: http://localhost:8000/v1 # Optional custom endpoint +fallback_providers: + - provider: openrouter + model: anthropic/claude-sonnet-4 + # base_url: http://localhost:8000/v1 # Optional custom endpoint ``` All three — auxiliary, compression, fallback — work the same way: set `provider` to pick who handles the request, `model` to pick which model, and `base_url` to point at a custom endpoint (overrides provider). ### Provider Options for Auxiliary Tasks -These options apply to `auxiliary:`, `compression:`, and `fallback_model:` configs only — `"main"` is **not** a valid value for your top-level `model.provider`. For custom endpoints, use `provider: custom` in your `model:` section (see [AI Providers](/integrations/providers)). +These options apply to `auxiliary:`, `compression:`, and `fallback_providers:` entries only — `"main"` is **not** a valid value for your top-level `model.provider`. For custom endpoints, use `provider: custom` in your `model:` section (see [AI Providers](/integrations/providers)). | Provider | Description | Requirements | |----------|-------------|-------------| @@ -362,7 +362,7 @@ If no provider is available for compression, Hermes drops middle conversation tu ## Delegation Provider Override -Subagents spawned by `delegate_task` do **not** use the primary fallback model. However, they can be routed to a different provider:model pair for cost optimization: +Subagents spawned by `delegate_task` inherit the parent agent's primary fallback chain. You can still route subagents to a different primary provider:model pair for cost optimization: ```yaml delegation: @@ -378,7 +378,7 @@ See [Subagent Delegation](/user-guide/features/delegation) for full configuratio ## Cron Job Providers -Cron jobs run with whatever provider is configured at execution time. They do not support a fallback model. To use a different provider for cron jobs, configure `provider` and `model` overrides on the cron job itself: +Cron jobs inherit your configured `fallback_providers` chain (or legacy `fallback_model`) when they create an agent. To use a different primary provider for a cron job, configure `provider` and `model` overrides on the cron job itself: ```python cronjob( @@ -398,7 +398,7 @@ See [Scheduled Tasks (Cron)](/user-guide/features/cron) for full configuration d | Feature | Fallback Mechanism | Config Location | |---------|-------------------|----------------| -| Main agent model | `fallback_model` in config.yaml — per-turn failover on errors (primary restored each turn) | `fallback_model:` (top-level) | +| Main agent model | `fallback_providers` in config.yaml — per-turn failover on errors (primary restored each turn) | `fallback_providers:` (top-level list) | | Auxiliary tasks (any) — auto users | Full auto-detection chain (main agent model first, then provider chain) on capacity errors | `auxiliary..provider: auto` | | Auxiliary tasks (any) — explicit provider | `fallback_chain` (if set) → main agent model → warn + raise, on capacity errors only | `auxiliary..fallback_chain` | | Vision | Layered (see above) + internal OpenRouter retry | `auxiliary.vision` |