HERMES DOCUMENTATIONDOCS / CURRENT

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 密鑰，或手動設置令牌）
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 Agent。支持三種認證方式：

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

# 首選：通過“0”進行身份驗證
# Hermes 將在可用時直接使用 Claude Code 的憑證存儲
hermes model

# 使用設置令牌手動覆蓋（後備“0”遺留）
export ANTHROPIC_TOKEN=***  # setup-token 或手動 OAuth token
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
# 需要 PATH 中的 GitHub Copilot CLI 和現有的 `copilot login` session

永久配置：

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
# 要求：“0”中的“1”

# 基米 / 登月人工智能
hermes chat --provider kimi-coding --model kimi-for-coding
# 要求：“0”中的“1”

# MiniMax（全局端點）
hermes chat --provider minimax --model MiniMax-M2.7
# 要求：“0”中的“1”

# MiniMax（中國端點）
hermes chat --provider minimax-cn --model MiniMax-M2.7
# 要求：“0”中的“1”

# 阿里雲 / DashScope (Qwen models)
hermes chat --provider alibaba --model qwen3.5-plus
# 要求：“0”中的“1”

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

model:
  provider: "zai"       # 或：kimi編碼、minimax、minimax-cn、阿里巴巴
  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 等），並支持自動故障轉移。

# 使用任何可用的 model
hermes chat --provider huggingface --model Qwen/Qwen3-235B-A22B-Thinking-2507
# 要求：“0”中的“1”

# 短別名
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
# 選擇“0”
# 輸入：API 底座 URL、API 密鑰、Model 名稱

手動配置（config.yaml）：

# 在“0”中
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
/model custom                    # 從端點自動檢測model
/model openrouter:claude-sonnet-4 # 切換回雲端 provider

如果你已配置了命名的自定義提供者（見下文），請使用三重語法：

/model custom:local:qwen-2.5    # 使用“0”自定義“1”和“2”“3”-2.5
/model custom:work:llama3       # 將 "work" 自定義 Provider 與 llama3 一起使用

切換提供者時，Hermes 會將基礎 URL 和提供者持久化到配置中，確保更改在重啟後仍然有效。當從自定義端點切換到內置提供者時，過時的基礎 URL 會自動清除。

提示

/model custom（無模型名稱）會查詢你的端點的 /models API，並在僅加載一個模型時自動選擇該模型。適用於運行單個模型的本地服務器。

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

Ollama — 本地模型，零配置

Ollama 通過一條命令即可在本地運行開源權重模型。適用於：快速本地實驗、對隱私敏感的工作、離線使用。支持通過 OpenAI 兼容 API 調用工具。

# 安裝並運行 model
ollama pull qwen2.5-coder:32b
ollama serve   # 在端口 11434 上啟動

然後配置 Hermes：

hermes model
# 選擇“0”
# 輸入“1”：“0”
# 跳過API密鑰（Ollama不需要）
# 輸入 模型 名稱（例如 qwen2.5-coder:32b）

或直接配置 config.yaml：

model:
  default: qwen2.5-coder:32b
  provider: custom
  base_url: http://localhost:11434/v1
  context_length: 32768   # 請參閱下面的警告

Ollama 默認上下文長度極低

Ollama 不會默認使用模型的完整上下文窗口。根據你的顯存情況，默認值如下：

可用顯存	默認上下文
少於 24 GB	4,096 個 token
24–48 GB	32,768 個 token
48 GB 以上	256,000 個 token

對於需要工具調用的 Agent 使用，至少需要 16k–32k 的上下文。在 4k 時，系統提示 + 工具模式本身可能就填滿窗口，導致沒有空間用於對話。

如何增加上下文長度（任選其一）：

# 選項 1：通過環境變量設置服務器範圍（推薦）
OLLAMA_CONTEXT_LENGTH=32768 ollama serve

# 選項 2：對於 systemd 管理的 Ollama
sudo systemctl edit ollama.service
# 添加：環境="OLLAMA_CONTEXT_LENGTH=32768"
# 然後： sudo systemctl daemon-reload && sudo systemctl restart ollama

