跳到主要内容

AI 提供商

本页介绍如何为 Hermes Agent 配置推理提供商——从 OpenRouter、Anthropic 等云端 API，到 Ollama、vLLM 等自托管端点，再到高级路由和故障转移配置。使用 Hermes 至少需要配置一个提供商。

推理提供商​

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

提供商配置方式
Nous Portalhermes model（OAuth，订阅制）
OpenAI Codexhermes model（ChatGPT OAuth，使用 Codex 模型）
GitHub Copilothermes model（OAuth 设备码流程，COPILOT_GITHUB_TOKEN、GH_TOKEN 或 gh auth token）
GitHub Copilot ACPhermes model（启动本地 copilot --acp --stdio）
Anthropichermes model（通过 OAuth 使用 Claude Max + 额外用量额度；也支持 Anthropic API 密钥或手动 setup-token——详见下方说明）
OpenRouter在 ~/.hermes/.env 中设置 OPENROUTER_API_KEY
NovitaAI在 ~/.hermes/.env 中设置 NOVITA_API_KEY（提供商：novita，200+ 模型，Model API，Agent Sandbox，GPU Cloud）
AI Gateway在 ~/.hermes/.env 中设置 AI_GATEWAY_API_KEY（提供商：ai-gateway）
z.ai / GLM在 ~/.hermes/.env 中设置 GLM_API_KEY（提供商：zai）
Kimi / Moonshot在 ~/.hermes/.env 中设置 KIMI_API_KEY（提供商：kimi-coding）
Kimi / Moonshot（中国）在 ~/.hermes/.env 中设置 KIMI_CN_API_KEY（提供商：kimi-coding-cn；别名：kimi-cn、moonshot-cn）
Arcee AI在 ~/.hermes/.env 中设置 ARCEEAI_API_KEY（提供商：arcee；别名：arcee-ai、arceeai）
GMI Cloud在 ~/.hermes/.env 中设置 GMI_API_KEY（提供商：gmi；别名：gmi-cloud、gmicloud）
MiniMax在 ~/.hermes/.env 中设置 MINIMAX_API_KEY（提供商：minimax）
MiniMax 中国在 ~/.hermes/.env 中设置 MINIMAX_CN_API_KEY（提供商：minimax-cn）
阿里云在 ~/.hermes/.env 中设置 DASHSCOPE_API_KEY（提供商：alibaba）
阿里云编码计划DASHSCOPE_API_KEY（提供商：alibaba-coding-plan，别名：alibaba_coding）——独立计费 SKU，不同端点
Kilo Code在 ~/.hermes/.env 中设置 KILOCODE_API_KEY（提供商：kilocode）
小米 MiMo在 ~/.hermes/.env 中设置 XIAOMI_API_KEY（提供商：xiaomi，别名：mimo、xiaomi-mimo）
腾讯 TokenHub在 ~/.hermes/.env 中设置 TOKENHUB_API_KEY（提供商：tencent-tokenhub，别名：tencent、tokenhub、tencentmaas）
OpenCode Zen在 ~/.hermes/.env 中设置 OPENCODE_ZEN_API_KEY（提供商：opencode-zen）
OpenCode Go在 ~/.hermes/.env 中设置 OPENCODE_GO_API_KEY（提供商：opencode-go）
DeepSeek在 ~/.hermes/.env 中设置 DEEPSEEK_API_KEY（提供商：deepseek）
Hugging Face在 ~/.hermes/.env 中设置 HF_TOKEN（提供商：huggingface，别名：hf）
Google / Gemini在 ~/.hermes/.env 中设置 GOOGLE_API_KEY（或 GEMINI_API_KEY）（提供商：gemini）
Google Gemini（OAuth）hermes model → "Google Gemini (OAuth)"（提供商：google-gemini-cli，支持免费层级，浏览器 PKCE 登录）
LM Studiohermes model → "LM Studio"（提供商：lmstudio，可选 LM_API_KEY）
自定义端点hermes model → 选择"自定义端点"（保存在 config.yaml 中）

