AI 提供商（AI Providers）

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

推理提供商（Inference Providers）

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

提供商	设置方式
Nous Portal	`hermes model`（OAuth，订阅制）
OpenAI Codex	`hermes model`（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 密钥或手动设置令牌——见下方注释）
OpenRouter	`OPENROUTER_API_KEY` 在 `~/.hermes/.env` 中
NovitaAI	`NOVITA_API_KEY` 在 `~/.hermes/.env` 中（provider: `novita`，200+ 模型，Model API，Agent Sandbox，GPU Cloud）
AI Gateway	`AI_GATEWAY_API_KEY` 在 `~/.hermes/.env` 中（provider: `ai-gateway`）
z.ai / GLM	`GLM_API_KEY` 在 `~/.hermes/.env` 中（provider: `zai`）
Kimi / Moonshot	`KIMI_API_KEY` 在 `~/.hermes/.env` 中（provider: `kimi-coding`）
Kimi / Moonshot（中国）	`KIMI_CN_API_KEY` 在 `~/.hermes/.env` 中（provider: `kimi-coding-cn`；别名：`kimi-cn`、`moonshot-cn`）
Arcee AI	`ARCEEAI_API_KEY` 在 `~/.hermes/.env` 中（provider: `arcee`；别名：`arcee-ai`、`arceeai`）
GMI Cloud	`GMI_API_KEY` 在 `~/.hermes/.env` 中（provider: `gmi`；别名：`gmi-cloud`、`gmicloud`）
MiniMax	`MINIMAX_API_KEY` 在 `~/.hermes/.env` 中（provider: `minimax`）
MiniMax 中国	`MINIMAX_CN_API_KEY` 在 `~/.hermes/.env` 中（provider: `minimax-cn`）
xAI（Grok）— Responses API	`XAI_API_KEY` 在 `~/.hermes/.env` 中（provider: `xai`）
xAI Grok OAuth（SuperGrok）	`hermes model` → “xAI Grok OAuth（SuperGrok Subscription）“——浏览器登录，无需 API 密钥。参见指南
通义千问云（阿里云 DashScope）	`DASHSCOPE_API_KEY` 在 `~/.hermes/.env` 中（provider: `alibaba`）
阿里云（编码计划）	`DASHSCOPE_API_KEY`（provider: `alibaba-coding-plan`，别名：`alibaba_coding`）——独立计费 SKU，不同端点
Kilo Code	`KILOCODE_API_KEY` 在 `~/.hermes/.env` 中（provider: `kilocode`）
小米 MiMo	`XIAOMI_API_KEY` 在 `~/.hermes/.env` 中（provider: `xiaomi`，别名：`mimo`、`xiaomi-mimo`）
腾讯 TokenHub	`TOKENHUB_API_KEY` 在 `~/.hermes/.env` 中（provider: `tencent-tokenhub`，别名：`tencent`、`tokenhub`、`tencentmaas`）
OpenCode Zen	`OPENCODE_ZEN_API_KEY` 在 `~/.hermes/.env` 中（provider: `opencode-zen`）
OpenCode Go	`OPENCODE_GO_API_KEY` 在 `~/.hermes/.env` 中（provider: `opencode-go`）
DeepSeek	`DEEPSEEK_API_KEY` 在 `~/.hermes/.env` 中（provider: `deepseek`）
Hugging Face	`HF_TOKEN` 在 `~/.hermes/.env` 中（provider: `huggingface`，别名：`hf`）
Google / Gemini	`GOOGLE_API_KEY`（或 `GEMINI_API_KEY`）在 `~/.hermes/.env` 中（provider: `gemini`）
Google Gemini（OAuth）	`hermes model` → “Google Gemini（OAuth）“（provider: `google-gemini-cli`，支持免费层，浏览器 PKCE 登录）
LM Studio	`hermes model` → “LM Studio”（provider: `lmstudio`，可选 `LM_API_KEY`）
自定义端点（Custom Endpoint）	`hermes model` → 选择”Custom endpoint”（保存在 `config.yaml` 中）

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

:::tip 模型键别名在 model: 配置部分中，您可以使用 default: 或 model: 作为模型 ID 的键名。model: { default: my-model } 和 model: { model: my-model } 的作用完全相同。 :::