# 選項 3：將其烘焙為自定義 模型（持久 per-模型）
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
# 選擇“0”
# 輸入網址：http://localhost:8000/v1
# 跳過 API 密鑰（如果您用 --api-key 配置了 vLLM，則輸入 1）
# 輸入模型名稱：meta-flame/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
# 選擇“0”
# 輸入“1”：“0”
# 輸入模型名稱：meta-flame/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 用戶、邊緣部署。

# 構建並啟動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 是 Agent 使用的好範圍）。若使用並行槽位（-np），總上下文將分配給各槽位——例如 -c 32768 -np 4 時，每個槽位僅獲得 8k。

然後配置 Hermes 指向它：

hermes model
# 選擇“0”
# 輸入“1”：“0”
# 跳過API密鑰（本地服務器不需要）
# 輸入 model 名稱 — 或留空以自動檢測是否僅加載一個 model

這會將端點保存至 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                        # 在端口 1234 上啟動
lms load qwen2.5-coder --context-length 32768

然後配置 Hermes：

hermes model
# 選擇“0”
# 輸入“1”：“0”
# 跳過API密鑰（LM Studio不需要）
# 輸入model名稱

上下文長度默認值通常為 2048

LM Studio 會從模型元數據中讀取上下文長度，但許多 GGUF 模型報告的默認值較低（2048 或 4096）。請始終在 LM Studio 模型設置中顯式設置上下文長度：

點擊模型選擇器旁邊的齒輪圖標
將“上下文長度”設置為至少 16384（建議設置為 32768）
重新加載模型以使更改生效

或者使用命令行：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 通信——最簡單的解決方案。

創建或編輯 %USERPROFILE%\.wslconfig（例如 C:\Users\YourName\.wslconfig）：
```
[wsl2]
networkingMode=mirrored
```
從 PowerShell 重啟 WSL：
```
wsl --shutdown
```
重新打開你的 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：

# 獲取Windows主機IP（WSL2的虛擬網絡默認gateway）
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，而不是本地主機

動態輔助工具

主機 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 模式必需）

