跳到主要内容

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（通过 Claude Code 认证使用 Claude Pro/Max，或 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）
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）
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 或自定义端点，某些工具（如视觉、网页摘要、MoA）仍会使用一个独立的“辅助”模型——默认通过 OpenRouter 使用 Gemini Flash。设置 OPENROUTER_API_KEY 可自动启用这些工具。您也可以配置这些工具使用的模型和提供商——详见 辅助模型。

Anthropic（原生）​

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

# With an API key (pay-per-token)
export ANTHROPIC_API_KEY=***
hermes chat --provider anthropic --model claude-sonnet-4-6

# Preferred: authenticate through `hermes model`
# Hermes will use Claude Code's credential store directly when available
hermes model

# Manual override with a setup-token (fallback / legacy)
export ANTHROPIC_TOKEN=***  # setup-token or manual OAuth token
hermes chat --provider anthropic

# Auto-detect Claude Code credentials (if you already use Claude Code)
hermes chat --provider anthropic  # reads Claude Code credential files automatically

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

或永久设置：

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

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

GitHub Copilot​

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

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

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

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

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

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

令牌类型

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

类型前缀获取方式
OAuth 令牌gho_hermes model → GitHub Copilot → 使用 GitHub 登录
细粒度 PATgithub_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 代理后端。作为子进程启动本地 Copilot CLI：

hermes chat --provider copilot-acp --model copilot-acp
# Requires the GitHub Copilot CLI in PATH and an existing `copilot login` session

永久配置：

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）

一级中文 AI 服务商​

这些服务商已内置支持，并拥有专用的提供者 ID。设置 API 密钥后，使用 --provider 选择：

# z.ai / ZhipuAI GLM
hermes chat --provider zai --model glm-5
# Requires: GLM_API_KEY in ~/.hermes/.env

# Kimi / Moonshot AI
hermes chat --provider kimi-coding --model kimi-for-coding
# Requires: KIMI_API_KEY in ~/.hermes/.env

# MiniMax (global endpoint)
hermes chat --provider minimax --model MiniMax-M2.7
# Requires: MINIMAX_API_KEY in ~/.hermes/.env

# MiniMax (China endpoint)
hermes chat --provider minimax-cn --model MiniMax-M2.7
# Requires: MINIMAX_CN_API_KEY in ~/.hermes/.env

# Alibaba Cloud / DashScope (Qwen models)
hermes chat --provider alibaba --model qwen3.5-plus
# Requires: DASHSCOPE_API_KEY in ~/.hermes/.env

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

model:
  provider: "zai"       # or: kimi-coding, minimax, minimax-cn, alibaba
  default: "glm-5"

可通过 GLM_BASE_URL、KIMI_BASE_URL、MINIMAX_BASE_URL、MINIMAX_CN_BASE_URL 或 DASHSCOPE_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 等），并支持自动故障转移。

# Use any available model
hermes chat --provider huggingface --model Qwen/Qwen3-235B-A22B-Thinking-2507
# Requires: HF_TOKEN in ~/.hermes/.env

# Short alias
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 获取你的令牌 —— 确保启用“对推理提供者发起调用”权限。免费套餐包含（每月 $0.10 信用额度，提供方费率无加价）。

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

基础 URL 可通过 HF_BASE_URL 覆盖。

自定义与自托管 LLM 提供者​

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

通用设置​

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

交互式设置（推荐）：

hermes model
# Select "Custom endpoint (self-hosted / VLLM / etc.)"
# Enter: API base URL, API key, Model name

手动配置（config.yaml）：

# In ~/.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          # Switch to a model on your custom endpoint
/model custom                    # Auto-detect the model from the endpoint
/model openrouter:claude-sonnet-4 # Switch back to a cloud provider

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

/model custom:local:qwen-2.5    # Use the "local" custom provider with model qwen-2.5
/model custom:work:llama3       # Use the "work" custom provider with llama3

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

提示