Google Gemini 通过 OAuth（`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 账户，想要免费层 | 无需操作——登录即可开始聊天 | | Workspace / Standard / Enterprise 账户 | 设置 HERMES_GEMINI_PROJECT_ID 或 GOOGLE_CLOUD_PROJECT 为您 GCP 项目 ID | | VPC-SC 保护的组织 | Hermes 检测到 SECURITY_POLICY_VIOLATED 并自动强制使用 standard-tier |

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

配额监控：

/gquota

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

Gemini Code Assist quota  (project: 123-abc)

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

:::warning 策略风险 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。

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

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

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

:::tip Nous 工具网关（Nous Tool Gateway）付费的 Nous Portal 订阅者还可以访问**工具网关（Tool Gateway）**——网页搜索、图像生成、TTS 和浏览器自动化，通过您的订阅路由。无需额外的 API 密钥。它会在 hermes model 设置过程中自动提供，或者稍后通过 hermes tools 启用。 :::

模型管理的两个命令

Hermes 有两个模型命令，服务于不同目的：

命令	在哪里运行	作用
`hermes model`	您的终端（在任何会话之外）	完整设置向导——添加提供商、运行 OAuth、输入 API 密钥、配置端点
`/model`	Hermes 聊天会话内部	在已配置的提供商和模型之间快速切换

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

Nous Portal

基于订阅的方式访问 Hermes-4 模型（Hermes-4-70B、Hermes-4.3-36B、Hermes-4-405B），通过 Nous Research 的门户网站。运行 hermes model，选择 Nous Portal，通过浏览器登录——Hermes 在 ~/.hermes/auth.json 中存储长期有效的刷新令牌。

刷新令牌还通过共享令牌存储在配置文件之间共享，因此在一个配置文件上登录会自动延续到其他配置文件。

令牌处理

Hermes 在每次推理调用时从存储的 Nous 刷新令牌签发生成短期 JWT，而非重用长期有效的 API 密钥。令牌生命周期完全自动——刷新、签发、在临时 401 时重试——您永远不会看到它。

如果门户使刷新令牌失效（密码更改、手动吊销、会话过期），无效的刷新令牌会在本地被隔离，以便 Hermes 停止重放，您不会看到大量相同的 401。下次调用会显示清晰的”需要重新认证”消息。运行 hermes auth add nous 重新登录；隔离区在下次成功登录后清除。

Anthropic（原生）

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

:::caution 需要 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 定价，独立于任何 Claude 订阅）。 :::

# 使用 API 密钥（按令牌付费）
export ANTHROPIC_API_KEY=***
hermes chat --provider anthropic --model claude-sonnet-4-6
 
# 推荐：通过 `hermes model` 认证
# Hermes 会在可用时直接使用 Claude Code 的凭据存储
hermes model
 
# 使用设置令牌手动覆盖（回退/旧版）
export ANTHROPIC_TOKEN=***  # setup-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"

:::tip 别名 --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

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

COPILOT_GITHUB_TOKEN 环境变量
GH_TOKEN 环境变量
GITHUB_TOKEN 环境变量
gh auth token CLI 回退

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

:::warning 令牌类型 Copilot API 不支持经典的个人访问令牌（ghp_*）。支持的令牌类型：

类型	前缀	获取方式
OAuth 令牌	`gho_`	`hermes model` → GitHub Copilot → 使用 GitHub 登录
细粒度 PAT	`github_pat_`	GitHub Settings → Developer settings → Fine-grained tokens（需要 Copilot Requests 权限）
GitHub App 令牌	`ghu_`	通过 GitHub App 安装

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

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

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

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

一些较旧的社区代理使用 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"

环境变量	描述
`COPILOT_GITHUB_TOKEN`	Copilot API 的 GitHub 令牌（第一优先级）
`HERMES_COPILOT_ACP_COMMAND`	覆盖 Copilot CLI 二进制路径（默认：`copilot`）
`HERMES_COPILOT_ACP_ARGS`	覆盖 ACP 参数（默认：`--acp --stdio`）

一等 API 密钥提供商（First-Class API-Key Providers）

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

# NovitaAI Model API
hermes chat --provider novita --model moonshotai/kimi-k2.5
# 需要：NOVITA_API_KEY 在 ~/.hermes/.env 中
 
# z.ai / 智谱AI 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 中
 
# 通义千问云 / 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"

Base URL 可以通过 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 环境变量覆盖。

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

xAI（Grok）— Responses API + 提示缓存（Prompt Caching）

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

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

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

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

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

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 密钥。Base URL 可以通过 NOVITA_BASE_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）通过规范化保留——不要使用破折号。

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

AWS Bedrock

Anthropic Claude、Amazon Nova、DeepSeek v3.2、Meta Llama 4 及其他模型通过 AWS Bedrock。使用 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）

阿里云通义千问 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）。

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

阿里云（编码计划/Coding Plan）

如果您已订阅阿里云的编码计划（与标准 DashScope API 访问分开的定价 SKU），Hermes 将其作为自己的一等提供商公开：alibaba-coding-plan。端点：https://coding-intl.dashscope.aliyuncs.com/v1。它与常规的 alibaba 提供商一样兼容 OpenAI，但具有不同的 base 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）

MiniMax-M2.7 通过浏览器 OAuth 登录——无需 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。

:::tip MiniMax OAuth 与 API 密钥 minimax-oauth 使用 MiniMax 面向消费者的门户，通过 OAuth 登录——无需计费设置。minimax 和 minimax-cn 提供商使用 MINIMAX_API_KEY / MINIMAX_CN_API_KEY——用于编程访问。完整步骤请参阅 MiniMax OAuth 指南。 :::

NVIDIA NIM

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

# 云（build.nvidia.com）
hermes chat --provider nvidia --model nvidia/nemotron-3-super-120b-a12b
# 需要：NVIDIA_API_KEY 在 ~/.hermes/.env 中
 
# 本地 NIM 端点——覆盖 base 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"

:::tip 本地 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-R1
# 需要：GMI_API_KEY 在 ~/.hermes/.env 中

或在 config.yaml 中永久设置：

model:
  provider: "gmi"
  default: "deepseek-ai/DeepSeek-R1"

Base URL 可以通过 GMI_BASE_URL 覆盖（默认：https://api.gmi-serving.com/v1）。

StepFun

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

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

或在 config.yaml 中永久设置：

model:
  provider: "stepfun"
  default: "step-3-mini"

Base URL 可以通过 STEPFUN_BASE_URL 覆盖（默认：https://api.stepfun.com/v1）。

Hugging Face 推理提供商（Hugging Face Inference Providers）

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

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

或在 config.yaml 中永久设置：

model:
  provider: "huggingface"
  default: "Qwen/Qwen3-235B-A22B-Thinking-2507"

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

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

Base URL 可以通过 HF_BASE_URL 覆盖。

自定义与自托管 LLM 提供商（Custom & Self-Hosted LLM Providers）

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

通用设置

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

交互式设置（推荐）：

hermes model
# 选择 "Custom endpoint (self-hosted / VLLM / etc.)"
# 输入：API base URL、API key、Model name

手动配置（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

:::warning 旧版环境变量 .env 中的 OPENAI_BASE_URL 和 LLM_MODEL 已移除。Hermes 的任何部分都不再读取它们——config.yaml 是模型和端点配置的唯一真实来源。如果您在 .env 中有过时的条目，它们将在下次 hermes setup 或配置迁移时自动清除。请使用 hermes model 或直接编辑 config.yaml。 :::

两种方法都持久化到 config.yaml，后者是模型、提供商和 base URL 的唯一真实来源。

使用 `/model` 切换模型

:::warning hermes model vs /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 将 base URL 和提供商持久化到配置中，以便更改在重启后仍然有效。当从自定义端点切换到内置提供商时，过时的 base URL 会自动清除。

:::tip /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 key（Ollama 不需要）
# 输入模型名称（例如 qwen2.5-coder:32b）

或直接配置 config.yaml：

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

:::caution Ollama 默认使用非常低的上下文长度 Ollama 默认不使用您模型的完整上下文窗口。根据您的 VRAM，默认值为：

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

对于使用工具的智能体，您至少需要 16k–32k 上下文。在 4k 时，仅系统提示 + 工具模式就可能填满窗口，没有空间留给对话。

如何增加（选择一种）：

# 选项 1：通过环境变量设置服务器范围（推荐）
OLLAMA_CONTEXT_LENGTH=32768 ollama serve
 
# 选项 2：对于 systemd 管理的 Ollama
sudo systemctl edit ollama.service
# 添加：Environment="OLLAMA_CONTEXT_LENGTH=32768"
# 然后：sudo systemctl daemon-reload && sudo systemctl restart ollama
 
# 选项 3：烘焙到自定义模型中（按模型持久化）
echo -e "FROM qwen2.5-coder:32b\\nPARAMETER num_ctx 32768" > Modelfile
ollama create qwen2.5-coder-32k -f Modelfile

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

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

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

:::tip 使用 ollama list 列出可用模型。使用 ollama pull <model> 从 Ollama library 拉取任何模型。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 key（或输入一个，如果您用 --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 中挤出更多上下文。

工具调用需要显式标志：

标志	用途
`--enable-auto-tool-choice`	`tool_choice: "auto"` 所需（Hermes 中的默认值）
`--tool-call-parser <name>`	模型工具调用格式的解析器

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

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

SGLang — 使用 RadixAttention 的快速服务

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

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。没有此标志，工具调用将作为纯文本返回。

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

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 32768 \
  -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 为您需要的值（对于智能体使用，32k–64k 是良好的范围）。如果使用并行插槽（-np），总上下文在插槽之间分配——使用 -c 32768 -np 4，每个插槽只有 8k。

然后配置 Hermes 指向它：

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

这将端点保存到 config.yaml，使其跨会话持久化。

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

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

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

:::tip 从 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 32768

然后配置 Hermes：

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

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

在 LM Studio 中更改上下文长度：

点击模型选择器旁边的齿轮图标
将”Context Length”设置为至少 64000 以获得流畅体验
重新加载模型使更改生效
如果您的机器无法容纳 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 VM，而不是 Windows 主机。

:::tip 两者都在 WSL2 中？没问题。如果您的模型服务器也在 WSL2 内部运行（vLLM、SGLang 和 llama-server 常见），localhost 按预期工作——它们共享相同的网络命名空间。跳过本节。 :::

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

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

创建或编辑 %USERPROFILE%\\.wslconfig（例如 C:\\Users\\YourName\\.wslconfig）：
```
[wsl2]
networkingMode=mirrored
```
从 PowerShell 重启 WSL：
```
wsl --shutdown
```

重新打开您的 WSL2 终端。localhost 现在可以到达 Windows 服务：

curl http://localhost:11434/v1/models   # Windows 上的 Ollama——工作

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

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

:::tip 动态辅助主机 IP 在 WSL2 重启后可能会变化。您可以在 shell 中动态获取它：

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

或使用您机器的 mDNS 名称（需要在 WSL2 中安装 libnss-mdns）：

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 绑定正常工作。

服务器	默认绑定	如何修复
Ollama	`127.0.0.1`	在启动 Ollama 前设置 `OLLAMA_HOST=0.0.0.0` 环境变量（Windows 上的系统设置 → 环境变量，或编辑 Ollama 服务）
LM Studio	`127.0.0.1`	在开发者标签 → 服务器设置中启用 “Serve on Network”
llama-server	`127.0.0.1`	在启动命令中添加 `--host 0.0.0.0`
vLLM	`0.0.0.0`	默认已绑定到所有接口
SGLang	`127.0.0.1`	在启动命令中添加 `--host 0.0.0.0`

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

打开系统属性 → 环境变量
添加新的系统变量：OLLAMA_HOST = 0.0.0.0
重启 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": {...}} 的消息，而不是实际调用工具。

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

服务器	修复
llama.cpp	在启动命令中添加 `--jinja`
vLLM	添加 `--enable-auto-tool-choice --tool-call-parser hermes`
SGLang	添加 `--tool-call-parser qwen`（或适当的解析器）
Ollama	工具调用默认已启用——确保您的模型支持（使用 `ollama show model-name` 检查）
LM Studio	更新到 0.3.6+ 并使用具有原生工具支持的模型

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

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

诊断：

# 检查 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

修复： 为智能体使用设置至少 32,768 tokens 的上下文。请参阅各服务器部分了解具体的标志。

启动时显示”Context limit: 2048 tokens”

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

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

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

响应在句子中间被截断

可能的原因：

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

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 → Custom endpoint → 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 → Custom endpoint → http://localhost:8402/v1 → 模型名称 blockrun/auto 配置 Hermes。

路由配置：

配置	策略	节省
`blockrun/auto`	平衡质量/成本	74-100%
`blockrun/eco`	最便宜的可能	95-100%
`blockrun/premium`	最佳质量模型	0%
`blockrun/free`	仅免费模型	100%
`blockrun/agentic`	针对工具使用优化	不等

:::note ClawRouter 需要一个在 Base 或 Solana 上使用 USDC 充值的钱包进行支付。所有请求通过 BlockRun 的后端 API 路由。运行 npx @blockrun/clawrouter doctor 检查钱包状态。 :::

其他兼容提供商

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

提供商	Base URL	备注
Together AI	`https://api.together.xyz/v1`	云托管开放模型
Groq	`https://api.groq.com/openai/v1`	超高速推理
DeepSeek	`https://api.deepseek.com/v1`	DeepSeek 模型
Fireworks AI	`https://api.fireworks.ai/inference/v1`	快速开放模型托管
GMI Cloud	`https://api.gmi-serving.com/v1`	托管兼容 OpenAI 的推理
Cerebras	`https://api.cerebras.ai/v1`	晶圆级芯片推理
Mistral AI	`https://api.mistral.ai/v1`	Mistral 模型
OpenAI	`https://api.openai.com/v1`	直接 OpenAI 访问
Azure OpenAI	`https://YOUR.openai.azure.com/`	企业级 OpenAI
LocalAI	`http://localhost:8080/v1`	自托管，多模型
Jan	`http://localhost:1337/v1`	带本地模型的桌面应用

