hermes教程-AI 提供商

本页介绍如何为 Hermes Agent 设置推理提供商——从云 API（如 OpenRouter 和 Anthropic）到自托管端点（如 Ollama 和 vLLM），再到高级路由和回退配置。你需要至少配置一个提供商才能使用 Hermes。

推理提供商

你需要至少一种方式连接到 LLM。使用 hermes model 以交互方式切换提供商和模型，或直接配置：

对于官方 API 密钥路径，请参见专门的 Google Gemini 指南。

提示 — 模型键别名

在 model: 配置部分，你可以使用 default: 或 model: 作为模型 ID 的键名。model: { default: my-model } 和 model: { model: my-model } 效果相同。

Nous Portal

Nous Portal 是 Nous Research 的统一订阅网关，也是运行 Hermes Agent 的推荐方式。一次 OAuth 登录即可覆盖 300 多个前沿智能体模型（Claude、GPT、Gemini、DeepSeek、Qwen、Kimi、GLM、MiniMax、Grok……）以及工具网关（网页搜索、图像生成、TTS、浏览器自动化）和 Nous Chat——费用计入你的 Nous 订阅，而不是单独的按提供商账户计费。

hermes setup --portal     # 全新安装 — 一条命令完成 OAuth + 提供商 + 网关
hermes model              # 已有安装 — 从列表中选择 "Nous Portal"
hermes portal info        # 随时查看登录和路由信息

还没有订阅？在 portal.nousresearch.com/manage-subscription 获取一个。

完整详情： 请参见专门的 Nous Portal 集成页面（订阅内容、模型目录、故障排除）以及逐步指南 使用 Nous Portal 运行 Hermes Agent。

客户端标识。 Hermes Agent 发出的每个 Portal 请求都带有 client=hermes-client-v<version> 标签（例如 client=hermes-client-v0.13.0），自动与已安装的版本对齐。该标签在所有 Portal 路径上发送——主聊天循环、辅助调用、压缩摘要器、网页提取——让 Portal 端遥测能够区分 Hermes 流量与其他客户端。无需配置；当你运行 hermes update 时，标签会自动更新。

JWT 认证（自动）。 Hermes 优先使用作用域为 inference:invoke 的 JWT 进行 Portal 请求，并将传统的 opaque session-key 路径作为回退。无需配置——凭证由 OAuth 流程管理并透明轮换。被撤销的刷新令牌会被隔离，以避免重放循环。

信息 — Codex 说明

OpenAI Codex 提供商通过设备码进行认证（打开 URL，输入代码）。Hermes 将生成的凭证存储在自己的认证存储中，位于 ~/.hermes/auth.json，并且可以导入现有的 Codex CLI 凭证（如果存在 ~/.codex/auth.json）。无需安装 Codex CLI。

如果令牌刷新失败并出现终端错误（HTTP 4xx、invalid_grant、被撤销的授权等），Hermes 会将刷新令牌标记为失效并停止重放，这样你就不会看到大量相同的认证失败。下一次请求会显示一条类型化的重新认证消息。运行 hermes auth add codex-oauth（或 hermes model → OpenAI Codex）以启动新的设备码登录；隔离会在下一次成功交换时清除。

警告

即使使用 Nous Portal、Codex 或自定义端点，某些工具（视觉、网页摘要、MoA）也会使用单独的“辅助”模型。默认情况下（auxiliary.*.provider: "auto"），Hermes 将这些任务路由到你的主聊天模型——即你在 hermes model 中选择的同一个模型。你可以单独覆盖每个任务，将其路由到更便宜/更快的模型（例如 OpenRouter 上的 Gemini Flash）——参见辅助模型。

提示 — Nous 工具网关

付费的 Nous Portal 订阅者还可以访问 工具网关——网页搜索、图像生成、TTS 和浏览器自动化，通过你的订阅路由。无需额外的 API 密钥。全新安装时，hermes setup --portal 会登录、将 Nous 设置为提供商并启用网关，一条命令完成。现有用户可以从 hermes model 或通过 hermes tools 按工具启用。随时使用 hermes portal info 检查路由。

两个模型管理命令

Hermes 有两个模型命令，用途不同：

如果你试图切换到一个尚未设置的提供商（例如你只配置了 OpenRouter，想使用 Anthropic），你需要 hermes model，而不是 /model。先退出会话（Ctrl+C 或 /quit），运行 hermes model，完成提供商设置，然后开始新会话。

Anthropic（原生）

直接通过 Anthropic API 使用 Claude 模型——无需 OpenRouter 代理。支持三种认证方式：

注意 — 需要 Claude Max "额外使用" 额度

当你通过 hermes model → Anthropic OAuth（或通过 hermes auth add anthropic --type oauth）进行认证时，Hermes 会以 Claude Code 的身份路由到你的 Anthropic 账户。它仅在你有 Claude Max 计划并购买了额外使用额度时才有效。 基础 Max 计划配额（Claude Code 默认包含的使用量）不会被 Hermes 消耗——只有你额外添加的额度才会被消耗。Claude Pro 订阅者无法使用此路径。

如果你没有 Max + 额外额度，请改用 ANTHROPIC_API_KEY——请求将按该密钥所属组织的标准 API 定价按 token 计费（与任何 Claude 订阅无关）。

## 使用 API 密钥（按 token 计费）
export ANTHROPIC_API_KEY=***
hermes chat --provider anthropic --model claude-sonnet-4-6
## 推荐：通过 `hermes model` 进行认证
## Hermes 会在可用时直接使用 Claude Code 的凭证存储
hermes model
## 使用设置令牌手动覆盖（回退/旧版）
export ANTHROPIC_TOKEN=***  # 设置令牌或手动 OAuth 令牌
hermes chat --provider anthropic
## 自动检测 Claude Code 凭证（如果你已在使用 Claude Code）
hermes chat --provider anthropic  # 自动读取 Claude Code 凭证文件

当你通过 hermes model 选择 Anthropic OAuth 时，Hermes 优先使用 Claude Code 自己的凭证存储，而不是将令牌复制到 ~/.hermes/.env。这样可以保持可刷新的 Claude 凭证可刷新。

或者永久设置：

model:
  provider: "anthropic"
  default: "claude-sonnet-4-6"

提示 — 别名

--provider claude 和 --provider claude-code 也可作为 --provider anthropic 的简写。

GitHub Copilot

Hermes 支持 GitHub Copilot 作为一级提供商，有两种模式：

copilot — 直接 Copilot API（推荐）。使用你的 GitHub Copilot 订阅通过 Copilot API 访问 GPT-5.x、Claude、Gemini 等模型。

hermes chat --provider copilot --model gpt-5.4

认证选项（按此顺序检查）：

1. COPILOT_GITHUB_TOKEN 环境变量
2. GH_TOKEN 环境变量
3. GITHUB_TOKEN 环境变量
4. gh auth token CLI 回退

如果未找到令牌，hermes model 会提供 OAuth 设备码登录——与 Copilot CLI 和 opencode 使用的流程相同。

警告 — 令牌类型

Copilot API 不支持传统的个人访问令牌（ghp_*）。支持的令牌类型：

类型	前缀	如何获取
OAuth 令牌	gho_	hermes model → GitHub Copilot → 使用 GitHub 登录
细粒度 PAT	github_pat_	GitHub 设置 → 开发者设置 → 细粒度令牌（需要 Copilot 请求 权限）
GitHub App 令牌	ghu_	通过 GitHub App 安装

如果你的 gh auth token 返回的是 ghp_* 令牌，请改用 hermes model 通过 OAuth 进行认证。

信息 — Hermes 中的 Copilot 认证行为

Hermes 将支持的 GitHub 令牌（gho_*、github_pat_* 或 ghu_*）直接发送到 api.githubcopilot.com，并包含 Copilot 特定的头部（Editor-Version、Copilot-Integration-Id、Openai-Intent、x-initiator）。