官方 API 密钥路径请参阅专属的 Google Gemini 指南。

模型键别名

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

Google Gemini via 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（权限 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%
政策风险

Google 认为将 Gemini CLI OAuth 客户端用于第三方软件违反政策。部分用户报告账号受到限制。为降低风险，建议通过 gemini 提供商使用你自己的 API 密钥。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。

Codex 注意事项

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

注意

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

Nous 工具网关

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

模型管理的两个命令​

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

命令运行位置作用
hermes model终端（任何会话之外）完整的设置向导——添加提供商、运行 OAuth、输入 API 密钥、配置端点
/model在 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 定价，与任何 Claude 订阅无关）。

# 使用 API 密钥（按使用量付费）
export ANTHROPIC_API_KEY=***
hermes chat --provider anthropic --model claude-sonnet-4-6

# 推荐：通过 `hermes model` 进行认证
# 有 Claude Code 凭据时，Hermes 会直接使用其凭据存储
hermes model

# 使用 setup-token 手动覆盖（回退/旧版方式）
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"
别名

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

GitHub Copilot​

Hermes 以一等提供商身份支持 GitHub Copilot，提供两种模式：

copilot — 直连 Copilot API（推荐）。通过你的 GitHub Copilot 订阅访问 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 登录
细粒度 PATgithub_pat_GitHub 设置 → 开发者设置 → 细粒度令牌（需要 Copilot Requests 权限）
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 Agent 后端。将本地 Copilot CLI 作为子进程启动：

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

永久配置：

model:
  provider: "copilot"
  default: "gpt-5.4"
环境变量描述
COPILOT_GITHUB_TOKENCopilot API 的 GitHub 令牌（最高优先级）
HERMES_COPILOT_ACP_COMMAND覆盖 Copilot CLI 二进制路径（默认：copilot）
HERMES_COPILOT_ACP_ARGS覆盖 ACP 参数（默认：--acp --stdio）

一等 API 密钥提供商​

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

# NovitaAI Model API
hermes chat --provider novita --model moonshotai/kimi-k2.5
# 需要：在 ~/.hermes/.env 中设置 NOVITA_API_KEY

# z.ai / ZhipuAI GLM
hermes chat --provider zai --model glm-5
# 需要：在 ~/.hermes/.env 中设置 GLM_API_KEY

# Kimi / Moonshot AI（国际版：api.moonshot.ai）
hermes chat --provider kimi-coding --model kimi-for-coding
# 需要：在 ~/.hermes/.env 中设置 KIMI_API_KEY

# Kimi / Moonshot AI（中国版：api.moonshot.cn）
hermes chat --provider kimi-coding-cn --model kimi-k2.5
# 需要：在 ~/.hermes/.env 中设置 KIMI_CN_API_KEY

# MiniMax（全球端点）
hermes chat --provider minimax --model MiniMax-M2.7
# 需要：在 ~/.hermes/.env 中设置 MINIMAX_API_KEY

# MiniMax（中国端点）
hermes chat --provider minimax-cn --model MiniMax-M2.7
# 需要：在 ~/.hermes/.env 中设置 MINIMAX_CN_API_KEY

# 阿里云 / DashScope（Qwen 模型）
hermes chat --provider alibaba --model qwen3.5-plus
# 需要：在 ~/.hermes/.env 中设置 DASHSCOPE_API_KEY

# 小米 MiMo
hermes chat --provider xiaomi --model mimo-v2-pro
# 需要：在 ~/.hermes/.env 中设置 XIAOMI_API_KEY

# 腾讯 TokenHub（Hy3 Preview）
hermes chat --provider tencent-tokenhub --model hy3-preview
# 需要：在 ~/.hermes/.env 中设置 TOKENHUB_API_KEY

# Arcee AI（Trinity 模型）
hermes chat --provider arcee --model trinity-large-thinking
# 需要：在 ~/.hermes/.env 中设置 ARCEEAI_API_KEY