使用 hermes model → Custom endpoint 或在 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 Detection）

:::note 两个设置，容易混淆 context_length 是总上下文窗口——输入和输出 tokens 的合计预算（例如 Claude Opus 4.6 为 200,000）。Hermes 使用它来决定何时压缩历史记录以及验证 API 请求。

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

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

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

配置覆盖——model.context_length 在 config.yaml 中（最高优先级）
自定义提供商按模型设置——custom_providers[].models.<id>.context_length
持久缓存——先前发现的值（跨重启存活）
端点 /models——查询您服务器的 API（本地/自定义端点）
Anthropic /v1/models——查询 Anthropic 的 API 以获取 max_input_tokens（仅 API 密钥用户）
OpenRouter API——来自 OpenRouter 的实时模型元数据
Nous Portal——后缀将 Nous 模型 ID 与 OpenRouter 元数据匹配
models.dev——社区维护的注册表，包含 100+ 提供商、3800+ 模型的提供商特定上下文长度
回退默认值——广泛的模型家族模式（默认 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: 32768
      deepseek-r1:70b:
        context_length: 65536

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

:::tip 何时手动设置

您正在使用 Ollama，且自定义 num_ctx 低于模型的最大值
您想要将上下文限制在模型最大值以下（例如在 128k 模型上使用 8k 以节省 VRAM）
您在未暴露 /v1/models 的代理后面运行 :::