在 HTTP 401 时，Hermes 现在会在回退前执行一次一次性凭证恢复：

1. 通过正常优先级链重新解析令牌（COPILOT_GITHUB_TOKEN → GH_TOKEN → GITHUB_TOKEN → gh auth token）
2. 使用刷新后的头部重建共享的 OpenAI 客户端
3. 重试请求一次

一些旧的社区代理使用 api.github.com/copilot_internal/v2/token 交换流程。该端点可能对某些账户类型不可用（返回 404）。因此 Hermes 将直接令牌认证作为主要路径，并依赖运行时凭证刷新 + 重试来保证健壮性。

API 路由：GPT-5+ 模型（gpt-5-mini 除外）自动使用 Responses API。所有其他模型（GPT-4o、Claude、Gemini 等）使用 Chat Completions。模型从实时 Copilot 目录中自动检测。

copilot-acp — Copilot ACP 智能体后端。将本地 Copilot CLI 作为子进程启动：

hermes chat --provider copilot-acp --model copilot-acp
## 需要 GitHub Copilot CLI 在 PATH 中，并且存在 `copilot login` 会话

永久配置：

model:
  provider: "copilot"
  default: "gpt-5.4"

一级 API 密钥提供商

这些提供商具有内置支持，带有专用的提供商 ID。设置 API 密钥并使用 --provider 选择：

## NovitaAI Model API
hermes chat --provider novita --model moonshotai/kimi-k2.5
## 需要：NOVITA_API_KEY 在 ~/.hermes/.env 中
## z.ai / ZhipuAI GLM
hermes chat --provider zai --model glm-5
## 需要：GLM_API_KEY 在 ~/.hermes/.env 中
## Kimi / Moonshot AI（国际：api.moonshot.ai）
hermes chat --provider kimi-coding --model kimi-for-coding
## 需要：KIMI_API_KEY 在 ~/.hermes/.env 中
## Kimi / Moonshot AI（中国：api.moonshot.cn）
hermes chat --provider kimi-coding-cn --model kimi-k2.5
## 需要：KIMI_CN_API_KEY 在 ~/.hermes/.env 中
## MiniMax（全球端点）
hermes chat --provider minimax --model MiniMax-M2.7
## 需要：MINIMAX_API_KEY 在 ~/.hermes/.env 中
## MiniMax（中国端点）
hermes chat --provider minimax-cn --model MiniMax-M2.7
## 需要：MINIMAX_CN_API_KEY 在 ~/.hermes/.env 中
## Qwen Cloud / DashScope（Qwen 模型）
hermes chat --provider alibaba --model qwen3.5-plus
## 需要：DASHSCOPE_API_KEY 在 ~/.hermes/.env 中
## 小米 MiMo
hermes chat --provider xiaomi --model mimo-v2-pro
## 需要：XIAOMI_API_KEY 在 ~/.hermes/.env 中
## 腾讯 TokenHub（Hy3 Preview）
hermes chat --provider tencent-tokenhub --model hy3-preview
## 需要：TOKENHUB_API_KEY 在 ~/.hermes/.env 中
## Arcee AI（Trinity 模型）
hermes chat --provider arcee --model trinity-large-thinking
## 需要：ARCEEAI_API_KEY 在 ~/.hermes/.env 中
## GMI Cloud
## 使用 GMI 的 /v1/models 端点返回的精确模型 ID。
hermes chat --provider gmi --model zai-org/GLM-5.1-FP8
## 需要：GMI_API_KEY 在 ~/.hermes/.env 中

或者在 config.yaml 中永久设置提供商：

model:
  provider: "gmi"
  default: "zai-org/GLM-5.1-FP8"

可以使用 NOVITA_BASE_URL、GLM_BASE_URL、KIMI_BASE_URL、MINIMAX_BASE_URL、MINIMAX_CN_BASE_URL、DASHSCOPE_BASE_URL、XIAOMI_BASE_URL、GMI_BASE_URL 或 TOKENHUB_BASE_URL 环境变量覆盖基础 URL。

注意 — Z.AI 端点自动检测

使用 Z.AI / GLM 提供商时，Hermes 会自动探测多个端点（全球、中国、编码变体），以找到接受你 API 密钥的端点。你无需手动设置 GLM_BASE_URL——工作端点会被自动检测并缓存。

xAI (Grok) — Responses API + 提示缓存

xAI 通过 Responses API（codex_responses 传输）连接，以在 Grok 4 模型上自动支持推理——无需 reasoning_effort 参数，服务器默认进行推理。在 ~/.hermes/.env 中设置 XAI_API_KEY，并在 hermes model 中选择 xAI，或者将 grok 作为快捷方式放入 /model grok-4-fast-reasoning。

SuperGrok 和 X Premium+ 订阅者可以使用浏览器 OAuth 登录，而不是使用 API 密钥——在 hermes model 中选择 xAI Grok OAuth (SuperGrok / Premium+)，或运行 hermes auth add xai-oauth。相同的 OAuth 承载令牌会自动被直接到 xAI 的工具（TTS、图像生成、视频生成、转录）重用。有关完整流程，请参见 xAI Grok OAuth 指南——如果 Hermes 在远程主机上运行，另请参见 通过 SSH / 远程主机的 OAuth 了解所需的 ssh -L 隧道。

当使用 xAI 作为提供商（任何包含 x.ai 的基础 URL）时，Hermes 会自动启用提示缓存，通过在每个 API 请求中发送 x-grok-conv-id 头部。这会将请求路由到同一会话中的同一服务器，允许 xAI 的基础设施重用缓存的系统提示和对话历史。

无需配置——当检测到 xAI 端点并且会话 ID 可用时，缓存会自动激活。这减少了多轮对话的延迟和成本。

xAI 还提供了一个专用的 TTS 端点（/v1/tts）。在 hermes tools → Voice & TTS 中选择 xAI TTS，或参见 Voice & TTS 页面进行配置。

已退役的 xAI 模型迁移（2026 年 5 月 15 日）： xAI 将于 2026 年 5 月 15 日退役 grok-4*、grok-3、grok-code-fast-1 和 grok-imagine-image-pro。hermes doctor 和 hermes chat 启动时都会检测任何仍指向已退役引用的配置，并打印推荐的替换。使用 hermes migrate xai 进行一次性配置重写——默认是 dry-run，添加 --apply 以写入更改（会自动创建带时间戳的 config.yaml.bak-pre-migrate-xai-* 备份）。

hermes migrate xai          # 预览替换
hermes migrate xai --apply  # 原地重写 ~/.hermes/config.yaml

xAI 网页搜索后端。 当启用网页搜索工具集时，web.backend: xai 通过 xAI 托管的搜索端点路由搜索，使用相同的 XAI_API_KEY / OAuth 凭证。如果 xAI 已配置为提供商，则无需额外设置。

NovitaAI

NovitaAI 是面向构建者和智能体的 AI 原生云。其三条产品线是：Model API（200+ 模型）、Agent Sandbox（构建和运行 AI 智能体）和 GPU Cloud（可扩展计算），全部来自一个平台。

## 使用任何可用模型
hermes chat --provider novita --model moonshotai/kimi-k2.5
## 需要：NOVITA_API_KEY 在 ~/.hermes/.env 中
## 短别名
hermes chat --provider novita-ai --model deepseek/deepseek-v3-0324

或者在 config.yaml 中永久设置：

model:
  provider: "novita"
  default: "moonshotai/kimi-k2.5"
  base_url: "https://api.novita.ai/openai/v1"

在 novita.ai/settings/key-management 获取你的 API 密钥。可以使用 NOVITA_BASE_URL 覆盖基础 URL。

Ollama Cloud — 托管 Ollama 模型，OAuth + API 密钥

Ollama Cloud 托管与本地 Ollama 相同的开放权重目录，但无需 GPU。在 hermes model 中选择 Ollama Cloud，粘贴来自 ollama.com/settings/keys 的 API 密钥，Hermes 会自动发现可用模型。

