<!-- Source: https://hermesbible.com/docs/integrations/providers -->

本頁面涵蓋為 Hermes Agent 設定推論提供者（inference providers）——從 OpenRouter 和 Anthropic 等雲端 API，到 Ollama 和 vLLM 等自架端點，再到進階的路由與容錯設定。你至少需要設定一個提供者才能使用 Hermes。

推論提供者

你至少需要一種連接 LLM 的方式。使用 hermes model 互動式切換提供者和模型，或直接進行設定：

關於官方 API 金鑰路徑，請參閱專門的 Google Gemini 指南。

提示 — 模型金鑰別名

在 model: 設定區段中，你可以使用 default: 或 model: 作為模型 ID 的金鑰名稱。model: { default: my-model } 和 model: { model: my-model } 的效果完全相同。

Nous Portal

Nous Portal 是 Nous Research 的統一訂閱閘道，也是執行 Hermes Agent 的推薦方式。一次 OAuth 登入即可使用 300+ 前沿代理模型（Claude、GPT、Gemini、DeepSeek、Qwen、Kimi、GLM、MiniMax、Grok……），加上 Tool Gateway（網路搜尋、圖片生成、TTS、瀏覽器自動化）和 Nous Chat —— 費用計入你的 Nous 訂閱，無需為各個提供者分別付費。

hermes setup --portal     # 全新安裝 — 一個指令完成 OAuth + 提供者 + 閘道
hermes model              # 已安裝 — 從清單中選擇 "Nous Portal"
hermes portal info        # 隨時查看登入和路由資訊

還沒有訂閱？請至 portal.nousresearch.com/manage-subscription 取得。

完整詳情： 請參閱專門的 Nous Portal 整合頁面（訂閱內容、模型目錄、疑難排解）以及逐步的 使用 Nous Portal 執行 Hermes Agent 指南。

用戶端識別。 來自 Hermes Agent 的每個 Portal 請求都會攜帶 client=hermes-client-v<version> 標籤（例如 client=hermes-client-v0.13.0），自動與你安裝的版本對齊。這適用於所有 Portal 路徑 —— 主聊天迴圈、輔助呼叫、壓縮摘要、網頁擷取 —— 讓 Portal 端的遙測能夠區分 Hermes 流量與其他用戶端。無需設定；當你執行 hermes update 時，標籤會自動更新。

JWT 認證（自動）。 Hermes 優先使用有範圍限制的 inference:invoke JWT 進行 Portal 請求，舊版不透明 session-key 路徑作為備用。無需任何設定 —— 憑證由 OAuth 流程管理並透明輪替。被撤銷的 refresh token 會被隔離以避免重放迴圈。

資訊 — Codex 說明

OpenAI Codex 提供者透過裝置代碼（開啟一個網址，輸入代碼）進行認證。Hermes 將產生的憑證儲存在自身的認證儲存中（~/.hermes/auth.json），並可在 ~/.codex/auth.json 存在時匯入現有的 Codex CLI 憑證。無需安裝 Codex CLI。

如果 token 更新因終端錯誤（HTTP 4xx、invalid_grant、撤銷的 grant 等）失敗，Hermes 會將 refresh token 標記為失效並停止重放，這樣你就不會看到一堆相同的認證失敗。下一個請求會顯示類型化的重新認證訊息。執行 hermes auth add codex-oauth（或 hermes model → OpenAI Codex）開始新的裝置代碼登入；隔離會在下一次成功的交換後清除。

警告

即使使用 Nous Portal、Codex 或自訂端點，某些工具（視覺、網頁摘要、MoA）會使用獨立的「輔助」模型。預設情況下（auxiliary.*.provider: "auto"），Hermes 會將這些任務路由到你的主要聊天模型 —— 即你在 hermes model 中選擇的模型。你可以為每個任務個別覆寫，將其路由到更便宜/更快的模型（例如 OpenRouter 上的 Gemini Flash）—— 請參閱輔助模型。

提示 — Nous Tool Gateway

付費的 Nous Portal 訂閱者還可以使用 Tool Gateway —— 網路搜尋、圖片生成、TTS 和瀏覽器自動化，透過你的訂閱路由。無需額外的 API 金鑰。在全新安裝中，hermes setup --portal 會幫你登入、設定 Nous 為你的提供者，並在一個指令中啟用閘道。現有使用者可以從 hermes model 啟用它，或從 hermes tools 按工具設定。使用 hermes portal info 隨時查看路由。

兩個模型管理指令

Hermes 有兩個模型指令，用途不同：

如果你想切換到尚未設定的提供者（例如你只設定了 OpenRouter 但想使用 Anthropic），你需要 hermes model，而不是 /model。先退出會話（Ctrl+C 或 /quit），執行 hermes model，完成提供者設定，然後開始新的會話。

Anthropic（原生）

直接透過 Anthropic API 使用 Claude 模型 —— 無需 OpenRouter 代理。支援三種認證方式：

注意 — 需要 Claude Max「額外用量」點數

當你透過 hermes model → Anthropic OAuth（或 hermes auth add anthropic --type oauth）認證時，Hermes 會以 Claude Code 的方式路由至你的 Anthropic 帳戶。這只有在你使用 Claude Max 方案並購買了額外用量點數時才有效。 基本 Max 方案配額（Claude Code 預設包含的用量）不會被 Hermes 消耗 —— 只有你在其上添加的額外/超量點數才會。Claude Pro 訂閱者無法使用此路徑。

如果你沒有 Max + 額外點數，請改用 ANTHROPIC_API_KEY —— 請求會按照該金鑰的組織按 token 計費（標準 API 定價，與任何 Claude 訂閱無關）。

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

# 推薦：透過 `hermes model` 認證
# 當可用時，Hermes 會直接使用 Claude Code 的憑證儲存
hermes model

# 使用 setup-token 手動覆寫（備用 / 舊版）
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 自身的憑證儲存，而非將 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

認證選項（按以下順序檢查）：

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 不支援經典的 Personal Access Token（ghp_*）。支援的 token 類型：

類型	前綴	取得方式
OAuth token	gho_	hermes model → GitHub Copilot → 用 GitHub 登入
精細化 PAT	github_pat_	GitHub 設定 → 開發者設定 → 精細化 token（需要 Copilot Requests 權限）
GitHub App token	ghu_	透過 GitHub App 安裝

如果你的 gh auth token 回傳 ghp_* token，請改用 hermes model 透過 OAuth 認證。

資訊 — Hermes 中的 Copilot 認證行為

Hermes 將支援的 GitHub token（gho_*、github_pat_* 或 ghu_*）直接傳送到 api.githubcopilot.com，並包含 Copilot 特定的標頭（Editor-Version、Copilot-Integration-Id、Openai-Intent、x-initiator）。

