AI Providers

本页面涵盖为 Hermes Agent 配置推理提供商的方法——从 OpenRouter 和 Anthropic 等云 API，到 Ollama 和 vLLM 等自托管端点，再到高级路由和回退配置。使用 Hermes 至少需要配置一个提供商。

推理提供商

你至少需要一种连接 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 Pro/Max 通过 Claude Code 认证、Anthropic API 密钥或手动设置令牌）
OpenRouter	`~/.hermes/.env` 中的 `OPENROUTER_API_KEY`
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`）
MiniMax	`~/.hermes/.env` 中的 `MINIMAX_API_KEY`（提供商：`minimax`）
MiniMax 中国	`~/.hermes/.env` 中的 `MINIMAX_CN_API_KEY`（提供商：`minimax-cn`）
阿里云	`~/.hermes/.env` 中的 `DASHSCOPE_API_KEY`（提供商：`alibaba`，别名：`dashscope`、`qwen`）
Kilo Code	`~/.hermes/.env` 中的 `KILOCODE_API_KEY`（提供商：`kilocode`）
小米 MiMo	`~/.hermes/.env` 中的 `XIAOMI_API_KEY`（提供商：`xiaomi`，别名：`mimo`、`xiaomi-mimo`）
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`）
自定义端点	`hermes model` → 选择"自定义端点"（保存在 `config.yaml` 中）

模型密钥别名

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

Codex 注意事项

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

注意

即使使用 Nous Portal、Codex 或自定义端点，一些工具（视觉、Web 摘要、MoA）也会使用单独的"辅助"模型——默认情况下通过 OpenRouter 使用 Gemini Flash。OPENROUTER_API_KEY 会自动启用这些工具。你也可以配置这些工具使用的模型和提供商——请参阅辅助模型。

Anthropic（原生）

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

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

# 推荐：通过 `hermes model` 认证
# 当 Claude Code 凭证可用时，Hermes 会直接使用其凭证存储
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

认证选项（按优先级顺序）：

COPILOT_GITHUB_TOKEN 环境变量
GH_TOKEN 环境变量
GITHUB_TOKEN 环境变量
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 Requests 权限）
GitHub App 令牌	`ghu_`	通过 GitHub App 安装

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

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
# 需要 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`）

一类中国 AI 提供商

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

# z.ai / 智谱 AI 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（通义千问模型）
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

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

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

model:
  provider: "zai"       # 或：kimi-coding、kimi-coding-cn、minimax、minimax-cn、alibaba、xiaomi、arcee
  default: "glm-5"

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

Z.AI 端点自动检测

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

xAI (Grok) 提示缓存

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

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

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 以强制使用特定后端。

基础 URL 可以用 HF_BASE_URL 覆盖。

自定义和自托管 LLM 提供商

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

基本设置

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

交互式设置（推荐）：

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

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

使用 `/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
# 选择"自定义端点（自托管 / 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 不使用你模型的完整上下文窗口。默认情况下取决于你的 VRAM：

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

对于使用工具的 agent，你需要至少 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 列 —— 应显示你配置的值

提示

用 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 配置了 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。没有这些标志，工具调用将不起作用 —— 模型会将工具调用作为文本输出。

提示

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 最大输出 tokens

如果响应被截断，请在请求中添加 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 是 agent 使用的良好范围）。如果使用并行槽（-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 不会将其识别为工具调用 —— 你会看到原始 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 字段应该存在。

提示

从 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
# 选择"自定义端点（自托管 / VLLM / 等）"
# 输入 URL：http://localhost:1234/v1
# 跳过 API 密钥（LM Studio 不需要）
# 输入模型名称

上下文长度通常默认为 2048

LM Studio 从模型元数据中读取上下文长度，但许多 GGUF 模型报告较低的默认值（2048 或 4096）。始终在 LM Studio 模型设置中明确设置上下文长度：

点击模型选择器旁边的齿轮图标
将"上下文长度"设置为至少 16384（最好 32768）
重新加载模型以使更改生效

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

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

工具调用： 自 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 主机。

两者都在 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 — 可用

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

动态助手

主机 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 上监听 —— WSL2 在 NAT 模式下从不同的虚拟子网连接，将被拒绝。在镜像模式下，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 响应，就一切正常。将相同的 URL 作为 base_url 用于 Hermes 配置。

本地模型故障排除

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

从 WSL2 到 Windows 托管的模型服务器"连接被拒绝"

如果你在 WSL2 内运行 Hermes 而模型服务器在 Windows 主机上，http://localhost:<port> 在 WSL2 的默认 NAT 网络模式下不起作用。见上文 WSL2 网络的修复方法。

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

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

原因： 你的服务器没有启用工具调用，或者模型不支持服务器的 tool calling 实现。

服务器	修复
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 用于 agent 使用。见上文每个服务器部分的特定标志。

启动时"上下文限制：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。注意：max_tokens 仅控制响应长度 —— 与会话历史可以多长无关（那是 context_length）。
上下文耗尽 —— 模型填满了其上下文窗口。增加 model.context_length 或在 Hermes 中启用上下文压缩。

LiteLLM Proxy — 多提供商网关

LiteLLM 是一个 OpenAI 兼容代理，在单个 API 后面统一 100+ LLM 提供商。最佳场景：在不更改配置的情况下在提供商之间切换、负载均衡、回退链、预算控制。

# 安装并启动
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`	针对工具使用优化	varies