hermes model
## → 选择 "Ollama Cloud"
## → 粘贴你的 OLLAMA_API_KEY
## → 从发现的模型中选择（gpt-oss:120b, glm-4.6:cloud, qwen3-coder:480b-cloud 等）

或者直接使用 config.yaml：

model:
  provider: "ollama-cloud"
  default: "gpt-oss:120b"

模型目录从 ollama.com/v1/models 动态获取并缓存一小时。model:tag 表示法（例如 qwen3-coder:480b-cloud）通过规范化保留——不要使用破折号。

提示 — Ollama Cloud 与本地 Ollama

两者都使用相同的 OpenAI 兼容 API。Cloud 是一级提供商（--provider ollama-cloud，OLLAMA_API_KEY）；本地 Ollama 通过自定义端点流程访问（基础 URL http://localhost:11434/v1，无需密钥）。对于无法在本地运行的大型模型，使用 Cloud；对于隐私或离线工作，使用本地。

AWS Bedrock

通过 AWS Bedrock 使用 Anthropic Claude、Amazon Nova、DeepSeek v3.2、Meta Llama 4 等模型。使用 AWS SDK（boto3）凭证链——无需 API 密钥，只需标准 AWS 认证。

## 最简单——在 ~/.aws/credentials 中使用命名配置文件
hermes chat --provider bedrock --model us.anthropic.claude-sonnet-4-6
## 或使用显式环境变量
AWS_PROFILE=myprofile AWS_REGION=us-east-1 hermes chat --provider bedrock --model us.anthropic.claude-sonnet-4-6

或者在 config.yaml 中永久设置：

model:
  provider: "bedrock"
  default: "us.anthropic.claude-sonnet-4-6"
bedrock:
  region: "us-east-1"          # 或设置 AWS_REGION
## profile: "myprofile"       # 或设置 AWS_PROFILE
## discovery: true            # 从 IAM 自动发现区域
## guardrail:                 # 可选的 Bedrock Guardrails
## guardrail_identifier: "your-guardrail-id"
## guardrail_version: "DRAFT"

认证使用标准的 boto3 链：显式的 AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY、来自 ~/.aws/credentials 的 AWS_PROFILE、EC2/ECS/Lambda 上的 IAM 角色、IMDS 或 SSO。如果你已经通过 AWS CLI 进行了认证，则无需环境变量。

Bedrock 在底层使用 Converse API——请求被转换为 Bedrock 的模型无关形状，因此相同的配置适用于 Claude、Nova、DeepSeek 和 Llama 模型。仅当你调用非默认的区域端点时，才设置 BEDROCK_BASE_URL。

有关 IAM 设置、区域选择和跨区域推理的详细指南，请参见 AWS Bedrock 指南。

Qwen Portal (OAuth)

阿里云的 Qwen Portal，支持基于浏览器的 OAuth 登录。在 hermes model 中选择 Qwen OAuth (Portal)，通过浏览器登录，Hermes 会持久化刷新令牌。

hermes model
## → 选择 "Qwen OAuth (Portal)"
## → 浏览器打开；使用你的阿里云账户登录
## → 确认——凭证保存到 ~/.hermes/auth.json

hermes chat   # 使用 portal.qwen.ai/v1 端点

或者配置 config.yaml：

model:
  provider: "qwen-oauth"
  default: "qwen3-coder-plus"

仅当门户端点迁移时，才设置 HERMES_QWEN_BASE_URL（默认：https://portal.qwen.ai/v1）。

提示 — Qwen OAuth 与 Qwen Cloud（阿里云 DashScope）

qwen-oauth 使用面向消费者的 Qwen Portal 和 OAuth 登录——适合个人用户。alibaba 提供商使用 Qwen Cloud（阿里云 DashScope）和 DASHSCOPE_API_KEY——适合程序化/生产工作负载。两者都路由到 Qwen 系列模型，但位于不同的端点。

阿里云（编程计划）

如果你订阅了阿里云的编程计划（与标准 DashScope API 访问分开的定价 SKU），Hermes 将其作为自己的一级提供商公开：alibaba-coding-plan。端点：https://coding-intl.dashscope.aliyuncs.com/v1。它与常规的 alibaba 提供商一样兼容 OpenAI，但具有不同的基础 URL 和计费表面。

model:
  provider: alibaba_coding     # alibaba-coding-plan 的别名
  model: qwen3-coder-plus

或者从 CLI：

hermes chat --provider alibaba_coding --model qwen3-coder-plus

alibaba_coding 使用你的 alibaba 条目已经使用的相同 DASHSCOPE_API_KEY——无需单独的密钥，只需不同的路由目标。在此提供商注册之前，在 config.yaml 中设置 provider: alibaba_coding 的用户会静默地回退到 OpenRouter 路由。

MiniMax (OAuth)

通过浏览器 OAuth 登录使用 MiniMax-M2.7——无需 API 密钥。在 hermes model 中选择 MiniMax (OAuth)，通过浏览器登录，Hermes 会持久化访问和刷新令牌。在底层使用 Anthropic Messages 兼容端点（/anthropic）。

hermes model
## → 选择 "MiniMax (OAuth)"
## → 浏览器打开；使用你的 MiniMax 账户登录（全球或中国区域）
## → 确认——凭证保存到 ~/.hermes/auth.json

hermes chat   # 使用 api.minimax.io/anthropic 端点

或者配置 config.yaml：

model:
  provider: "minimax-oauth"
  default: "MiniMax-M2.7"

支持的模型：MiniMax-M2.7（主要）和 MiniMax-M2.7-highspeed（作为默认辅助模型连接）。OAuth 路径忽略 MINIMAX_API_KEY / MINIMAX_BASE_URL。

提示 — MiniMax OAuth 与 API 密钥

minimax-oauth 使用 MiniMax 面向消费者的门户和 OAuth 登录——无需计费设置。minimax 和 minimax-cn 提供商使用 MINIMAX_API_KEY / MINIMAX_CN_API_KEY——用于程序化访问。有关完整指南，请参见 MiniMax OAuth 指南。

NVIDIA NIM

通过 build.nvidia.com（免费 API 密钥）或本地 NIM 端点使用 Nemotron 和其他开源模型。

## 云端（build.nvidia.com）
hermes chat --provider nvidia --model nvidia/nemotron-3-super-120b-a12b
## 需要：NVIDIA_API_KEY 在 ~/.hermes/.env 中
## 本地 NIM 端点——覆盖基础 URL
NVIDIA_BASE_URL=http://localhost:8000/v1 hermes chat --provider nvidia --model nvidia/nemotron-3-super-120b-a12b

或者在 config.yaml 中永久设置：

model:
  provider: "nvidia"
  default: "nvidia/nemotron-3-super-120b-a12b"

提示 — 本地 NIM

对于本地部署（DGX Spark、本地 GPU），设置 NVIDIA_BASE_URL=http://localhost:8000/v1。NIM 暴露与 build.nvidia.com 相同的 OpenAI 兼容聊天补全 API，因此在云端和本地之间切换只需一行环境变量更改。

Hermes 自动在每个请求上向 build.nvidia.com 附加 NIM 计费来源头部——无需配置。这会将消耗路由到 NVIDIA 计费仪表板中的正确来源。

GMI Cloud

通过 GMI Cloud 使用开放和推理模型——OpenAI 兼容 API，API 密钥认证。

## GMI Cloud
hermes chat --provider gmi --model deepseek-ai/DeepSeek-V3.2
## 需要：GMI_API_KEY 在 ~/.hermes/.env 中

或者在 config.yaml 中永久设置：

model:
  provider: "gmi"
  default: "deepseek-ai/DeepSeek-V3.2"

可以使用 GMI_BASE_URL 覆盖基础 URL（默认：https://api.gmi-serving.com/v1）。

StepFun

通过 StepFun 使用 Step 系列模型——OpenAI 兼容 API，API 密钥认证。