在 HTTP 401 時，Hermes 現在會在回退前執行一次性憑證恢復：

1. 透過正常優先順序鏈重新解析 token（COPILOT_GITHUB_TOKEN → GH_TOKEN → GITHUB_TOKEN → gh auth token）
2. 用更新的標頭重建共用的 OpenAI 用戶端
3. 重試請求一次

一些較舊的社群代理使用 api.github.com/copilot_internal/v2/token 交換流程。該端點可能對某些帳戶類型不可用（回傳 404）。因此 Hermes 保持直接 token 認證為主要路徑，並依賴運行時憑證刷新 + 重試來確保穩定性。

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
# 需要 GitHub Copilot CLI 在 PATH 中且已有 `copilot login` 會話

永久設定：

model:
  provider: "copilot"
  default: "gpt-5.4"

一等 API 金鑰提供者

這些提供者具有內建支援和專屬提供者 ID。設定 API 金鑰並使用 --provider 選擇：

# NovitaAI Model API
hermes chat --provider novita --model moonshotai/kimi-k2.5
# 需要：NOVITA_API_KEY 於 ~/.hermes/.env

# z.ai / ZhipuAI GLM
hermes chat --provider zai --model glm-5
# 需要：GLM_API_KEY 於 ~/.hermes/.env

# Kimi / Moonshot AI（國際版：api.moonshot.ai）
hermes chat --provider kimi-coding --model kimi-for-coding
# 需要：KIMI_API_KEY 於 ~/.hermes/.env

# Kimi / Moonshot AI（中國版：api.moonshot.cn）
hermes chat --provider kimi-coding-cn --model kimi-k2.5
# 需要：KIMI_CN_API_KEY 於 ~/.hermes/.env

# MiniMax（全球端點）
hermes chat --provider minimax --model MiniMax-M2.7
# 需要：MINIMAX_API_KEY 於 ~/.hermes/.env

# MiniMax（中國端點）
hermes chat --provider minimax-cn --model MiniMax-M2.7
# 需要：MINIMAX_CN_API_KEY 於 ~/.hermes/.env

# Qwen Cloud / DashScope（Qwen 模型）
hermes chat --provider alibaba --model qwen3.5-plus
# 需要：DASHSCOPE_API_KEY 於 ~/.hermes/.env

# Xiaomi MiMo
hermes chat --provider xiaomi --model mimo-v2-pro
# 需要：XIAOMI_API_KEY 於 ~/.hermes/.env

# Tencent TokenHub（Hy3 Preview）
hermes chat --provider tencent-tokenhub --model hy3-preview
# 需要：TOKENHUB_API_KEY 於 ~/.hermes/.env

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

# GMI Cloud
# 使用 GMI /v1/models 端點回傳的精確模型 ID。
hermes chat --provider gmi --model zai-org/GLM-5.1-FP8
# 需要：GMI_API_KEY 於 ~/.hermes/.env

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

model:
  provider: "gmi"
  default: "zai-org/GLM-5.1-FP8"

基礎 URL 可透過 NOVITA_BASE_URL、GLM_BASE_URL、KIMI_BASE_URL、MINIMAX_BASE_URL、MINIMAX_CN_BASE_URL、DASHSCOPE_BASE_URL、XIAOMI_BASE_URL、GMI_BASE_URL 或 TOKENHUB_BASE_URL 環境變數覆寫。

備註 — Z.AI 端點自動偵測

使用 Z.AI / GLM 提供者時，Hermes 會自動探測多個端點（全球、中國、程式變體）以找到接受你 API 金鑰的一個。你不需要手動設定 GLM_BASE_URL —— 可用的端點會被自動偵測並快取。

xAI (Grok) — Responses API + 提示快取

xAI 透過 Responses API（codex_responses 傳輸）連線，為 Grok 4 模型提供自動推理支援 —— 無需 reasoning_effort 參數，伺服器預設就會進行推理。在 ~/.hermes/.env 中設定 XAI_API_KEY，並在 hermes model 中選擇 xAI，或將 grok 作為捷徑輸入到 /model grok-4-fast-reasoning。

SuperGrok 和 X Premium+ 訂閱者可以使用瀏覽器 OAuth 登入，無需 API 金鑰 —— 在 hermes model 中選擇 xAI Grok OAuth (SuperGrok / Premium+)，或執行 hermes auth add xai-oauth。相同的 OAuth bearer token 會自動被直接連線 xAI 的工具（TTS、圖片生成、影片生成、轉錄）重用。請參閱 xAI Grok OAuth 指南 了解完整流程 —— 如果 Hermes 在遠端主機上運行，也請參閱 透過 SSH / 遠端主機的 OAuth 了解所需的 ssh -L 通道。

當使用 xAI 作為提供者（任何包含 x.ai 的基礎 URL）時，Hermes 會透過在每個 API 請求中發送 x-grok-conv-id 標頭來自動啟用提示快取。這會將請求路由到對話會話中的同一台伺服器，讓 xAI 的基礎設施可以重用快取的系統提示和對話歷史。

無需設定 —— 當偵測到 xAI 端點且有可用的會話 ID 時，快取會自動啟用。這減少了多輪對話的延遲和成本。

xAI 還提供專屬的 TTS 端點（/v1/tts）。在 hermes tools → 語音與 TTS 中選擇 xAI TTS，或參閱語音與 TTS頁面進行設定。

已淘汰 xAI 模型遷移（2026 年 5 月 15 日）： xAI 將於 2026-05-15 淘汰 grok-4*、grok-3、grok-code-fast-1 和 grok-imagine-image-pro。hermes doctor 和 hermes chat 啟動時都會偵測仍指向已淘汰模型參照的設定，並列印建議的替代方案。使用 hermes migrate xai 進行一次性設定重寫 —— 預設為試運行，新增 --apply 以寫入變更（會自動建立帶時間戳的 config.yaml.bak-pre-migrate-xai-* 備份）。

hermes migrate xai          # 預覽替換
hermes migrate xai --apply  # 就地重寫 ~/.hermes/config.yaml

xAI 網路搜尋後端。 當 網路搜尋 工具組啟用時，web.backend: xai 使用相同的 XAI_API_KEY / OAuth 憑證，透過 xAI 的託管搜尋端點路由搜尋。如果 xAI 已設定為提供者，無需額外設定。

NovitaAI

NovitaAI 是為建構者和代理打造的 AI 原生雲端平台。其三條產品線分別是：支援 200+ 模型的 Model API、用於建構和運行 AI 代理的 Agent Sandbox，以及可擴展運算的 GPU Cloud，全部從一個平台取得。

# 使用任何可用模型
hermes chat --provider novita --model moonshotai/kimi-k2.5
# 需要：NOVITA_API_KEY 於 ~/.hermes/.env