备注

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

其他兼容提供商

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

提供商	基础 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`	快速开放模型托管
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 → 自定义端点或 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 是总上下文窗口 —— 输入和输出 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 使用多源解析链来检测你模型和提供商的正确上下文窗口：

配置覆盖 —— config.yaml 中的 model.context_length（最高优先级）
自定义提供商每模型 —— custom_providers[].models.<id>.context_length
持久缓存 —— 之前发现的 values（重启后保留）
端点 /models —— 查询你服务器的 API（本地/自定义端点）
Anthropic /v1/models —— 为 API 密钥用户查询 max_input_tokens
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 会提示输入上下文长度。留空以进行自动检测。

何时手动设置

你正在使用自定义 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
    api_key: corp-api-key
    api_mode: chat_completions   # 可选，从 URL 自动检测
  - name: anthropic-proxy
    base_url: https://proxy.example.com/anthropic
    api_key: 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 菜单中选择命名的自定义提供商。

选择正确的设置

使用场景	推荐
只想让它工作	OpenRouter（默认）或 Nous Portal
本地模型，简单设置	Ollama
生产 GPU 服务	vLLM 或 SGLang
Mac / 无 GPU	Ollama 或 llama.cpp
多提供商路由	LiteLLM Proxy 或 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（一类提供商）

提示

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

可选 API 密钥

功能	提供商	环境变量
Web 抓取	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`
RL 训练	Tinker + WandB	`TINKER_API_KEY`、`WANDB_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 提供商路由

使用 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 以获得价格排序。

回退模型

配置一个备份 provider:model，当你的主模型失败时（速率限制、服务器错误、认证失败）Hermes 自动切换到：

fallback_model:
  provider: openrouter                    # 必需
  model: anthropic/claude-sonnet-4        # 必需
  # base_url: http://localhost:8000/v1    # 可选，用于自定义端点
  # api_key_env: MY_CUSTOM_KEY           # 可选，自定义端点 API 密钥的环境变量名

激活时，回退在会话中切换模型和提供商而不丢失会话。它在每个会话中最多触发一次。

支持的提供商：openrouter、nous、openai-codex、copilot、copilot-acp、anthropic、huggingface、zai、kimi-coding、kimi-coding-cn、minimax、minimax-cn、deepseek、ai-gateway、opencode-zen、opencode-go、kilocode、xiaomi、arcee、alibaba、custom。

提示

回退仅通过 config.yaml 配置 —— 没有用于它的环境变量。有关其触发时机、支持提供商以及如何与辅助任务和委托交互的完整详情，请参阅回退提供商。

智能模型路由

可选的便宜 vs 强力路由让 Hermes 将主模型保留用于复杂工作，同时将非常短/简单的轮次发送到更便宜的模型。

smart_model_routing:
  enabled: true
  max_simple_chars: 160
  max_simple_words: 28
  cheap_model:
    provider: openrouter
    model: google/gemini-2.5-flash
    # base_url: http://localhost:8000/v1  # 可选自定义端点
    # api_key_env: MY_CUSTOM_KEY          # 可选，该端点 API 密钥的环境变量名

工作原理：

如果一轮对话很短、单一且看起来不像代码/工具/调试密集型，Hermes 可能将其路由到 cheap_model
如果轮次看起来复杂，Hermes 留在主模型/提供商上
如果廉价路由无法干净地解析，Hermes 自动回退到主模型

这是有意保守的。它适用于快速、低风险的轮次，例如：

简短的实事问题
快速重写
轻量级摘要

它会避免路由看起来像这样的提示：

编码/调试工作
工具密集型请求
长的或多行的分析请求

当你想要更低的延迟或成本而又不想完全更改默认模型时使用此功能。

另请参阅

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

推理提供商​

Anthropic（原生）​

GitHub Copilot​

一类中国 AI 提供商​

xAI (Grok) 提示缓存​

Hugging Face 推理提供商​

自定义和自托管 LLM 提供商​

基本设置​

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

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

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

启动时"上下文限制：2048 tokens"​

响应在句子中间被截断​

LiteLLM Proxy — 多提供商网关​

ClawRouter — 成本优化路由​

其他兼容提供商​

上下文长度检测​

命名的自定义提供商​

选择正确的设置​

可选 API 密钥​

自托管 Firecrawl​

OpenRouter 提供商路由​

回退模型​

智能模型路由​

另请参阅​

推理提供商

Anthropic（原生）

GitHub Copilot

一类中国 AI 提供商

xAI (Grok) 提示缓存

Hugging Face 推理提供商

自定义和自托管 LLM 提供商

基本设置

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

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

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

启动时"上下文限制：2048 tokens"

响应在句子中间被截断

LiteLLM Proxy — 多提供商网关

ClawRouter — 成本优化路由

其他兼容提供商

上下文长度检测

命名的自定义提供商

选择正确的设置

可选 API 密钥

自托管 Firecrawl

OpenRouter 提供商路由

回退模型

智能模型路由

另请参阅