## StepFun
hermes chat --provider stepfun --model step-3.5-flash
## 需要：STEPFUN_API_KEY 在 ~/.hermes/.env 中

或者在 config.yaml 中永久设置：

model:
  provider: "stepfun"
  default: "step-3.5-flash"

可以使用 STEPFUN_BASE_URL 覆盖基础 URL（默认：https://api.stepfun.com/v1）。

Hugging Face 推理提供商

Hugging Face 推理提供商 通过统一的 OpenAI 兼容端点（router.huggingface.co/v1）路由到 20 多个开放模型。请求会自动路由到最快的可用后端（Groq、Together、SambaNova 等），并自动故障转移。

## 使用任何可用模型
hermes chat --provider huggingface --model Qwen/Qwen3.5-397B-A17B
## 需要：HF_TOKEN 在 ~/.hermes/.env 中
## 短别名
hermes chat --provider hf --model deepseek-ai/DeepSeek-V3.2

或者在 config.yaml 中永久设置：

model:
  provider: "huggingface"
  default: "Qwen/Qwen3.5-397B-A17B"

在 huggingface.co/settings/tokens 获取你的令牌——确保启用“Make calls to Inference Providers”权限。包含免费层（每月 $0.10 额度，提供商费率无加价）。

你可以向模型名称附加路由后缀：:fastest（默认）、:cheapest 或 :provider_name 以强制使用特定后端。

可以使用 HF_BASE_URL 覆盖基础 URL。

通过 OAuth 的 Google Gemini（google-gemini-cli）

google-gemini-cli 提供商使用 Google 的 Cloud Code Assist 后端——与 Google 自己的 gemini-cli 工具使用的 API 相同。这支持免费层（个人账户的慷慨每日配额）和付费层（通过 GCP 项目的 Standard/Enterprise）。

快速开始：

hermes model
## → 选择 "Google Gemini (OAuth)"
## → 查看策略警告，确认
## → 浏览器打开到 accounts.google.com，登录
## → 完成——Hermes 在第一次请求时自动配置你的免费层

Hermes 默认附带 Google 的公共 gemini-cli 桌面 OAuth 客户端——与 Google 在其开源 gemini-cli 中包含的相同凭证。桌面 OAuth 客户端不是机密的（PKCE 提供安全性）。你无需安装 gemini-cli 或注册自己的 GCP OAuth 客户端。

认证工作原理：

• 针对 accounts.google.com 的 PKCE 授权码流程
• 浏览器回调在 http://127.0.0.1:8085/oauth2callback（如果端口忙，则使用临时端口回退）
• 令牌存储在 ~/.hermes/auth/google_oauth.json（chmod 0600，原子写入，跨进程 fcntl 锁）
• 在过期前 60 秒自动刷新
• 无头环境（SSH、HERMES_HEADLESS=1）→ 粘贴模式回退
• 飞行中刷新去重——两个并发请求不会双重刷新
• invalid_grant（被撤销的刷新）→ 凭证文件被清除，提示用户重新登录

推理工作原理：

• 流量发送到 https://cloudcode-pa.googleapis.com/v1internal:generateContent（或 :streamGenerateContent?alt=sse 用于流式），而不是付费的 v1beta/openai 端点
• 请求体包装为 {project, model, user_prompt_id, request}
• OpenAI 形状的 messages[]、tools[]、tool_choice 被转换为 Gemini 原生的 contents[]、tools[].functionDeclarations、toolConfig 形状
• 响应被转换回 OpenAI 形状，因此 Hermes 的其余部分保持不变

层级和项目 ID：

免费层在首次使用时自动配置一个 Google 管理的项目。无需 GCP 设置。

配额监控：

显示每个模型的剩余 Code Assist 配额，带有进度条：

Gemini Code Assist 配额  (项目: 123-abc)

  gemini-2.5-pro                      ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░   85%
  gemini-2.5-flash [输入]            ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░   92%

警告 — 策略风险

Google 认为将 Gemini CLI OAuth 客户端与第三方软件一起使用是违反策略的。一些用户报告了账户限制。为了获得最低风险体验，请改用你自己的 API 密钥通过 gemini 提供商。Hermes 会显示预先警告，并要求在 OAuth 开始前明确确认。

自定义 OAuth 客户端（可选）：

如果你更愿意注册自己的 Google OAuth 客户端——例如，将配额和同意范围限定在你自己的 GCP 项目中——设置：

HERMES_GEMINI_CLIENT_ID=your-client.apps.googleusercontent.com
HERMES_GEMINI_CLIENT_SECRET=...   # 对于桌面客户端可选

在 console.cloud.google.com/apis/credentials 注册一个桌面应用 OAuth 客户端，并启用 Generative Language API。

自定义和自托管 LLM 提供商

Hermes Agent 适用于任何 OpenAI 兼容的 API 端点。如果服务器实现了 /v1/chat/completions，你可以将 Hermes 指向它。这意味着你可以使用本地模型、GPU 推理服务器、多提供商路由器或任何第三方 API。

通用设置

配置自定义端点的三种方式：

交互式设置（推荐）：

hermes model
## 选择 "Custom endpoint (self-hosted / VLLM / etc.)"
## 输入：API 基础 URL、API 密钥、模型名称

手动配置（config.yaml）：

## 在 ~/.hermes/config.yaml 中
model:
  default: your-model-name
  provider: custom
  base_url: http://localhost:8000/v1
  api_key: your-key-or-leave-empty-for-local

警告 — 旧版环境变量

.env 中的 LLM_MODEL 已被移除——config.yaml 是模型和端点配置的唯一真实来源。OPENAI_BASE_URL 仍然被支持，但仅用于 openai-api 提供商（它覆盖 OpenAI 端点以进行直接 API 密钥访问）。对于其他提供商和自定义端点，使用 hermes model 或直接在 config.yaml 中设置 model.base_url。如果你的 .env 中有过时条目，它们会在下一次 hermes setup 或配置迁移时自动清除。

两种方法都会持久化到 config.yaml，这是模型、提供商和基础 URL 的真实来源。

使用 /model 切换模型

警告 — hermes model 与 /model

hermes model（从你的终端运行，在任何聊天会话之外）是完整的提供商设置向导。用于添加新提供商、运行 OAuth 流程、输入 API 密钥和配置自定义端点。

/model（在活动的 Hermes 聊天会话中键入）只能在已设置的提供商和模型之间切换。它不能添加新提供商、运行 OAuth 或提示输入 API 密钥。如果你只配置了一个提供商（例如 OpenRouter），/model 只会显示该提供商的模型。

要添加新提供商： 退出会话（Ctrl+C 或 /quit），运行 hermes model，设置新提供商，然后开始新会话。

一旦你至少配置了一个自定义端点，你可以在会话中切换模型：

/model custom:qwen-2.5          # 切换到自定义端点上的模型
/model custom                    # 从端点自动检测模型
/model openrouter:claude-sonnet-4 # 切换回云提供商

如果你配置了命名的自定义提供商（见下文），使用三重语法：

/model custom:local:qwen-2.5    # 使用 "local" 自定义提供商和模型 qwen-2.5
/model custom:work:llama3       # 使用 "work" 自定义提供商和 llama3

切换提供商时，Hermes 会将基础 URL 和提供商持久化到配置中，以便更改在重启后仍然有效。当从自定义端点切换到内置提供商时，过时的基础 URL 会自动清除。

提示

/model custom（裸，无模型名称）会查询你的端点的 /models API，如果恰好加载了一个模型，则自动选择。对于运行单个模型的本地服务器很有用。

以下所有内容都遵循相同的模式——只需更改 URL、密钥和模型名称。

Ollama — 本地模型，零配置

Ollama 通过一条命令在本地运行开放权重模型。最适合：快速本地实验、隐私敏感工作、离线使用。通过 OpenAI 兼容 API 支持工具调用。

## 安装并运行模型
ollama pull qwen2.5-coder:32b
ollama serve   # 在端口 11434 上启动