# 簡短別名
hermes chat --provider novita-ai --model deepseek/deepseek-v3-0324

或在 config.yaml 中永久設定：

model:
  provider: "novita"
  default: "moonshotai/kimi-k2.5"
  base_url: "https://api.novita.ai/openai/v1"

在 novita.ai/settings/key-management 取得你的 API 金鑰。基礎 URL 可透過 NOVITA_BASE_URL 覆寫。

Ollama Cloud — 管理式 Ollama 模型，OAuth + API 金鑰

Ollama Cloud 托管與本地 Ollama 相同的開放權重目錄，但無需 GPU。在 hermes model 中選擇 Ollama Cloud，貼上你從 ollama.com/settings/keys 取得的 API 金鑰，Hermes 會自動探索可用模型。

hermes model
# → 選擇 "Ollama Cloud"
# → 貼上你的 OLLAMA_API_KEY
# → 從探索到的模型中選擇（gpt-oss:120b、glm-4.6:cloud、qwen3-coder:480b-cloud 等）

或直接設定 config.yaml：

model:
  provider: "ollama-cloud"
  default: "gpt-oss:120b"

模型目錄從 ollama.com/v1/models 動態取得並快取一小時。model:tag 註記法（例如 qwen3-coder:480b-cloud）在正規化過程中會被保留 —— 請勿使用破折號。

提示 — Ollama Cloud 與本地 Ollama

兩者都使用相同的 OpenAI 相容 API。Cloud 是一等提供者（--provider ollama-cloud、OLLAMA_API_KEY）；本地 Ollama 透過自訂端點流程連線（基礎 URL http://localhost:11434/v1，無需金鑰）。使用雲端處理無法在本地運行的大型模型；使用本地處理注重隱私或離線工作。

AWS Bedrock

透過 AWS Bedrock 使用 Anthropic Claude、Amazon Nova、DeepSeek v3.2、Meta Llama 4 和其他模型。使用 AWS SDK（boto3）憑證鏈 —— 無需 API 金鑰，只需標準 AWS 認證。

# 最簡單 — ~/.aws/credentials 中的具名設定檔
hermes chat --provider bedrock --model us.anthropic.claude-sonnet-4-6

# 或使用明確的環境變數
AWS_PROFILE=myprofile AWS_REGION=us-east-1 hermes chat --provider bedrock --model us.anthropic.claude-sonnet-4-6

或在 config.yaml 中永久設定：

model:
  provider: "bedrock"
  default: "us.anthropic.claude-sonnet-4-6"
bedrock:
  region: "us-east-1"          # 或設定 AWS_REGION
  # profile: "myprofile"       # 或設定 AWS_PROFILE
  # discovery: true            # 從 IAM 自動探索區域
  # guardrail:                 # 可選的 Bedrock Guardrails
  #   guardrail_identifier: "your-guardrail-id"
  #   guardrail_version: "DRAFT"

認證使用標準的 boto3 鏈：明確的 AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY、~/.aws/credentials 中的 AWS_PROFILE、EC2/ECS/Lambda 上的 IAM 角色、IMDS 或 SSO。如果你已使用 AWS CLI 認證，不需要任何環境變數。

Bedrock 底層使用 Converse API —— 請求會被轉換為 Bedrock 的模型無關格式，因此相同的設定適用於 Claude、Nova、DeepSeek 和 Llama 模型。只有在呼叫非預設區域端點時才需要設定 BEDROCK_BASE_URL。

請參閱 AWS Bedrock 指南 了解 IAM 設定、區域選擇和跨區域推論的完整說明。

Qwen Portal (OAuth)

阿里的 Qwen Portal，支援基於瀏覽器的 OAuth 登入。在 hermes model 中選擇 Qwen OAuth (Portal)，透過瀏覽器登入，Hermes 會持久儲存 refresh token。

hermes model
# → 選擇 "Qwen OAuth (Portal)"
# → 瀏覽器開啟；用你的阿里帳戶登入
# → 確認 — 憑證儲存至 ~/.hermes/auth.json

hermes chat   # 使用 portal.qwen.ai/v1 端點

或設定 config.yaml：

model:
  provider: "qwen-oauth"
  default: "qwen3-coder-plus"

只有在閘道端點變更時才需設定 HERMES_QWEN_BASE_URL（預設：https://portal.qwen.ai/v1）。

提示 — Qwen OAuth 與 Qwen Cloud（Alibaba DashScope）

qwen-oauth 使用面向消費者的 Qwen Portal 搭配 OAuth 登入 —— 適合個人使用者。alibaba 提供者使用 Qwen Cloud（Alibaba DashScope）搭配 DASHSCOPE_API_KEY —— 適合程式化/生產環境工作負載。兩者都路由到 Qwen 系列模型，但位於不同的端點。

Alibaba Cloud（Coding Plan）

如果你訂閱了阿里的 Coding Plan（與標準 DashScope API 存取分開的計費 SKU），Hermes 將其作為自己的第一方提供者：alibaba-coding-plan。端點：https://coding-intl.dashscope.aliyuncs.com/v1。它與一般 alibaba 提供者一樣相容 OpenAI，但有不同的基礎 URL 和計費面向。

model:
  provider: alibaba_coding     # alibaba-coding-plan 的別名
  model: qwen3-coder-plus

或從 CLI：

hermes chat --provider alibaba_coding --model qwen3-coder-plus

alibaba_coding 使用與你的 alibaba 條目相同的 DASHSCOPE_API_KEY —— 無需單獨的金鑰，只是不同的路由目標。在此提供者註冊之前，在 config.yaml 中設定 provider: alibaba_coding 的使用者會靜默回退到 OpenRouter 路由。

MiniMax (OAuth)

透過瀏覽器 OAuth 登入使用 MiniMax-M2.7 —— 無需 API 金鑰。在 hermes model 中選擇 MiniMax (OAuth)，透過瀏覽器登入，Hermes 會持久儲存 access + refresh token。底層使用相容 Anthropic Messages 的端點（/anthropic）。

hermes model
# → 選擇 "MiniMax (OAuth)"
# → 瀏覽器開啟；用你的 MiniMax 帳戶登入（全球或中國區域）
# → 確認 — 憑證儲存至 ~/.hermes/auth.json

hermes chat   # 使用 api.minimax.io/anthropic 端點

或設定 config.yaml：

model:
  provider: "minimax-oauth"
  default: "MiniMax-M2.7"

支援的模型：MiniMax-M2.7（主要）和 MiniMax-M2.7-highspeed（設定為預設輔助模型）。OAuth 路徑會忽略 MINIMAX_API_KEY / MINIMAX_BASE_URL。

提示 — MiniMax OAuth 與 API 金鑰

