AI 服务提供商

本页面介绍如何为 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 Code 认证访问 Claude Pro/Max，或 Anthropic API 密钥，或手动设置 token）
OpenRouter	`OPENROUTER_API_KEY` 在 `~/.hermes/.env` 中配置
AI Gateway	`AI_GATEWAY_API_KEY` 在 `~/.hermes/.env` 中配置（提供者：`ai-gateway`）
z.ai / GLM	`GLM_API_KEY` 在 `~/.hermes/.env` 中配置（提供者：`zai`）
Kimi / Moonshot	`KIMI_API_KEY` 在 `~/.hermes/.env` 中配置（提供者：`kimi-coding`）
MiniMax	`MINIMAX_API_KEY` 在 `~/.hermes/.env` 中配置（提供者：`minimax`）
MiniMax 中国版	`MINIMAX_CN_API_KEY` 在 `~/.hermes/.env` 中配置（提供者：`minimax-cn`）
阿里云	`DASHSCOPE_API_KEY` 在 `~/.hermes/.env` 中配置（提供者：`alibaba`，别名：`dashscope`，`qwen`）
Kilo Code	`KILOCODE_API_KEY` 在 `~/.hermes/.env` 中配置（提供者：`kilocode`）
OpenCode Zen	`OPENCODE_ZEN_API_KEY` 在 `~/.hermes/.env` 中配置（提供者：`opencode-zen`）
OpenCode Go	`OPENCODE_GO_API_KEY` 在 `~/.hermes/.env` 中配置（提供者：`opencode-go`）
DeepSeek	`DEEPSEEK_API_KEY` 在 `~/.hermes/.env` 中配置（提供者：`deepseek`）
Hugging Face	`HF_TOKEN` 在 `~/.hermes/.env` 中配置（提供者：`huggingface`，别名：`hf`）
Google / Gemini	`GOOGLE_API_KEY`（或 `GEMINI_API_KEY`）在 `~/.hermes/.env` 中配置（提供者：`gemini`）
自定义端点	`hermes model` → 选择“自定义端点”（保存于 `config.yaml`）

模型键别名

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

Codex 注意事项

OpenAI Codex 服务提供商通过设备码方式认证（打开网页，输入代码）。Hermes 将生成的凭据存储在自身的认证仓库中，位于 ~/.hermes/auth.json。当存在时，Hermes 可以导入已有的 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。这能保持可刷新的 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 降级方案

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

Token 类型

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

类型	前缀	获取方式
OAuth token	`gho_`	`hermes model` → GitHub Copilot → 使用 GitHub 登录
细粒度 PAT	`github_pat_`	GitHub 设置 → 开发者设置 → 细粒度令牌（需具备 Copilot Requests 权限）
GitHub App token	`ghu_`	通过 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_TOKEN`	GitHub 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
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 获取您的 token——请确保开启“对推理服务发起调用”的权限。免费套餐包含（每月 $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 中已移除。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 会自动清除。

tip

/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 GB	4,096 tokens
24–48 GB	32,768 tokens
48 GB 以上	256,000 tokens

对于需要工具调用的代理任务，至少需要 16k–32k 上下文。若只有 4k 上下文，系统提示词 + 工具 Schema 本身就会占满窗口，几乎没有空间用于对话。

如何提升上下文长度（任选其一）：

# 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 — the 的chat_template` 字段是否存在来验证工具支持是否生效。

tip

从 Hugging Face 下载 GGUF 模型。Q4_K_M 量化在质量与内存占用之间提供了最佳平衡。

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

LM Studio 是一款带有图形界面的本地模型运行桌面应用。适用于：偏好可视化界面的用户、快速测试模型、macOS/Windows/Linux 开发者。

从 LM Studio 应用启动服务器（开发者标签 → 启动服务器），或使用 CLI：

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 模型设置中显式设置上下文长度：

点击模型选择器旁边的齿轮图标
将“上下文长度”设为至少 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 使用虚拟网络适配器并拥有独立子网，因此 localhost 在 WSL2 内部指向的是 Linux 虚拟机本身，而非 Windows 主机。

两者都在 WSL2？没问题。

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

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

适用于 Windows 11 22H2 及以上版本，镜像模式可实现 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

方案二：使用 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 上的模型服务器必须接受来自外部 127.0.0.1 的连接。默认情况下，大多数服务器仅监听 localhost——在 NAT 模式下，WSL2 的连接来自不同虚拟子网，会被拒绝。而在镜像模式下，localhost 会直接映射，因此默认的 127.0.0.1 绑定即可正常工作。

服务器	默认绑定	修复方法
Ollama	`127.0.0.1`	启动前设置 `OLLAMA_HOST=0.0.0.0` 环境变量（Windows 系统设置 → 环境变量，或编辑 Ollama 服务）
LM Studio	`127.0.0.1`	在开发者选项 → 服务器设置中启用 “在局域网中提供服务”
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 还是镜像模式）。如果上述步骤完成后连接仍失败，请为模型服务器的端口添加防火墙规则：

