docs: tool provider selection follows the hermes tools pick (post #90317)
This commit is contained in:
Teknium
@@ -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
|
||||
|
||||
@@ -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` |
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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:<url>` tag that platform adapters convert to native media.
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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 <provider> (set via hermes tools), but <failure>. 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
|
||||
|
||||
|
||||
@@ -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 |
|
||||
|--------------------|-----------------------|
|
||||
|
||||
@@ -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.)
|
||||
|
||||
---
|
||||
|
||||
|
||||
+1
-1
@@ -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 标签页 |
|
||||
|
||||
+1
-1
@@ -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` 不再自动切换后端（从未配置过的环境仍会自动检测）。
|
||||
|
||||
#### 持久化浏览器会话
|
||||
|
||||
|
||||
+3
-1
@@ -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 系模型。
|
||||
|
||||
+20
-20
@@ -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。
|
||||
|
||||
### 订阅到期会怎样？
|
||||
|
||||
|
||||
Reference in New Issue
Block a user