minimax-oauth 使用 MiniMax 的消費者導向入口搭配 OAuth 登入 —— 無需設定計費。minimax 和 minimax-cn 提供者使用 MINIMAX_API_KEY / MINIMAX_CN_API_KEY —— 用於程式化存取。請參閱 MiniMax OAuth 指南 了解完整說明。

NVIDIA NIM

透過 build.nvidia.com（免費 API 金鑰）或本地 NIM 端點使用 Nemotron 和其他開源模型。

# 雲端（build.nvidia.com）
hermes chat --provider nvidia --model nvidia/nemotron-3-super-120b-a12b
# 需要：NVIDIA_API_KEY 於 ~/.hermes/.env

# 本地 NIM 端點 — 覆寫基礎 URL
NVIDIA_BASE_URL=http://localhost:8000/v1 hermes chat --provider nvidia --model nvidia/nemotron-3-super-120b-a12b

或在 config.yaml 中永久設定：

model:
  provider: "nvidia"
  default: "nvidia/nemotron-3-super-120b-a12b"

提示 — 本地 NIM

對於本地部署（DGX Spark、本地 GPU），設定 NVIDIA_BASE_URL=http://localhost:8000/v1。NIM 提供與 build.nvidia.com 相同的 OpenAI 相容聊天補全 API，因此在雲端和本地之間切換只需改一行環境變數。

Hermes 會自動在每個傳送到 build.nvidia.com 的請求上附加 NIM 計費來源標頭 —— 無需設定。這會將消耗路由到 NVIDIA 計費儀表板中的正確來源。

GMI Cloud

透過 GMI Cloud 使用開放和推理模型 —— OpenAI 相容 API，API 金鑰認證。

# GMI Cloud
hermes chat --provider gmi --model deepseek-ai/DeepSeek-V3.2
# 需要：GMI_API_KEY 於 ~/.hermes/.env

或在 config.yaml 中永久設定：

model:
  provider: "gmi"
  default: "deepseek-ai/DeepSeek-V3.2"

基礎 URL 可透過 GMI_BASE_URL 覆寫（預設：https://api.gmi-serving.com/v1）。

StepFun

透過 StepFun 使用 Step 系列模型 —— OpenAI 相容 API，API 金鑰認證。

# StepFun
hermes chat --provider stepfun --model step-3.5-flash
# 需要：STEPFUN_API_KEY 於 ~/.hermes/.env

或在 config.yaml 中永久設定：

model:
  provider: "stepfun"
  default: "step-3.5-flash"

基礎 URL 可透過 STEPFUN_BASE_URL 覆寫（預設：https://api.stepfun.com/v1）。

Hugging Face Inference Providers

Hugging Face Inference Providers 透過統一的 OpenAI 相容端點（router.huggingface.co/v1）路由到 20+ 開放模型。請求會自動路由到最快的可用後端（Groq、Together、SambaNova 等），並自動容錯。

# 使用任何可用模型
hermes chat --provider huggingface --model Qwen/Qwen3.5-397B-A17B
# 需要：HF_TOKEN 於 ~/.hermes/.env

# 簡短別名
hermes chat --provider hf --model deepseek-ai/DeepSeek-V3.2

或在 config.yaml 中永久設定：

model:
  provider: "huggingface"
  default: "Qwen/Qwen3.5-397B-A17B"

在 huggingface.co/settings/tokens 取得你的 token —— 確保啟用 "Make calls to Inference Providers" 權限。包含免費層級（每月 $0.10 額度，不加收提供者費率）。

你可以在模型名稱後附加路由後綴：:fastest（預設）、:cheapest 或 :provider_name 以強制指定特定後端。

基礎 URL 可透過 HF_BASE_URL 覆寫。

透過 OAuth 的 Google Gemini (google-gemini-cli)

google-gemini-cli 提供者使用 Google 的 Cloud Code Assist 後端 —— 與 Google 自己的 gemini-cli 工具使用的 API 相同。這支援免費層級（個人帳戶的慷慨每日配額）和付費層級（透過 GCP 項目的 Standard/Enterprise）。

快速開始：

hermes model
# → 選擇 "Google Gemini (OAuth)"
# → 查看策略警告，確認
# → 瀏覽器開啟至 accounts.google.com，登入
# → 完成 — Hermes 在首次請求時自動配置你的免費層級

Hermes 預設搭载 Google 的公開 gemini-cli 桌面 OAuth 用戶端 —— 與 Google 在其開源 gemini-cli 中包含的憑證相同。桌面 OAuth 用戶端不是機密的（PKCE 提供安全性）。你不需要安裝 gemini-cli 或註冊自己的 GCP OAuth 用戶端。

認證運作方式：

• 對 accounts.google.com 執行 PKCE 授權碼流程
• 在 http://127.0.0.1:8085/oauth2callback 進行瀏覽器回調（繁忙時使用臨時端口備用）
• Token 儲存於 ~/.hermes/auth/google_oauth.json（chmod 0600，原子寫入，跨程序 fcntl 鎖）
• 到期前 60 秒自動刷新
• 無頭環境（SSH、HERMES_HEADLESS=1）→ 貼上模式備用
• 進行中刷新去重 —— 兩個並發請求不會重複刷新
• invalid_grant（撤銷的 refresh）→ 憑證檔案清除，提示使用者重新登入

推論運作方式：

• 流量傳送到 https://cloudcode-pa.googleapis.com/v1internal:generateContent （或 :streamGenerateContent?alt=sse 用於串流），而非付費的 v1beta/openai 端點
• 請求主體包裝 {project, model, user_prompt_id, request}
• OpenAI 格式的 messages[]、tools[]、tool_choice 被轉換為 Gemini 原生的 contents[]、tools[].functionDeclarations、toolConfig 格式
• 回應被轉換回 OpenAI 格式，使 Hermes 其餘部分正常運作

層級與專案 ID：

免費層級在首次使用時自動配置 Google 管理的專案。無需 GCP 設定。

配額監控：

/gquota

顯示每個模型的剩餘 Code Assist 配額及進度條：

Gemini Code Assist quota  (project: 123-abc)

  gemini-2.5-pro                      ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░   85%
  gemini-2.5-flash [input]            ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░   92%

警告 — 策略風險

Google 認為將 Gemini CLI OAuth 用戶端用於第三方軟體違反政策。部分使用者回報帳戶受到限制。為獲得最低風險體驗，請改用你自己的 API 金鑰搭配 gemini 提供者。Hermes 會在 OAuth 開始前顯示警告並要求明確確認。

自訂 OAuth 用戶端（可選）：

如果你想要註冊自己的 Google OAuth 用戶端 — 例如，將配額和同意範圍限定在你自己的 GCP 專案 — 請設定：

HERMES_GEMINI_CLIENT_ID=your-client.apps.googleusercontent.com
HERMES_GEMINI_CLIENT_SECRET=...   # 對桌面用戶端可選