/model custom（无模型名称）会查询你的端点的 /models API，并在仅加载一个模型时自动选择该模型。适用于运行单个模型的本地服务器。

以下所有操作均遵循相同模式 —— 只需更改 URL、密钥和模型名称即可。

Ollama — 本地模型，零配置​

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

# Install and run a model
ollama pull qwen2.5-coder:32b
ollama serve   # Starts on port 11434

然后配置 Hermes：

hermes model
# Select "Custom endpoint (self-hosted / VLLM / etc.)"
# Enter URL: http://localhost:11434/v1
# Skip API key (Ollama doesn't need one)
# Enter model name (e.g. qwen2.5-coder:32b)

或直接配置 config.yaml：

model:
  default: qwen2.5-coder:32b
  provider: custom
  base_url: http://localhost:11434/v1
  context_length: 32768   # See warning below
Ollama 默认上下文长度极低

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

可用显存默认上下文
少于 24 GB4,096 个 token
24–48 GB32,768 个 token
48 GB 以上256,000 个 token

对于需要工具调用的代理使用，至少需要 16k–32k 的上下文。在 4k 时，系统提示 + 工具模式本身可能就填满窗口，导致没有空间用于对话。

如何增加上下文长度（任选其一）：

# Option 1: Set server-wide via environment variable (recommended)
OLLAMA_CONTEXT_LENGTH=32768 ollama serve

# Option 2: For systemd-managed Ollama
sudo systemctl edit ollama.service
# Add: Environment="OLLAMA_CONTEXT_LENGTH=32768"
# Then: sudo systemctl daemon-reload && sudo systemctl restart ollama

# Option 3: Bake it into a custom model (persistent per-model)
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
# Look at the CONTEXT column — it should show your configured value
提示

使用 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
# Select "Custom endpoint (self-hosted / VLLM / etc.)"
# Enter URL: http://localhost:8000/v1
# Skip API key (or enter one if you configured vLLM with --api-key)
# Enter model name: 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）可进一步压缩上下文以节省显存。

工具调用需要显式启用标志：

标志用途
--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
# Select "Custom endpoint (self-hosted / VLLM / etc.)"
# Enter URL: http://localhost:30000/v1
# Enter model name: meta-llama/Llama-3.1-70B-Instruct

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

工具调用：使用 --tool-call-parser 并配合对应模型家族的解析器：qwen（Qwen 2.5）、llama3、llama4、deepseekv3、mistral、glm。缺少此标志时，工具调用将以纯文本形式返回。

SGLang 默认最大输出 token 数为 128

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

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

llama.cpp 可在 CPU、Apple Silicon（Metal）和消费级 GPU 上运行量化模型。适用于：无需数据中心 GPU 运行模型、Mac 用户、边缘部署。

# Build and start 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 的模型，这可能导致内存溢出（OOM），因尝试分配完整的 KV 缓存。请显式设置 -c 为所需值（32k–64k 是代理使用的好范围）。若使用并行槽位（-np），总上下文将分配给各槽位——例如 -c 32768 -np 4 时，每个槽位仅获得 8k。

然后配置 Hermes 指向它：

hermes model
# Select "Custom endpoint (self-hosted / VLLM / etc.)"
# Enter URL: http://localhost:8080/v1
# Skip API key (local servers don't need one)
# Enter model name — or leave blank to auto-detect if only one model is loaded

这会将端点保存至 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 是一款带有图形界面的桌面应用程序，用于运行本地模型。适用于：偏好可视化界面的用户、快速测试模型、macOS/Windows/Linux 上的开发者。

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

lms server start                        # Starts on port 1234
lms load qwen2.5-coder --context-length 32768

然后配置 Hermes：

hermes model
# Select "Custom endpoint (self-hosted / VLLM / etc.)"
# Enter URL: http://localhost:1234/v1
# Skip API key (LM Studio doesn't require one)
# Enter model name
上下文长度默认值通常为 2048

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

  1. 点击模型选择器旁边的齿轮图标
  2. 将“上下文长度”设置为至少 16384（建议设置为 32768）
  3. 重新加载模型以使更改生效

