The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
docs: GitHub Copilot is the github-copilot labs plugin; document the provider seams
Tekniumee3bcbbbc1c6
diff --git a/cli-config.yaml.example b/cli-config.yaml.exampleindex b7af85dba72..170dac34123 100644--- a/cli-config.yaml.example+++ b/cli-config.yaml.example@@ -81,7 +81,6 @@ model:# "nous-api" - Nous Portal API key (requires: NOUS_API_KEY)# "anthropic" - Direct Anthropic API (requires: ANTHROPIC_API_KEY)# "openai-codex" - OpenAI Codex (requires: hermes auth)- # "copilot" - GitHub Copilot / GitHub Models (requires: GITHUB_TOKEN)# "gemini" - Use Google AI Studio direct (requires: GOOGLE_API_KEY or GEMINI_API_KEY)# "zai" - Use z.ai / ZhipuAI GLM models (requires: GLM_API_KEY)# "kimi-coding" - Kimi / Moonshot AI (requires: KIMI_API_KEY)diff --git a/skills/autonomous-ai-agents/hermes-agent/references/providers-and-models.md b/skills/autonomous-ai-agents/hermes-agent/references/providers-and-models.mdindex 71d46afe525..0e75c231ab0 100644--- a/skills/autonomous-ai-agents/hermes-agent/references/providers-and-models.md+++ b/skills/autonomous-ai-agents/hermes-agent/references/providers-and-models.md@@ -14,8 +14,6 @@ Full docs: https://hermes-agent.nousresearch.com/docs/integrations/providers| openai-codex | OAuth | `hermes auth add openai-codex` || qwen-oauth | OAuth | `hermes auth add qwen-oauth` || minimax-oauth | OAuth | `hermes auth add minimax-oauth` |-| copilot | Token | `COPILOT_GITHUB_TOKEN` / `GH_TOKEN` (Copilot device flow — `gh auth login` tokens do NOT work) |-| copilot-acp | External CLI | Copilot CLI on PATH or `COPILOT_CLI_PATH` || gemini | API key | `GOOGLE_API_KEY` or `GEMINI_API_KEY` || xai | API key | `XAI_API_KEY` (SuperGrok OAuth also supported) || deepseek | API key | `DEEPSEEK_API_KEY` |@@ -29,6 +27,8 @@ Full docs: https://hermes-agent.nousresearch.com/docs/integrations/providers| bedrock / vertex / azure-foundry | Cloud SDK / key | AWS SDK creds / Vertex ADC / `AZURE_FOUNDRY_API_KEY` || custom | Config | `model.base_url` + `model.api_key` in config.yaml |+GitHub Copilot (`copilot`, `copilot-acp`) is a labs plugin, not core: `hermes plugins install github-copilot`, then `hermes auth add copilot` (https://github.com/NousResearch/hermes-labs-plugins/tree/main/github-copilot).+Multiple credentials per provider pool and rotate automatically (`hermes auth`).Fallback chain when the primary fails: `hermes fallback add|remove|list`.diff --git a/skills/autonomous-ai-agents/hermes-agent/references/troubleshooting.md b/skills/autonomous-ai-agents/hermes-agent/references/troubleshooting.mdindex 7d76e6fa4ee..1a70d3c1394 100644--- a/skills/autonomous-ai-agents/hermes-agent/references/troubleshooting.md+++ b/skills/autonomous-ai-agents/hermes-agent/references/troubleshooting.md@@ -14,7 +14,7 @@1. `hermes doctor` — check config and dependencies2. `hermes auth` — re-authenticate OAuth providers (or `hermes auth add <provider>`)3. Check `.env` has the right API key-4. **Copilot 403**: `gh auth login` tokens do NOT work for Copilot API. You must use the Copilot-specific OAuth device code flow via `hermes model` → GitHub Copilot.+4. **GitHub Copilot** (`copilot` / `copilot-acp`) lives in the `github-copilot` labs plugin (`hermes plugins install github-copilot`); sign in with `hermes auth add copilot` — `gh` CLI logins are not read.### Changes not taking effect- **Tools/skills:** `/reset` starts a new session with updated toolsetdiff --git a/website/docs/developer-guide/adding-providers.md b/website/docs/developer-guide/adding-providers.mdindex 2bf4ef8efde..1cd0964858a 100644--- a/website/docs/developer-guide/adding-providers.md+++ b/website/docs/developer-guide/adding-providers.md@@ -132,7 +132,7 @@ See `plugins/model-providers/nvidia/` or `plugins/model-providers/gmi/` as a temUse the full checklist below when your provider needs any of the following:-- OAuth or token refresh (Nous Portal, Codex, Qwen Portal, Copilot)+- OAuth or token refresh (Nous Portal, Codex, Qwen Portal)- A non-OpenAI API shape that requires a new adapter (Anthropic Messages, Codex Responses)- Custom endpoint detection or multi-region probing (z.ai, Kimi)- A curated static model catalog or live `/models` fetchdiff --git a/website/docs/developer-guide/context-compression-and-caching.md b/website/docs/developer-guide/context-compression-and-caching.mdindex 6dd5aea303f..1738bf4ce02 100644--- a/website/docs/developer-guide/context-compression-and-caching.md+++ b/website/docs/developer-guide/context-compression-and-caching.md@@ -410,8 +410,8 @@ map.### Codex gpt-5.x / Astra threshold autoraiseThe ChatGPT Codex OAuth backend hard-caps gpt-5.4/5.5/5.6 and gpt-6 Astra at a **272K** context window-(the same slug exposes 1.05M on OpenAI's direct API and OpenRouter, and 400K on-GitHub Copilot). At the default 50% trigger, compaction would fire at ~136K —+(the same slug exposes 1.05M on OpenAI's direct API and OpenRouter, and smaller+windows through some resellers). At the default 50% trigger, compaction would fire at ~136K —half the window the model can actually use. When the active route is CodexOAuth (`provider: openai-codex`) and the model is one of those families (Astramatches any slug containing `astra`; the opt-in `-900k` picker variants are@@ -499,7 +499,7 @@ narrow, re-checked on every request:Astra variants and other GPT-6 models are excluded. gpt-5.1/5.2 return HTTP 500 or stall the stream when thefield is present (no structured rejection to downgrade on, verified live Aug 2026).- **Routes:** `api.openai.com` (OpenAI API key) or the ChatGPT Codex backend- (Codex subscription OAuth) only. xAI, GitHub/Copilot, OpenRouter, relays, and+ (Codex subscription OAuth) only. xAI, plugin providers, OpenRouter, relays, andlocal servers never see the field.For Astra, both the resolved `openai-codex` provider and an official HTTPSdiff --git a/website/docs/developer-guide/model-provider-plugin.md b/website/docs/developer-guide/model-provider-plugin.mdindex d670dbdb6be..adcca23fb8b 100644--- a/website/docs/developer-guide/model-provider-plugin.md+++ b/website/docs/developer-guide/model-provider-plugin.md@@ -104,14 +104,14 @@ Full definition in `providers/base.py`. The most useful ones:| `base_url` | str | Default inference endpoint || `models_url` | str | Explicit catalog URL (falls back to `{base_url}/models`) || `supports_streaming` | `bool \| None` | `None` (default) preserves transport defaults; `True` opts streaming-capable `external_process` clients into host streaming; `False` disables provider streaming. ACP URLs and session-level streaming disables still take precedence. Only opt in when the client implements the selected API mode's streaming contract, including cancellation and cleanup. |-| `auth_type` | str | `api_key` \| `oauth_device_code` \| `oauth_external` \| `copilot` \| `aws_sdk` \| `external_process` |+| `auth_type` | str | `api_key` \| `oauth_device_code` \| `oauth_external` \| `aws_sdk` \| `external_process` \| any plugin-defined value (login is then provider-owned) || `auth_handler` | `Callable \| None` | Provider-owned `hermes auth add/status/logout/refresh <name>` — see [Provider-owned auth](#provider-owned-auth-auth_handler-refresh_credential) || `refresh_credential` | `Callable \| None` | Provider-owned rotation of a pooled OAuth row — same section || `classify_api_error` | `Callable \| None` | Provider-scoped error-classification override — see [Recovery and error classification](#recovery-and-error-classification) || `fallback_models` | `tuple[str, ...]` | Curated list shown when live catalog fetch fails — in the `/model` picker AND the first-time `hermes setup` / `hermes model` API-key flow, which resolve the catalog the same way (`fetch_models()` merged curated-first with `fallback_models`; `fallback_models` alone when the fetch returns `None` or raises) || `supports_vision` | bool | Declares the provider's API accepts image content inside **tool-result** messages (a provider-wide wire capability). Per-model user-image routing comes from `model_capabilities` / models.dev, not from this flag || `model_capabilities` | `dict[str, dict[str, Any]]` | Per-model capability declarations in the `model_overrides` schema — see [Declaring model capabilities](#declaring-model-capabilities) |-| `default_headers` | `dict[str, str]` | Sent on every request (e.g. Copilot's `Editor-Version`); also forwarded by the default `fetch_models()` catalog request. A value that is costly to compute at import (a User-Agent carrying the release) can be deferred with `providers.base.LazyHeaders({"User-Agent": lambda: hermes_user_agent("MyAgent")})`, a `dict` whose callable values run on first read (`hermes_user_agent` is in `hermes_cli.version_info`) |+| `default_headers` | `dict[str, str]` | Sent on every request (e.g. an `Editor-Version` header an IDE-subscription API requires); also forwarded by the default `fetch_models()` catalog request. A value that is costly to compute at import (a User-Agent carrying the release) can be deferred with `providers.base.LazyHeaders({"User-Agent": lambda: hermes_user_agent("MyAgent")})`, a `dict` whose callable values run on first read (`hermes_user_agent` is in `hermes_cli.version_info`) || `fixed_temperature` | Any | `None` = use caller's value; `OMIT_TEMPERATURE` sentinel = don't send temperature at all (Kimi) || `default_max_tokens` | `int \| None` | Provider-level max_tokens cap (Nvidia: 16384) || `unsupported_response_formats` | `tuple` | `response_format` types the API rejects outright; auxiliary requests omit them instead of paying a guaranteed 400 (DeepSeek: `("json_schema",)`) |@@ -217,6 +217,125 @@ class AcmeProfile(ProviderProfile):return None```+## ProviderProfile fields and hooks++Every field and hook `providers/base.py` declares, in declaration order. Names ending in `()` are methods+to override in a subclass; the rest are dataclass fields (a few, such as `picker_catalog` and the+device-login callables, take a callable). Endpoint-keyed hooks (`client_headers`, `request_headers`,+`max_tokens_param`) receive the request's `base_url` and return `None` / `{}` for an endpoint that is+not yours; the `responses_*` and `message_carrier_*` fields and the reasoning-replay hooks apply only on+hosts the profile lists in `hostnames`. Hot-path hooks must be pure and cheap (no I/O) unless the+meaning says otherwise.++| Name | Meaning | Default |+|---|---|---|+| `name` | Canonical provider id (`model.provider`, `--provider`) | required |+| `api_mode` | Static wire protocol; `api_mode_for_model()` can vary it per model | `"chat_completions"` |+| `aliases` | Alternative names `get_provider_profile()` resolves | `()` |+| `display_name` | Human label in pickers | `""` |+| `description` | Picker subtitle | `""` |+| `signup_url` | Shown during setup | `""` |+| `hidden` | Pre-release: kept off discovery surfaces until `listed()` is true; resolution by name still works | `False` |+| `env_vars` | API-key env vars in priority order; a final `*_BASE_URL` entry is the base-URL override | `()` |+| `base_url` | Default inference endpoint | `""` |+| `models_url` | Explicit models endpoint (else `{base_url}/models`) | `""` |+| `auth_type` | `api_key` \| `oauth_device_code` \| `oauth_external` \| `external_process` \| `aws_sdk` \| plugin-defined | `"api_key"` |+| `supports_streaming` | `None` keeps transport defaults, `True` opts a process client into streaming, `False` disables it | `None` |+| `supports_health_check` | `False`: `hermes doctor` skips the `/models` probe | `True` |+| `supports_model_listing` | `False`: `fetch_models()` returns `None` without a network call | `True` |+| `auth_handler` | Provider-owned `hermes auth add\|status\|logout\|refresh <name>`; truthy return = handled | `None` |+| `refresh_credential` | Rotates a pooled OAuth row and returns the rotated fields | `None` |+| `classify_api_error` | Error classification for this provider's failures, before the built-in pipeline | `None` |+| `supports_vision` | API accepts images inside tool-result messages | `False` |+| `supports_vision_tool_messages` | API accepts list-type (multipart) tool message content | `True` |+| `supports_prompt_cache_key` | Chat Completions endpoint documents `prompt_cache_key` | `False` |+| `native_reasoning_details_type` | Namespaced `<provider>.native_assistant` reasoning carrier only this profile receives | `None` |+| `process_command` | External-process default binary | `""` |+| `process_args` | External-process default argv tail | `()` |+| `process_command_env_vars` | Env vars overriding the binary, in priority order | `()` |+| `process_args_env_var` | Env var overriding argv (shlex-split) | `""` |+| `process_command_fallback` | Serves a pinned `delegation.command` no profile's `process_command` names; first registered wins | `False` |+| `fallback_models` | Curated picker list when the live fetch fails | `()` |+| `model_aliases` | Short name → model id; `/model <alias>` resolves here first | `{}` |+| `hostname` | Base hostname for URL → provider reverse mapping (derived from `base_url` when empty) | `""` |+| `default_headers` | Headers on every request and on the default catalog fetch | `{}` |+| `fixed_temperature` | `None` = caller's value; `OMIT_TEMPERATURE` = never send temperature | `None` |+| `default_max_tokens` | Provider-level max_tokens cap | `None` |+| `unsupported_response_formats` | `response_format` types auxiliary requests omit | `()` |+| `default_aux_model` | Cheap model for auxiliary tasks; empty = main model | `""` |+| `model_capabilities` | Per-model metadata in the `model_overrides` schema | `{}` |+| `account_card` | Accounts-tab card overrides `{name, flow, cli_command, docs_url}` (Desktop/dashboard) | `{}` |+| `account_status` | Live status for that card; subprocess- and network-free | `None` (`auth.get_auth_status(name)`) |+| `start_device_login` | In-app device-code sign-in: returns `{user_code, verification_url, expires_in, interval, state}` | `None` |+| `poll_device_login` | One poll of that login: `{status, interval?, credential?, message?}` | `None` |+| `save_device_login` | Persists the approved credential (core calls it in the session's profile scope) | `None` |+| `model_setup_flow` | The provider's own `hermes model` step (credential prompt, catalog, persist) | `None` (generic flow for `auth_type`) |+| `setup_reasoning_efforts` | Effort levels the setup picker offers for a model; `()` = no reasoning control | `None` (generic ladder) |+| `fetch_account_usage()` | `/usage` snapshot when no built-in usage fetcher owns the provider | `None` |+| `resolve_aux_model()` | Live cheap-model id for auxiliary tasks; cached, never raises | `""` (use `default_aux_model`) |+| `get_hostname()` | Provider hostname for URL detection | `hostname`, else from `base_url` |+| `prepare_messages()` | Message preprocessing after codex sanitization, before the developer-role swap | pass-through |+| `build_extra_body()` | Provider-specific `extra_body` fields | `{}` |+| `default_reasoning_config()` | Reasoning config sent when `agent.reasoning_effort` is unset | `None` |+| `build_api_kwargs_extras()` | `(extra_body_additions, top_level_kwargs)` split | `({}, {})` |+| `build_client_kwargs_extras()` | OpenAI-client kwargs defaults (explicit settings win; no I/O) | `{}` |+| `default_vision_model()` | Provider's default vision model id | `None` |+| `get_model_context_length()` | Provider-qualified context bound; explicit user overrides win | `None` |+| `get_usage_cost()` | `CostResult` from canonical usage (estimates are never `actual`) | `None` |+| `get_max_tokens()` | Per-model max_tokens cap when the user set none | `default_max_tokens` |+| `supported_reasoning_efforts()` | Effort vocabulary for a model: `None` unknown, `()` none, tuple = clamp; no I/O | `None` |+| `api_mode_for_model()` | Wire this provider serves a model on; `api_key` given only at resolution time | `None` (static `api_mode`) |+| `client_headers()` | Default headers for a client built for `base_url` (`has_images` for image requests) | `None` (static `default_headers`) |+| `request_headers()` | Per-request `extra_headers` for `base_url`; `user_initiated` on a turn's first call | `{}` |+| `max_tokens_param()` | `"max_completion_tokens"` or `"max_tokens"` for `base_url` | `None` (core heuristic) |+| `listed()` | Whether discovery surfaces may offer the provider | `True` unless `hidden` with no pool row |+| `create_client()` | Provider-specific client object (ACP shim, native SDK) | `None` (standard client) |+| `setup_status()` | External-process login state `{available, logged_in, plan, detail, login_command}` | `None` |+| `discover_models()` | External-process live picker `[{id, label, note}]` without inference | `None` (`fallback_models`) |+| `fetch_models()` | Live model ids | GET `{models_url or base_url}/models` |+| `hostnames` | Hosts (and subdomains) serving this API, so a `custom` endpoint or aux client there is recognised | `()` |+| `metadata_hostnames` | Hosts identifying this catalog for model metadata only (other credentials) | `()` |+| `models_dev_id` | models.dev provider id when it differs from `name` | `""` |+| `live_context_length()` | Context window from the live, credentialed catalog; after the persistent cache | `None` |+| `normalize_model_id()` | Provider-native id for a model (aliases, catalog repair) | `None` (generic normalization) |+| `ambient_credentials` | Credentials are ambient: never auto-detected; aux fallback skips unless configured | `False` |+| `resolve_api_key_secret()` | Provider-owned `(runtime_api_key, source)` | `None` (env/pool ladder) |+| `runtime_base_url()` | Base URL derived from the credential | `None` (env or default) |+| `prepare_pool_entry()` | Turns the selected pool row's secret into the runtime key | the secret as-is |+| `seed_pool_credentials()` | Pool rows `{source, access_token, base_url, label}` the provider seeds itself | `None` (generic env seeding) |+| `remove_credential_source()` | `hermes auth remove`: `(sources_to_suppress, hints)` | `None` (generic removal) |+| `refresh_runtime_credentials()` | Re-mints `(api_key, base_url)` on `unauthorized` \| `stale` \| `auxiliary_unauthorized`; error path only | `None` |+| `is_stale_credential_error()` | A non-auth error really means the credential went stale (pure) | `False` |+| `credential_refresh_notice()` | Status line after a successful runtime refresh | `""` (generic wording) |+| `request_rejection_hint()` | User-facing lines for an endpoint's hard rejection of any route | `()` |+| `external_auth_evidence()` | Subprocess-free `(verified, source)` login evidence for an external CLI | `None` (binary resolves) |+| `responses_replay_item_ids` | Replayed Responses `message` items keep their `id` | `True` |+| `responses_prompt_cache_key` | The Responses body carries `prompt_cache_key` | `True` |+| `responses_issuer_kind` | Persisted issuer stamp for encrypted reasoning minted here | `""` (URL-derived) |+| `responses_trusts_completed_status` | `False`: a reasoning-only `completed` response continues | `True` |+| `responses_native_compaction` | `False`: never send `context_management` | `True` |+| `responses_profile_reasoning` | `True`: `reasoning` = `reasoning_payload()` + summary, no `include` | `False` |+| `message_carrier_opaque` | Top-level assistant key of an opaque reasoning blob (latest streamed wins) | `""` |+| `message_carrier_text` | Top-level assistant key of readable reasoning text (streamed parts concatenate) | `""` |+| `replays_tool_call_signatures` | Tool calls keep Gemini `extra_content` signatures | `False` |+| `reasoning_payload()` | Verbatim `reasoning` object for a model (catalog-clamped) | `None` |+| `replay_message_carriers()` | Captured `message_carrier_*` values to put back on a replayed assistant message | `{}` |+| `replays_function_thought_signature()` | Replayed tool calls keep `function.thought_signature` | `False` |+| `picker_catalog` | `(force_refresh) -> list`: the provider's own model-picker catalog, tried before the generic fetch | `None` |+| `static_models` | Curated ids registered as this provider's row of the static catalog | `()` |+| `catalog_credential_files` | Credential files whose mtime joins every cached catalog's fingerprint | `()` |+| `probe_models()` | `(ids or None, probed_url, resolved_base_url)` for a `/models` probe this provider answers | `None` (generic HTTP probe) |+| `invalidate_catalog_cache()` | Drops in-process catalog memos (`/model --refresh`) | no-op |+| `picker_after` | Provider slug this row follows in the provider list | `""` (appended) |+| `picker_group` | `(group_id, label, description)`: folds same-group rows in interactive pickers | `()` |+| `catalog_aliases` | `aliases` also normalize in the model catalog | `False` |+| `aggregator` | Catalog re-exposes many vendors' models | `False` |+| `provider_overlay` | HermesOverlay fields for the models.dev-keyed definition | `{}` |+| `overlay_aliases` | Extra names normalizing to the `provider_overlay` definition | `()` |+| `registry_auth_type` | Auth-registry row `auth_type` when credential resolution differs from the setup flow | `""` (`auth_type`) |+| `base_url_env_var` | Env var overriding `base_url` on the registry row when not in `env_vars` | `""` |+| `registry_after` | Registry id this row follows in priority-ordered scans | `""` (appended) |+## Account usageModel-provider plugins can provide account or plan usage to `/usage` by@@ -250,7 +369,7 @@ def fetch_account_usage(self, *, api_key=None, base_url=None):## External-process (ACP) providers-An agent CLI driven over stdio is not an HTTP endpoint. Set `auth_type="external_process"`, describe how to launch the binary, and supply the client with `create_client`. No core edits are needed — `hermes -m <name>`, `/model`, credential resolution, runtime resolution and the auxiliary client (compression, vision) all key on `auth_type`, not on the provider name. `plugins/model-providers/copilot-acp/` is the in-tree example (its `client.py` subclasses the public `ACPClient` below).+An agent CLI driven over stdio is not an HTTP endpoint. Set `auth_type="external_process"`, describe how to launch the binary, and supply the client with `create_client`. No core edits are needed — `hermes -m <name>`, `/model`, credential resolution, runtime resolution and the auxiliary client (compression, vision) all key on `auth_type`, not on the provider name. The `copilot-acp` provider in the [`github-copilot` labs plugin](https://github.com/NousResearch/hermes-labs-plugins/tree/main/github-copilot) is a worked out-of-tree example (its client subclasses the public `ACPClient` below).| Field | Purpose ||---|---|@@ -297,11 +416,11 @@ Keep the class attributes in step with the profile's `process_*` fields. Overrid### Picker rows for non-api-key plugins-Every registered profile joins `CANONICAL_PROVIDERS` by slug (a plugin re-declaring a built-in slug such as `bedrock` is deduped, never doubled), so external-process and OAuth plugins appear in `hermes model`, `/model` and the Desktop model selector alongside `copilot-acp`. Visibility is gated by credentials, not by `auth_type`:+Every registered profile joins `CANONICAL_PROVIDERS` by slug (a plugin re-declaring a built-in slug such as `bedrock` is deduped, never doubled), so external-process and OAuth plugins appear in `hermes model`, `/model` and the Desktop model selector alongside the built-in providers. Visibility is gated by credentials, not by `auth_type`:| `auth_type` | Row is listed / `authenticated` when | Model list ||---|---|---|-| `external_process` | the binary resolves (`process_command` or one of `process_command_env_vars` is on `PATH`), or `base_url` is `acp+tcp://…` — the same structural gate `hermes auth status` reports. A resolving binary is also the sign-in evidence (`auth_verified`) the Desktop model selector's explicit-only filter uses, so the row shows there like the bundled ACP provider does | `fetch_models()` (your subprocess probe), else `fallback_models` |+| `external_process` | the binary resolves (`process_command` or one of `process_command_env_vars` is on `PATH`), or `base_url` is `acp+tcp://…` — the same structural gate `hermes auth status` reports. A resolving binary is also the sign-in evidence (`auth_verified`) the Desktop model selector's explicit-only filter uses, so the row shows there like any signed-in provider does | `fetch_models()` (your subprocess probe), else `fallback_models` || `oauth_external` / `oauth_device_code` | the credential pool holds a row for the slug with a live (non-expired) token — `hermes auth status <name>` and `list_available_providers().authenticated` both read the pool; an expired row with `refresh_token` and a `refresh_credential` hook reports `needs_refresh` | `fetch_models()` with the pooled token, else `fallback_models` (declare at least one) |The catalog cache is keyed on the profile's `process_command_env_vars` / `process_args_env_var` values, so pointing `HERMES_<X>_COMMAND` at a different binary re-discovers models. Executable discovery is not a login check: an unauthenticated CLI still lists, and the subprocess reports the failure at first use.@@ -366,7 +485,7 @@ The override also reaches the runtime. Built-in providers have a row in `hermes_| `env_vars` (non-URL entries) | `api_key_env_vars` | api-key row and profile sets `env_vars` || `env_vars` (final `*_BASE_URL` / `*_URL` entry) | `base_url_env_var` | profile declares one; otherwise the built-in env var (e.g. `GMI_BASE_URL`) stays |-Only a **user** plugin (`$HERMES_HOME/plugins/model-providers/` or an installed `kind: model-provider` plugin) triggers this; a bundled profile never rewrites a built-in row, and `copilot`, `kimi-coding`, `kimi-coding-cn` and `zai` keep their bespoke credential resolution. A field the profile leaves empty keeps the built-in value. A `*_BASE_URL` env var still wins over both.+Only a **user** plugin (`$HERMES_HOME/plugins/model-providers/` or an installed `kind: model-provider` plugin) triggers this; a bundled profile never rewrites a built-in row, and `kimi-coding`, `kimi-coding-cn` and `zai` keep their bespoke credential resolution. A field the profile leaves empty keeps the built-in value. A `*_BASE_URL` env var still wins over both.## api_mode selection@@ -405,11 +524,11 @@ Every `api_mode` gate (`determine_api_mode`, runtime resolution, agent construct| `api_key` | Single env var carries a static API key | Most providers || `oauth_device_code` | Device-code OAuth flow | Nous Portal; out-of-tree plugins via `auth_handler` || `oauth_external` | User signs in elsewhere, tokens land in `auth.json` | Anthropic OAuth, MiniMax OAuth, Qwen Portal, Nous Portal |-| `copilot` | GitHub Copilot token refresh cycle | `copilot` plugin only |+| *plugin-defined* | Any other value: login and refresh are provider-owned (`auth_handler`, `refresh_credential`, the credential hooks below); `registry_auth_type` names the auth-registry row when it differs | e.g. `copilot` in the [`github-copilot` labs plugin](https://github.com/NousResearch/hermes-labs-plugins/tree/main/github-copilot) || `aws_sdk` | AWS SDK credential chain (IAM role, profile, env) | `bedrock` plugin only |-| `external_process` | Auth handled by a subprocess the agent spawns (see [External-process providers](#external-process-acp-providers)) | `copilot-acp` plugin, out-of-tree ACP plugins |+| `external_process` | Auth handled by a subprocess the agent spawns (see [External-process providers](#external-process-acp-providers)) | out-of-tree ACP plugins (e.g. `copilot-acp` in the `github-copilot` labs plugin) |-Every profile is mirrored into Hermes' auth registry under the `auth_type` it declares (two exclusions: an `api_key` profile with empty `env_vars`, and the aggregator/user-supplied slugs `openrouter`/`custom` plus the bespoke-refresh built-ins `copilot`/`kimi-coding`/`zai`), so `hermes auth`,+Every profile is mirrored into Hermes' auth registry under the `auth_type` it declares (two exclusions: an `api_key` profile with empty `env_vars`, and the aggregator/user-supplied slugs `openrouter`/`custom` plus the bespoke-refresh built-ins `kimi-coding`/`kimi-coding-cn`/`zai`), so `hermes auth`,`--provider <name>` and runtime resolution accept it whatever its shape. What differs is who performs thelogin: `api_key` profiles get the built-in key prompt / env-var resolution; every other `auth_type` is**provider-owned** — the plugin ships the two hooks below, and a non-api-key profile without andiff --git a/website/docs/developer-guide/provider-runtime.md b/website/docs/developer-guide/provider-runtime.mdindex 60f1638b1f9..04801d675f5 100644--- a/website/docs/developer-guide/provider-runtime.md+++ b/website/docs/developer-guide/provider-runtime.md@@ -63,7 +63,6 @@ Current provider families include (see `plugins/model-providers/` for the comple- OpenRouter- Nous Portal- OpenAI Codex-- Copilot / Copilot ACP- Anthropic (native)- Google / Gemini (`gemini`)- Alibaba / DashScope (`alibaba`, `alibaba-coding-plan`)diff --git a/website/docs/getting-started/quickstart.md b/website/docs/getting-started/quickstart.mdindex b3304561ffd..0d7c3a7e542 100644--- a/website/docs/getting-started/quickstart.md+++ b/website/docs/getting-started/quickstart.md@@ -149,8 +149,6 @@ Good defaults:| **OpenCode Go** | $10/month subscription for open models | Set `OPENCODE_GO_API_KEY` || **DeepSeek** | Direct DeepSeek API access | Set `DEEPSEEK_API_KEY` || **NVIDIA NIM** | Nemotron models via build.nvidia.com or local NIM | Set `NVIDIA_API_KEY` (optional: `NVIDIA_BASE_URL`) |-| **GitHub Copilot** | GitHub Copilot subscription (GPT-5.x, Claude, Gemini, etc.) | OAuth via `hermes model`, or `COPILOT_GITHUB_TOKEN` / `GH_TOKEN` |-| **GitHub Copilot ACP** | Copilot ACP agent backend (spawns local `copilot` CLI) | `hermes model` (requires `copilot` CLI + `copilot login`) || **Vercel AI Gateway** | Vercel AI Gateway routing | Set `AI_GATEWAY_API_KEY` || **Custom Endpoint** | VLLM, SGLang, Ollama, or any OpenAI-compatible API | Set base URL + API key |diff --git a/website/docs/integrations/providers.md b/website/docs/integrations/providers.mdindex 7e85f0bea90..5b8f0504cb5 100644--- a/website/docs/integrations/providers.md+++ b/website/docs/integrations/providers.md@@ -16,8 +16,6 @@ You need at least one way to connect to an LLM. Use `hermes model` to switch pro|----------|-------|| **Nous Portal** | `hermes model` (OAuth, subscription-based) || **OpenAI Codex** | `hermes model` → **ChatGPT or Codex Subscription** (ChatGPT OAuth, uses Codex models) |-| **GitHub Copilot** | `hermes model` (OAuth device code flow, `COPILOT_GITHUB_TOKEN`, `GH_TOKEN`, or `gh auth token`) |-| **GitHub Copilot ACP** | `hermes model` (spawns local `copilot --acp --stdio`) || **Anthropic** | `hermes model` (Claude Max + extra usage credits via OAuth; also supports Anthropic API key or manual setup-token — see note below) || **OpenRouter** | `OPENROUTER_API_KEY` in `~/.hermes/.env`, or `hermes auth add openrouter --type oauth` (browser login via OpenRouter's PKCE flow; stores a key in the credential pool) || **Ramp Router** | `RAMP_ROUTER_API_KEY` in `~/.hermes/.env` (provider: `router`; aliases: `ramp-router`, `ramp`, `router.com`; Responses-native gateway, live account-scoped catalog) |@@ -207,70 +205,19 @@ model:`--provider claude` and `--provider claude-code` also work as shorthand for `--provider anthropic`.:::-### GitHub Copilot+### GitHub Copilot (labs plugin)-Hermes supports GitHub Copilot as a first-class provider with two modes:--**`copilot` — Direct Copilot API** (recommended). Uses your GitHub Copilot subscription to access GPT-5.x, Claude, Gemini, and other models through the Copilot API.+The GitHub Copilot providers (`copilot` for the Copilot API, `copilot-acp` for the Copilot CLI over ACP) are no longer built into Hermes. They ship as the `github-copilot` **labs plugin** — built by Nous Research, but not supported:```bash-hermes chat --provider copilot --model gpt-5.4+hermes plugins install github-copilot```-**Authentication options** (checked in this order):--1. `COPILOT_GITHUB_TOKEN` environment variable-2. `GH_TOKEN` environment variable-3. `GITHUB_TOKEN` environment variable-4. `gh auth token` CLI fallback--If no token is found, `hermes model` offers an **OAuth device code login** — the same flow used by the Copilot CLI and opencode.--:::warning Token types-The Copilot API does **not** support classic Personal Access Tokens (`ghp_*`). Supported token types:--| Type | Prefix | How to get |-|------|--------|------------|-| OAuth token | `gho_` | `hermes model` → GitHub Copilot → Login with GitHub |-| Fine-grained PAT | `github_pat_` | GitHub Settings → Developer settings → Fine-grained tokens (needs **Copilot Requests** permission) |-| GitHub App token | `ghu_` | Via GitHub App installation |--If your `gh auth token` returns a `ghp_*` token, use `hermes model` to authenticate via OAuth instead.-:::--:::info Copilot auth behavior in Hermes-Hermes sends a supported GitHub token (`gho_*`, `github_pat_*`, or `ghu_*`) directly to `api.githubcopilot.com` and includes Copilot-specific headers (`Editor-Version`, `Copilot-Integration-Id`, `Openai-Intent`, `x-initiator`).--On HTTP 401, Hermes now performs a one-shot credential recovery before fallback:--1. Re-resolve token via the normal priority chain (`COPILOT_GITHUB_TOKEN` → `GH_TOKEN` → `GITHUB_TOKEN` → `gh auth token`)-2. Rebuild the shared OpenAI client with refreshed headers-3. Retry the request once+Profiles that already use `copilot` or `copilot-acp` (main model, fallback, auxiliary, delegation, MoA or cron) get the plugin installed automatically by `hermes update` or at their next agent or gateway start.-Some older community proxies use `api.github.com/copilot_internal/v2/token` exchange flows. That endpoint can be unavailable for some account types (returns 404). Hermes therefore keeps direct-token auth as the primary path and relies on runtime credential refresh + retry for robustness.-:::--**API routing**: GPT-5+ models (except `gpt-5-mini`) automatically use the Responses API. All other models (GPT-4o, Claude, Gemini, etc.) use Chat Completions. Models are auto-detected from the live Copilot catalog.--**`copilot-acp` — Copilot ACP agent backend**. Spawns the local Copilot CLI as a subprocess:--```bash-hermes chat --provider copilot-acp --model copilot-acp-# Requires the GitHub Copilot CLI in PATH and an existing `copilot login` session-```--**Permanent config:**-```yaml-model:- provider: "copilot"- default: "gpt-5.4"-```+Sign in with `hermes auth add copilot` (device-code login), or set `COPILOT_GITHUB_TOKEN`, `GH_TOKEN` or `GITHUB_TOKEN`. Logins made with the `gh` CLI or the Copilot CLI are no longer read: if you relied on them, run `hermes auth add copilot`.-| Environment variable | Description |-|---------------------|-------------|-| `COPILOT_GITHUB_TOKEN` | GitHub token for Copilot API (first priority) |-| `HERMES_COPILOT_ACP_COMMAND` | Override the Copilot CLI binary path (default: `copilot`) |-| `HERMES_COPILOT_ACP_ARGS` | Override ACP args (default: `--acp --stdio`) |+Setup, models and environment variables: [github-copilot plugin docs](https://github.com/NousResearch/hermes-labs-plugins/tree/main/github-copilot).### First-Class API-Key Providers@@ -1323,7 +1270,7 @@ Hermes uses a multi-source resolution chain to detect the correct context window8. **[models.dev](https://models.dev)** — community-maintained registry with provider-specific context lengths for 3800+ models across 100+ providers9. **Fallback defaults** — broad model family patterns (128K default)-For most setups this works out of the box. The system is provider-aware — the same model can have different context limits depending on who serves it (e.g., `claude-opus-4.6` is 1M on Anthropic direct but 128K on GitHub Copilot).+For most setups this works out of the box. The system is provider-aware — the same model can have different context limits depending on who serves it (e.g., `claude-opus-4.6` is 1M on Anthropic direct but smaller through some resellers and aggregators).To set the context length explicitly, add `context_length` to your model config:@@ -1725,7 +1672,7 @@ fallback_model:When activated, the fallback swaps the model and provider mid-session without losing your conversation. The chain is tried entry-by-entry; activation is one-shot per session.-Supported providers: `openrouter`, `nous`, `novita`, `openai-codex`, `copilot`, `copilot-acp`, `anthropic`, `gemini`, `qwen-oauth`, `huggingface`, `zai`, `kimi-coding`, `kimi-coding-cn`, `minimax`, `minimax-cn`, `minimax-oauth`, `deepseek`, `nvidia`, `xai`, `xai-oauth`, `ollama-cloud`, `bedrock`, `ai-gateway`, `azure-foundry`, `opencode-zen`, `opencode-go`, `commandcode`, `commandcode-anthropic`, `kilocode`, `xiaomi`, `arcee`, `gmi`, `actual`, `stepfun`, `lmstudio`, `alibaba`, `alibaba-coding-plan`, `tencent-tokenhub`, `tencent-tokenplan`, `nebius-token-factory`, `router`, `custom`.+Supported providers: `openrouter`, `nous`, `novita`, `openai-codex`, `anthropic`, `gemini`, `qwen-oauth`, `huggingface`, `zai`, `kimi-coding`, `kimi-coding-cn`, `minimax`, `minimax-cn`, `minimax-oauth`, `deepseek`, `nvidia`, `xai`, `xai-oauth`, `ollama-cloud`, `bedrock`, `ai-gateway`, `azure-foundry`, `opencode-zen`, `opencode-go`, `commandcode`, `commandcode-anthropic`, `kilocode`, `xiaomi`, `arcee`, `gmi`, `actual`, `stepfun`, `lmstudio`, `alibaba`, `alibaba-coding-plan`, `tencent-tokenhub`, `tencent-tokenplan`, `nebius-token-factory`, `router`, `custom`.:::tipFallback is configured exclusively through `config.yaml` — or interactively via `hermes fallback`. For full details on when it triggers, how the chain advances, and how it interacts with auxiliary tasks and delegation, see [Fallback Providers](../user-guide/features/fallback-providers.md).diff --git a/website/docs/reference/cli-commands.md b/website/docs/reference/cli-commands.mdindex b9d0edff7db..c4be43cac11 100644--- a/website/docs/reference/cli-commands.md+++ b/website/docs/reference/cli-commands.md@@ -129,7 +129,7 @@ Common options:| `--oneshot` | With `-q`/`--query-file`: answer the query and exit (the pre-0.21 single-query behavior) instead of seeding an interactive session. Implied on non-TTY stdio and by `-Q`. || `-m`, `--model <model>` | Override the model for this run. || `-t`, `--toolsets <csv>` | Enable a comma-separated set of toolsets. |-| `--provider <provider>` | Force a provider: `auto`, `openrouter`, `nous`, `openai-codex` (aliases `chatgpt`, `chatgpt-codex`), `copilot-acp`, `copilot`, `anthropic`, `gemini`, `huggingface`, `novita` (aliases `novita-ai`, `novitaai`), `openai-api`, `zai`, `kimi-coding`, `kimi-coding-cn`, `minimax`, `minimax-cn`, `minimax-oauth`, `kilocode`, `xiaomi`, `arcee`, `gmi`, `upstage` (alias `solar`), `alibaba`, `alibaba-cn`, `alibaba-coding-plan` (alias `alibaba_coding`), `alibaba-coding-plan-cn`, `alibaba-token-plan`, `alibaba-token-plan-cn`, `deepseek`, `nvidia`, `ollama-cloud`, `xai` (alias `grok`), `xai-oauth` (alias `grok-oauth`), `qwen-oauth`, `bedrock`, `opencode-zen`, `opencode-go`, `commandcode`, `commandcode-anthropic`, `ai-gateway`, `azure-foundry`, `lmstudio`, `stepfun`, `tencent-tokenhub` (alias `tencent`, `tokenhub`), `router` (aliases `ramp-router`, `ramp`), `nebius-token-factory` (aliases `nebius`, `nebius-tf`, `tokenfactory`), `tencent-tokenplan` (aliases `tokenplan`, `tencent-lkeap`). |+| `--provider <provider>` | Force a provider: `auto`, `openrouter`, `nous`, `openai-codex` (aliases `chatgpt`, `chatgpt-codex`), `anthropic`, `gemini`, `huggingface`, `novita` (aliases `novita-ai`, `novitaai`), `openai-api`, `zai`, `kimi-coding`, `kimi-coding-cn`, `minimax`, `minimax-cn`, `minimax-oauth`, `kilocode`, `xiaomi`, `arcee`, `gmi`, `upstage` (alias `solar`), `alibaba`, `alibaba-cn`, `alibaba-coding-plan` (alias `alibaba_coding`), `alibaba-coding-plan-cn`, `alibaba-token-plan`, `alibaba-token-plan-cn`, `deepseek`, `nvidia`, `ollama-cloud`, `xai` (alias `grok`), `xai-oauth` (alias `grok-oauth`), `qwen-oauth`, `bedrock`, `opencode-zen`, `opencode-go`, `commandcode`, `commandcode-anthropic`, `ai-gateway`, `azure-foundry`, `lmstudio`, `stepfun`, `tencent-tokenhub` (alias `tencent`, `tokenhub`), `router` (aliases `ramp-router`, `ramp`), `nebius-token-factory` (aliases `nebius`, `nebius-tf`, `tokenfactory`), `tencent-tokenplan` (aliases `tokenplan`, `tencent-lkeap`). || `-s`, `--skills <name>` | Preload one or more skills for the session (can be repeated or comma-separated). || `-v`, `--verbose` | Verbose output. || `-Q`, `--quiet` | Programmatic mode: suppress banner/spinner/tool previews. |@@ -264,8 +264,8 @@ hermes model```Use this when you want to:-- **add a new provider** (OpenRouter, Anthropic, Copilot, DeepSeek, custom, etc.)-- log into OAuth-backed providers (Anthropic, Copilot, Codex, Nous Portal)+- **add a new provider** (OpenRouter, Anthropic, DeepSeek, custom, etc.)+- log into OAuth-backed providers (Anthropic, Codex, Nous Portal)- enter or update API keys- pick from provider-specific model lists- configure a custom/self-hosted endpoint@@ -300,7 +300,7 @@ By default, `/model` changes apply **to the current session only**. Add `--globa```:::info What if I only see OpenRouter models?-If you've only configured OpenRouter, `/model` will only show OpenRouter models. To add another provider (Anthropic, DeepSeek, Copilot, etc.), exit your session and run `hermes model` from the terminal.+If you've only configured OpenRouter, `/model` will only show OpenRouter models. To add another provider (Anthropic, DeepSeek, etc.), exit your session and run `hermes model` from the terminal.:::On a `--global` switch, provider and base URL changes are persisted to `config.yaml` alongside the model. When switching away from a custom endpoint, the stale base URL is cleared to prevent it leaking into other providers.diff --git a/website/docs/reference/environment-variables.md b/website/docs/reference/environment-variables.mdindex dba43302610..fb1f9b10bd8 100644--- a/website/docs/reference/environment-variables.md+++ b/website/docs/reference/environment-variables.md@@ -26,14 +26,8 @@ Hermes reads environment variables from the process environment and, for user-ma| `HERMES_CODEX_BASE_URL` | Route the `openai-codex` (ChatGPT subscription) provider through a proxy instead of the default Codex backend. Applies everywhere the credential is used: pool resolution, auxiliary/raw clients, and 401/429 credential rotation. `model.base_url` under `model.provider: openai-codex` is the secondary override when this is unset. || `LM_API_KEY` | API key for LM Studio (`lmstudio` provider). Often a placeholder for local servers || `LM_BASE_URL` | LM Studio base URL (default: `http://localhost:1234/v1`) |-| `COPILOT_GITHUB_TOKEN` | GitHub token for Copilot API — first priority (OAuth `gho_*` or fine-grained PAT `github_pat_*`; classic PATs `ghp_*` are **not supported**) |-| `GH_TOKEN` | GitHub token — second priority for Copilot (also used by `gh` CLI) |-| `GITHUB_TOKEN` | GitHub token — third priority for Copilot |-| `HERMES_COPILOT_ACP_COMMAND` | Override Copilot ACP CLI binary path (default: `copilot`) |-| `COPILOT_CLI_PATH` | Alias for `HERMES_COPILOT_ACP_COMMAND` |-| `HERMES_COPILOT_ACP_ARGS` | Override Copilot ACP arguments (default: `--acp --stdio`) |-| `COPILOT_ACP_BASE_URL` | Override Copilot ACP base URL |-| `COPILOT_API_BASE_URL` | Override the Copilot API base URL (`copilot` provider) |+| `GH_TOKEN` | GitHub token (also used by the `gh` CLI); honoured wherever Hermes reads `GITHUB_TOKEN` |+| `GITHUB_TOKEN` | GitHub token for GitHub API access (Skills Hub, git credentials, update checks; see the Skills Hub row below) || `GLM_API_KEY` | z.ai / ZhipuAI GLM API key ([z.ai](https://z.ai)) || `ZAI_API_KEY` | Alias for `GLM_API_KEY` || `Z_AI_API_KEY` | Alias for `GLM_API_KEY` |diff --git a/website/docs/user-guide/configuration.md b/website/docs/user-guide/configuration.mdindex 0b841f59c20..13ca79883b0 100644--- a/website/docs/user-guide/configuration.md+++ b/website/docs/user-guide/configuration.md@@ -159,7 +159,7 @@ A local `hermes chat` / TUI session served by the gateway resolves these referenCursor-style SecretRef syntax is also accepted: `${env:VAR_NAME}` resolves exactly like `${VAR_NAME}` (the `env:` prefix is stripped), so MCP or provider snippets copied from Cursor / Claude configs work unchanged in both `config.yaml` and the `mcp_servers` block. Other SecretRef sources (`${file:...}`, `${vault:...}`, `${bitwarden:...}`) are **not** resolved inline — external secret backends inject their values into the environment at startup via the `secrets:` block, so reference them as `${env:NAME}` instead; unknown prefixes warn once and stay verbatim.-For AI provider setup (OpenRouter, Anthropic, Copilot, custom endpoints, self-hosted LLMs, fallback models, etc.), see [AI Providers](../integrations/providers.md).+For AI provider setup (OpenRouter, Anthropic, custom endpoints, self-hosted LLMs, fallback models, etc.), see [AI Providers](../integrations/providers.md).### Provider Timeouts@@ -1572,7 +1572,7 @@ auxiliary:When `base_url` is set, Hermes ignores the provider and calls that endpoint directly (using `api_key` or `OPENAI_API_KEY` for auth). When only `provider` is set, Hermes uses that provider's built-in auth and base URL.-Available providers for auxiliary tasks: `auto`, `main`, plus any provider in the [provider registry](../reference/environment-variables.md) — `openrouter`, `nous`, `openai-codex`, `copilot`, `copilot-acp`, `anthropic`, `gemini`, `qwen-oauth`, `zai`, `kimi-coding`, `kimi-coding-cn`, `minimax`, `minimax-cn`, `minimax-oauth`, `deepseek`, `nvidia`, `xai`, `xai-oauth`, `ollama-cloud`, `alibaba`, `bedrock`, `huggingface`, `arcee`, `xiaomi`, `kilocode`, `opencode-zen`, `opencode-go`, `commandcode`, `commandcode-anthropic`, `ai-gateway`, `azure-foundry` — or any named custom provider from your `providers:` dict (e.g. `provider: "beans"`).+Available providers for auxiliary tasks: `auto`, `main`, plus any provider in the [provider registry](../reference/environment-variables.md) — `openrouter`, `nous`, `openai-codex`, `anthropic`, `gemini`, `qwen-oauth`, `zai`, `kimi-coding`, `kimi-coding-cn`, `minimax`, `minimax-cn`, `minimax-oauth`, `deepseek`, `nvidia`, `xai`, `xai-oauth`, `ollama-cloud`, `alibaba`, `bedrock`, `huggingface`, `arcee`, `xiaomi`, `kilocode`, `opencode-zen`, `opencode-go`, `commandcode`, `commandcode-anthropic`, `ai-gateway`, `azure-foundry` — or any named custom provider from your `providers:` dict (e.g. `provider: "beans"`).Local OpenAI-compatible servers work under their own names too: `provider: ollama` (also `vllm`, `llamacpp`, `llama.cpp`) with a `base_url` such as `http://127.0.0.1:11434` and an empty `api_key` routes through the custom endpoint with a placeholder key, and a bare `host:port` base_url gets the `/v1` suffix automatically.@@ -2041,7 +2041,7 @@ agent:`/fast normal|fast|ultrafast|auto|cold` switches the mode for the session (`/fast ultra` is shorthand for `ultrafast`). On a ChatGPT/Codex subscription, Ultrafast is offered only when your account's Codex model catalog lists it for the current model; the backend otherwise accepts the request and serves standard speed. Add `--global` to persist to `config.yaml`. `/fast` alone shows the current mode.-**Cost note:** both providers bill fast requests at a multiplier on standard rates (Anthropic: $8 / $40 per MTok in/out on Opus 5.5, $10 / $50 on Opus 5 and Opus 4.8), stacking with prompt-cache pricing. Hermes prices each Anthropic response from the speed the API reports in `usage.speed`. `auto`/`cold` bound that premium to the window only. Fast params are only sent to the first-party endpoint that supports them (`api.openai.com` / Codex subscription, `api.anthropic.com`, `api.x.ai`); OpenRouter, Nous Portal, Copilot, Azure, Bedrock, and custom `base_url` routes never receive them in any mode.+**Cost note:** both providers bill fast requests at a multiplier on standard rates (Anthropic: $8 / $40 per MTok in/out on Opus 5.5, $10 / $50 on Opus 5 and Opus 4.8), stacking with prompt-cache pricing. Hermes prices each Anthropic response from the speed the API reports in `usage.speed`. `auto`/`cold` bound that premium to the window only. Fast params are only sent to the first-party endpoint that supports them (`api.openai.com` / Codex subscription, `api.anthropic.com`, `api.x.ai`); OpenRouter, Nous Portal, Azure, Bedrock, and custom `base_url` routes never receive them in any mode.**Prompt cache:** only the per-request parameter changes between requests; the system prompt, tools, and messages stay byte-identical. Anthropic keeps a separate prompt cache for each speed, so on Anthropic every `auto`/`cold` window boundary re-writes the conversation prefix at the new speed. For long Anthropic sessions, `fast` or `normal` keeps a single warm cache.@@ -3079,7 +3079,7 @@ delegation:```**Wire protocol (`api_mode`):** Hermes auto-detects the wire protocol from `delegation.base_url` (e.g. paths ending in `/anthropic` → `anthropic_messages`; Codex / native Anthropic / Kimi-coding hostnames keep their existing detection). For endpoints the heuristic can't classify — for example Azure AI Foundry, MiniMax, Zhipu GLM, or LiteLLM proxies fronting an Anthropic-shaped backend — set `delegation.api_mode` explicitly to one of `chat_completions`, `codex_responses`, or `anthropic_messages`. Leave it empty (the default) to keep auto-detection.-The delegation provider uses the same credential resolution as CLI/gateway startup. All configured providers are supported: `openrouter`, `nous`, `copilot`, `zai`, `kimi-coding`, `minimax`, `minimax-cn`. When a provider is set, the system automatically resolves the correct base URL, API key, and API mode — no manual credential wiring needed.+The delegation provider uses the same credential resolution as CLI/gateway startup. All configured providers are supported: `openrouter`, `nous`, `zai`, `kimi-coding`, `minimax`, `minimax-cn`. When a provider is set, the system automatically resolves the correct base URL, API key, and API mode — no manual credential wiring needed.**Precedence:** `delegation.base_url` in config → `delegation.provider` in config → parent provider (inherited). `delegation.model` in config → parent model (inherited). Setting just `model` without `provider` changes only the model name while keeping the parent's credentials (useful for switching models within the same provider like OpenRouter).diff --git a/website/docs/user-guide/features/fallback-providers.md b/website/docs/user-guide/features/fallback-providers.mdindex 32d698c0202..849e6ee68ba 100644--- a/website/docs/user-guide/features/fallback-providers.md+++ b/website/docs/user-guide/features/fallback-providers.md@@ -67,8 +67,6 @@ OpenAI-compatible base URL continues to use the compatible client instead.| OpenRouter | `openrouter` | `OPENROUTER_API_KEY` || Nous Portal | `nous` | `hermes setup --portal` (fresh) or `hermes auth add nous` (OAuth) || OpenAI Codex | `openai-codex` | `hermes model` → **ChatGPT or Codex Subscription** (ChatGPT OAuth) |-| GitHub Copilot | `copilot` | `COPILOT_GITHUB_TOKEN`, `GH_TOKEN`, or `GITHUB_TOKEN` |-| GitHub Copilot ACP | `copilot-acp` | External process (editor integration) || Anthropic | `anthropic` | `ANTHROPIC_API_KEY` or Claude Code credentials || z.ai / GLM | `zai` | `GLM_API_KEY` || Kimi / Moonshot | `kimi-coding` | `KIMI_API_KEY` |diff --git a/website/docs/user-guide/features/subscription-proxy.md b/website/docs/user-guide/features/subscription-proxy.mdindex 666969772bc..b2b9ce097d8 100644--- a/website/docs/user-guide/features/subscription-proxy.md+++ b/website/docs/user-guide/features/subscription-proxy.md@@ -202,7 +202,7 @@ proxy is a credential-attaching pass-through.## Future: more OAuth providersThe adapter system is pluggable. Adding a new provider (e.g.-HuggingFace, GitHub Copilot's chat endpoint, Anthropic via OAuth)+HuggingFace, Anthropic via OAuth)requires implementing `UpstreamAdapter` in`hermes_cli/proxy/adapters/<provider>.py` and registering it in`adapters/__init__.py`. Providers that aren't OpenAI-compatible at thediff --git a/website/docs/user-guide/multi-profile-gateways.md b/website/docs/user-guide/multi-profile-gateways.mdindex bb9531b1f0a..af1411a614c 100644--- a/website/docs/user-guide/multi-profile-gateways.md+++ b/website/docs/user-guide/multi-profile-gateways.md@@ -677,7 +677,7 @@ profile and never shares with the default or any sibling:| Working directory of a turn (unset `terminal.cwd`) | Same rule as a standalone gateway: `$HOME` for the local backend, sandbox default otherwise | Never the directory the multiplexer process was launched from || Command approvals (`command_allowlist`, "always" choices) | The profile's own `config.yaml` | A default-profile "always" never pre-approves a secondary's command; a secondary's choice is saved to its own config || Sandbox credential-file mounts (`terminal.credential_files`), `security.redact_secrets`, `browser.*` engine/headed flags, `lsp.*`, auxiliary-provider health marks, `logs/mcp-stderr.log` | The profile's own `config.yaml` / `.env` | Documented default — never the launch profile's cached value |-| Cloud-SDK credential clients (Bedrock boto3 clients + model discovery, Azure Entra credential), credential-fetched catalogs (DeepInfra, Copilot context limits, Nous reasoning caps, Ramp Router efforts, xAI / OpenRouter image models, custom-endpoint `/models`), computer-use aux-vision routing, remote-backend probe text, learned image token costs, `display.skin`, guest-mint back-off, banner skills, Yuanbao "active" adapter, Langfuse client | The profile's own `.env` / `config.yaml` / `<home>/cache` | Documented default — never the launch profile's cached value or its credentials |+| Cloud-SDK credential clients (Bedrock boto3 clients + model discovery, Azure Entra credential), credential-fetched catalogs (DeepInfra, plugin-provider context limits, Nous reasoning caps, Ramp Router efforts, xAI / OpenRouter image models, custom-endpoint `/models`), computer-use aux-vision routing, remote-backend probe text, learned image token costs, `display.skin`, guest-mint back-off, banner skills, Yuanbao "active" adapter, Langfuse client | The profile's own `.env` / `config.yaml` / `<home>/cache` | Documented default — never the launch profile's cached value or its credentials || Session-search knobs (`sessions.cjk_fts`, `sessions.search_slow_ms`) | The profile's `config.yaml` | Documented default — never the default profile's bridged value || RoomLink capability catalog and the signed execution policy it advertises to a remote Bot (`approvals.mode`, `agent.max_turns`, `platform_toolsets.api_server`) | The served profile named by the request (`/p/<profile>/v1/room-members/...`, the RPC `profile` param); `target_profile` is **required** on every catalog — there is no `HERMES_PROFILE` fallback | Invitation/capabilities fail with the offending `target_profile` named; a profile that does not exist is refused, never resolved from the launch profile's config || Platform proxies (`TELEGRAM_PROXY`, `DISCORD_PROXY`, `HTTPS_PROXY`, …) | The profile's own `.env` | Direct connection — never the default profile's proxy |diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/adding-providers.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/adding-providers.mdindex 46b12e56d0c..21fe94e7f0e 100644--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/adding-providers.md+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/adding-providers.md@@ -127,7 +127,7 @@ Hermes 已经可以通过自定义 provider 路径与任何 OpenAI 兼容的端当你的 provider 需要以下任何内容时,使用下面的完整清单:-- OAuth 或 token 刷新(Nous Portal、Codex、Qwen Portal、Copilot)+- OAuth 或 token 刷新(Nous Portal、Codex、Qwen Portal)- 需要新适配器的非 OpenAI API 格式(Anthropic Messages、Codex Responses)- 自定义端点检测或多区域探测(z.ai、Kimi)- 精选的静态模型目录或实时 `/models` 获取diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/model-provider-plugin.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/model-provider-plugin.mdindex 9940782d6ce..4ee028994c3 100644--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/model-provider-plugin.md+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/model-provider-plugin.md@@ -98,9 +98,9 @@ author: Your Name| `env_vars` | `tuple[str, ...]` | 按优先级排列的 API key 环境变量;最后一个 `*_BASE_URL` 条目用作用户 base URL 覆盖 || `base_url` | str | 默认推理端点 || `models_url` | str | 显式目录 URL(回退到 `{base_url}/models`) |-| `auth_type` | str | `api_key` \| `oauth_device_code` \| `oauth_external` \| `copilot` \| `aws_sdk` \| `external_process` |+| `auth_type` | str | `api_key` \| `oauth_device_code` \| `oauth_external` \| `aws_sdk` \| `external_process` \| 任意插件自定义值(此时登录由提供商自行负责) || `fallback_models` | `tuple[str, ...]` | 实时目录获取失败时显示的精选列表 |-| `default_headers` | `dict[str, str]` | 随每个请求发送(如 Copilot 的 `Editor-Version`) |+| `default_headers` | `dict[str, str]` | 随每个请求发送(如 IDE 订阅类 API 要求的 `Editor-Version` 请求头) || `fixed_temperature` | Any | `None` = 使用调用方的值;`OMIT_TEMPERATURE` 哨兵值 = 完全不发送 temperature(Kimi) || `default_max_tokens` | `int \| None` | 提供商级别的 max_tokens 上限(Nvidia:16384) || `default_aux_model` | str | 用于辅助任务(压缩、视觉、摘要)的廉价模型 |@@ -142,6 +142,119 @@ class AcmeProfile(ProviderProfile):return super().fetch_models(api_key=api_key, timeout=timeout)```+## ProviderProfile fields and hooks++`providers/base.py` 声明的全部字段与 hook,按声明顺序排列(下表保留英文原文)。名称以 `()` 结尾的是需在子类中覆盖的方法,其余为 dataclass 字段(其中少数,如 `picker_catalog` 和设备码登录相关字段,接收可调用对象)。按端点区分的 hook(`client_headers`、`request_headers`、`max_tokens_param`)接收请求的 `base_url`,对不属于你的端点返回 `None` / `{}`;`responses_*`、`message_carrier_*` 字段及推理回放 hook 仅作用于 profile 在 `hostnames` 中声明的主机。热路径 hook 必须是纯函数且开销低(无 I/O),除非说明中另有注明。++| Name | Meaning | Default |+|---|---|---|+| `name` | Canonical provider id (`model.provider`, `--provider`) | required |+| `api_mode` | Static wire protocol; `api_mode_for_model()` can vary it per model | `"chat_completions"` |+| `aliases` | Alternative names `get_provider_profile()` resolves | `()` |+| `display_name` | Human label in pickers | `""` |+| `description` | Picker subtitle | `""` |+| `signup_url` | Shown during setup | `""` |+| `hidden` | Pre-release: kept off discovery surfaces until `listed()` is true; resolution by name still works | `False` |+| `env_vars` | API-key env vars in priority order; a final `*_BASE_URL` entry is the base-URL override | `()` |+| `base_url` | Default inference endpoint | `""` |+| `models_url` | Explicit models endpoint (else `{base_url}/models`) | `""` |+| `auth_type` | `api_key` \| `oauth_device_code` \| `oauth_external` \| `external_process` \| `aws_sdk` \| plugin-defined | `"api_key"` |+| `supports_streaming` | `None` keeps transport defaults, `True` opts a process client into streaming, `False` disables it | `None` |+| `supports_health_check` | `False`: `hermes doctor` skips the `/models` probe | `True` |+| `supports_model_listing` | `False`: `fetch_models()` returns `None` without a network call | `True` |+| `auth_handler` | Provider-owned `hermes auth add\|status\|logout\|refresh <name>`; truthy return = handled | `None` |+| `refresh_credential` | Rotates a pooled OAuth row and returns the rotated fields | `None` |+| `classify_api_error` | Error classification for this provider's failures, before the built-in pipeline | `None` |+| `supports_vision` | API accepts images inside tool-result messages | `False` |+| `supports_vision_tool_messages` | API accepts list-type (multipart) tool message content | `True` |+| `supports_prompt_cache_key` | Chat Completions endpoint documents `prompt_cache_key` | `False` |+| `native_reasoning_details_type` | Namespaced `<provider>.native_assistant` reasoning carrier only this profile receives | `None` |+| `process_command` | External-process default binary | `""` |+| `process_args` | External-process default argv tail | `()` |+| `process_command_env_vars` | Env vars overriding the binary, in priority order | `()` |+| `process_args_env_var` | Env var overriding argv (shlex-split) | `""` |+| `process_command_fallback` | Serves a pinned `delegation.command` no profile's `process_command` names; first registered wins | `False` |+| `fallback_models` | Curated picker list when the live fetch fails | `()` |+| `model_aliases` | Short name → model id; `/model <alias>` resolves here first | `{}` |+| `hostname` | Base hostname for URL → provider reverse mapping (derived from `base_url` when empty) | `""` |+| `default_headers` | Headers on every request and on the default catalog fetch | `{}` |+| `fixed_temperature` | `None` = caller's value; `OMIT_TEMPERATURE` = never send temperature | `None` |+| `default_max_tokens` | Provider-level max_tokens cap | `None` |+| `unsupported_response_formats` | `response_format` types auxiliary requests omit | `()` |+| `default_aux_model` | Cheap model for auxiliary tasks; empty = main model | `""` |+| `model_capabilities` | Per-model metadata in the `model_overrides` schema | `{}` |+| `account_card` | Accounts-tab card overrides `{name, flow, cli_command, docs_url}` (Desktop/dashboard) | `{}` |+| `account_status` | Live status for that card; subprocess- and network-free | `None` (`auth.get_auth_status(name)`) |+| `start_device_login` | In-app device-code sign-in: returns `{user_code, verification_url, expires_in, interval, state}` | `None` |+| `poll_device_login` | One poll of that login: `{status, interval?, credential?, message?}` | `None` |+| `save_device_login` | Persists the approved credential (core calls it in the session's profile scope) | `None` |+| `model_setup_flow` | The provider's own `hermes model` step (credential prompt, catalog, persist) | `None` (generic flow for `auth_type`) |+| `setup_reasoning_efforts` | Effort levels the setup picker offers for a model; `()` = no reasoning control | `None` (generic ladder) |+| `fetch_account_usage()` | `/usage` snapshot when no built-in usage fetcher owns the provider | `None` |+| `resolve_aux_model()` | Live cheap-model id for auxiliary tasks; cached, never raises | `""` (use `default_aux_model`) |+| `get_hostname()` | Provider hostname for URL detection | `hostname`, else from `base_url` |+| `prepare_messages()` | Message preprocessing after codex sanitization, before the developer-role swap | pass-through |+| `build_extra_body()` | Provider-specific `extra_body` fields | `{}` |+| `default_reasoning_config()` | Reasoning config sent when `agent.reasoning_effort` is unset | `None` |+| `build_api_kwargs_extras()` | `(extra_body_additions, top_level_kwargs)` split | `({}, {})` |+| `build_client_kwargs_extras()` | OpenAI-client kwargs defaults (explicit settings win; no I/O) | `{}` |+| `default_vision_model()` | Provider's default vision model id | `None` |+| `get_model_context_length()` | Provider-qualified context bound; explicit user overrides win | `None` |+| `get_usage_cost()` | `CostResult` from canonical usage (estimates are never `actual`) | `None` |+| `get_max_tokens()` | Per-model max_tokens cap when the user set none | `default_max_tokens` |+| `supported_reasoning_efforts()` | Effort vocabulary for a model: `None` unknown, `()` none, tuple = clamp; no I/O | `None` |+| `api_mode_for_model()` | Wire this provider serves a model on; `api_key` given only at resolution time | `None` (static `api_mode`) |+| `client_headers()` | Default headers for a client built for `base_url` (`has_images` for image requests) | `None` (static `default_headers`) |+| `request_headers()` | Per-request `extra_headers` for `base_url`; `user_initiated` on a turn's first call | `{}` |+| `max_tokens_param()` | `"max_completion_tokens"` or `"max_tokens"` for `base_url` | `None` (core heuristic) |+| `listed()` | Whether discovery surfaces may offer the provider | `True` unless `hidden` with no pool row |+| `create_client()` | Provider-specific client object (ACP shim, native SDK) | `None` (standard client) |+| `setup_status()` | External-process login state `{available, logged_in, plan, detail, login_command}` | `None` |+| `discover_models()` | External-process live picker `[{id, label, note}]` without inference | `None` (`fallback_models`) |+| `fetch_models()` | Live model ids | GET `{models_url or base_url}/models` |+| `hostnames` | Hosts (and subdomains) serving this API, so a `custom` endpoint or aux client there is recognised | `()` |+| `metadata_hostnames` | Hosts identifying this catalog for model metadata only (other credentials) | `()` |+| `models_dev_id` | models.dev provider id when it differs from `name` | `""` |+| `live_context_length()` | Context window from the live, credentialed catalog; after the persistent cache | `None` |+| `normalize_model_id()` | Provider-native id for a model (aliases, catalog repair) | `None` (generic normalization) |+| `ambient_credentials` | Credentials are ambient: never auto-detected; aux fallback skips unless configured | `False` |+| `resolve_api_key_secret()` | Provider-owned `(runtime_api_key, source)` | `None` (env/pool ladder) |+| `runtime_base_url()` | Base URL derived from the credential | `None` (env or default) |+| `prepare_pool_entry()` | Turns the selected pool row's secret into the runtime key | the secret as-is |+| `seed_pool_credentials()` | Pool rows `{source, access_token, base_url, label}` the provider seeds itself | `None` (generic env seeding) |+| `remove_credential_source()` | `hermes auth remove`: `(sources_to_suppress, hints)` | `None` (generic removal) |+| `refresh_runtime_credentials()` | Re-mints `(api_key, base_url)` on `unauthorized` \| `stale` \| `auxiliary_unauthorized`; error path only | `None` |+| `is_stale_credential_error()` | A non-auth error really means the credential went stale (pure) | `False` |+| `credential_refresh_notice()` | Status line after a successful runtime refresh | `""` (generic wording) |+| `request_rejection_hint()` | User-facing lines for an endpoint's hard rejection of any route | `()` |+| `external_auth_evidence()` | Subprocess-free `(verified, source)` login evidence for an external CLI | `None` (binary resolves) |+| `responses_replay_item_ids` | Replayed Responses `message` items keep their `id` | `True` |+| `responses_prompt_cache_key` | The Responses body carries `prompt_cache_key` | `True` |+| `responses_issuer_kind` | Persisted issuer stamp for encrypted reasoning minted here | `""` (URL-derived) |+| `responses_trusts_completed_status` | `False`: a reasoning-only `completed` response continues | `True` |+| `responses_native_compaction` | `False`: never send `context_management` | `True` |+| `responses_profile_reasoning` | `True`: `reasoning` = `reasoning_payload()` + summary, no `include` | `False` |+| `message_carrier_opaque` | Top-level assistant key of an opaque reasoning blob (latest streamed wins) | `""` |+| `message_carrier_text` | Top-level assistant key of readable reasoning text (streamed parts concatenate) | `""` |+| `replays_tool_call_signatures` | Tool calls keep Gemini `extra_content` signatures | `False` |+| `reasoning_payload()` | Verbatim `reasoning` object for a model (catalog-clamped) | `None` |+| `replay_message_carriers()` | Captured `message_carrier_*` values to put back on a replayed assistant message | `{}` |+| `replays_function_thought_signature()` | Replayed tool calls keep `function.thought_signature` | `False` |+| `picker_catalog` | `(force_refresh) -> list`: the provider's own model-picker catalog, tried before the generic fetch | `None` |+| `static_models` | Curated ids registered as this provider's row of the static catalog | `()` |+| `catalog_credential_files` | Credential files whose mtime joins every cached catalog's fingerprint | `()` |+| `probe_models()` | `(ids or None, probed_url, resolved_base_url)` for a `/models` probe this provider answers | `None` (generic HTTP probe) |+| `invalidate_catalog_cache()` | Drops in-process catalog memos (`/model --refresh`) | no-op |+| `picker_after` | Provider slug this row follows in the provider list | `""` (appended) |+| `picker_group` | `(group_id, label, description)`: folds same-group rows in interactive pickers | `()` |+| `catalog_aliases` | `aliases` also normalize in the model catalog | `False` |+| `aggregator` | Catalog re-exposes many vendors' models | `False` |+| `provider_overlay` | HermesOverlay fields for the models.dev-keyed definition | `{}` |+| `overlay_aliases` | Extra names normalizing to the `provider_overlay` definition | `()` |+| `registry_auth_type` | Auth-registry row `auth_type` when credential resolution differs from the setup flow | `""` (`auth_type`) |+| `base_url_env_var` | Env var overriding `base_url` on the registry row when not in `env_vars` | `""` |+| `registry_after` | Registry id this row follows in priority-ordered scans | `""` (appended) |+## Hook 参考示例参考以下内置插件了解常用写法:@@ -195,9 +308,9 @@ register_provider(ProviderProfile(| `api_key` | 单个环境变量携带静态 API key | 大多数提供商 || `oauth_device_code` | 设备码 OAuth 流程 | — || `oauth_external` | 用户在其他地方登录,token 存入 `auth.json` | Anthropic OAuth、MiniMax OAuth、Qwen Portal、Nous Portal |-| `copilot` | GitHub Copilot token 刷新周期 | 仅 `copilot` 插件 |+| *插件自定义* | 其他任意值:登录与刷新由提供商自行负责(`auth_handler`、`refresh_credential` 及凭据 hook);若认证注册表行不同,用 `registry_auth_type` 指定 | 例如 [`github-copilot` labs 插件](https://github.com/NousResearch/hermes-labs-plugins/tree/main/github-copilot) 中的 `copilot` || `aws_sdk` | AWS SDK 凭据链(IAM role、profile、env) | 仅 `bedrock` 插件 |-| `external_process` | 认证由 agent 启动的子进程处理 | 仅 `copilot-acp` 插件 |+| `external_process` | 认证由 agent 启动的子进程处理 | 树外 ACP 插件(例如 `github-copilot` labs 插件中的 `copilot-acp`) |`auth_type` 控制哪些代码路径将你的提供商视为"简单 api-key 提供商"——若不是 `api_key`,PluginManager 仍会记录 manifest,但 Hermes CLI 层面的自动化(doctor 检查、`--provider` 标志、设置向导委托)可能会跳过它。diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/provider-runtime.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/provider-runtime.mdindex 175244cd782..3483e632ee5 100644--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/provider-runtime.md+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/provider-runtime.md@@ -46,7 +46,6 @@ Hermes 拥有一个共享的 provider 运行时解析器,用于以下场景:- OpenRouter- Nous Portal- OpenAI Codex-- Copilot / Copilot ACP- Anthropic(原生)- Google / Gemini(`gemini`)- Alibaba / DashScope(`alibaba`、`alibaba-coding-plan`)diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/getting-started/quickstart.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/getting-started/quickstart.mdindex aee1b315e83..41e95ffe520 100644--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/getting-started/quickstart.md+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/getting-started/quickstart.md@@ -120,8 +120,6 @@ hermes setup --portal| **OpenCode Go** | $10/月订阅,访问开源模型 | 设置 `OPENCODE_GO_API_KEY` || **DeepSeek** | 直接访问 DeepSeek API | 设置 `DEEPSEEK_API_KEY` || **NVIDIA NIM** | 通过 build.nvidia.com 或本地 NIM 使用 Nemotron 模型 | 设置 `NVIDIA_API_KEY`(可选:`NVIDIA_BASE_URL`) |-| **GitHub Copilot** | GitHub Copilot 订阅(GPT-5.x、Claude、Gemini 等) | 通过 `hermes model` 进行 OAuth,或设置 `COPILOT_GITHUB_TOKEN` / `GH_TOKEN` |-| **GitHub Copilot ACP** | Copilot ACP agent 后端(在本地启动 `copilot` CLI) | `hermes model`(需要 `copilot` CLI + `copilot login`) || **Vercel AI Gateway** | Vercel AI Gateway 路由 | 设置 `AI_GATEWAY_API_KEY` || **Custom Endpoint** | VLLM、SGLang、Ollama 或任何兼容 OpenAI 的 API | 设置 base URL + API key |diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/integrations/providers.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/integrations/providers.mdindex 565edf9d8b8..cfc2da5132d 100644--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/integrations/providers.md+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/integrations/providers.md@@ -16,8 +16,6 @@ sidebar_position: 1|----------|-------|| **Nous Portal** | `hermes model`(OAuth,订阅制) || **OpenAI Codex** | `hermes model` → **ChatGPT or Codex Subscription**(ChatGPT OAuth,使用 Codex 模型) |-| **GitHub Copilot** | `hermes model`(OAuth 设备码流程,`COPILOT_GITHUB_TOKEN`、`GH_TOKEN` 或 `gh auth token`) |-| **GitHub Copilot ACP** | `hermes model`(在本地生成 `copilot --acp --stdio` 子进程) || **Anthropic** | `hermes model`(Claude Max + 额外用量积分,通过 OAuth;也支持 Anthropic API key 或手动 setup-token——见下方说明) || **OpenRouter** | `~/.hermes/.env` 中的 `OPENROUTER_API_KEY` || **NovitaAI** | `~/.hermes/.env` 中的 `NOVITA_API_KEY`(provider: `novita`,200+ 模型,Model API、Agent Sandbox、GPU Cloud) |@@ -147,70 +145,19 @@ model:`--provider claude` 和 `--provider claude-code` 也可作为 `--provider anthropic` 的简写。:::-### GitHub Copilot+### GitHub Copilot(labs 插件)-Hermes 以一等提供商身份支持 GitHub Copilot,提供两种模式:--**`copilot` — 直连 Copilot API**(推荐)。使用你的 GitHub Copilot 订阅,通过 Copilot API 访问 GPT-5.x、Claude、Gemini 等模型。+GitHub Copilot 提供商(`copilot` 对应 Copilot API,`copilot-acp` 对应通过 ACP 驱动的 Copilot CLI)已不再内置于 Hermes,而是以 `github-copilot` **labs 插件**的形式发布——由 Nous Research 构建,但不提供支持:```bash-hermes chat --provider copilot --model gpt-5.4+hermes plugins install github-copilot```-**认证选项**(按以下顺序检查):--1. `COPILOT_GITHUB_TOKEN` 环境变量-2. `GH_TOKEN` 环境变量-3. `GITHUB_TOKEN` 环境变量-4. `gh auth token` CLI 回退--如果未找到 token,`hermes model` 会提供 **OAuth 设备码登录**——与 Copilot CLI 和 opencode 使用的流程相同。--:::warning Token 类型-Copilot API **不**支持经典个人访问 token(`ghp_*`)。支持的 token 类型:--| 类型 | 前缀 | 获取方式 |-|------|--------|------------|-| OAuth token | `gho_` | `hermes model` → GitHub Copilot → 使用 GitHub 登录 |-| 细粒度 PAT | `github_pat_` | GitHub 设置 → 开发者设置 → 细粒度 token(需要 **Copilot Requests** 权限) |-| GitHub App token | `ghu_` | 通过 GitHub App 安装获取 |--如果你的 `gh auth token` 返回 `ghp_*` token,请使用 `hermes model` 通过 OAuth 认证。-:::--:::info Hermes 中的 Copilot 认证行为-Hermes 将支持的 GitHub token(`gho_*`、`github_pat_*` 或 `ghu_*`)直接发送到 `api.githubcopilot.com`,并附带 Copilot 专用请求头(`Editor-Version`、`Copilot-Integration-Id`、`Openai-Intent`、`x-initiator`)。--收到 HTTP 401 时,Hermes 在回退前会执行一次性凭据恢复:--1. 通过正常优先级链重新解析 token(`COPILOT_GITHUB_TOKEN` → `GH_TOKEN` → `GITHUB_TOKEN` → `gh auth token`)-2. 使用刷新后的请求头重建共享 OpenAI 客户端-3. 重试请求一次+已在使用 `copilot` 或 `copilot-acp` 的 profile(主模型、回退、辅助任务、委托、MoA 或 cron)会在 `hermes update` 或下一次启动 agent 或网关时自动安装该插件。-部分旧版社区代理使用 `api.github.com/copilot_internal/v2/token` 交换流程。该端点对某些账户类型可能不可用(返回 404)。因此 Hermes 以直接 token 认证为主路径,依靠运行时凭据刷新 + 重试保证健壮性。-:::--**API 路由**:GPT-5+ 模型(`gpt-5-mini` 除外)自动使用 Responses API。其他所有模型(GPT-4o、Claude、Gemini 等)使用 Chat Completions。模型从 Copilot 实时目录自动检测。--**`copilot-acp` — Copilot ACP 智能体后端**。将本地 Copilot CLI 作为子进程启动:--```bash-hermes chat --provider copilot-acp --model copilot-acp-# 需要 PATH 中存在 GitHub Copilot CLI 且已完成 `copilot login`-```--**永久配置:**-```yaml-model:- provider: "copilot"- default: "gpt-5.4"-```+使用 `hermes auth add copilot`(设备码登录)登录,或设置 `COPILOT_GITHUB_TOKEN`、`GH_TOKEN` 或 `GITHUB_TOKEN`。插件不再读取 `gh` CLI 或 Copilot CLI 的登录信息:如果你此前依赖它们,请运行 `hermes auth add copilot`。-| 环境变量 | 说明 |-|---------------------|-------------|-| `COPILOT_GITHUB_TOKEN` | Copilot API 的 GitHub token(最高优先级) |-| `HERMES_COPILOT_ACP_COMMAND` | 覆盖 Copilot CLI 二进制路径(默认:`copilot`) |-| `HERMES_COPILOT_ACP_ARGS` | 覆盖 ACP 参数(默认:`--acp --stdio`) |+安装、模型和环境变量说明:[github-copilot 插件文档](https://github.com/NousResearch/hermes-labs-plugins/tree/main/github-copilot)。### 一等 API Key 提供商@@ -1108,7 +1055,7 @@ Hermes 使用多源解析链来检测模型和提供商的正确上下文窗口8. **[models.dev](https://models.dev)** — 社区维护的注册表,包含 100+ 提供商 3800+ 模型的提供商特定上下文长度9. **回退默认值** — 广泛的模型系列模式(默认 128K)-大多数配置开箱即用。该系统具有提供商感知能力——同一模型在不同服务商处可能有不同的上下文限制(例如 `claude-opus-4.6` 在 Anthropic 直连时为 1M,在 GitHub Copilot 上为 128K)。+大多数配置开箱即用。该系统具有提供商感知能力——同一模型在不同服务商处可能有不同的上下文限制(例如 `claude-opus-4.6` 在 Anthropic 直连时为 1M,经部分转售商和聚合商访问时则更小)。要显式设置上下文长度,在模型配置中添加 `context_length`:@@ -1419,7 +1366,7 @@ fallback_model:激活时,故障转移在不丢失对话的情况下中途切换模型和提供商。链按条目逐一尝试;每个会话激活一次。-支持的提供商:`openrouter`、`nous`、`openai-codex`、`copilot`、`copilot-acp`、`anthropic`、`gemini`、`qwen-oauth`、`huggingface`、`zai`、`kimi-coding`、`kimi-coding-cn`、`minimax`、`minimax-cn`、`minimax-oauth`、`deepseek`、`nvidia`、`xai`、`xai-oauth`、`ollama-cloud`、`bedrock`、`azure-foundry`、`opencode-zen`、`opencode-go`、`kilocode`、`xiaomi`、`arcee`、`gmi`、`stepfun`、`lmstudio`、`alibaba`、`alibaba-coding-plan`、`tencent-tokenhub`、`custom`。+支持的提供商:`openrouter`、`nous`、`openai-codex`、`anthropic`、`gemini`、`qwen-oauth`、`huggingface`、`zai`、`kimi-coding`、`kimi-coding-cn`、`minimax`、`minimax-cn`、`minimax-oauth`、`deepseek`、`nvidia`、`xai`、`xai-oauth`、`ollama-cloud`、`bedrock`、`azure-foundry`、`opencode-zen`、`opencode-go`、`kilocode`、`xiaomi`、`arcee`、`gmi`、`stepfun`、`lmstudio`、`alibaba`、`alibaba-coding-plan`、`tencent-tokenhub`、`custom`。:::tip故障转移仅通过 `config.yaml` 配置——或通过 `hermes fallback` 交互式配置。有关触发时机、链推进方式以及与辅助任务和委托的交互,参见[故障转移提供商](../user-guide/features/fallback-providers.md)。diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/cli-commands.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/cli-commands.mdindex 9dfe6349e78..26f9b3bf929 100644--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/cli-commands.md+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/cli-commands.md@@ -98,7 +98,7 @@ hermes chat [options]| `-q`, `--query "..."` | 单次非交互式 prompt。 || `-m`, `--model <model>` | 覆盖本次运行的模型。 || `-t`, `--toolsets <csv>` | 启用逗号分隔的 toolset 集合。 |-| `--provider <provider>` | 强制指定 provider:`auto`、`openrouter`、`nous`、`openai-codex`、`copilot-acp`、`copilot`、`anthropic`、`gemini`、`huggingface`、`novita`(别名 `novita-ai`、`novitaai`)、`openai-api`、`zai`、`kimi-coding`、`kimi-coding-cn`、`minimax`、`minimax-cn`、`minimax-oauth`、`kilocode`、`xiaomi`、`arcee`、`gmi`、`alibaba`、`alibaba-coding-plan`(别名 `alibaba_coding`)、`deepseek`、`nvidia`、`ollama-cloud`、`xai`(别名 `grok`)、`xai-oauth`(别名 `grok-oauth`)、`qwen-oauth`、`bedrock`、`opencode-zen`、`opencode-go`、`ai-gateway`、`azure-foundry`、`lmstudio`、`stepfun`、`tencent-tokenhub`(别名 `tencent`、`tokenhub`)。 |+| `--provider <provider>` | 强制指定 provider:`auto`、`openrouter`、`nous`、`openai-codex`、`anthropic`、`gemini`、`huggingface`、`novita`(别名 `novita-ai`、`novitaai`)、`openai-api`、`zai`、`kimi-coding`、`kimi-coding-cn`、`minimax`、`minimax-cn`、`minimax-oauth`、`kilocode`、`xiaomi`、`arcee`、`gmi`、`alibaba`、`alibaba-coding-plan`(别名 `alibaba_coding`)、`deepseek`、`nvidia`、`ollama-cloud`、`xai`(别名 `grok`)、`xai-oauth`(别名 `grok-oauth`)、`qwen-oauth`、`bedrock`、`opencode-zen`、`opencode-go`、`ai-gateway`、`azure-foundry`、`lmstudio`、`stepfun`、`tencent-tokenhub`(别名 `tencent`、`tokenhub`)。 || `-s`, `--skills <name>` | 为会话预加载一个或多个 skill(可重复或逗号分隔)。 || `-v`, `--verbose` | 详细输出。 || `-Q`, `--quiet` | 程序化模式:抑制横幅/spinner/工具预览。 |@@ -161,8 +161,8 @@ hermes model```在以下情况使用此命令:-- **添加新 provider**(OpenRouter、Anthropic、Copilot、DeepSeek、自定义等)-- 登录基于 OAuth 的 provider(Anthropic、Copilot、Codex、Nous Portal)+- **添加新 provider**(OpenRouter、Anthropic、DeepSeek、自定义等)+- 登录基于 OAuth 的 provider(Anthropic、Codex、Nous Portal)- 输入或更新 API 密钥- 从 provider 特定的模型列表中选择- 配置自定义/自托管端点@@ -197,7 +197,7 @@ hermes model```:::info 如果我只看到 OpenRouter 模型怎么办?-如果你只配置了 OpenRouter,`/model` 将只显示 OpenRouter 模型。要添加其他 provider(Anthropic、DeepSeek、Copilot 等),请退出会话并从终端运行 `hermes model`。+如果你只配置了 OpenRouter,`/model` 将只显示 OpenRouter 模型。要添加其他 provider(Anthropic、DeepSeek 等),请退出会话并从终端运行 `hermes model`。:::Provider 和 base URL 的更改会自动持久化到 `config.yaml`。从自定义端点切换走时,过时的 base URL 会被清除,以防止其泄漏到其他 provider。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.mdindex bcb41d0c117..429b38f1e98 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@@ -22,13 +22,8 @@ description: "Hermes Agent 使用的所有环境变量完整参考"| `AI_GATEWAY_BASE_URL` | 覆盖 AI Gateway base URL(默认:`https://ai-gateway.vercel.sh/v1`) || `OPENAI_API_KEY` | 自定义 OpenAI 兼容端点的 API 密钥(与 `OPENAI_BASE_URL` 配合使用)。设置 `OPENAI_BASE_URL` 后,它只会发送到该 URL 完全相同的源(scheme、主机和端口),绝不会发送到同一主机的其他端口或 `http://` || `OPENAI_BASE_URL` | 自定义端点的 base URL(VLLM、SGLang 等) |-| `COPILOT_GITHUB_TOKEN` | 用于 Copilot API 的 GitHub token——最高优先级(OAuth `gho_*` 或细粒度 PAT `github_pat_*`;经典 PAT `ghp_*` **不支持**) |-| `GH_TOKEN` | GitHub token——Copilot 第二优先级(也供 `gh` CLI 使用) |-| `GITHUB_TOKEN` | GitHub token——Copilot 第三优先级 |-| `HERMES_COPILOT_ACP_COMMAND` | 覆盖 Copilot ACP CLI 二进制路径(默认:`copilot`) |-| `COPILOT_CLI_PATH` | `HERMES_COPILOT_ACP_COMMAND` 的别名 |-| `HERMES_COPILOT_ACP_ARGS` | 覆盖 Copilot ACP 参数(默认:`--acp --stdio`) |-| `COPILOT_ACP_BASE_URL` | 覆盖 Copilot ACP base URL |+| `GH_TOKEN` | GitHub token(也供 `gh` CLI 使用);凡 Hermes 读取 `GITHUB_TOKEN` 之处均可作为其替代 |+| `GITHUB_TOKEN` | 用于访问 GitHub API 的 GitHub token(Skills Hub、git 凭据、更新检查;另见下方 Skills Hub 一行) || `GLM_API_KEY` | z.ai / ZhipuAI GLM API 密钥([z.ai](https://z.ai)) || `ZAI_API_KEY` | `GLM_API_KEY` 的别名 || `Z_AI_API_KEY` | `GLM_API_KEY` 的别名 |diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/configuration.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/configuration.mdindex 961e5f3a755..d5ef7ff936f 100644--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/configuration.md+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/configuration.md@@ -74,7 +74,7 @@ delegation:单个值中可以有多个引用:`url: "${HOST}:${PORT}"`。如果引用的变量未设置,占位符将保持原样(`${UNDEFINED_VAR}` 保持不变)。仅支持 `${VAR}` 语法 —— 裸 `$VAR` 不会被展开。-关于 AI provider 设置(OpenRouter、Anthropic、Copilot、自定义端点、自托管 LLM、回退模型等),请参阅 [AI Providers](../integrations/providers.md)。+关于 AI provider 设置(OpenRouter、Anthropic、自定义端点、自托管 LLM、回退模型等),请参阅 [AI Providers](../integrations/providers.md)。### Provider 超时@@ -841,7 +841,7 @@ Hermes 中的每个模型槽位 —— 辅助任务、压缩、回退 —— 使当设置 `base_url` 时,Hermes 忽略 provider 并直接调用该端点(使用 `api_key` 或 `OPENAI_API_KEY` 进行认证)。当仅设置 `provider` 时,Hermes 使用该 provider 的内置认证和基础 URL。-辅助任务的可用 providers:`auto`、`main`,以及[provider 注册表](../reference/environment-variables.md)中的任何 provider —— `openrouter`、`nous`、`openai-codex`、`copilot`、`copilot-acp`、`anthropic`、`gemini`、`qwen-oauth`、`zai`、`kimi-coding`、`kimi-coding-cn`、`minimax`、`minimax-cn`、`minimax-oauth`、`deepseek`、`nvidia`、`xai`、`xai-oauth`、`ollama-cloud`、`alibaba`、`bedrock`、`huggingface`、`arcee`、`xiaomi`、`kilocode`、`opencode-zen`、`opencode-go`、`ai-gateway`、`azure-foundry` —— 或您 `custom_providers` 列表中任何命名的自定义 provider(例如 `provider: "beans"`)。+辅助任务的可用 providers:`auto`、`main`,以及[provider 注册表](../reference/environment-variables.md)中的任何 provider —— `openrouter`、`nous`、`openai-codex`、`anthropic`、`gemini`、`qwen-oauth`、`zai`、`kimi-coding`、`kimi-coding-cn`、`minimax`、`minimax-cn`、`minimax-oauth`、`deepseek`、`nvidia`、`xai`、`xai-oauth`、`ollama-cloud`、`alibaba`、`bedrock`、`huggingface`、`arcee`、`xiaomi`、`kilocode`、`opencode-zen`、`opencode-go`、`ai-gateway`、`azure-foundry` —— 或您 `custom_providers` 列表中任何命名的自定义 provider(例如 `provider: "beans"`)。:::tip MiniMax OAuth`minimax-oauth` 通过浏览器 OAuth 登录(无需 API 密钥)。运行 `hermes model` 并选择 **MiniMax (OAuth)** 进行认证。辅助任务自动使用 `MiniMax-M2.7-highspeed`。参阅 [MiniMax OAuth 指南](../guides/minimax-oauth.md)。@@ -1703,7 +1703,7 @@ delegation:**线路协议(`api_mode`):** Hermes 从 `delegation.base_url` 自动检测线路协议(例如以 `/anthropic` 结尾的路径 → `anthropic_messages`;Codex/原生 Anthropic/Kimi-coding 主机名保留其现有检测)。对于启发式无法分类的端点 —— 例如 Azure AI Foundry、MiniMax、Zhipu GLM 或前置 Anthropic 形状后端的 LiteLLM 代理 —— 请将 `delegation.api_mode` 显式设置为 `chat_completions`、`codex_responses` 或 `anthropic_messages` 之一。留空(默认)以保持自动检测。-委托 provider 使用与 CLI/gateway 启动相同的凭据解析。所有配置的 provider 均受支持:`openrouter`、`nous`、`copilot`、`zai`、`kimi-coding`、`minimax`、`minimax-cn`。设置 provider 时,系统自动解析正确的基础 URL、API 密钥和 API 模式 —— 无需手动凭据连接。+委托 provider 使用与 CLI/gateway 启动相同的凭据解析。所有配置的 provider 均受支持:`openrouter`、`nous`、`zai`、`kimi-coding`、`minimax`、`minimax-cn`。设置 provider 时,系统自动解析正确的基础 URL、API 密钥和 API 模式 —— 无需手动凭据连接。**优先级:** 配置中的 `delegation.base_url` → 配置中的 `delegation.provider` → 父 provider(继承)。配置中的 `delegation.model` → 父模型(继承)。仅设置 `model` 而不设置 `provider` 仅更改模型名称,同时保留父级凭据(适用于在同一 provider(如 OpenRouter)内切换模型)。diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/fallback-providers.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/fallback-providers.mdindex e679e33db7a..e886205661b 100644--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/fallback-providers.md+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/fallback-providers.md@@ -51,8 +51,6 @@ fallback_model:| OpenRouter | `openrouter` | `OPENROUTER_API_KEY` || Nous Portal | `nous` | `hermes setup --portal`(全新安装)或 `hermes auth add nous`(OAuth) || OpenAI Codex | `openai-codex` | `hermes model` → **ChatGPT or Codex Subscription**(ChatGPT OAuth) |-| GitHub Copilot | `copilot` | `COPILOT_GITHUB_TOKEN`、`GH_TOKEN` 或 `GITHUB_TOKEN` |-| GitHub Copilot ACP | `copilot-acp` | 外部进程(编辑器集成) || Anthropic | `anthropic` | `ANTHROPIC_API_KEY` 或 Claude Code 凭据 || z.ai / GLM | `zai` | `GLM_API_KEY` || Kimi / Moonshot | `kimi-coding` | `KIMI_API_KEY` |diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/subscription-proxy.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/subscription-proxy.mdindex 9ff0f0ebf1f..216b66767b2 100644--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/subscription-proxy.md+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/subscription-proxy.md@@ -160,4 +160,4 @@ hermes proxy start --host 0.0.0.0 --port 8645## 未来:更多 OAuth 提供商-适配器系统是可插拔的。添加新提供商(例如 HuggingFace、GitHub Copilot 的聊天端点、通过 OAuth 接入的 Anthropic)需要在 `hermes_cli/proxy/adapters/<provider>.py` 中实现 `UpstreamAdapter`,并在 `adapters/__init__.py` 中注册。协议层面不兼容 OpenAI 的提供商(例如 Anthropic Messages API)需要额外的转换层,这超出了当前版本的范围。\ No newline at end of file+适配器系统是可插拔的。添加新提供商(例如 HuggingFace、通过 OAuth 接入的 Anthropic)需要在 `hermes_cli/proxy/adapters/<provider>.py` 中实现 `UpstreamAdapter`,并在 `adapters/__init__.py` 中注册。协议层面不兼容 OpenAI 的提供商(例如 Anthropic Messages API)需要额外的转换层,这超出了当前版本的范围。\ No newline at end of file