Skip to main content

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 认证、Anthropic API 密钥，或手动设置 token）
OpenRouterOPENROUTER_API_KEY 写入 ~/.hermes/.env
AI GatewayAI_GATEWAY_API_KEY 写入 ~/.hermes/.env（提供者：ai-gateway）
z.ai / GLMGLM_API_KEY 写入 ~/.hermes/.env（提供者：zai）
Kimi / MoonshotKIMI_API_KEY 写入 ~/.hermes/.env（提供者：kimi-coding）
Kimi / Moonshot（中国区）KIMI_CN_API_KEY 写入 ~/.hermes/.env（提供者：kimi-coding-cn；别名：kimi-cn、moonshot-cn）
Arcee AIARCEEAI_API_KEY 写入 ~/.hermes/.env（提供者：arcee；别名：arcee-ai、arceeai）
MiniMaxMINIMAX_API_KEY 写入 ~/.hermes/.env（提供者：minimax）
MiniMax 中国区MINIMAX_CN_API_KEY 写入 ~/.hermes/.env（提供者：minimax-cn）
阿里云DASHSCOPE_API_KEY 写入 ~/.hermes/.env（提供者：alibaba；别名：dashscope、qwen）
Kilo CodeKILOCODE_API_KEY 写入 ~/.hermes/.env（提供者：kilocode）
小米 MiMoXIAOMI_API_KEY 写入 ~/.hermes/.env（提供者：xiaomi；别名：mimo、xiaomi-mimo）
OpenCode ZenOPENCODE_ZEN_API_KEY 写入 ~/.hermes/.env（提供者：opencode-zen）
OpenCode GoOPENCODE_GO_API_KEY 写入 ~/.hermes/.env（提供者：opencode-go）
DeepSeekDEEPSEEK_API_KEY 写入 ~/.hermes/.env（提供者：deepseek）
Hugging FaceHF_TOKEN 写入 ~/.hermes/.env（提供者：huggingface；别名：hf）
Google / GeminiGOOGLE_API_KEY（或 GEMINI_API_KEY）写入 ~/.hermes/.env（提供者：gemini）
自定义端点hermes model → 选择“自定义端点”（保存在 config.yaml 中）
模型密钥别名

在 model: 配置块中，你可以使用 default: 或 model: 作为模型 ID 的键名，两者作用完全相同。

Codex 说明

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

warning

即使使用 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 自身的凭证存储，而非将 token 复制到 ~/.hermes/.env。这可保持凭证可刷新状态。

或永久设置：

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 降级备用

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

Token 类型

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

类型前缀获取方式
OAuth tokengho_hermes model → GitHub Copilot → 使用 GitHub 登录
细粒度 PATgithub_pat_GitHub 设置 → 开发者设置 → 细粒度令牌（需具备 Copilot Requests 权限）
GitHub App tokenghu_通过 GitHub App 安装获取

如果您的 gh auth token 返回的是 ghp_* 类型的 token，请使用 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_TOKENGitHub token，用于 Copilot API（优先级最高）
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 (international: api.moonshot.ai)
hermes chat --provider kimi-coding --model kimi-for-coding
# Requires: KIMI_API_KEY in ~/.hermes/.env

# Kimi / Moonshot AI (China: api.moonshot.cn)
hermes chat --provider kimi-coding-cn --model kimi-k2.5
# Requires: KIMI_CN_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

# Xiaomi MiMo
hermes chat --provider xiaomi --model mimo-v2-pro
# Requires: XIAOMI_API_KEY in ~/.hermes/.env

# Arcee AI (Trinity models)
hermes chat --provider arcee --model trinity-large-thinking
# Requires: ARCEEAI_API_KEY in ~/.hermes/.env

也可以在 config.yaml 中将其设为默认提供商：

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

基础 URL 可通过以下环境变量覆盖：GLM_BASE_URL、KIMI_BASE_URL、MINIMAX_BASE_URL、MINIMAX_CN_BASE_URL、DASHSCOPE_BASE_URL 或 XIAOMI_BASE_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
旧版环境变量

OPENAI_BASE_URL 和 LLM_MODEL 在 .env 中已被 移除。系统中任何部分均不再读取它们 —— 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 也会自动清除。

tip

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

其他 OpenAI 兼容服务的接入方式也都遵循同一模式，你只需要替换 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 不会默认使用模型的完整上下文窗口。根据你的显存情况，默认值如下：

可用 VRAM默认上下文
小于 24 GB4,096 tokens
24–48 GB32,768 tokens
48+ GB256,000 tokens

对于需要工具调用的代理任务，至少需要 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
tip

使用 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。缺少这些标志，工具调用将无法正常工作 —— 模型只会输出文本形式的工具调用。

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
# 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 默认最大输出为 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 用户、边缘部署。

# 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 无法识别为实际工具调用 —— 你会看到类似 {"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 字段，以确认工具调用支持是否已经启用。

tip

从 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
caution

上下文长度默认常为 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 主机。

tip

如果模型服务器也在 WSL2 内运行（常见于 vLLM、SGLang 和 llama-server），则无需额外配置——两者共享同一网络命名空间。可跳过此节。

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

仅适用于 Windows 11 22H2 及以上版本。镜像模式可实现 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   # Ollama on Windows — works
Hyper-V 防火墙

部分 Windows 11 版本中，Hyper-V 防火墙默认阻止镜像连接。若启用镜像模式后仍无法连接，请以 管理员身份运行 PowerShell 执行以下命令：

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

方案二：使用 Windows 主机 IP（Windows 10 / 较旧版本）​

若无法使用镜像模式，可在 WSL2 内获取 Windows 主机 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 上的模型服务器必须接受来自 WSL2 外部的连接。默认情况下，大多数服务器仅监听 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

Ollama on Windows（详细说明）：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 主机上时，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。

诊断方法：

# 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 tokens。请参阅各服务器章节中的具体参数。

启动时提示“上下文限制：2048 个 token”​

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 接口后面。它适合用在这类场景：希望在不改 Hermes 配置的前提下切换提供商、做负载均衡、配置故障转移链路，或增加预算控制能力。

# 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 配置 Hermes，选择“自定义端点”，并填写 http://localhost:4000/v1。

示例：带有回退机制的 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 配置 Hermes，选择“自定义端点”，填写 http://localhost:8402/v1，模型名填写 blockrun/auto。

路由配置文件：

配置文件策略节省成本
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 的服务都可以接入。下面是一些常见选项：

提供商基础 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. 配置覆盖 —— model.context_length 在 config.yaml 中（优先级最高）
  2. 自定义提供商中的模型级覆盖 —— custom_providers[].models.<id>.context_length
  3. 持久缓存 —— 之前发现的值（重启后仍保留）
  4. 端点 /models —— 查询你服务器的 API（本地/自定义端点）
  5. Anthropic /v1/models —— 查询 Anthropic API 获取 max_input_tokens（仅需 API Key 用户）
  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（kimi-coding 或 kimi-coding-cn）、MiniMax、小米 MiMo（内置一级支持）
tip

你可以随时通过 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
强化学习训练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、验证码、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
    # 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、kimi-coding-cn、minimax、minimax-cn、deepseek、ai-gateway、opencode-zen、opencode-go、kilocode、xiaomi、arcee、alibaba、custom。

tip

备用模型仅通过 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 会自动回退到主模型

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

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

它会避免将以下类型的提示路由出去：

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

当你希望降低延迟或成本，又不想完全更换默认模型时，可以使用此功能。

参考阅读​

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