From 26da56fd53bd4bc8498b6abee590d64ccc3f735f Mon Sep 17 00:00:00 2001 From: Teknium <127238744+teknium1@users.noreply.github.com> Date: Wed, 19 Aug 2026 16:31:23 -0700 Subject: [PATCH] docs: tool provider selection follows the hermes tools pick (post #90317) --- website/docs/integrations/nous-portal.md | 15 ++++--- .../docs/reference/environment-variables.md | 2 +- website/docs/user-guide/configuration.md | 4 +- website/docs/user-guide/features/browser.md | 6 ++- .../user-guide/features/image-generation.md | 8 ++-- .../docs/user-guide/features/tool-gateway.md | 42 ++++++++++++------- website/docs/user-guide/features/tts.md | 10 +++-- .../docs/user-guide/features/web-search.md | 8 ++-- .../user-guide/messaging/whatsapp-cloud.md | 7 ++-- .../reference/environment-variables.md | 2 +- .../current/user-guide/features/browser.md | 2 +- .../user-guide/features/image-generation.md | 4 +- .../user-guide/features/tool-gateway.md | 40 +++++++++--------- 13 files changed, 86 insertions(+), 64 deletions(-) diff --git a/website/docs/integrations/nous-portal.md b/website/docs/integrations/nous-portal.md index 61098b3ef4..ffcbe49409 100644 --- a/website/docs/integrations/nous-portal.md +++ b/website/docs/integrations/nous-portal.md @@ -213,25 +213,24 @@ model: base_url: https://inference-api.nousresearch.com/v1 ``` -The Tool Gateway settings live under their respective tool sections: +The Tool Gateway settings live under their respective tool sections — each category has a single selection key, and picking **Nous Subscription** in `hermes tools` (or `hermes setup --portal`) writes the value `nous`: ```yaml web: - backend: firecrawl - use_gateway: true # web search/extract routes through Tool Gateway + backend: nous # web search/extract routes through Tool Gateway image_gen: - use_gateway: true + provider: nous tts: - provider: openai - use_gateway: true + provider: nous browser: - cloud_provider: browser-use - use_gateway: true + cloud_provider: nous ``` +The runtime always follows the stored selection — direct API keys left in `.env` are ignored while a category is set to `nous`, and picking a direct provider (e.g. `image_gen.provider: fal`) without its key produces a clear error rather than silently rerouting through the gateway. (Older configs used a legacy `use_gateway: true` flag; it is read as equivalent to `nous` but is no longer written.) + The OAuth refresh token is stored separately at `~/.hermes/auth.json` (not in `config.yaml` — credentials and configuration are kept separate by design). ## Token handling diff --git a/website/docs/reference/environment-variables.md b/website/docs/reference/environment-variables.md index da2bbb7a90..87efeef579 100644 --- a/website/docs/reference/environment-variables.md +++ b/website/docs/reference/environment-variables.md @@ -150,7 +150,7 @@ For native Anthropic auth, Hermes prefers Claude Code's own credential files whe | `BROWSER_USE_API_KEY` | Browser Use cloud browser API key ([browser-use.com](https://browser-use.com/)) | | `FIRECRAWL_BROWSER_TTL` | Firecrawl browser session TTL in seconds (default: 300) | | `BROWSER_CDP_URL` | Chrome DevTools Protocol URL for local browser (set via `/browser connect`, e.g. `ws://localhost:9222`) | -| `CAMOFOX_URL` | Camofox local anti-detection browser URL (default: `http://localhost:9377`) | +| `CAMOFOX_URL` | Camofox local anti-detection browser server address (default: `http://localhost:9377`). Address only — it does not select Camofox as the backend; pick Camofox in `hermes tools` (`browser.cloud_provider: camofox`) | | `CAMOFOX_API_KEY` | Optional bearer token sent as Authorization header to a remote/authenticated Camofox server | | `CAMOFOX_USER_ID` | Optional externally managed Camofox user ID for shared visible sessions | | `CAMOFOX_SESSION_KEY` | Optional Camofox session key used when creating tabs for `CAMOFOX_USER_ID` | diff --git a/website/docs/user-guide/configuration.md b/website/docs/user-guide/configuration.md index e937e2d59d..391898fbda 100644 --- a/website/docs/user-guide/configuration.md +++ b/website/docs/user-guide/configuration.md @@ -2042,7 +2042,7 @@ Provider behavior: Cloud providers (groq, openai, mistral, xai, elevenlabs, deepinfra) get a **pre-upload silence trim** by default when `ffmpeg` is installed: long pauses in a voice note are collapsed client-side before the file uploads, keeping `cloud_trim_keep_ms` of each pause so natural pacing survives. Shorter audio means faster uploads, lower per-audio-minute billing, and fewer silence hallucinations from the remote model. Clips shorter than 12 seconds skip the trim entirely (savings can't matter there, and several providers bill a per-request minimum anyway). The trim is best-effort — if ffmpeg is missing, the trim fails, the clip is mostly silence, or trimming would save less than ~10%, the original file is uploaded untouched. Set `stt.cloud_trim_silence: false` to always upload the original (e.g. when transcribing music or ambient audio through a cloud provider). Command-type and plugin providers never get trimmed audio. -If the requested provider is unavailable, Hermes falls back automatically in this order: `local` → `groq` → `openai`. +An explicitly selected `stt.provider` is honored strictly — if it's unavailable, transcription errors with guidance to run `hermes tools` rather than switching providers. Only when no provider has ever been selected does Hermes auto-detect in this order: `local` → `groq` → `openai`. Groq and OpenAI model overrides are environment-driven: @@ -2278,7 +2278,7 @@ web: | **Tavily** | `TAVILY_API_KEY` | ✔ | ✔ | | **Exa** | `EXA_API_KEY` | ✔ | ✔ | -**Backend selection:** If `web.backend` is not set, the backend is auto-detected from available API keys. If only `SEARXNG_URL` is set, SearXNG is used. If only `EXA_API_KEY` is set, Exa is used. If only `TAVILY_API_KEY` is set, Tavily is used. If only `PARALLEL_API_KEY` is set, Parallel is used. Otherwise Firecrawl is the default. +**Backend selection:** The runtime always uses the stored `web.backend` selection (set via `hermes tools`; `nous` routes through the managed Tool Gateway). Only if no web backend has ever been selected is one auto-detected from available API keys: if only `SEARXNG_URL` is set, SearXNG is used; if only `EXA_API_KEY` is set, Exa; if only `TAVILY_API_KEY` is set, Tavily; if only `PARALLEL_API_KEY` is set, Parallel. Otherwise Firecrawl is the default. Once a selection exists, adding a key to `.env` does not change the route. **SearXNG** is a free, self-hosted, privacy-respecting metasearch engine that queries 70+ search engines. No API key needed — just set `SEARXNG_URL` to your instance (e.g., `http://localhost:8080`). SearXNG is search-only; `web_extract` requires a separate extract provider (set `web.extract_backend`). See the [Web Search setup guide](/user-guide/features/web-search) for Docker setup instructions. diff --git a/website/docs/user-guide/features/browser.md b/website/docs/user-guide/features/browser.md index 99fb0e84c2..f968777201 100644 --- a/website/docs/user-guide/features/browser.md +++ b/website/docs/user-guide/features/browser.md @@ -62,6 +62,10 @@ BROWSER_USE_API_KEY=*** Get your API key at [browser-use.com](https://browser-use.com). +:::note Selecting the provider +The `.env` keys above supply **credentials only**. The active cloud browser is chosen by the `browser.cloud_provider` selection written by `hermes tools` → Browser Automation (`browserbase`, `browser-use`, `camofox`, or `nous` for the Nous Subscription). Once a selection exists, adding or removing a key does not switch providers — and a selected provider with a missing key errors with guidance to run `hermes tools` instead of silently rerouting. Never-configured setups still autodetect from available credentials. +::: + ### Browser Use mode (default) Browser Use mode uses the [Browser Use CLI 3.0](https://github.com/browser-use/browser-use) — a new browser harness that is state-of-the-art at web tasks — instead of the built-in browser tools. The agent writes and executes Python in the browser to click, type, drag, scrape, and interact with webpages. @@ -237,7 +241,7 @@ The rewrite only applies to page navigation URLs with loopback hosts (`localhost Or configure via `hermes tools` → Browser Automation → Camofox. -When `CAMOFOX_URL` is set, all browser tools automatically route through Camofox instead of Browserbase or agent-browser. +Camofox is selected like any other browser backend: pick **Camofox** in `hermes tools` → Browser Automation, which writes `browser.cloud_provider: camofox` to `config.yaml`. `CAMOFOX_URL` is only the server address — setting it no longer selects the backend by itself once a browser selection exists (never-configured setups still autodetect it). #### Persistent browser sessions diff --git a/website/docs/user-guide/features/image-generation.md b/website/docs/user-guide/features/image-generation.md index 51528d81c6..33c4abc747 100644 --- a/website/docs/user-guide/features/image-generation.md +++ b/website/docs/user-guide/features/image-generation.md @@ -32,7 +32,7 @@ Prices are FAL's pricing at time of writing; check [fal.ai](https://fal.ai/) for :::tip Nous Subscribers If you have a paid [Nous Portal](https://portal.nousresearch.com) subscription, you can use image generation through the **[Tool Gateway](tool-gateway.md)** without a FAL API key. Your model selection persists across both paths. New installs can run `hermes setup --portal` to log in and turn on every gateway tool at once; existing installs can pick **Nous Subscription** as the image-gen backend via `hermes tools`. -If the managed gateway returns `HTTP 4xx` for a specific model, that model isn't yet proxied on the portal side — the agent will tell you so, with remediation steps (set `FAL_KEY` for direct access, or pick a different model). +If the managed gateway returns `HTTP 4xx` for a specific model, that model isn't yet proxied on the portal side — the agent will tell you so, with remediation steps (switch to FAL.ai in `hermes tools` with your own `FAL_KEY` for direct access, or pick a different model). ::: ### Get a FAL API Key @@ -62,11 +62,13 @@ Your selection is saved to `config.yaml`: ```yaml image_gen: + provider: fal # `nous` if you picked Nous Subscription model: fal-ai/flux-2/klein/9b - use_gateway: false # true if using Nous Subscription max_parallel_requests: 4 # concurrent images in one tool-call batch ``` +`image_gen.provider` is the single selection key: `nous` routes through the managed Tool Gateway; a vendor name (`fal`, `openai`, `xai`, `krea`, ...) goes direct with your own key. The runtime always follows this stored selection — a `FAL_KEY` in `.env` is ignored while `provider: nous`, and `provider: fal` without `FAL_KEY` errors with `image_gen is configured to use fal (set via hermes tools), but FAL_KEY is not set. Run 'hermes tools' to change it.` rather than silently rerouting. Change providers via `hermes tools`, not by adding/removing keys. (The old `use_gateway` boolean is legacy — still read as `nous` when `true`, but never written anymore.) + `max_parallel_requests` defaults to `4`. Hermes clamps it to at least one and to the global tool-worker limit, so image providers receive bounded parallel requests without allowing an image batch to bypass the agent's concurrency cap. @@ -227,7 +229,7 @@ If upscaling fails (network issue, rate limit), the original image is returned a 1. **Model resolution** — `_resolve_fal_model()` reads `image_gen.model` from `config.yaml`, falls back to the `FAL_IMAGE_MODEL` env var, then to `fal-ai/flux-2/klein/9b`. 2. **Payload building** — `_build_fal_payload()` translates your `aspect_ratio` into the model's native format (preset enum, aspect-ratio enum, or GPT literal), merges the model's default params, applies any caller overrides, then filters to the model's `supports` whitelist so unsupported keys are never sent. -3. **Submission** — `_submit_fal_request()` routes via direct FAL credentials or the managed Nous gateway. +3. **Submission** — `_submit_fal_request()` routes via direct FAL credentials or the managed Nous gateway, according to the stored `image_gen.provider` selection. 4. **Upscaling** — runs only when the agent passed `upscale: true`; every model's catalog default is off. 5. **Delivery** — final image URL returned to the agent, which emits a `MEDIA:` tag that platform adapters convert to native media. diff --git a/website/docs/user-guide/features/tool-gateway.md b/website/docs/user-guide/features/tool-gateway.md index 43a6c7dcb8..247b4ed383 100644 --- a/website/docs/user-guide/features/tool-gateway.md +++ b/website/docs/user-guide/features/tool-gateway.md @@ -124,37 +124,51 @@ The set evolves — `hermes tools` → Image Generation shows the current live l Most users never need to touch this — `hermes model` and `hermes tools` cover every workflow interactively. This section is for writing config.yaml directly or scripting setups. -### Per-tool `use_gateway` flag +### One selection key per tool category -Each tool's config block takes a `use_gateway` boolean: +Each tool category has a single provider-selection key, written by the `hermes tools` picker (or the desktop GUI). Picking the **Nous Subscription** row stores the value `nous`, which routes that category through the managed Tool Gateway. Picking a BYOK row stores the vendor name (`fal`, `openai`, `firecrawl`, `browser-use`, ...), which goes direct with your own credentials: ```yaml web: - backend: firecrawl - use_gateway: true + backend: nous # web search/extract via the Tool Gateway image_gen: - use_gateway: true + provider: nous # image generation via the Tool Gateway tts: - provider: openai - use_gateway: true + provider: nous # TTS via the Tool Gateway + +stt: + provider: nous # speech-to-text via the Tool Gateway browser: - cloud_provider: browser-use - use_gateway: true + cloud_provider: nous # cloud browser via the Tool Gateway ``` -Precedence: `use_gateway: true` routes through Nous regardless of any direct keys in `.env`. `use_gateway: false` (or absent) uses direct keys if available and only falls back to the gateway when none exist. +The runtime **always uses the stored selection** — credential presence never selects or reroutes a category. A `FAL_KEY` sitting in `.env` is ignored while `image_gen.provider: nous`; conversely, `image_gen.provider: fal` with no `FAL_KEY` set produces a clear error instead of silently falling back to the gateway: -### Disabling the gateway +``` +image_gen is configured to use fal (set via hermes tools), but FAL_KEY is not set. Run 'hermes tools' to change it. +``` + +Categories you have **never configured** (no selection key ever written) autodetect from available credentials, same as before. But once a selection exists, adding a key to `.env` does not change the route — only `hermes tools` (or editing the selection key) does. + +### Switching back to your own keys + +```bash +hermes tools # pick the tool → choose a direct provider (e.g. Firecrawl) +``` + +Or set the selection key directly: ```yaml web: - use_gateway: false # Hermes now uses FIRECRAWL_API_KEY from .env + backend: firecrawl # Hermes now uses FIRECRAWL_API_KEY from .env ``` -`hermes tools` automatically clears the flag when you pick a non-gateway provider, so this usually happens for you. +### Legacy `use_gateway` flag (deprecated) + +Older Hermes versions used a per-tool `use_gateway: true` boolean to route through the gateway. That flag is **legacy**: it is never written anymore, and the `hermes tools` picker removes it from a category's config when it rewrites the selection. Old configs that still contain `use_gateway: true` are interpreted at read time as the `nous` selection, so existing setups keep working. Don't set `use_gateway` in new configs — select the provider in `hermes tools` instead. ### Self-hosted gateway (advanced) @@ -189,4 +203,4 @@ Modal is available as an **optional add-on** through the Nous subscription, not ### Do I need to delete my existing API keys when I enable the gateway? -No — keep them in `.env`. When `use_gateway: true`, Hermes skips direct keys and uses the gateway. Flip the flag back to `false` and your keys become the source again. The gateway isn't a lock-in. +No — keep them in `.env`. While a tool's selection is **Nous Subscription**, direct keys for that tool are simply ignored. Pick the direct provider again in `hermes tools` and your keys become the source again. The gateway isn't a lock-in. diff --git a/website/docs/user-guide/features/tts.md b/website/docs/user-guide/features/tts.md index 7552cfeb21..3fbfce34b6 100644 --- a/website/docs/user-guide/features/tts.md +++ b/website/docs/user-guide/features/tts.md @@ -44,7 +44,7 @@ Convert text to speech with eleven providers: ```yaml # In ~/.hermes/config.yaml tts: - provider: "edge" # "edge" | "elevenlabs" | "openai" | "minimax" | "mistral" | "gemini" | "xai" | "deepinfra" | "neutts" | "kittentts" | "piper" + provider: "edge" # "edge" | "elevenlabs" | "openai" | "minimax" | "mistral" | "gemini" | "xai" | "deepinfra" | "neutts" | "kittentts" | "piper" — or "nous" for the managed Tool Gateway (written when you pick Nous Subscription in `hermes tools`) speed: 1.0 # Global speed multiplier (provider-specific settings override this) edge: voice: "en-US-AriaNeural" # 322 voices, 74 languages @@ -525,10 +525,12 @@ Hermes writes the incoming voice message to `{input_path}`, runs the command, an ### Fallback Behavior -If your configured provider isn't available, Hermes automatically falls back: +An **explicit** `stt.provider` selection (written in `config.yaml`, e.g. via `hermes tools`) is honored strictly — if that provider can't run, transcription fails with a clear error (`stt is configured to use (set via hermes tools), but . Run 'hermes tools' to change it.`) instead of silently switching engines. Note that `stt.provider: local` written in your config counts as an explicit selection. + +When **no provider has ever been selected**, Hermes auto-detects from what's available: - **Local faster-whisper unavailable** → Tries a local `whisper` CLI or `HERMES_LOCAL_STT_COMMAND` before cloud providers -- **Groq key not set** → Falls back to local transcription, then OpenAI -- **OpenAI key not set** → Falls back to local transcription, then Groq +- **Groq key not set** → Skipped; next available provider +- **OpenAI key not set** → Skipped; next available provider - **Mistral key/SDK not set** → Skipped in auto-detect; falls through to next available provider - **Nothing available** → Voice messages pass through with an accurate note to the user diff --git a/website/docs/user-guide/features/web-search.md b/website/docs/user-guide/features/web-search.md index ca7f529bbc..92e4b2ce25 100644 --- a/website/docs/user-guide/features/web-search.md +++ b/website/docs/user-guide/features/web-search.md @@ -340,16 +340,16 @@ web: extract_backend: "firecrawl" # used by web_extract ``` -When per-capability keys are empty, both fall through to `web.backend`. When `web.backend` is also empty, the backend is auto-detected from whichever API key/URL is present. +When per-capability keys are empty, both fall through to `web.backend`. Only when no web selection has ever been written is the backend auto-detected from whichever API key/URL is present — once a selection exists, the runtime always uses it, and adding a key to `.env` does not reroute web traffic. **Priority order (per capability):** 1. `web.search_backend` / `web.extract_backend` (explicit per-capability) -2. `web.backend` (shared fallback) -3. Auto-detect from environment variables +2. `web.backend` (shared fallback; `nous` = managed Tool Gateway) +3. Auto-detect from environment variables (never-configured setups only) ### Auto-detection -If no backend is explicitly configured, Hermes picks the first available one based on which credentials are set: +If no backend has **ever** been selected (no `web.backend` / per-capability key written by you or `hermes tools`), Hermes picks the first available one based on which credentials are set: | Credential present | Auto-selected backend | |--------------------|-----------------------| diff --git a/website/docs/user-guide/messaging/whatsapp-cloud.md b/website/docs/user-guide/messaging/whatsapp-cloud.md index 1bf7e68eda..dc07114df4 100644 --- a/website/docs/user-guide/messaging/whatsapp-cloud.md +++ b/website/docs/user-guide/messaging/whatsapp-cloud.md @@ -365,15 +365,14 @@ If the model emits tool-call-shaped text instead of a structured call, it usuall ### STT (voice note transcription) returns empty / "could not transcribe" -The default `stt.provider: local` requires `pip install faster-whisper`. If you're a Nous subscriber, you can route STT through Meta's managed audio gateway instead: +The default `stt.provider: local` requires `pip install faster-whisper`. If you're a Nous subscriber, you can route STT through the managed gateway instead — select **Nous Subscription** for speech-to-text in `hermes tools`, or set it directly: ```bash -hermes config set stt.provider openai -hermes config set stt.use_gateway true +hermes config set stt.provider nous hermes gateway restart ``` -This uses your Nous Portal access token instead of needing a separate OpenAI key. +This uses your Nous Portal access token instead of needing a separate OpenAI key. (Older docs suggested `stt.use_gateway true` — that flag is legacy; the provider selection alone controls routing now.) --- diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/environment-variables.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/environment-variables.md index 69c7871a2a..d8747e9395 100644 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/environment-variables.md +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/environment-variables.md @@ -134,7 +134,7 @@ description: "Hermes Agent 使用的所有环境变量完整参考" | `BROWSER_USE_API_KEY` | Browser Use 云浏览器 API 密钥（[browser-use.com](https://browser-use.com/)） | | `FIRECRAWL_BROWSER_TTL` | Firecrawl 浏览器会话 TTL（秒，默认：300） | | `BROWSER_CDP_URL` | 本地浏览器的 Chrome DevTools Protocol（CDP）URL（通过 `/browser connect` 设置，例如 `ws://localhost:9222`） | -| `CAMOFOX_URL` | Camofox 本地反检测浏览器 URL（默认：`http://localhost:9377`） | +| `CAMOFOX_URL` | Camofox 本地反检测浏览器服务器地址（默认：`http://localhost:9377`）。仅为地址——不会选择后端；请在 `hermes tools` 中选择 Camofox（`browser.cloud_provider: camofox`） | | `CAMOFOX_USER_ID` | 可选的外部管理 Camofox 用户 ID，用于共享可见会话 | | `CAMOFOX_SESSION_KEY` | 为 `CAMOFOX_USER_ID` 创建标签页时使用的可选 Camofox 会话密钥 | | `CAMOFOX_ADOPT_EXISTING_TAB` | 设为 `true` 可在创建新标签页前复用现有 Camofox 标签页 | diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/browser.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/browser.md index e8a0e87510..57a7ac3719 100644 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/browser.md +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/browser.md @@ -172,7 +172,7 @@ CAMOFOX_URL=http://localhost:9377 或通过 `hermes tools` → Browser Automation → Camofox 进行配置。 -设置 `CAMOFOX_URL` 后，所有浏览器工具将自动通过 Camofox 路由，而非 Browserbase 或 agent-browser。 +设置 `CAMOFOX_URL` 仅提供服务器地址。要启用 Camofox，请在 `hermes tools` → Browser Automation 中选择 Camofox（写入 `browser.cloud_provider: camofox`）——一旦存在浏览器后端选择，仅设置 `CAMOFOX_URL` 不再自动切换后端（从未配置过的环境仍会自动检测）。 #### 持久化浏览器会话 diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/image-generation.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/image-generation.md index e9a884915a..70a97e6d25 100644 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/image-generation.md +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/image-generation.md @@ -59,10 +59,12 @@ hermes tools ```yaml image_gen: + provider: fal # 选 Nous Subscription 时为 `nous` model: fal-ai/flux-2/klein/9b - use_gateway: false # 使用 Nous Subscription 时为 true ``` +`image_gen.provider` 是唯一的选择键：`nous` 走托管网关，厂商名（如 `fal`）走直连。运行时始终按该选择路由——`provider: nous` 时 `.env` 里的 `FAL_KEY` 会被忽略；`provider: fal` 而缺少 `FAL_KEY` 会直接报错并提示运行 `hermes tools`，不会静默回退。（旧的 `use_gateway` 键已废弃，读取时 `true` 等同于 `nous`。） + ### GPT-Image 画质档位 `fal-ai/gpt-image-1.5` 的请求画质固定为 `medium`（约 1024×1024 下 $0.034/张）。面向用户**不开放** `low` / `high` 档位，以便 Nous Portal 侧计费在全体用户间更可预期（档位价差约 22×）。若需要更便宜的 GPT-Image 路线，请换其他模型；若追求更高画质，可考虑 Klein 9B 或同类 Imagen 系模型。 diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/tool-gateway.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/tool-gateway.md index e561641571..45574815dd 100644 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/tool-gateway.md +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/tool-gateway.md @@ -70,32 +70,32 @@ Your Nous subscription includes the Tool Gateway. hermes tools ``` -选择工具类别（Web、Browser、Image Generation、TTS），再将提供商选为 **Nous Subscription**。这会在配置里把对应工具的 `use_gateway` 设为 `true`。 +选择工具类别（Web、Browser、Image Generation、TTS），再将提供商选为 **Nous Subscription**。这会把该类别的选择键写为 `nous`（例如 `image_gen.provider: nous`）。 ### 手动编辑配置 -在 `~/.hermes/config.yaml` 中直接设置 `use_gateway`： +每个工具类别只有一个选择键，选 **Nous Subscription** 即写入 `nous`： ```yaml web: - backend: firecrawl - use_gateway: true + backend: nous # 网页搜索/抓取走 Tool Gateway image_gen: - use_gateway: true + provider: nous tts: - provider: openai - use_gateway: true + provider: nous + +stt: + provider: nous browser: - cloud_provider: browser-use - use_gateway: true + cloud_provider: nous ``` ## 工作原理 -当某工具的 `use_gateway: true` 时，运行时会把 API 调用路由到 Nous Tool Gateway，而不是使用直连 Key： +当某工具类别的选择键为 `nous` 时，运行时会把 API 调用路由到 Nous Tool Gateway，而不是使用直连 Key： 1. **网页工具** — `web_search` / `web_extract` 走网关的 Firecrawl 端点 2. **文生图** — `image_generate` 走网关的 FAL 端点 @@ -106,12 +106,13 @@ browser: ### 优先级 -每个工具都会先看 `use_gateway`： +运行时**始终使用已保存的选择**，凭据是否存在不会影响路由： -- **`use_gateway: true`** → 强制走网关，即使 `.env` 里仍有直连 Key -- **`use_gateway: false`**（或未设置）→ 若有直连 Key 则优先直连；仅在没有直连凭据时才回退到网关 +- **选择为 `nous`** → 走网关，即使 `.env` 里仍有直连 Key（例如 `FAL_KEY` 会被忽略） +- **选择为具体厂商**（如 `fal`、`firecrawl`）→ 直连；若对应 Key 缺失则报错并提示运行 `hermes tools`，**不会**静默回退到网关 +- **从未配置过的类别** → 按可用凭据自动检测（行为不变）；但一旦存在选择，仅往 `.env` 加 Key 不会改变路由 -因此你可以在网关与直连之间切换，而无需删除 `.env` 中的旧 Key。 +（旧版的 `use_gateway` 布尔键已废弃：不再写入，读取时 `use_gateway: true` 等同于 `nous`。请改用 `hermes tools` 选择提供商。） ## 切回直连 Key @@ -121,15 +122,14 @@ browser: hermes tools # 选择该工具 → 选直连提供商 ``` -或在配置中设 `use_gateway: false`： +或在配置中把选择键改回具体厂商： ```yaml web: - backend: firecrawl - use_gateway: false # 此时使用 .env 中的 FIRECRAWL_API_KEY + backend: firecrawl # 此时使用 .env 中的 FIRECRAWL_API_KEY ``` -在 `hermes tools` 中选择非网关提供商时，`use_gateway` 会自动设为 `false`，避免配置自相矛盾。 +在 `hermes tools` 中选择非网关提供商时，选择键会被改写为该厂商名（旧的 `use_gateway` 键若存在会被一并移除），避免配置自相矛盾。 ## 查看状态 @@ -168,11 +168,11 @@ FIRECRAWL_GATEWAY_URL=https://... # 单独覆盖 Firecrawl 端点 ### 需要删掉已有的 API Key 吗？ -不需要。`use_gateway: true` 时运行时会跳过直连 Key 并走网关；Key 仍保留在 `.env`。之后若关闭网关，会自动恢复使用直连 Key。 +不需要。类别选择为 **Nous Subscription**（`nous`）时，运行时会忽略该类别的直连 Key；Key 仍保留在 `.env`。之后在 `hermes tools` 里改回直连提供商，Key 即恢复生效。 ### 能否部分工具走网关、部分走直连？ -可以。`use_gateway` 按工具独立配置。例如：网页与文生图走网关，TTS 用 ElevenLabs，浏览器用 Browserbase。 +可以。选择按工具类别独立配置。例如：网页与文生图选 Nous Subscription，TTS 用 ElevenLabs，浏览器用 Browserbase。 ### 订阅到期会怎样？