# GMI Cloud
# 使用 GMI 的 /v1/models 端点返回的精确模型 ID。
hermes chat --provider gmi --model zai-org/GLM-5.1-FP8
# 需要：在 ~/.hermes/.env 中设置 GMI_API_KEY

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

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

基础 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 环境变量覆盖。

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-1-fast-reasoning。

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

无需配置——检测到 xAI 端点且存在会话 ID 时缓存自动激活。这可以降低多轮对话的延迟和成本。

xAI 还提供专属 TTS 端点（/v1/tts）。在 hermes tools → 语音与 TTS 中选择 xAI TTS，或参阅语音与 TTS 页面进行配置。

NovitaAI​

NovitaAI 是面向构建者和 Agent 的 AI 原生云端平台。其三条产品线分别是：200+ 模型的 Model API、构建和运行 AI Agent 的 Agent Sandbox，以及可扩展计算的 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）在规范化过程中会保留——不要使用连字符。

Ollama Cloud 与本地 Ollama

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

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）​

通过浏览器 OAuth 登录使用阿里巴巴的 Qwen Portal。在 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 与 DashScope（阿里云）

qwen-oauth 使用面向消费者的 Qwen Portal 进行 OAuth 登录——适合个人用户。alibaba 提供商使用 DashScope 企业 API，需要 DASHSCOPE_API_KEY——适合程序化/生产工作负载。两者都路由到 Qwen 系列模型，但端点不同。

阿里云编码计划​

如果你订阅了阿里巴巴的编码计划（与标准 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）​

通过浏览器 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
# 需要：在 ~/.hermes/.env 中设置 NVIDIA_API_KEY

# 本地 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"
本地 NIM

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

GMI Cloud​

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

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

或在 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
# 需要：在 ~/.hermes/.env 中设置 STEPFUN_API_KEY

或在 config.yaml 中永久设置：

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

base URL 可通过 STEPFUN_BASE_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-235B-A22B-Thinking-2507
# 需要：在 ~/.hermes/.env 中设置 HF_TOKEN

# 简短别名
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 提供商​

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

通用配置​

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

交互式设置（推荐）：

hermes model
# 选择"自定义端点（自托管 / VLLM 等）"
# 输入：API base 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 中的 OPENAI_BASE_URL 和 LLM_MODEL 已移除。Hermes 的任何部分都不再读取它们——config.yaml 是模型和端点配置的唯一真实来源。如果你的 .env 中有过时条目，下次运行 hermes setup 或配置迁移时会自动清除。请使用 hermes model 或直接编辑 config.yaml。

两种方式都会持久化到 config.yaml，这是模型、提供商和 base 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 会将 base URL 和提供商持久化到配置中，重启后仍然生效。从自定义端点切换回内置提供商时，过时的 base URL 会自动清除。

提示

/model custom（不带模型名称）会查询端点的 /models API，如果只加载了一个模型则自动选择。适用于运行单个模型的本地服务器。

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

Ollama——本地模型，零配置​

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

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

然后配置 Hermes：

hermes model
# 选择"自定义端点（自托管 / VLLM 等）"
# 输入 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: 32768   # 参见下方警告
Ollama 默认上下文长度极小

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

可用显存默认上下文
小于 24 GB4,096 个 token
24–48 GB32,768 个 token
48+ GB256,000 个 token

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

增加上下文的方法（选其一）：

# 方案一：通过环境变量设置服务器全局配置（推荐）
OLLAMA_CONTEXT_LENGTH=32768 ollama serve

# 方案二：对于 systemd 管理的 Ollama
sudo systemctl edit ollama.service
# 添加：Environment="OLLAMA_CONTEXT_LENGTH=32768"
# 然后：sudo systemctl daemon-reload && sudo systemctl restart ollama

# 方案三：烘焙到自定义模型（每模型持久化）
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 列——应该显示你配置的值
提示