如果你使用 方案二（NAT 模式，使用主機 IP），則運行在 Windows 上的模型服務器必須接受來自 127.0.0.1 以外的連接。默認情況下，大多數服務器僅監聽 localhost——在 NAT 模式下，WSL2 的連接來自不同的虛擬子網，將被拒絕。在鏡像模式下，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`	在開發者標籤頁 → 服務器設置中啟用 “在局域網中提供服務”
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 用作 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。

診斷：

# 檢查 Hermes 認為 context 是什麼
# 查看啟動行：“0”

# 檢查您服務器的實際 context
# Ollama：ollama ps（上下文支柱）
# llama.cpp：捲曲http://localhost:8080/props | jq '.default_generation_settings.n_ctx'
# vLLM：檢查啟動參數中的--max-model-len

修復： 為 Agent 使用至少 32,768 個 token 的上下文。請參見上文各服務器部分，瞭解具體配置標誌。

啟動時出現 "Context limit: 2048 tokens"

Hermes 會自動從服務器的 /v1/models 端點檢測上下文長度。如果服務器報告的值過低（或根本未報告），Hermes 將使用模型聲明的限制，這可能是錯誤的。

修復： 在 config.yaml 中顯式設置：

model:
  default: your-model
  provider: custom
  base_url: http://localhost:11434/v1
  context_length: 32768

響應在句子中間被截斷

可能原因：

服務器輸出上限（max_tokens）過低 —— SGLang 默認每響應限制為 128 個 token。請在服務器上設置 --default-max-tokens，或在 config.yaml 中通過 model.max_tokens 配置 Hermes。注意：max_tokens 僅控制響應長度，與對話歷史長度無關（後者由 context_length 控制）。
上下文耗盡 —— 模型已填滿其上下文窗口。請增加 model.context_length 或在 Hermes 中啟用上下文壓縮。

LiteLLM 代理 —— 多提供商網關

LiteLLM 是一個兼容 OpenAI 的 Agent，可將 100 多個大模型提供商統一為單一 API。適用於：無需更改配置即可在不同提供商間切換、負載均衡、故障轉移鏈、預算控制。

# 安裝並啟動
pip install "litellm[proxy]"
litellm --model anthropic/claude-sonnet-4 --port 4000

# 或者使用多個 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 開發，是一個本地路由 Agent，可根據查詢複雜度自動選擇模型。它在 14 個維度上對請求進行分類，並將任務路由至最經濟的可用模型。支付方式為 USDC 加密貨幣（無需 API 密鑰）。

# 安裝並啟動
npx @blockrun/clawrouter    # 在端口 8402 上啟動

然後通過 hermes model → 自定義端點 → http://localhost:8402/v1 → 模型名稱 blockrun/auto 配置 Hermes。

路由配置文件：

配置文件	策略	節省成本
`blockrun/auto`	質量與成本的平衡	74–100%
`blockrun/eco`	儘可能便宜	95–100%
`blockrun/premium`	最佳質量模型	0%
`blockrun/free`	僅限免費模型	100%
`blockrun/agentic`	針對工具使用優化	變化

備註

ClawRouter 需要在 Base 或 Solana 網絡上使用已充值 USDC 的錢包進行支付。所有請求均通過 BlockRun 的後端 API 路由。運行 npx @blockrun/clawrouter doctor 可檢查錢包狀態。

其他兼容提供商

任何具備 OpenAI 兼容 API 的服務均可使用。部分流行選項如下：

服務商	基礎 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 是 總上下文窗口 —— 輸入與輸出 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 使用多源解析鏈來檢測模型和提供商的正確上下文窗口：

配置覆蓋 —— 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 的 Agent 之後

命名的自定義提供商

如果你使用多個自定義端點（例如本地開發服務器和遠程 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       # 使用“0”端點和“1”-2.5
/model custom:work:llama3-70b      # 使用 llama3-70b 的“0”端點
/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 或 OpenRouter 配合 `sort: "price"`
最大隱私保護	Ollama、vLLM 或 llama.cpp（完全本地）
企業級 / Azure 環境	Azure OpenAI 自定義端點
中文 AI 模型	z.ai（GLM）、Kimi/Moonshot 或 MiniMax（一級支持提供商）

提示

你可以隨時通過 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`
強化學習訓練	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 內存）：

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

將 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"] # 跳過這些 Providers
  # order: ["anthropic", "google"] # 按此順序嘗試 Providers
  # require_parameters: true # 僅使用支持所有請求參數的 Providers
  # data_collection: "deny" # 排除可能存儲 /train 數據的 Providers

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

備用模型

配置一個備用提供者/模型，當你的主模型出現故障時（如速率限制、服務器錯誤、認證失敗），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、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 # 可選的自定義端點
    # 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 用戶）​

方案一：鏡像網絡模式（推薦）​

方案二：使用 Windows 主機 IP（Windows 10 / 較舊版本）​

服務器綁定地址（NAT 模式必需）​

Windows 防火牆​

快速驗證​

本地模型故障排除​

“連接被拒絕”：從 WSL2 訪問運行在 Windows 主機上的模型服務器​

工具調用以文本形式出現，而非執行​

模型似乎忘記上下文或給出不連貫的響應​

啟動時出現 "Context limit: 2048 tokens"​

響應在句子中間被截斷​

LiteLLM 代理 —— 多提供商網關​

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 用戶）

方案一：鏡像網絡模式（推薦）

方案二：使用 Windows 主機 IP（Windows 10 / 較舊版本）

服務器綁定地址（NAT 模式必需）

Windows 防火牆

快速驗證

本地模型故障排除

“連接被拒絕”：從 WSL2 訪問運行在 Windows 主機上的模型服務器

工具調用以文本形式出現，而非執行

模型似乎忘記上下文或給出不連貫的響應

啟動時出現 "Context limit: 2048 tokens"

響應在句子中間被截斷

LiteLLM 代理 —— 多提供商網關

ClawRouter —— 成本優化路由

其他兼容提供商

上下文長度檢測

命名的自定義提供商

選擇合適的配置方案

可選 API 密鑰

自託管 Firecrawl

OpenRouter 提供商路由

備用模型

智能模型路由

參考