命名自定义提供商（Named Custom Providers）

如果您使用多个自定义端点（例如本地开发服务器和远程 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` → Custom Endpoint 向导显式设置；自动检测仍作为回退发生
  - 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 → Custom Endpoint 向导现在会显式提示 api_mode 并将您的答案持久化到 config.yaml。基于 URL 的自动检测（例如 /anthropic 路径 → anthropic_messages）在字段留空时仍会作为回退发生。

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

/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

托管开放权重模型（Llama、MiniMax、Gemma、DeepSeek、Qwen），价格显著低于第一方 API。多模型集群的良好默认选择。

# ~/.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；之后自由切换

:::tip 故障排除

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

选择正确的设置

使用场景	推荐
只想让它工作	OpenRouter（默认）或 Nous Portal
本地模型，简单设置	Ollama
生产级 GPU 服务	vLLM 或 SGLang
Mac / 无 GPU	Ollama 或 llama.cpp
多提供商路由	LiteLLM Proxy 或 OpenRouter
成本优化	ClawRouter 或 OpenRouter 配合 `sort: "price"`
最大隐私	Ollama、vLLM 或 llama.cpp（完全本地）
企业 / Azure	带自定义端点的 Azure OpenAI
中国 AI 模型	z.ai（GLM）、Kimi/Moonshot（`kimi-coding` 或 `kimi-coding-cn`）、MiniMax、小米 MiMo 或腾讯 TokenHub（一等提供商）

:::tip 您可以随时使用 hermes model 在提供商之间切换——无需重启。无论您使用哪个提供商，您的对话历史、记忆和技能都会保持不变。 :::

可选 API 密钥（Optional API Keys）

功能	提供商	环境变量
网页抓取	Firecrawl	`FIRECRAWL_API_KEY`、`FIRECRAWL_API_URL`
浏览器自动化	Browserbase	`BROWSERBASE_API_KEY`、`BROWSERBASE_PROJECT_ID`
图像生成	FAL	`FAL_KEY`
高级 TTS 语音	ElevenLabs	`ELEVENLABS_API_KEY`
OpenAI TTS + 语音转录	OpenAI	`VOICE_TOOLS_OPENAI_KEY`
Mistral TTS + 语音转录	Mistral	`MISTRAL_API_KEY`
跨会话用户建模	Honcho	`HONCHO_API_KEY`
语义长期记忆	Supermemory	`SUPERMEMORY_API_KEY`

自托管 Firecrawl

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

优点： 无需 API 密钥，无速率限制，无按页成本，完全的数据主权。

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

设置：

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

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

将 Hermes 指向您的实例（无需 API 密钥）：

hermes config set FIRECRAWL_API_URL http://localhost:3002

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

OpenRouter 提供商路由（Provider Routing）

使用 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 Router 文档了解路由器的完整行为。
要为特定的辅助任务（压缩、视觉等）而不是主智能体使用 Pareto Code 路由器，请在该任务下设置 extra_body.plugins——参见辅助模型 → OpenRouter 路由与辅助任务的 Pareto Code。

回退提供商（Fallback Providers）

配置一个后备提供商链，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、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、ai-gateway、azure-foundry、opencode-zen、opencode-go、kilocode、xiaomi、arcee、gmi、stepfun、lmstudio、alibaba、alibaba-coding-plan、tencent-tokenhub、custom。

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

参见（See Also）

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

好奇心花园🪴

探索

最近的笔记

note-template

getMoon.js

getWeather.js

AI 提供商

AI 提供商（AI Providers）

推理提供商（Inference Providers）

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

模型管理的两个命令

Nous Portal

令牌处理

Anthropic（原生）

GitHub Copilot

一等 API 密钥提供商（First-Class API-Key Providers）

xAI（Grok）— Responses API + 提示缓存（Prompt Caching）

NovitaAI

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

AWS Bedrock

Qwen Portal（OAuth）

阿里云（编码计划/Coding Plan）

MiniMax（OAuth）

NVIDIA NIM

GMI Cloud

StepFun

Hugging Face 推理提供商（Hugging Face Inference Providers）

自定义与自托管 LLM 提供商（Custom & Self-Hosted LLM Providers）

通用设置

使用 /model 切换模型

Ollama — 本地模型，零配置

vLLM — 高性能 GPU 推理

SGLang — 使用 RadixAttention 的快速服务

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

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

WSL2 网络（Windows 用户）

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

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

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

Windows 防火墙

快速验证

本地模型故障排除

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

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

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

启动时显示”Context limit: 2048 tokens”

响应在句子中间被截断

LiteLLM 代理——多提供商网关

ClawRouter——成本优化路由

其他兼容提供商

上下文长度检测（Context Length Detection）

命名自定义提供商（Named Custom Providers）

食谱：Together AI、Groq、Perplexity

Together AI

Groq

Perplexity

一个配置中的多个提供商

选择正确的设置

可选 API 密钥（Optional API Keys）

自托管 Firecrawl

OpenRouter 提供商路由（Provider Routing）

OpenRouter Pareto Code 路由器

回退提供商（Fallback Providers）

参见（See Also）

关系图谱

目录

反向链接

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

使用 `/model` 切换模型