# 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 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 以用于代理场景。详见各服务器章节中的具体参数。

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

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 token。请在服务器上设置 --default-max-tokens，或在 config.yaml 中配置 Hermes 的 model.max_tokens。注意：max_tokens 仅控制响应长度，与对话历史长度无关（那是由 context_length 控制的）。
上下文耗尽 —— 模型已填满上下文窗口。请增加 model.context_length 或在 Hermes 中启用上下文压缩。

LiteLLM 代理 — 多提供商网关

LiteLLM 是一个兼容 OpenAI 的代理，可将 100 多个 LLM 提供商统一到单一 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 中配置 hermes model → 自定义端点 → 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 中配置 hermes model → 自定义端点 → http://localhost:8402/v1 → model name 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 AI | https://api.together.xyz/v1`` | 云端托管的开源模型 | | [Groq](https://groq.com) | https://api.groq.com/openai/v1`` | 超快推理速度 | | DeepSeek | https://api.deepseek.com/v1`` | DeepSeek 模型 | | [Fireworks AI](https://fireworks.ai) | https://api.fireworks.ai/inference/v1`` | 快速开源模型托管 | | Cerebras | https://api.cerebras.ai/v1`` | 芯片级规模推理 | | [Mistral AI](https://mistral.ai) | https://api.mistral.ai/v1`` | Mistral 模型 | | OpenAI | https://api.openai.com/v1`` | 直接访问 OpenAI | | [Azure OpenAI](https://azure.microsoft.com) | https://YOUR.openai.azure.com/`` | 企业级 OpenAI | | LocalAI | http://localhost:8080/v1`` | 自托管，支持多模型 | | [Jan](https://jan.ai) | 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 是 总上下文窗口 —— 输入和输出令牌的总预算（例如 Claude Opus 4.6 为 200,000）。Hermes 使用此值来决定何时压缩历史记录，并验证 API 请求。

model.max_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
持久化缓存 —— 之前发现的值（重启后仍保留）
端点 /models —— 查询你服务器的 API（本地/自定义端点）
Anthropic /v1/models —— 查询 Anthropic API 获取 max_input_tokens（仅限 API 密钥用户）
OpenRouter API —— 实时获取 OpenRouter 的模型元数据
Nous Portal —— 匹配 Nous 模型 ID 后缀与 OpenRouter 元数据
models.dev —— 社区维护的注册表，包含 3800+ 模型、100+ 提供方的提供方特定上下文长度
默认回退值 —— 广泛的模型家族模式（默认 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（一级支持提供方）

tip

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

可选 API 密钥

功能	提供方	环境变量
网页抓取	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`
强化学习训练	Tinker + WandB	`TINKER_API_KEY`, `WANDB_API_KEY`
跨会话用户建模	Honcho	`HONCHO_API_KEY`
语义长期记忆	Supermemory	`SUPERMEMORY_API_KEY`

自托管 Firecrawl

默认情况下，Hermes 使用 Firecrawl 云 API 进行网页搜索与抓取。若希望本地运行 Firecrawl，可指向自托管实例。详见 Firecrawl 的 SELF_HOST.md 完整安装说明。

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

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

安装步骤：

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

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" (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。

tip

备用提供方仅通过 config.yaml 配置——无对应环境变量。关于其触发条件、支持提供方及与辅助任务、委托行为的交互详情，请参阅备用提供方。

智能模型路由可选的低成本与高性能路由功能，使 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 会自动回退到主模型

此策略设计为保守模式，适用于快速、低风险的对话轮次，例如：

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

它会避免路由以下类型的请求：

编程或调试任务
高度依赖工具的请求
长文本或多行分析类问题

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

参考阅读

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

推理服务提供商​

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

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

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

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

Windows 防火墙​

快速验证​

本地模型故障排查​

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

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

模型似乎忘记上下文或给出混乱响应​

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

响应在句子中间被截断​

LiteLLM 代理 — 多提供商网关​

ClawRouter — 成本优化路由​

其他兼容的提供商​

上下文长度检测​

命名的自定义提供方​

选择合适的配置​

可选 API 密钥​

自托管 Firecrawl​

OpenRouter 提供方路由​

备用模型​

智能模型路由可选的低成本与高性能路由功能，使 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 用户）

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

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

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

Windows 防火墙

快速验证

本地模型故障排查

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

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

模型似乎忘记上下文或给出混乱响应

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

响应在句子中间被截断

LiteLLM 代理 — 多提供商网关

ClawRouter — 成本优化路由

其他兼容的提供商

上下文长度检测

命名的自定义提供方

选择合适的配置

可选 API 密钥

自托管 Firecrawl

OpenRouter 提供方路由

备用模型

智能模型路由可选的低成本与高性能路由功能，使 Hermes 能够将复杂任务交由主模型处理，同时将非常简短或简单的对话轮次发送至成本更低的模型。

参考阅读