或者使用命令行：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 虚拟机，而非 Windows 主机。

两者都在 WSL2？没问题。

如果模型服务器也运行在 WSL2 中（如 vLLM、SGLang 和 llama-server 常见情况），localhost 可正常工作——它们共享同一网络命名空间。可跳过本节。

适用于 Windows 11 22H2 及以上版本，镜像模式可实现 Windows 与 WSL2 之间的双向 localhost 通信——最简单的解决方案。

  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   # Ollama on Windows — works
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，并使用该 IP 替代 localhost：

# Get the Windows host IP (the default gateway of WSL2's virtual network)
ip route show | grep -i default | awk '{ print $3 }'
# Example output: 172.29.192.1

在 Hermes 配置中使用该 IP：

model:
  default: qwen2.5-coder:32b
  provider: custom
  base_url: http://172.29.192.1:11434/v1   # Windows host IP, not 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   # Test 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——在 NAT 模式下，WSL2 的连接来自不同的虚拟子网，将被拒绝。在镜像模式下，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 模式还是镜像模式下）。如果在完成上述步骤后连接仍失败，请为模型服务器的端口添加防火墙规则：

# Run in Admin PowerShell — replace PORT with your server's 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 内部测试是否可以访问你的模型服务器：

# Replace URL with your server's address and port
curl http://localhost:11434/v1/models          # Mirrored mode
curl http://172.29.192.1:11434/v1/models       # NAT mode (use your actual host IP)

如果返回包含模型列表的 JSON 响应，则说明配置正确。请将此 URL 用作 Hermes 配置中的 base_url。

本地模型故障排除​

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

“连接被拒绝”：从 WSL2 访问运行在 Windows 主机上的模型服务器​

如果你在 WSL2 中运行 Hermes，而模型服务器在 Windows 主机上，WSL2 默认的 NAT 网络模式下 http://localhost:<port> 将无法工作。请参阅上方的 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。

诊断：

# Check what Hermes thinks the context is
# Look at startup line: "Context limit: X tokens"

# Check your server's actual context
# Ollama: ollama ps (CONTEXT column)
# llama.cpp: curl http://localhost:8080/props | jq '.default_generation_settings.n_ctx'
# vLLM: check --max-model-len in startup args

修复： 为代理使用至少 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 中通过 model.max_tokens 配置 Hermes。注意：max_tokens 仅控制响应长度，与对话历史长度无关（后者由 context_length 控制）。
  2. 上下文耗尽 —— 模型已填满其上下文窗口。请增加 model.context_length 或在 Hermes 中启用 上下文压缩。

LiteLLM 代理 —— 多提供商网关​

LiteLLM 是一个兼容 OpenAI 的代理，可将 100 多个大模型提供商统一为单一 API。适用于：无需更改配置即可在不同提供商间切换、负载均衡、故障转移链、预算控制。

# Install and start
pip install "litellm[proxy]"
litellm --model anthropic/claude-sonnet-4 --port 4000

# Or with a config file for multiple models:
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 密钥）。

# Install and start
npx @blockrun/clawrouter    # Starts on port 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 的服务均可使用。部分流行选项如下：

服务商基础 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快速开源模型托管
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 —— 社区维护的注册表，包含 3800+ 模型、100+ 服务商的提供商特定上下文长度
  9. 回退默认值 —— 基于广泛模型家族模式的默认值（128K 为默认）

对于大多数设置，系统可开箱即用。该系统具备提供商感知能力——同一模型在不同服务商处可能具有不同的上下文限制（例如，claude-opus-4.6 在 Anthropic 直连时为 1M，但在 GitHub Copilot 上为 128K）。

如需显式设置上下文长度，请在模型配置中添加 context_length：

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

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

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

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