在 console.cloud.google.com/apis/credentials 註冊一個桌面應用 OAuth 用戶端，並啟用 Generative Language API。

自訂與自架 LLM 提供者

Hermes Agent 可與任何 OpenAI 相容的 API 端點配合使用。如果伺服器實作了 /v1/chat/completions，你就可以將 Hermes 指向它。這意味著你可以使用本地模型、GPU 推論伺服器、多提供者路由器或任何第三方 API。

一般設定

設定自訂端點有三種方式：

互動式設定（推薦）：

hermes model
# 選擇 "Custom endpoint (self-hosted / VLLM / etc.)"
# 輸入：API 基礎 URL、API 金鑰、模型名稱

手動設定（config.yaml）：

# 在 ~/.hermes/config.yaml 中
model:
  default: your-model-name
  provider: custom
  base_url: http://localhost:8000/v1
  api_key: your-key-or-leave-empty-for-local

警告 — 舊版環境變數

.env 中的 LLM_MODEL 已移除 —— config.yaml 是模型和端點設定的唯一真實來源。OPENAI_BASE_URL 仍然有效，但僅適用於 openai-api 提供者（它覆寫 OpenAI 端點用於直接 API 金鑰存取）。對於其他提供者和自訂端點，請使用 hermes model 或直接在 config.yaml 中設定 model.base_url。如果你的 .env 中有過時的條目，它們會在下一次 hermes setup 或設定遷移時自動清除。

兩種方式都會持久儲存到 config.yaml，這是模型、提供者和基礎 URL 的真實來源。

使用 /model 切換模型

警告 — hermes model 與 /model

hermes model（從你的終端機執行，在任何聊天會話之外）是完整的提供者設定精靈。用於新增提供者、執行 OAuth 流程、輸入 API 金鑰和設定自訂端點。

/model（在活躍的 Hermes 聊天會話中輸入）只能在你已設定的提供者和模型之間切換。它無法新增提供者、執行 OAuth 或提示輸入 API 金鑰。如果你只設定了一個提供者（例如 OpenRouter），/model 只會顯示該提供者的模型。

要新增提供者： 退出你的會話（Ctrl+C 或 /quit），執行 hermes model，設定新提供者，然後開始新會話。

一旦你設定至少一個自訂端點，就可以在會話中切換模型：

/model custom:qwen-2.5          # 切換到自訂端點上的模型
/model custom                    # 從端點自動偵測模型
/model openrouter:claude-sonnet-4 # 切換回雲端提供者

如果你設定了具名自訂提供者（見下文），使用三段式語法：

/model custom:local:qwen-2.5    # 使用 "local" 自訂提供者搭配模型 qwen-2.5
/model custom:work:llama3       # 使用 "work" 自訂提供者搭配 llama3

切換提供者時，Hermes 會將基礎 URL 和提供者持久儲存到設定檔，使變更在重啟後仍有效。從自訂端點切換到內建提供者時，過時的基礎 URL 會自動清除。

提示

/model custom（裸呼叫，無模型名稱）會查詢你的端點的 /models API，如果恰好只有一個模型已載入，會自動選取。適用於運行單一模型的本地伺服器。

以下所有內容都遵循相同的模式 —— 只需更改 URL、金鑰和模型名稱。

---

Ollama — 本地模型，零設定

Ollama 使用一個指令在本地運行開放權重模型。最適合：快速本地實驗、注重隱私的工作、離線使用。透過 OpenAI 相容 API 支援工具呼叫。

# 安裝並運行模型
ollama pull qwen2.5-coder:32b
ollama serve   # 在連接埠 11434 啟動

然後設定 Hermes：

hermes model
# 選擇 "Custom endpoint (self-hosted / VLLM / etc.)"
# 輸入 URL：http://localhost:11434/v1
# 跳過 API 金鑰（Ollama 不需要）
# 輸入模型名稱（例如 qwen2.5-coder:32b）

或直接設定 config.yaml：

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

注意 — Ollama 預設使用非常低的上下文長度

Ollama 不會預設使用你模型的完整上下文視窗。根據你的 VRAM，預設值為：

可用 VRAM	預設上下文
少於 24 GB	4,096 tokens
24–48 GB	32,768 tokens
48+ GB	256,000 tokens

Hermes Agent 在使用工具的代理模式下至少需要 64,000 tokens 的上下文。較小的視窗會在啟動時被拒絕，因為系統提示、工具架構和運行中的對話狀態需要足夠空間才能可靠地執行多步驟工作流程。

如何增加（擇一）：

# 選項 1：透過環境變數設定伺服器範圍（推薦）
OLLAMA_CONTEXT_LENGTH=64000 ollama serve

# 選項 2：用於 systemd 管理的 Ollama
sudo systemctl edit ollama.service
# 新增：Environment="OLLAMA_CONTEXT_LENGTH=64000"
# 然後：sudo systemctl daemon-reload && sudo systemctl restart ollama

# 選項 3：嵌入自訂模型（按模型持久化）
echo -e "FROM qwen2.5-coder:32b\nPARAMETER num_ctx 64000" > Modelfile
ollama create qwen2.5-coder-64k -f Modelfile

你無法透過 OpenAI 相容 API 設定上下文長度（/v1/chat/completions）。它必須在伺服器端或透過 Modelfile 設定。這是整合 Ollama 與 Hermes 等工具時最常見的困惑來源。

驗證你的上下文已正確設定：

ollama ps
# 查看 CONTEXT 欄位 — 應顯示你設定的值

提示

使用 ollama list 列出可用模型。從 Ollama 函式庫 使用 ollama pull <model> 拉取任何模型。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
# 選擇 "Custom endpoint (self-hosted / VLLM / etc.)"
# 輸入 URL：http://localhost:8000/v1
# 跳過 API 金鑰（或在你使用 --api-key 設定 vLLM 時輸入一個）
# 輸入模型名稱：meta-llama/Llama-3.1-70B-Instruct

上下文長度： vLLM 預設讀取模型的 max_position_embeddings。如果超出你的 GPU 記憶體，它會出錯並要求你設定更低的 --max-model-len。你也可以使用 --max-model-len auto 自動找到適合的最大值。設定 --gpu-memory-utilization 0.95（預設 0.9）以在 VRAM 中擠出更多上下文。

工具呼叫需要明確標誌：

支援的解析器：hermes（Qwen 2.5、Hermse 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
# 選擇 "Custom endpoint (self-hosted / VLLM / etc.)"
# 輸入 URL：http://localhost:30000/v1
# 輸入模型名稱：meta-llama/Llama-3.1-70B-Instruct

上下文長度： SGLang 預設從模型設定中讀取。使用 --context-length 覆寫。如果需要超出模型宣告的最大值，設定 SGLANG_ALLOW_OVERWRITE_LONGER_CONTEXT_LEN=1。