然后配置 Hermes：

hermes model
## 选择 "Custom endpoint (self-hosted / VLLM / etc.)"
## 输入 URL: http://localhost:11434/v1
## 跳过 API 密钥（Ollama 不需要）
## 输入模型名称（例如 qwen2.5-coder:32b）

或者直接配置 config.yaml：

model:
  default: qwen2.5-coder:32b
  provider: custom
  base_url: http://localhost:11434/v1
  context_length: 64000   # 见下方警告

注意 — Ollama 默认使用非常低的上下文长度

Ollama 不默认使用模型的完整上下文窗口。根据你的 VRAM，默认值为：

可用 VRAM	默认上下文
小于 24 GB	4,096 个 token
24–48 GB	32,768 个 token
48+ GB	256,000 个 token

Hermes Agent 需要至少 64,000 个 token 的上下文才能用于带有工具的智能体使用。较小的窗口会在启动时被拒绝，因为系统提示、工具模式和对话状态需要足够的空间来执行可靠的多步骤工作流。

如何增加它（选择一种）：

bashCopy

# 选项 1：通过环境变量设置服务器范围（推荐）
OLLAMA_CONTEXT_LENGTH=64000 ollama serve

# 选项 2：对于 systemd 管理的 Ollama
sudo systemctl edit ollama.service
# 添加：Environment="OLLAMA_CONTEXT_LENGTH=64000"
# 然后：sudo systemctl daemon-reload && sudo systemctl restart ollama

# 选项 3：将其烘焙到自定义模型中（每个模型持久化）
echo -e "FROM qwen2.5-coder:32b\nPARAMETER num_ctx 64000" > Modelfile
ollama create qwen2.5-coder-64k -f Modelfile

你不能通过 OpenAI 兼容 API（/v1/chat/completions）设置上下文长度。它必须在服务器端或通过 Modelfile 配置。这是将 Ollama 与 Hermes 等工具集成时最常见的困惑来源。

验证你的上下文设置正确：

ollama ps
## 查看 CONTEXT 列——它应该显示你配置的值

提示

使用 ollama list 列出可用模型。使用 ollama pull <model> 从 Ollama 库 拉取任何模型。Ollama 自动处理 GPU 卸载——大多数设置无需配置。

vLLM — 高性能 GPU 推理

vLLM 是生产级 LLM 服务的标准。最适合：GPU 硬件上的最大吞吐量、服务大型模型、连续批处理。

pip install vllm
vllm serve meta-llama/Llama-3.1-70B-Instruct \
  --port 8000 \
  --max-model-len 65536 \
  --tensor-parallel-size 2 \
  --enable-auto-tool-choice \
  --tool-call-parser hermes

然后配置 Hermes：

hermes model
## 选择 "Custom endpoint (self-hosted / VLLM / etc.)"
## 输入 URL: http://localhost:8000/v1
## 跳过 API 密钥（或输入一个，如果你用 --api-key 配置了 vLLM）
## 输入模型名称: meta-llama/Llama-3.1-70B-Instruct

上下文长度： vLLM 默认读取模型的 max_position_embeddings。如果超过你的 GPU 内存，它会报错并要求你设置更低的 --max-model-len。你也可以使用 --max-model-len auto 自动找到适合的最大值。设置 --gpu-memory-utilization 0.95（默认 0.9）以在 VRAM 中挤出更多上下文。

工具调用需要显式标志：

支持的解析器：hermes（Qwen 2.5、Hermes 2/3）、llama3_json（Llama 3.x）、mistral、deepseek_v3、deepseek_v31、xlam、pythonic。没有这些标志，工具调用将无法工作——模型会将工具调用输出为文本。

提示

vLLM 支持人类可读的大小：--max-model-len 64k（小写 k = 1000，大写 K = 1024）。

SGLang — 使用 RadixAttention 的快速服务

SGLang 是 vLLM 的替代方案，具有用于 KV 缓存重用的 RadixAttention。最适合：多轮对话（前缀缓存）、约束解码、结构化输出。

pip install "sglang[all]"
python -m sglang.launch_server \
  --model meta-llama/Llama-3.1-70B-Instruct \
  --port 30000 \
  --context-length 65536 \
  --tp 2 \
  --tool-call-parser qwen

然后配置 Hermes：

hermes model
## 选择 "Custom endpoint (self-hosted / VLLM / etc.)"
## 输入 URL: http://localhost:30000/v1
## 输入模型名称: meta-llama/Llama-3.1-70B-Instruct

上下文长度： SGLang 默认从模型配置中读取。使用 --context-length 覆盖。如果你需要超过模型声明的最大值，设置 SGLANG_ALLOW_OVERWRITE_LONGER_CONTEXT_LEN=1。

工具调用： 使用 --tool-call-parser 和适合你模型系列的解析器：qwen（Qwen 2.5）、llama3、llama4、deepseekv3、mistral、glm。没有这个标志，工具调用会以纯文本形式返回。

注意 — SGLang 默认最大输出 token 为 128

如果响应似乎被截断，请向请求添加 max_tokens 或在服务器上设置 --default-max-tokens。如果请求中未指定，SGLang 的默认值仅为每个响应 128 个 token。

llama.cpp / llama-server — CPU 和 Metal 推理

llama.cpp 在 CPU、Apple Silicon（Metal）和消费级 GPU 上运行量化模型。最适合：在没有数据中心 GPU 的情况下运行模型、Mac 用户、边缘部署。

## 构建并启动 llama-server
cmake -B build && cmake --build build --config Release
./build/bin/llama-server \
  --jinja -fa \
  -c 64000 \
  -ngl 99 \
  -m models/qwen2.5-coder-32b-instruct-Q4_K_M.gguf \
  --port 8080 --host 0.0.0.0

上下文长度（-c）： 最近的构建默认为 0，从 GGUF 元数据读取模型的训练上下文。对于具有 128k+ 训练上下文的模型，这可能会因尝试分配完整的 KV 缓存而导致 OOM。显式设置 -c 至少为 64,000 个 token 用于 Hermes。如果使用并行插槽（-np），总上下文会在插槽之间分配——使用 -c 64000 -np 4，每个插槽只得到 16k，低于 Hermes 每个活动会话的最小值。

然后将 Hermes 指向它：

hermes model
## 选择 "Custom endpoint (self-hosted / VLLM / etc.)"
## 输入 URL: http://localhost:8080/v1
## 跳过 API 密钥（本地服务器不需要）
## 输入模型名称——或留空以自动检测（如果只加载了一个模型）

这会将端点保存到 config.yaml，以便在会话之间持久化。

注意 — 工具调用需要 --jinja

没有 --jinja，llama-server 会完全忽略 tools 参数。模型会尝试通过在其响应文本中编写 JSON 来调用工具，但 Hermes 不会将其识别为工具调用——你会看到像 {"name": "web_search", ...} 这样的原始 JSON 作为消息打印，而不是实际的搜索。

原生工具调用支持（最佳性能）：Llama 3.x、Qwen 2.5（包括 Coder）、Hermes 2/3、Mistral、DeepSeek、Functionary。所有其他模型使用一个通用处理程序，该处理程序可以工作但效率可能较低。有关完整列表，请参见 llama.cpp 函数调用文档。

你可以通过检查 http://localhost:8080/props 来验证工具支持是否激活——chat_template 字段应该存在。

提示

从 Hugging Face 下载 GGUF 模型。Q4_K_M 量化提供了质量和内存使用的最佳平衡。

LM Studio — 带有本地模型的桌面应用

LM Studio 是一个用于运行本地模型的桌面应用，带有 GUI。最适合：喜欢可视化界面的用户、快速模型测试、macOS/Windows/Linux 上的开发者。

从 LM Studio 应用启动服务器（开发者选项卡 → 启动服务器），或使用 CLI：

lms server start                        # 在端口 1234 上启动
lms load qwen2.5-coder --context-length 64000