使用 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
# 选择"自定义端点（自托管 / VLLM 等）"
# 输入 URL: http://localhost:8000/v1
# 跳过 API 密钥（或如果配置了 --api-key 则输入）
# 输入模型名称: meta-llama/Llama-3.1-70B-Instruct

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

工具调用需要显式标志：

标志用途
--enable-auto-tool-choicetool_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。没有这些标志，工具调用将作为文本输出。

提示

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
# 选择"自定义端点（自托管 / VLLM 等）"
# 输入 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 默认最多 128 个输出 token

如果响应似乎被截断，请在请求中添加 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 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 显式设置为你需要的值（Agent 使用建议 32k–64k）。如果使用并行槽（-np），总上下文在槽位间分配——-c 32768 -np 4 时每个槽位只有 8k。

然后配置 Hermes 指向它：

hermes model
# 选择"自定义端点（自托管 / VLLM 等）"
# 输入 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 32768

然后配置 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 按预期工作——它们共享同一个网络命名空间。跳过此节。

方案一：镜像网络模式（推荐）​

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

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

    [wsl2]
    networkingMode=mirrored

  2. 从 PowerShell 重启 WSL：

    wsl --shutdown

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

    curl http://localhost:11434/v1/models   # Windows 上的 Ollama——有效
Hyper-V 防火墙

在某些 Windows 11 版本上，Hyper-V 防火墙默认阻止镜像连接。如果启用镜像模式后 localhost 仍然无效，在管理员 PowerShell 中运行：

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

方案二：使用 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
动态辅助工具

WSL2 重启后主机 IP 可能改变。可以在 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 模式必需）​

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

服务器默认绑定修复方法
Ollama127.0.0.1在启动 Ollama 前设置 OLLAMA_HOST=0.0.0.0 环境变量（在 Windows 上：系统设置 → 环境变量，或编辑 Ollama 服务）
LM Studio127.0.0.1在开发者标签页 → 服务器设置中启用**"在网络上提供服务"**
llama-server127.0.0.1在启动命令中添加 --host 0.0.0.0
vLLM0.0.0.0默认已绑定到所有接口
SGLang127.0.0.1在启动命令中添加 --host 0.0.0.0

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 托管模型服务器的"连接被拒绝"​

如果你在 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 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

修复： 将上下文设置为 Agent 使用的至少 32,768 个 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: 32768

响应在句子中间被截断​

可能原因：

  1. 服务器上输出上限（max_tokens）太低 — SGLang 默认每次响应 128 个 token。在服务器上设置 --default-max-tokens，或在 config.yaml 中配置 Hermes 的 model.max_tokens。注意：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。

路由配置文件：

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

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

其他兼容提供商​

任何具有 OpenAI 兼容 API 的服务均可使用。一些热门选项：

提供商Base URL说明
Together AIhttps://api.together.xyz/v1云托管开源模型
Groqhttps://api.groq.com/openai/v1超快速推理
DeepSeekhttps://api.deepseek.com/v1DeepSeek 模型
Fireworks AIhttps://api.fireworks.ai/inference/v1快速开源模型托管
GMI Cloudhttps://api.gmi-serving.com/v1托管的 OpenAI 兼容推理
Cerebrashttps://api.cerebras.ai/v1晶圆级芯片推理
Mistral AIhttps://api.mistral.ai/v1Mistral 模型
OpenAIhttps://api.openai.com/v1直连 OpenAI
Azure OpenAIhttps://YOUR.openai.azure.com/企业级 OpenAI
LocalAIhttp://localhost:8080/v1自托管，多模型
Janhttp://localhost:1337/v1带本地模型的桌面应用

使用 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 — 社区维护的注册表，包含 100+ 提供商的 3800+ 个模型的提供商特定上下文长度
  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  # token 数

对于自定义端点，也可以按模型设置上下文长度：

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 会提示输入上下文长度。留空则使用自动检测。