工具呼叫： 使用 --tool-call-parser 搭配適合你模型系列的解析器：qwen（Qwen 2.5）、llama3、llama4、deepseekv3、mistral、glm。沒有此標誌，工具呼叫會以純文字形式回傳。

注意 — SGLang 預設最大輸出為 128 tokens

如果回應似乎被截斷，請在你的請求中新增 max_tokens，或在伺服器上設定 --default-max-tokens。如果在請求中未指定，SGLang 的預設值為每次回應僅 128 tokens。

---

llama.cpp / llama-server — CPU 與 Metal 推論

llama.cpp 在 CPU、Apple Silicon（Metal）和消費級 GPU 上運行量化模型。最適合：無需資料中心 GPU 即可運行模型、Mac 使用者、邊緣部署。

# 建構並啟動 llama-server
cmake -B build && cmake --build build --config Release
./build/bin/llama-server \
  --jinja -fa \
  -c 64000 \
  -ngl 99 \
  -m models/qwen2.5-coder-32b-instruct-Q4_K_M.gguf \
  --port 8080 --host 0.0.0.0

上下文長度（-c）： 近期版本預設為 0，這會從 GGUF 元資料讀取模型的訓練上下文。對於具有 128k+ 訓練上下文的模型，嘗試分配完整的 KV 快取時可能會導致記憶體不足。為 Hermes 明確設定 -c 至少 64,000 tokens。如果使用並行插槽（-np），總上下文會在插槽之間分配 — 以 -c 64000 -np 4 為例，每個插槽只能獲得 16k，低於 Hermes 每個活躍會話的最低要求。

然後設定 Hermes 指向它：

hermes model
# 選擇 "Custom endpoint (self-hosted / VLLM / etc.)"
# 輸入 URL：http://localhost:8080/v1
# 跳過 API 金鑰（本地伺服器不需要）
# 輸入模型名稱 — 或留空以在只載入一個模型時自動偵測

這會將端點儲存到 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 欄位應該存在。

提示

從 Hugging Face 下載 GGUF 模型。Q4_K_M 量化在品質與記憶體使用之間提供最佳平衡。

---

LM Studio — 帶有本地模型的桌面應用程式

LM Studio 是一個用於透過 GUI 運行本地模型的桌面應用程式。最適合：偏好視覺介面的使用者、快速模型測試、macOS/Windows/Linux 上的開發者。

從 LM Studio 應用程式啟動伺服器（開發者分頁 → 啟動伺服器），或使用 CLI：

lms server start                        # 在連接埠 1234 啟動
lms load qwen2.5-coder --context-length 64000

然後設定 Hermes：

hermes model
# 選擇 "LM Studio"
# 按 Enter 使用 http://localhost:1234/v1
# 選擇已探索到的模型之一
# 如果 LM Studio 伺服器認證已啟用，在提示時輸入 LM_API_KEY

Hermes 會自動載入具有 64K 上下文長度的 LM Studio 模型。

在 LM Studio 中更改上下文長度：

1. 點擊模型選擇器旁邊的齒輪圖示
2. 將「上下文長度」設定為至少 64000 以獲得流暢體驗
3. 重新載入模型以使變更生效
4. 如果你的機器無法容納 64000，考慮使用更小但具有更大上下文長度的模型。

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

你可以使用 CLI 來估算模型是否適合：lms load model-name --context-length 64000 --estimate-only

要設定持久的按模型預設值：我的模型分頁 → 模型上的齒輪圖示 → 設定上下文大小。 :::

工具呼叫： 自 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 如預期運作 —— 它們共享相同的網路命名空間。跳過本節。

選項 1：鏡像網路模式（推薦）

在 Windows 11 22H2+ 上可用，鏡像模式使 localhost 在 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   # Windows 上的 Ollama — 可用
   

備註 — Hyper-V 防火牆

在某些 Windows 11 版本上，Hyper-V 防火牆預設會封鎖鏡像連線。如果啟用鏡像模式後 localhost 仍無法運作，請在管理員 PowerShell 中執行：

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

選項 2：使用 Windows 主機 IP（Windows 10 / 較舊版本）

如果無法使用鏡像模式，從 WSL2 內部找到 Windows 主機 IP 並使用它代替 localhost：

# 取得 Windows 主機 IP（WSL2 虛擬網路的預設閘道）
ip route show | grep -i default | awk '{ print $3 }'
# 範例輸出：172.29.192.1

在你的 Hermes 設定中使用該 IP：

model:
  default: qwen2.5-coder:32b
  provider: custom
  base_url: http://172.29.192.1:11434/v1   # Windows 主機 IP，非 localhost

提示 — 動態輔助工具

主機 IP 可能在 WSL2 重啟時變更。你可以在 shell 中動態取得：

export WSL_HOST=$(ip route show | grep -i default | awk '{ print $3 }')
echo "Windows host at: $WSL_HOST"
curl http://$WSL_HOST:11434/v1/models   # 測試 Ollama

或使用你機器的 mDNS 名稱（需要 WSL2 中的 libnss-mdns）：

sudo apt install libnss-mdns
curl http://$(hostname).local:11434/v1/models

伺服器綁定地址（NAT 模式所需）

如果你使用選項 2（使用主機 IP 的 NAT 模式），Windows 上的模型伺服器必須接受來自 127.0.0.1 以外的連線。預設情況下，大多數伺服器只在 localhost 上監聽 —— NAT 模式下的 WSL2 連線來自不同的虛擬子網路，會被拒絕。在鏡像模式下，localhost 直接映射，因此預設的 127.0.0.1 綁定可以正常運作。

Windows 上的 Ollama（詳細）： Ollama 作為 Windows 服務運行。要設定 OLLAMA_HOST：

1. 開啟系統內容 → 環境變數
2. 新增新的系統變數：OLLAMA_HOST = 0.0.0.0
3. 重新啟動 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 回應，就表示沒問題。在你的 Hermes 設定中使用相同的 URL 作為 base_url。

---

本地模型疑難排解

這些問題影響所有與 Hermes 配合使用的本地推論伺服器。

從 WSL2 連線到 Windows 主機上的模型伺服器時出現「Connection refused」

如果你在 WSL2 內執行 Hermes，而模型伺服器在 Windows 主機上，http://localhost:<port> 在 WSL2 的預設 NAT 網路模式下無法運作。請參閱上方的 WSL2 網路 了解修復方式。

工具呼叫以文字形式顯示而非執行

模型輸出類似 {"name": "web_search", "arguments": {...}} 的內容作為訊息，而非實際呼叫工具。

原因： 你的伺服器未啟用工具呼叫，或模型不支援伺服器的工具呼叫實作。

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