然后配置 Hermes：

hermes model
## 选择 "LM Studio"
## 按 Enter 使用 http://localhost:1234/v1
## 从发现的模型中选择一个
## 如果启用了 LM Studio 服务器认证，在提示时输入 LM_API_KEY

Hermes 会自动加载一个具有 64K 上下文长度的 LM Studio 模型

要更改 LM Studio 中的上下文长度：

1. 点击模型选择器旁边的齿轮图标
2. 将 "Context Length" 设置为至少 64000 以获得流畅体验
3. 重新加载模型以使更改生效
4. 如果你的机器无法容纳 64000，考虑使用具有更大上下文长度的较小模型。

或者，使用 CLI：lms load model-name --context-length 64000

你可以使用 CLI 估计模型是否适合：lms load model-name --context-length 64000 --estimate-only

要设置持久的每个模型默认值：我的模型选项卡 → 模型上的齿轮图标 → 设置上下文大小。 :::

工具调用： 自 LM Studio 0.3.6 起支持。具有原生工具调用训练的模型（Qwen 2.5、Llama 3.x、Mistral、Hermes）会被自动检测并显示工具徽章。其他模型使用一个通用回退，可能不太可靠。

WSL2 网络（Windows 用户）

由于 Hermes Agent 需要 Unix 环境，Windows 用户在 WSL2 内运行它。如果你的模型服务器（Ollama、LM Studio 等）在 Windows 主机上运行，你需要桥接网络差距——WSL2 使用带有自己子网的虚拟网络适配器，因此 WSL2 内的 localhost 指的是 Linux 虚拟机，而不是 Windows 主机。

提示 — 两者都在 WSL2 中？没问题。

如果你的模型服务器也在 WSL2 内运行（常见于 vLLM、SGLang 和 llama-server），localhost 按预期工作——它们共享相同的网络命名空间。跳过本节。

选项 1：镜像网络模式（推荐）

在 Windows 11 22H2+ 上可用，镜像模式使 localhost 在 Windows 和 WSL2 之间双向工作——最简单的修复。

1. 创建或编辑 %USERPROFILE%\.wslconfig（例如 C:\Users\YourName\.wslconfig）：

   iniCopy

   [wsl2]
   networkingMode=mirrored

2. 从 PowerShell 重启 WSL：

   powershellCopy

   wsl --shutdown

3. 重新打开你的 WSL2 终端。localhost 现在可以访问 Windows 服务：

   bashCopy

   curl http://localhost:11434/v1/models   # Windows 上的 Ollama — 有效

注意 — Hyper-V 防火墙

在某些 Windows 11 构建中，Hyper-V 防火墙默认阻止镜像连接。如果启用镜像模式后 localhost 仍然无法工作，在管理员 PowerShell 中运行以下命令：

powershellCopy

Set-NetFirewallHyperVVMSetting -Name '{40E0AC32-46A5-438A-A0B2-2B479E8F2E90}' -DefaultInboundAction Allow

选项 2：使用 Windows 主机 IP（Windows 10 / 旧版本）

如果你无法使用镜像模式，从 WSL2 内部找到 Windows 主机 IP，并使用它代替 localhost：

## 获取 Windows 主机 IP（WSL2 虚拟网络的默认网关）
ip route show | grep -i default | awk '{ print $3 }'
## 示例输出：172.29.192.1

在你的 Hermes 配置中使用该 IP：

model:
  default: qwen2.5-coder:32b
  provider: custom
  base_url: http://172.29.192.1:11434/v1   # Windows 主机 IP，不是 localhost

提示 — 动态助手

主机 IP 在 WSL2 重启后可能会更改。你可以在 shell 中动态获取它：

bashCopy

export WSL_HOST=$(ip route show | grep -i default | awk '{ print $3 }')
echo "Windows 主机位于: $WSL_HOST"
curl http://$WSL_HOST:11434/v1/models   # 测试 Ollama

或者使用你机器的 mDNS 名称（需要 WSL2 中的 libnss-mdns）：

bashCopy

sudo apt install libnss-mdns
curl http://$(hostname).local:11434/v1/models

服务器绑定地址（NAT 模式必需）

如果你使用选项 2（使用主机 IP 的 NAT 模式），Windows 上的模型服务器必须接受来自 127.0.0.1 之外的连接。默认情况下，大多数服务器只监听 localhost——NAT 模式下的 WSL2 连接来自不同的虚拟子网，会被拒绝。在镜像模式下，localhost 直接映射，因此默认的 127.0.0.1 绑定可以正常工作。

Windows 上的 Ollama（详细）： Ollama 作为 Windows 服务运行。要设置 OLLAMA_HOST：

1. 打开系统属性 → 环境变量
2. 添加一个新的系统变量：OLLAMA_HOST = 0.0.0.0
3. 重启 Ollama 服务（或重启）

Windows 防火墙

Windows 防火墙将 WSL2 视为单独的网络（在 NAT 和镜像模式下都是如此）。如果上述步骤后连接仍然失败，为你的模型服务器端口添加防火墙规则：

## 在管理员 PowerShell 中运行 — 将 PORT 替换为你的服务器端口
New-NetFirewallRule -DisplayName "Allow WSL2 to Model Server" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 11434

常见端口：Ollama 11434、vLLM 8000、SGLang 30000、llama-server 8080、LM Studio 1234。

快速验证

从 WSL2 内部，测试你是否可以到达模型服务器：

## 将 URL 替换为你的服务器地址和端口
curl http://localhost:11434/v1/models          # 镜像模式
curl http://172.29.192.1:11434/v1/models       # NAT 模式（使用你的实际主机 IP）

如果你收到列出模型的 JSON 响应，就成功了。在 Hermes 配置中使用相同的 URL 作为 base_url。

本地模型故障排除

这些问题影响所有与 Hermes 一起使用的本地推理服务器。

从 WSL2 到 Windows 托管的模型服务器出现 "Connection refused"

如果你在 WSL2 内运行 Hermes，在 Windows 主机上运行模型服务器，http://localhost:<port> 在 WSL2 的默认 NAT 网络模式下无法工作。请参见上面的 WSL2 网络 以获取修复方法。

工具调用显示为文本而不是执行

模型输出类似 {"name": "web_search", "arguments": {...}} 作为消息，而不是实际调用工具。

原因： 你的服务器未启用工具调用，或者模型不支持通过服务器的工具调用实现。

模型似乎忘记上下文或给出不连贯的响应

原因： 上下文窗口太小。当对话超过上下文限制时，大多数服务器会静默地丢弃较旧的消息。Hermes 的系统提示 + 工具模式本身可能使用 4k–8k 个 token。

诊断：

## 检查 Hermes 认为的上下文是什么
## 查看启动行："Context limit: X tokens"
## 检查你的服务器的实际上下文
## Ollama: ollama ps（CONTEXT 列）
## llama.cpp: curl http://localhost:8080/props | jq '.default_generation_settings.n_ctx'
## vLLM: 检查启动参数中的 --max-model-len

修复： 将上下文设置为至少 64,000 个 token 用于智能体使用。请参见上面每个服务器的部分以获取特定标志。

启动时出现 "Context limit: 2048 tokens"

Hermes 从你的服务器的 /v1/models 端点自动检测上下文长度。如果服务器报告的值较低（或根本不报告），Hermes 会使用模型声明的限制，这可能是错误的。

修复： 在 config.yaml 中显式设置：

model:
  default: your-model
  provider: custom
  base_url: http://localhost:11434/v1
  context_length: 64000

响应在句子中间被截断

可能的原因：

1. 服务器上的输出上限（max_tokens）较低——SGLang 默认为每个响应 128 个 token。在服务器上设置 --default-max-tokens，或在 config.yaml 中使用 model.max_tokens 配置 Hermes。注意：max_tokens 仅控制响应长度——与你的对话历史可以有多长无关（那是 context_length）。
2. 上下文耗尽——模型填满了其上下文窗口。增加 model.context_length 或在 Hermes 中启用上下文压缩。