何时手动设置
  • 使用 Ollama 并设置了低于模型最大值的 num_ctx
  • 希望将上下文限制在模型最大值以下（例如，在 128K 模型上设为 8K 以节省 VRAM）
  • 运行在不暴露 /v1/models 的代理之后

命名的自定义提供商​

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

custom_providers:
  - name: local
    base_url: http://localhost:8080/v1
    # api_key omitted — Hermes uses "no-key-required" for keyless local servers
  - name: work
    base_url: https://gpu-server.internal.corp/v1
    api_key: corp-api-key
    api_mode: chat_completions   # optional, auto-detected from URL
  - name: anthropic-proxy
    base_url: https://proxy.example.com/anthropic
    api_key: proxy-key
    api_mode: anthropic_messages  # for Anthropic-compatible proxies

在会话中随时切换，使用三重语法：

/model custom:local:qwen-2.5       # Use the "local" endpoint with qwen-2.5
/model custom:work:llama3-70b      # Use the "work" endpoint with llama3-70b
/model custom:anthropic-proxy:claude-sonnet-4  # Use the proxy

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

选择合适的配置方案​

使用场景推荐方案
只想让它正常工作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 或 MiniMax（一级支持提供商）
提示

你可以随时通过 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
强化学习训练Tinker + WandBTINKER_API_KEY, WANDB_API_KEY
跨会话用户建模HonchoHONCHO_API_KEY
语义长期记忆SupermemorySUPERMEMORY_API_KEY

自托管 Firecrawl​

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

你将获得： 无需 API 密钥，无速率限制，无按页计费，完全数据主权。

你将失去： 云版本使用 Firecrawl 的专有“Fire-engine”技术实现高级反机器人绕过（Cloudflare、CAPTCHA、IP 轮换）。自托管版本使用基础的 fetch + Playwright，因此部分受保护网站可能无法成功访问。搜索使用 DuckDuckGo 而非 Google。

设置步骤：

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

    git clone https://github.com/firecrawl/firecrawl
    cd firecrawl
    # In .env, set: 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" (default), "throughput", or "latency"
  # only: ["anthropic"]      # Only use these providers
  # ignore: ["deepinfra"]    # Skip these providers
  # order: ["anthropic", "google"]  # Try providers in this order
  # require_parameters: true  # Only use providers that support all request params
  # data_collection: "deny"   # Exclude providers that may store/train on data

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

备用模型​

配置一个备用提供者/模型，当你的主模型出现故障时（如速率限制、服务器错误、认证失败），Hermes 会自动切换到该备用模型：

fallback_model:
  provider: openrouter                    # required
  model: anthropic/claude-sonnet-4        # required
  # base_url: http://localhost:8000/v1    # optional, for custom endpoints
  # api_key_env: MY_CUSTOM_KEY           # optional, env var name for custom endpoint API key

启用后，备用模型会在会话过程中自动切换，而不会丢失你的对话记录。每个会话中最多触发一次。

支持的提供者：openrouter、nous、openai-codex、copilot、copilot-acp、anthropic、huggingface、zai、kimi-coding、minimax、minimax-cn、deepseek、ai-gateway、opencode-zen、opencode-go、kilocode、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  # optional custom endpoint
    # api_key_env: MY_CUSTOM_KEY          # optional env var name for that endpoint's API key

工作原理：

  • 如果某次交互简短、单行且不包含代码/工具/调试类内容，Hermes 可能会将其路由到 cheap_model
  • 如果该次交互看起来较复杂，Hermes 会继续使用主模型/提供者
  • 如果廉价路径无法干净地处理请求，Hermes 会自动回退到主模型

此策略设计得较为保守，适用于快速、低风险的交互，例如：

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

它会避免将以下类型的提示进行路由：

  • 编码/调试任务
  • 工具密集型请求
  • 长文本或多行分析请求

当你希望在不完全更换默认模型的前提下降低延迟或成本时，可使用此功能。

参考​

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