原因： 上下文視窗太小。當對話超出上下文限制時，大多數伺服器會靜默丟棄較舊的訊息。Hermes 的系統提示 + 工具架構本身可能使用 4k–8k tokens。

診斷：

# 檢查 Hermes 認為的上下文大小
# 查看啟動行："Context limit: X tokens"

# 檢查你伺服器的實際上下文
# Ollama：ollama ps（CONTEXT 欄位）
# llama.cpp：curl http://localhost:8080/props | jq '.default_generation_settings.n_ctx'
# vLLM：檢查啟動引數中的 --max-model-len

修復： 為代理使用設定至少 64,000 tokens 的上下文。請參閱上方各伺服器章節了解具體標誌。

啟動時顯示「Context limit: 2048 tokens」

Hermes 從你的伺服器的 /v1/models 端點自動偵測上下文長度。如果伺服器回傳低值（或根本未回傳），Hermes 會使用模型宣告的限制，這可能是錯誤的。

修復： 在 config.yaml 中明確設定：

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

回應在句子中間被截斷

可能原因：

1. 伺服器上的輸出上限（max_tokens）過低 — SGLang 預設為每次回應 128 tokens。在伺服器上設定 --default-max-tokens 或在 config.yaml 中使用 model.max_tokens 設定 Hermes。注意：max_tokens 只控制回應長度 — 與你的對話歷史能多長（那是 context_length）無關。
2. 上下文耗盡 — 模型填滿了其上下文視窗。增加 model.context_length 或在 Hermes 中啟用上下文壓縮。

---

LiteLLM Proxy — 多提供者閘道

LiteLLM 是一個 OpenAI 相容的代理，在單一 API 後統一了 100+ LLM 提供者。最適合：無需更改設定即可切換提供者、負載平衡、容錯鏈、預算控制。

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

# 或使用設定檔配置多個模型：
litellm --config litellm_config.yaml --port 4000

然後使用 hermes model → Custom endpoint → http://localhost:4000/v1 設定 Hermes。

帶有容錯的 litellm_config.yaml 範例：

model_list:
  - model_name: "best"
    litellm_params:
      model: anthropic/claude-sonnet-4
      api_key: sk-ant-...
  - model_name: "best"
    litellm_params:
      model: openai/gpt-4o
      api_key: sk-...
router_settings:
  routing_strategy: "latency-based-routing"

---

ClawRouter — 成本最佳化路由

ClawRouter 由 BlockRunAI 開發，是一個本地路由代理，根據查詢複雜度自動選擇模型。它在 14 個維度上對請求進行分類，並路由到能處理任務的最便宜模型。支付方式為 USDC 加密貨幣（無需 API 金鑰）。

# 安裝並啟動
npx @blockrun/clawrouter    # 在連接埠 8402 啟動

然後使用 hermes model → Custom endpoint → http://localhost:8402/v1 → 模型名稱 blockrun/auto 設定 Hermes。

路由設定檔：

備註

ClawRouter 需要 Base 或 Solana 上的 USDC 資助錢包進行支付。所有請求都透過 BlockRun 的後端 API 路由。執行 npx @blockrun/clawrouter doctor 檢查錢包狀態。

---

其他相容提供者

任何具有 OpenAI 相容 API 的服務都可使用。一些熱門選項：

使用 hermes model → Custom endpoint 或在 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 — 社群維護的註冊表，包含 100+ 提供者中 3800+ 模型的提供者特定上下文長度
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: 64000
      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 省略 — Hermes 對無金鑰的本地伺服器使用 "no-key-required"
  - name: work
    base_url: https://gpu-server.internal.corp/v1
    key_env: CORP_API_KEY
    api_mode: chat_completions   # 由 `hermes model` → Custom Endpoint 精靈明確設定；自動偵測仍作為備用
  - name: anthropic-proxy
    base_url: https://proxy.example.com/anthropic
    key_env: ANTHROPIC_PROXY_KEY
    api_mode: anthropic_messages  # 用於相容 Anthropic 的代理

一些 OpenAI 相容端點需要提供者特定的請求主體欄位。在匹配的自訂提供者中加入 extra_body 映射，Hermes 會將其合併到該端點的每個聊天補全請求中：

custom_providers:
  - name: gemma-local
    base_url: http://localhost:8080/v1
    model: google/gemma-4-31b-it
    extra_body:
      enable_thinking: true
      reasoning_effort: high

使用你的伺服器文件記錄的格式。例如，vLLM Gemma 部署和某些 NVIDIA NIM 端點預期 enable_thinking 位於 chat_template_kwargs 下，而非作為頂層 extra_body 欄位：

extra_body:
  chat_template_kwargs:
    enable_thinking: true

hermes model → Custom Endpoint 精靈現在會明確提示 api_mode 並將你的答案持久儲存到 config.yaml。基於 URL 的自動偵測（例如 /anthropic 路徑 → anthropic_messages）在欄位留空時仍作為備用。

自訂提供者模型的原生視覺。 如果你的自訂端點提供視覺功能模型且不在 models.dev 中，設定 model.supports_vision: true，使 Hermes 以原生方式（作為 image_url 部分）路由附加的圖片，而非透過 vision_analyze 預處理。單一開關 — 無需同時設定 agent.image_input_mode: native。

model:
  provider: custom
  base_url: http://localhost:8080/v1
  default: qwen3.6-35b-a3b
  supports_vision: true   # 以原生方式傳送圖片；否則 vision_analyze 會預先描述它們

相同的金鑰也適用於按具名提供者的模型（custom_providers[*].models[*].supports_vision），並接受標準的 YAML 布林值（true/false/yes/no/on/off/1/0）。

在會話中使用三段式語法切換：

/model custom:local:qwen-2.5       # 使用 "local" 端點搭配 qwen-2.5
/model custom:work:llama3-70b      # 使用 "work" 端點搭配 llama3-70b
/model custom:anthropic-proxy:claude-sonnet-4  # 使用代理

你也可以從互動式 hermes model 選單中選擇具名自訂提供者。

---

實用食譜：Together AI、Groq、Perplexity

其他相容提供者中列出的雲端提供者都使用 OpenAI 的 REST 格式，因此它們在 custom_providers: 下的連線方式相同。以下是三個實用食譜。每個都放入 ~/.hermes/config.yaml，對應的 API 金鑰放在 ~/.hermes/.env 中。

Together AI

以低於第一方 API 許多的價格託管開放權重模型（Llama、MiniMax、Gemma、DeepSeek、Qwen）。多模型群組的良好預設選擇。

# ~/.hermes/config.yaml
custom_providers:
  - name: together
    base_url: https://api.together.xyz/v1
    key_env: TOGETHER_API_KEY
    # api_mode: chat_completions  # 預設 — 無需設定

model:
  default: MiniMaxAI/MiniMax-M2.7   # 或 together.ai/models 上的任何模型
  provider: custom:together