LiteLLM 代理 — 多提供商网关

LiteLLM 是一个 OpenAI 兼容的代理，将 100 多个 LLM 提供商统一在单个 API 后面。最适合：无需配置更改即可在提供商之间切换、负载均衡、回退链、预算控制。

## 安装并启动
pip install "litellm[proxy]"
litellm --model anthropic/claude-sonnet-4 --port 4000
## 或使用配置文件用于多个模型：
litellm --config litellm_config.yaml --port 4000

然后使用 hermes model → 自定义端点 → http://localhost:4000/v1 配置 Hermes。

带有回退的示例 litellm_config.yaml：

model_list:
  - model_name: "best"
    litellm_params:
      model: anthropic/claude-sonnet-4
      api_key: sk-ant-...
  - model_name: "best"
    litellm_params:
      model: openai/gpt-4o
      api_key: sk-...
router_settings:
  routing_strategy: "latency-based-routing"

ClawRouter — 成本优化路由

ClawRouter 由 BlockRunAI 开发，是一个本地路由代理，根据查询复杂度自动选择模型。它在 14 个维度上对请求进行分类，并路由到能够处理该任务的最便宜模型。支付通过 USDC 加密货币进行（无需 API 密钥）。

## 安装并启动
npx @blockrun/clawrouter    # 在端口 8402 上启动

然后使用 hermes model → 自定义端点 → http://localhost:8402/v1 → 模型名称 blockrun/auto 配置 Hermes。

路由配置文件：

注意

ClawRouter 需要一个在 Base 或 Solana 上以 USDC 资助的钱包用于支付。所有请求都通过 BlockRun 的后端 API 路由。运行 npx @blockrun/clawrouter doctor 检查钱包状态。

其他兼容提供商

任何具有 OpenAI 兼容 API 的服务都可以。一些流行的选项：

使用 hermes model → 自定义端点配置其中任何一个，或在 config.yaml 中配置：

model:
  default: meta-llama/Llama-3.1-70B-Instruct-Turbo
  provider: custom
  base_url: https://api.together.xyz/v1
  api_key: your-together-key

上下文长度检测

注意 — 两个设置，容易混淆

context_length 是总上下文窗口——输入和输出 token 的合并预算（例如 Claude Opus 4.6 的 200,000）。Hermes 使用它来决定何时压缩历史记录以及验证 API 请求。

model.max_tokens 是输出上限——模型在单个响应中可能生成的最大 token 数。它与你的对话历史可以有多长无关。行业标准名称 max_tokens 是常见的混淆来源；Anthropic 的原生 API 已将其重命名为 max_output_tokens 以更清晰。

当自动检测得到错误的窗口大小时，设置 context_length。 仅当你需要限制单个响应的长度时，设置 model.max_tokens。

Hermes 使用多源解析链来检测你的模型和提供商的正确上下文窗口：

1. 配置覆盖 — config.yaml 中的 model.context_length（最高优先级）
2. 自定义提供商每个模型 — custom_providers[].models.<id>.context_length
3. 持久缓存 — 先前发现的值（重启后仍然有效）
4. 端点 /models — 查询你的服务器 API（本地/自定义端点）
5. Anthropic /v1/models — 查询 Anthropic 的 API 以获取 max_input_tokens（仅 API 密钥用户）
6. OpenRouter API — 来自 OpenRouter 的实时模型元数据
7. Nous Portal — 后缀匹配 Nous 模型 ID 与 OpenRouter 元数据
8. models.dev — 社区维护的注册表，包含 3800+ 个模型在 100+ 个提供商上的提供商特定上下文长度
9. 回退默认值 — 广泛的模型家族模式（128K 默认值）

对于大多数设置，这开箱即用。系统是提供商感知的——相同的模型根据服务提供商的不同可以有不同的上下文限制（例如，claude-opus-4.6 在 Anthropic 直接上是 1M，但在 GitHub Copilot 上是 128K）。

要显式设置上下文长度，将 context_length 添加到你的模型配置中：

model:
  default: "qwen3.5:9b"
  base_url: "http://localhost:8080/v1"
  context_length: 131072  # tokens

对于自定义端点，你还可以为每个模型设置上下文长度：

custom_providers:
  - name: "My Local LLM"
    base_url: "http://localhost:11434/v1"
    models:
      qwen3.5:27b:
        context_length: 64000
      deepseek-r1:70b:
        context_length: 65536

hermes model 在配置自定义端点时会提示输入上下文长度。留空以进行自动检测。

提示 — 何时手动设置

• 你正在使用具有自定义 num_ctx 的 Ollama，该值低于模型的最大值
• 你想将上下文限制在模型最大值以下（例如，在 128k 模型上使用 8k 以节省 VRAM）
• 你在一个不暴露 /v1/models 的代理后面运行

命名的自定义提供商

如果你使用多个自定义端点（例如，本地开发服务器和远程 GPU 服务器），你可以在 config.yaml 中将它们定义为命名的自定义提供商：

custom_providers:
  - name: local
    base_url: http://localhost:8080/v1
## api_key 省略 — Hermes 对无密钥的本地服务器使用 "no-key-required"
  - name: work
    base_url: https://gpu-server.internal.corp/v1
    key_env: CORP_API_KEY
    api_mode: chat_completions   # 由 `hermes model` → 自定义端点向导显式设置；自动检测仍作为回退发生
  - name: anthropic-proxy
    base_url: https://proxy.example.com/anthropic
    key_env: ANTHROPIC_PROXY_KEY
    api_mode: anthropic_messages  # 用于 Anthropic 兼容的代理

一些 OpenAI 兼容的端点需要提供商特定的请求体字段。向匹配的自定义提供商添加一个 extra_body 映射，Hermes 会将其合并到该端点的每个聊天补全请求中：

custom_providers:
  - name: gemma-local
    base_url: http://localhost:8080/v1
    model: google/gemma-4-31b-it
    extra_body:
      enable_thinking: true
      reasoning_effort: high

使用你的服务器文档中指定的形状。例如，vLLM Gemma 部署和一些 NVIDIA NIM 端点期望 enable_thinking 在 chat_template_kwargs 下，而不是作为顶层的 extra_body 字段：

extra_body:
  chat_template_kwargs:
    enable_thinking: true

hermes model → 自定义端点向导现在会显式提示 api_mode，并将你的答案持久化到 config.yaml。基于 URL 的自动检测（例如 /anthropic 路径 → anthropic_messages）在字段留空时仍作为回退发生。

自定义提供商模型的原生视觉支持。 如果你的自定义端点提供支持视觉的模型，但不在 models.dev 中，设置 model.supports_vision: true，这样 Hermes 会原生路由附加的图像（作为 image_url 部分），而不是通过 vision_analyze 预处理它们。单个开关——无需同时设置 agent.image_input_mode: native。

model:
  provider: custom
  base_url: http://localhost:8080/v1
  default: qwen3.6-35b-a3b
  supports_vision: true   # 原生发送图像；否则 vision_analyze 会预先描述它们

相同的键在按命名提供商的模型上也被支持（custom_providers[*].models[*].supports_vision），并接受标准的 YAML 布尔值（true/false/yes/no/on/off/1/0）。

在会话中使用三重语法在它们之间切换：

/model custom:local:qwen-2.5       # 使用 "local" 端点和 qwen-2.5
/model custom:work:llama3-70b      # 使用 "work" 端点和 llama3-70b
/model custom:anthropic-proxy:claude-sonnet-4  # 使用代理

你也可以从交互式 hermes model 菜单中选择命名的自定义提供商。

食谱：Together AI、Groq、Perplexity

其他兼容提供商 中列出的云提供商都使用 OpenAI 的 REST 方言，因此它们在 custom_providers: 下以相同方式连接。以下是三个可行的食谱。每个都放入 ~/.hermes/config.yaml，匹配的 API 密钥放入 ~/.hermes/.env。