何时需要手动设置
  • 你使用的 Ollama 自定义 num_ctx 低于模型最大值
  • 你想将上下文限制在模型最大值以下（例如在 128k 模型上限制为 8k 以节省显存）
  • 你在不暴露 /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   # 可选，从 URL 自动检测
  - name: anthropic-proxy
    base_url: https://proxy.example.com/anthropic
    key_env: ANTHROPIC_PROXY_KEY
    api_mode: anthropic_messages  # 用于 Anthropic 兼容代理

在会话中使用三段式语法切换：

/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；之后可自由切换
故障排查
  • 在这些名称的 CLI 验证器修复（#15083）之后，hermes doctor 不应打印任何 Unknown provider 警告。
  • 如果某个提供商的 /v1/models 端点不可达（Perplexity 是常见情况），hermes model 会在警告后持久化模型而非直接拒绝——参见 #15136。
  • 如需完全跳过 custom_providers: 并使用带 CUSTOM_BASE_URL 环境变量的裸 provider: custom，参见 #15103。

选择合适的配置方案​

使用场景推荐方案
直接可用OpenRouter（默认）或 Nous Portal
本地模型，易于设置Ollama
生产 GPU 服务vLLM 或 SGLang
Mac / 无 GPUOllama 或 llama.cpp
多提供商路由LiteLLM 代理或 OpenRouter
成本优化ClawRouter 或带 sort: "price" 的 OpenRouter
最大隐私保护Ollama、vLLM 或 llama.cpp（完全本地）
企业级 / Azure带自定义端点的 Azure OpenAI
中国 AI 模型z.ai（GLM）、Kimi/Moonshot（kimi-coding 或 kimi-coding-cn）、MiniMax、小米 MiMo 或腾讯 TokenHub（一等提供商）
提示

随时可以用 hermes model 切换提供商——无需重启。无论使用哪个提供商，对话历史、记忆和技能都会保留。

可选 API 密钥​

功能提供商环境变量
网页抓取FirecrawlFIRECRAWL_API_KEY、FIRECRAWL_API_URL
浏览器自动化BrowserbaseBROWSERBASE_API_KEY、BROWSERBASE_PROJECT_ID
图像生成FALFAL_KEY
高级 TTS 语音ElevenLabsELEVENLABS_API_KEY
OpenAI TTS + 语音转录OpenAIVOICE_TOOLS_OPENAI_KEY
Mistral TTS + 语音转录MistralMISTRAL_API_KEY
跨会话用户建模HonchoHONCHO_API_KEY
语义长期记忆SupermemorySUPERMEMORY_API_KEY

自托管 Firecrawl​

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

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

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

配置步骤：

  1. 克隆并启动 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

  2. 将 Hermes 指向你的实例（无需 API 密钥）：

    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 编码路由器​

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 选择最强的可用编码模型 —— 这是省略 plugins 块时的已记录行为。
  • 选择在特定日期按分数是确定性的，但实际选择的模型会随着 Pareto 前沿的移动（新模型、基准更新）而转变。
  • 有关完整的路由器行为，请参阅 OpenRouter 的 Pareto 路由器文档。
  • 要对特定的辅助任务（压缩、视觉等）使用 Pareto 编码路由器，而不是主 Agent，请在那个任务下设置 extra_body.plugins —— 请参阅辅助模型 → OpenRouter 路由 & Pareto 编码辅助任务。

备用提供商​

配置一个备用提供商链，当主模型失败时（速率限制、服务器错误、认证失败），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、ollama-cloud、bedrock、ai-gateway、azure-foundry、opencode-zen、opencode-go、kilocode、xiaomi、arcee、gmi、stepfun、lmstudio、alibaba、alibaba-coding-plan、tencent-tokenhub、custom。

提示

备用模型仅通过 config.yaml 配置——或交互式通过 hermes fallback。触发条件、链如何推进以及与辅助任务和委派的交互方式，请参阅备用提供商。

另请参阅​

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