# ~/.hermes/.env
TOGETHER_API_KEY=your-together-key

在會話中切換模型：

/model custom:together:meta-llama/Llama-3.3-70B-Instruct-Turbo
/model custom:together:google/gemma-4-31b-it
/model custom:together:deepseek-ai/DeepSeek-V3

Together 的 /v1/models 端點可用，因此 hermes model 可以自動探索可用模型。

Groq

超快推論（Llama-3.3-70B 上約 500 tok/s）。目錄較小，但對延遲敏感的互動式使用表現強勁。

# ~/.hermes/config.yaml
custom_providers:
  - name: groq
    base_url: https://api.groq.com/openai/v1
    key_env: GROQ_API_KEY

model:
  default: llama-3.3-70b-versatile
  provider: custom:groq

# ~/.hermes/.env
GROQ_API_KEY=your-groq-key

Perplexity

當你想要一個自動進行即時網路搜尋和引用的模型時很有用。對可用模型有嚴格限制 — 請檢查 perplexity.ai/settings/api 了解當前清單。

# ~/.hermes/config.yaml
custom_providers:
  - name: perplexity
    base_url: https://api.perplexity.ai
    key_env: PERPLEXITY_API_KEY

model:
  default: sonar
  provider: custom:perplexity

# ~/.hermes/.env
PERPLEXITY_API_KEY=your-perplexity-key

在一個設定中使用多個提供者

三個食譜可以組合使用 — 全部一起使用並透過 /model custom:<name>:<model> 按輪次切換：

custom_providers:
  - name: together
    base_url: https://api.together.xyz/v1
    key_env: TOGETHER_API_KEY
  - name: groq
    base_url: https://api.groq.com/openai/v1
    key_env: GROQ_API_KEY
  - name: perplexity
    base_url: https://api.perplexity.ai
    key_env: PERPLEXITY_API_KEY

model:
  default: MiniMaxAI/MiniMax-M2.7
  provider: custom:together      # 從 Together 啟動；之後自由切換

提示 — 疑難排解

• 在 #15083 的 CLI 驗證器修復後，hermes doctor 不應對這些名稱中的任何一個列印 Unknown provider 警告。
• 如果提供者的 /v1/models 端點無法到達（Perplexity 是常見的），hermes model 會帶有警告地持久儲存模型，而非硬性拒絕 — 請參閱 #15136。
• 要完全跳過 custom_providers: 並使用裸 provider: custom 搭配 CUSTOM_BASE_URL 環境變數，請參閱 #15103。

---

選擇合適的設定

提示

你可以隨時使用 hermes model 在提供者之間切換 — 無需重啟。無論使用哪個提供者，你的對話歷史、記憶和技能都會延續。

可選 API 金鑰

自架 Firecrawl

預設情況下，Hermes 使用 Firecrawl 雲端 API 進行網路搜尋和爬蟲。如果你偏好在本地運行 Firecrawl，可以將 Hermes 指向自架實例。請參閱 Firecrawl 的 SELF_HOST.md 了解完整設定說明。

你獲得的： 無需 API 金鑰、無速率限制、無每頁成本、完全資料自主權。

你失去的： 雲端版本使用 Firecrawl 的專有「Fire-engine」進行高級反機器人繞過（Cloudflare、CAPTCHAs、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
   # 在 .env 中設定：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"（預設）、"throughput" 或 "latency"
  # only: ["anthropic"]      # 只使用這些提供者
  # ignore: ["deepinfra"]    # 跳過這些提供者
  # order: ["anthropic", "google"]  # 按此順序嘗試提供者
  # require_parameters: true  # 只使用支援所有請求參數的提供者
  # data_collection: "deny"   # 排除可能儲存/訓練資料的提供者

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

OpenRouter Pareto Code 路由器

OpenRouter 在 openrouter/pareto-code 提供了一個實驗性的程式模型路由器，自動將請求路由到符合程式品質門檻的最便宜模型（由 Artificial Analysis 排名）。選擇此模型並在 ~/.hermes/config.yaml 中調整 min_coding_score 參數：

model:
  provider: openrouter
  model: openrouter/pareto-code

openrouter:
  min_coding_score: 0.65   # 0.0–1.0；越高 = 越強（越貴）的程式模型。預設 0.65。

說明：

• min_coding_score 只有在 model.model 為 openrouter/pareto-code 時才會傳送。在任何其他模型上，此值無效。
• 設為空字串（或移除該行）讓 OpenRouter 選擇最強的可用程式模型 — 這省略 plugins 區塊時的文件記錄行為。
• 選擇在給定分數上是確定性的，但實際選擇的模型可能隨 Pareto 前沿移動（新模型、基準測試更新）而變化。
• 請參閱 OpenRouter 的 Pareto 路由器文件 了解完整的路由器行為。
• 要將 Pareto Code 路由器用於特定的輔助任務（壓縮、視覺等）而非主代理，請在該任務下設定 extra_body.plugins — 請參閱輔助模型 → OpenRouter 路由與輔助任務的 Pareto Code。

容錯提供者

設定備用提供者鏈，當主要模型失敗時（速率限制、伺服器錯誤、認證失敗）Hermes 會按順序嘗試。標準格式是頂層的 fallback_providers: 列表：

fallback_providers:
  - provider: openrouter
    model: anthropic/claude-sonnet-4
  - provider: anthropic
    model: claude-sonnet-4
    # base_url: http://localhost:8000/v1    # 可選，用於自訂端點
    # api_mode: chat_completions           # 可選覆寫

舊版的單對 fallback_model: 字典仍然接受以保持向後相容：

fallback_model:
  provider: openrouter
  model: anthropic/claude-sonnet-4

啟用時，容錯會在會話中切換模型和提供者，不會遺失你的對話。鏈會逐項嘗試；每個會話只觸發一次。

支援的提供者：openrouter、nous、novita、openai-codex、copilot、copilot-acp、anthropic、gemini、google-gemini-cli、qwen-oauth、huggingface、zai、kimi-coding、kimi-coding-cn、minimax、minimax-cn、minimax-oauth、deepseek、nvidia、xai、xai-oauth、ollama-cloud、bedrock、azure-foundry、opencode-zen、opencode-go、kilocode、xiaomi、arcee、gmi、stepfun、lmstudio、alibaba、alibaba-coding-plan、tencent-tokenhub、custom。

提示

容錯僅透過 config.yaml 設定 — 或透過 hermes fallback 互動式設定。關於何時觸發、鏈如何推進以及與輔助任務和委託的互動方式的完整詳情，請參閱容錯提供者。

---

參閱

• 設定 — 一般設定（目錄結構、設定優先順序、終端後端、記憶、壓縮等）
• 環境變數 — 所有環境變數的完整參考

---

---

Nous Portal