Together AI

以远低于第一方 API 的价格托管开放权重模型（Llama、MiniMax、Gemma、DeepSeek、Qwen）。对于多模型集群来说是一个很好的默认选择。

## ~/.hermes/config.yaml
custom_providers:
  - name: together
    base_url: https://api.together.xyz/v1
    key_env: TOGETHER_API_KEY
## api_mode: chat_completions  # 默认 — 无需设置

model:
  default: MiniMaxAI/MiniMax-M2.7   # 或任何来自 together.ai/models 的模型
  provider: custom:together

## ~/.hermes/.env
TOGETHER_API_KEY=your-together-key

在会话中切换模型：

/model custom:together:meta-llama/Llama-3.3-70B-Instruct-Turbo
/model custom:together:google/gemma-4-31b-it
/model custom:together:deepseek-ai/DeepSeek-V3

Together 的 /v1/models 端点可以工作，因此 hermes model 可以自动发现可用模型。

Groq

超快推理（Llama-3.3-70B 上约 500 tok/s）。目录较小，但对于延迟敏感的交互式使用来说很强。

## ~/.hermes/config.yaml
custom_providers:
  - name: groq
    base_url: https://api.groq.com/openai/v1
    key_env: GROQ_API_KEY

model:
  default: llama-3.3-70b-versatile
  provider: custom:groq

## ~/.hermes/.env
GROQ_API_KEY=your-groq-key

Perplexity

当你想要一个自动进行实时网页搜索和引用的模型时很有用。对哪些模型可用很严格——查看 perplexity.ai/settings/api 获取当前列表。

## ~/.hermes/config.yaml
custom_providers:
  - name: perplexity
    base_url: https://api.perplexity.ai
    key_env: PERPLEXITY_API_KEY

model:
  default: sonar
  provider: custom:perplexity

## ~/.hermes/.env
PERPLEXITY_API_KEY=your-perplexity-key

一个配置中的多个提供商

这三个食谱可以组合——一起使用它们，并通过 /model custom:<name>:<model> 在每轮切换：

custom_providers:
  - name: together
    base_url: https://api.together.xyz/v1
    key_env: TOGETHER_API_KEY
  - name: groq
    base_url: https://api.groq.com/openai/v1
    key_env: GROQ_API_KEY
  - name: perplexity
    base_url: https://api.perplexity.ai
    key_env: PERPLEXITY_API_KEY

model:
  default: MiniMaxAI/MiniMax-M2.7
  provider: custom:together      # 启动到 Together；之后自由切换

提示 — 故障排除

• hermes doctor 应该不会为这些名称打印任何 Unknown provider 警告（在 #15083 中的 CLI 验证器修复之后）。
• 如果提供商的 /v1/models 端点不可达（Perplexity 是常见情况），hermes model 会以警告而不是硬拒绝的方式持久化模型——参见 #15136。
• 要完全跳过 custom_providers: 并使用裸的 provider: custom 和 CUSTOM_BASE_URL 环境变量，参见 #15103。

选择合适的设置

提示

你可以随时使用 hermes model 在提供商之间切换——无需重启。你的对话历史、记忆和技能会随着你使用的提供商而转移。

可选的 API 密钥

自托管 Firecrawl

默认情况下，Hermes 使用 Firecrawl 云 API 进行网页搜索和抓取。如果你更愿意在本地运行 Firecrawl，可以将 Hermes 指向自托管实例。请参见 Firecrawl 的 SELF_HOST.md 获取完整的设置说明。

你得到的好处： 无需 API 密钥，无速率限制，无每页成本，完全的数据主权。

你失去的： 云版本使用 Firecrawl 专有的 "Fire-engine" 进行高级反机器人绕过（Cloudflare、CAPTCHA、IP 轮换）。自托管使用基本的 fetch + Playwright，因此一些受保护的网站可能会失败。搜索使用 DuckDuckGo 而不是 Google。

设置：

1. 克隆并启动 Firecrawl Docker 堆栈（5 个容器：API、Playwright、Redis、RabbitMQ、PostgreSQL——需要约 4-8 GB RAM）：
   bashCopy

   git clone https://github.com/firecrawl/firecrawl
   cd firecrawl

在 .env 中，设置：USE_DB_AUTHENTICATION=false, HOST=0.0.0.0, PORT=3002

docker compose up -d

2. 将 Hermes 指向你的实例（无需 API 密钥）：
```bash
hermes config set FIRECRAWL_API_URL http://localhost:3002

如果你的自托管实例启用了认证，你也可以同时设置 FIRECRAWL_API_KEY 和 FIRECRAWL_API_URL。

OpenRouter 提供商路由

使用 OpenRouter 时，你可以控制请求如何在提供商之间路由。在 ~/.hermes/config.yaml 中添加一个 provider_routing 部分：

provider_routing:
  sort: "throughput"          # "price"（默认）、"throughput" 或 "latency"
## only: ["anthropic"]      # 仅使用这些提供商
## ignore: ["deepinfra"]    # 跳过这些提供商
## order: ["anthropic", "google"]  # 按此顺序尝试提供商
## require_parameters: true  # 仅使用支持所有请求参数的提供商
## data_collection: "deny"   # 排除可能存储/训练数据的提供商

快捷方式： 在任何模型名称后附加 :nitro 以进行吞吐量排序（例如 anthropic/claude-sonnet-4:nitro），或附加 :floor 以进行价格排序。

OpenRouter Pareto Code 路由器

OpenRouter 在 openrouter/pareto-code 上提供了一个实验性的编码模型路由器，它会自动将请求路由到满足编码质量门槛的最便宜模型（由 Artificial Analysis 排名）。选择此模型并在 ~/.hermes/config.yaml 中调整 min_coding_score 旋钮：

model:
  provider: openrouter
  model: openrouter/pareto-code

openrouter:
  min_coding_score: 0.65   # 0.0–1.0；越高 = 越强（更贵）的编码器。默认 0.65。

注意：

• min_coding_score 仅在 model.model 为 openrouter/pareto-code 时发送。在任何其他模型上，该值无效。
• 设置为空字符串（或删除该行）以让 OpenRouter 选择最强的可用编码器——这是其文档中省略插件块时的行为。
• 选择在给定分数下是确定性的，但实际选择的模型可能会随着帕累托前沿的移动（新模型、基准更新）而变化。
• 请参见 OpenRouter 的 Pareto 路由器文档 了解完整的路由器行为。
• 要为特定的辅助任务（压缩、视觉等）而不是主智能体使用 Pareto Code 路由器，请在该任务下设置 extra_body.plugins——参见辅助模型 → OpenRouter 路由和辅助任务的 Pareto Code。

回退提供商

配置一个备份提供商链，当主模型失败时（速率限制、服务器错误、认证失败），Hermes 会按顺序尝试。规范格式是一个顶层的 fallback_providers: 列表：

fallback_providers:
  - provider: openrouter
    model: anthropic/claude-sonnet-4
  - provider: anthropic
    model: claude-sonnet-4
## base_url: http://localhost:8000/v1    # 可选，用于自定义端点
## api_mode: chat_completions           # 可选覆盖

为了向后兼容，仍然接受旧式的单对 fallback_model: 字典：

fallback_model:
  provider: openrouter
  model: anthropic/claude-sonnet-4

激活时，回退会在会话中交换模型和提供商，而不会丢失你的对话。链会逐条尝试；激活在每个会话中只发生一次。

支持的提供商：openrouter、nous、novita、openai-codex、copilot、copilot-acp、anthropic、gemini、google-gemini-cli、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。

提示

回退完全通过 config.yaml 配置——或通过 hermes fallback 交互式配置。有关何时触发、链如何推进以及如何与辅助任务和委托交互的完整详细信息，请参见回退提供商。

参见

• 配置 — 通用配置（目录结构、配置优先级、终端后端、内存、压缩等）
• 环境变量 — 所有环境变量的完整参考