adding providers — The Hermes Bible

Hermes 已經可以透過自訂供應商路徑與任何 OpenAI 相容端點通訊。除非你想要該服務的一等 UX，否則不要新增內建供應商：

供應商特定的認證或權杖刷新
精選的模型目錄
設定 / hermes model 選單項目
provider:model 語法的供應商別名
需要適配器的非 OpenAI API 形式

如果供應商只是「另一個 OpenAI 相容基礎 URL 和 API 金鑰」，命名自訂供應商可能就足夠了。

心智模型

內建供應商需要在幾個層級上對齊：

hermes_cli/auth.py 決定憑證如何被找到。
hermes_cli/runtime_provider.py 將其轉換為執行時資料：
- provider
- api_mode
- base_url
- api_key
- source
run_agent.py 使用 api_mode 決定請求如何被建構和發送。
hermes_cli/models.py 和 hermes_cli/main.py 讓供應商出現在 CLI 中。（hermes_cli/setup.py 自動委託給 main.py——不需要更改那裡。）
agent/auxiliary_client.py 和 agent/model_metadata.py 保持副任務和 token 預算運作。

重要的抽象是 api_mode。

大多數供應商使用 chat_completions。
Codex 使用 codex_responses。
Anthropic 使用 anthropic_messages。
新的非 OpenAI 協議通常意味著新增新的適配器和新的 api_mode 分支。

首先選擇實作路徑

路徑 A — OpenAI 相容供應商

當供應商接受標準 chat-completions 風格的請求時使用此路徑。

典型工作：

新增認證中繼資料
新增模型目錄 / 別名
新增執行時解析
新增 CLI 選單接線
新增輔助模型預設值
新增測試和使用者文件

你通常不需要新的適配器或新的 api_mode。

路徑 B — 原生供應商

當供應商的行為不像 OpenAI chat completions 時使用此路徑。

目前樹中的範例：

codex_responses
anthropic_messages

此路徑包含路徑 A 的所有內容加上：

agent/ 中的供應商適配器
run_agent.py 中用於請求建構、分派、用量提取、中斷處理和回應正規化的分支
適配器測試

檔案檢查清單

每個內建供應商都需要的

hermes_cli/auth.py
hermes_cli/models.py
hermes_cli/runtime_provider.py
hermes_cli/main.py
agent/auxiliary_client.py
agent/model_metadata.py
測試
website/docs/ 下的使用者文件

提示

hermes_cli/setup.py 不需要更改。設定精靈委託 provider/model 選擇給 main.py 中的 select_provider_and_model()——在那裡新增的供應商自動在 hermes setup 中可用。

原生/非 OpenAI 供應商額外需要的

agent/<provider>_adapter.py
run_agent.py
若需要供應商 SDK 則 pyproject.toml

快速路徑：簡單 API 金鑰供應商

如果你的供應商只是一個使用單一 API 金鑰認證的 OpenAI 相容端點，你不需要觸及 auth.py、runtime_provider.py、main.py 或下方完整檢查清單中的任何其他檔案。

你只需要：

plugins/model-providers/<your-provider>/ 下的外掛目錄，包含：
- __init__.py — 在模組層級呼叫 register_provider(profile)
- plugin.yaml — 設定檔（name、kind: model-provider、version、description）
就這樣。Provider 外掛在首次有東西呼叫 get_provider_profile() 或 list_providers() 時自動載入——內建外掛（此 repo）和 $HERMES_HOME/plugins/model-providers/ 中的使用者外掛都會被拾取。

當你新增外掛並呼叫 register_provider() 時，以下會自動連接：

auth.py 中的 PROVIDER_REGISTRY 項目（憑證解析、env-var 查找）
api_mode 設定為 chat_completions
base_url 來自設定或宣告的 env var
env_vars 按優先順序檢查 API 金鑰
fallback_models 列表為供應商註冊
--provider CLI 旗標接受供應商 ID
hermes model 選單包含該供應商
hermes setup 精靈自動委託給 main.py
provider:model 別名語法運作
執行時解析器回傳正確的 base_url 和 api_key
--provider <name> CLI 旗標接受供應商 ID
降級模型啟用可以乾淨地切換到該供應商

$HERMES_HOME/plugins/model-providers/<name>/ 中的使用者外掛覆寫同名的內建外掛（在 register_provider() 中後寫者勝出）——因此第三方可以不必編輯 repo 就能 monkey-patch 或替換任何內建 profile。

參見 plugins/model-providers/nvidia/ 或 plugins/model-providers/gmi/ 作為範本，以及完整的模型供應商外掛指南了解欄位參考、hook 慣用法和端到端範例。

完整路徑：OAuth 和複雜供應商

當你的供應商需要以下任何內容時，使用下方的完整檢查清單：

OAuth 或權杖刷新（Nous Portal、Codex、Google Gemini、Qwen Portal、Copilot）
需要新適配器的非 OpenAI API 形式（Anthropic Messages、Codex Responses）
自訂端點偵測或多區域探測（z.ai、Kimi）
精選的靜態模型目錄或即時 /models 取得
供應商特定的 hermes model 選單項目，帶有專屬認證流程

步驟 1：選擇一個標準供應商 ID

選擇單一供應商 ID 並在所有地方使用它。

來自 repo 的範例：

openai-codex
kimi-coding
minimax-cn

相同的 ID 應出現在：

hermes_cli/auth.py 中的 PROVIDER_REGISTRY
hermes_cli/models.py 中的 _PROVIDER_LABELS
hermes_cli/auth.py 和 hermes_cli/models.py 中的 _PROVIDER_ALIASES
hermes_cli/main.py 中的 CLI --provider 選項
設定 / 模型選擇分支
輔助模型預設值
測試

如果 ID 在這些檔案之間不一致，供應商會感覺半接線：認證可能運作，但 /model、設定或執行時解析靜默地遺漏它。

步驟 2：在 `hermes_cli/auth.py` 中新增認證中繼資料

對於 API 金鑰供應商，在 PROVIDER_REGISTRY 中新增一個 ProviderConfig 項目，包含：

id
name
auth_type="api_key"
inference_base_url
api_key_env_vars
選用的 base_url_env_var

也將別名加入 _PROVIDER_ALIASES。

使用現有供應商作為範本：

簡單 API 金鑰路徑：Z.AI、MiniMax
帶端點偵測的 API 金鑰路徑：Kimi、Z.AI
原生權杖解析：Anthropic
OAuth / auth-store 路徑：Nous、OpenAI Codex

需要在此回答的問題：

Hermes 應該檢查哪些環境變數，以什麼優先順序？
供應商是否需要基礎 URL 覆寫？
是否需要端點探測或權杖刷新？
當憑證缺少時，認證錯誤應該說什麼？

如果供應商需要比「查找 API 金鑰」更多的東西，請新增專用的憑證解析器，而非將邏輯塞進不相關的分支。

步驟 3：在 `hermes_cli/models.py` 中新增模型目錄和別名

更新供應商目錄，使供應商在選單和 provider:model 語法中運作。

典型編輯：

_PROVIDER_MODELS
_PROVIDER_LABELS
_PROVIDER_ALIASES
list_available_providers() 中的供應商顯示順序
provider_model_ids()（若供應商支援即時 /models 取得）

若供應商暴露即時模型列表，優先使用它並將 _PROVIDER_MODELS 作為靜態回退。

此檔案也使這些輸入運作：

anthropic:claude-sonnet-4-6
kimi:model-name

如果別名在此缺少，供應商可能正確認證但在 /model 解析中仍然失敗。

步驟 4：在 `hermes_cli/runtime_provider.py` 中解析執行時資料

resolve_runtime_provider() 是 CLI、閘道器、排程任務、ACP 和輔助用戶端共用的路徑。

新增一個分支，回傳至少包含以下內容的字典：

{
    "provider": "your-provider",
    "api_mode": "chat_completions",  # 或你的原生模式
    "base_url": "https://...",
    "api_key": "...",
    "source": "env|portal|auth-store|explicit",
    "requested_provider": requested_provider,
}

若供應商是 OpenAI 相容的，api_mode 通常應保持 chat_completions。

小心 API 金鑰優先順序。Hermes 已包含避免將 OpenRouter 金鑰洩漏到不相關端點的邏輯。新供應商應同樣明確地指定哪個金鑰送到哪個基礎 URL。

步驟 5：在 `hermes_cli/main.py` 中接線 CLI

供應商在出現在互動式 hermes model 流程之前是不可發現的。

在 hermes_cli/main.py 中更新：

provider_labels 字典
select_provider_and_model() 中的 providers 列表
供應商分派（if selected_provider == ...）
--provider 參數選項
登入/登出選項（若供應商支援這些流程）
_model_flow_<provider>() 函數，或若合適則重用 _model_flow_api_key_provider()

提示

hermes_cli/setup.py 不需要更改——它從 main.py 呼叫 select_provider_and_model()，因此你的新供應商自動出現在 hermes model 和 hermes setup 中。

步驟 6：保持輔助呼叫運作

兩個檔案在此重要：

`agent/auxiliary_client.py`

若這是直接 API 金鑰供應商，將便宜/快速的預設輔助模型加入 _API_KEY_PROVIDER_AUX_MODELS。

輔助任務包括：

視覺摘要
網頁擷取摘要
上下文壓縮摘要
會話搜尋摘要
記憶刷新

若供應商沒有合理的輔助預設值，副任務可能不良回退或意外使用昂貴的主模型。

`agent/model_metadata.py`

為供應商的模型新增上下文長度，使 token 預算、壓縮閾值和限制保持合理。

步驟 7：若供應商是原生的，新增適配器和 `run_agent.py` 支援

若供應商不是純 chat completions，將供應商特定邏輯隔離在 agent/<provider>_adapter.py 中。

保持 run_agent.py 專注於協調。它應呼叫適配器輔助函數，而非在整個檔案中手動建構供應商 payload。

原生供應商通常需要在這些位置工作：

新適配器檔案

典型職責：

建構 SDK / HTTP 用戶端
解析權杖
將 OpenAI 風格的對話訊息轉換為供應商的請求格式
視需要轉換工具 schema
將供應商回應正規化回 run_agent.py 期望的格式
提取用量和 finish-reason 資料

`run_agent.py`

搜尋 api_mode 並審計每個開關點。至少驗證：

__init__ 選擇新的 api_mode
用戶端建構對供應商運作
_build_api_kwargs() 知道如何格式化請求
_interruptible_api_call() 分派到正確的用戶端呼叫
中斷/用戶端重建路徑運作
回應驗證接受供應商的形式
finish-reason 提取正確
token 用量提取正確
降級模型啟用可以乾淨地切換到新供應商
摘要產生和記憶刷新路徑仍然運作

也在 run_agent.py 中搜尋 self.client.。任何假設標準 OpenAI 用戶端存在的程式碼路徑在原生供應商使用不同的用戶端物件或 self.client = None 時可能中斷。

提示快取和供應商特定請求欄位

提示快取和供應商特定的調節旋鈕很容易退化。

樹中已有的範例：

Anthropic 有原生的提示快取路徑
OpenRouter 獲得供應商路由欄位
並非每個供應商都應接收每個請求端選項

當你新增原生供應商時，仔細檢查 Hermes 只發送該供應商實際理解的欄位。

步驟 8：測試

至少觸及保護供應商接線的測試。

常見位置：

tests/hermes_cli/test_runtime_provider_resolution.py
tests/cli/test_cli_provider_resolution.py
tests/hermes_cli/test_model_switch_custom_providers.py（及相鄰的 tests/hermes_cli/test_model_switch_*.py）
tests/hermes_cli/test_setup_model_provider.py
tests/run_agent/test_provider_parity.py
tests/run_agent/test_run_agent.py
tests/test_<provider>_adapter.py（原生供應商）

對於僅文件的範例，確切的檔案集可能不同。重點是涵蓋：

認證解析
CLI 選單/供應商選擇
執行時供應商解析
Agent 執行路徑
provider:model 解析
任何適配器特定的訊息轉換

停用 xdist 執行測試：

source venv/bin/activate
python -m pytest tests/hermes_cli/test_runtime_provider_resolution.py tests/cli/test_cli_provider_resolution.py tests/hermes_cli/test_setup_model_provider.py tests/run_agent/test_provider_parity.py -n0 -q

對於更深層的變更，在推送前執行完整套件：

source venv/bin/activate
python -m pytest tests/ -n0 -q

步驟 9：即時驗證

測試後，執行真實的冒煙測試。

source venv/bin/activate
python -m hermes_cli.main chat -q "Say hello" --provider your-provider --model your-model

若你更改了選單，也測試互動式流程：

source venv/bin/activate
python -m hermes_cli.main model
python -m hermes_cli.main setup

對於原生供應商，也驗證至少一次工具呼叫，而非純文字回應。

步驟 10：更新使用者文件

若供應商旨在作為一等選項發行，也更新使用者文件：

website/docs/getting-started/quickstart.md
website/docs/user-guide/configuration.md
website/docs/reference/environment-variables.md

開發者可以完美地接線供應商，但仍然讓使用者無法發現所需的環境變數或設定流程。

OpenAI 相容供應商檢查清單

當供應商是標準 chat completions 時使用此清單。

ProviderConfig 已加入 hermes_cli/auth.py
別名已加入 hermes_cli/auth.py 和 hermes_cli/models.py
模型目錄已加入 hermes_cli/models.py
執行時分支已加入 hermes_cli/runtime_provider.py
CLI 接線已加入 hermes_cli/main.py（setup.py 自動繼承）
輔助模型已加入 agent/auxiliary_client.py
上下文長度已加入 agent/model_metadata.py
執行時/CLI 測試已更新
使用者文件已更新

原生供應商檢查清單

當供應商需要新的協議路徑時使用此清單。

OpenAI 相容檢查清單中的所有內容
適配器已加入 agent/<provider>_adapter.py
run_agent.py 中支援新的 api_mode
中斷/重建路徑運作
用量和 finish-reason 提取運作
降級路徑運作
適配器測試已新增
即時冒煙測試通過

常見陷阱

1. 將供應商加入認證但不加入模型解析

這使憑證正確解析，而 /model 和 provider:model 輸入失敗。

2. 忘記 `config["model"]` 可以是字串或字典

大量供應商選擇程式碼必須正規化兩種形式。

3. 假設需要內建供應商

如果服務只是 OpenAI 相容的，自訂供應商可能已經以更少的維護解決了使用者問題。

4. 忘記輔助路徑

主聊天路徑可能運作，但摘要、記憶刷新或視覺輔助失敗，因為輔助路由從未更新。

5. `run_agent.py` 中隱藏的原生供應商分支

搜尋 api_mode 和 self.client.。不要假設明顯的請求路徑是唯一的。

6. 將 OpenRouter 專屬的調節旋鈕發送到其他供應商

像供應商路由這樣的欄位只應屬於支援它們的供應商。

7. 更新了 `hermes model` 但沒有更新 `hermes setup`

兩個流程都需要知道該供應商。

實作期間的良好搜尋目標

如果你在搜尋供應商觸及的所有位置，搜尋這些符號：

PROVIDER_REGISTRY
_PROVIDER_ALIASES
_PROVIDER_MODELS
resolve_runtime_provider
_model_flow_
select_provider_and_model
api_mode
_API_KEY_PROVIDER_AUX_MODELS
self.client.

心智模型

首先選擇實作路徑

路徑 A — OpenAI 相容供應商

路徑 B — 原生供應商

檔案檢查清單

每個內建供應商都需要的

原生/非 OpenAI 供應商額外需要的

快速路徑：簡單 API 金鑰供應商

完整路徑：OAuth 和複雜供應商

步驟 1：選擇一個標準供應商 ID

步驟 2：在 `hermes_cli/auth.py` 中新增認證中繼資料

步驟 3：在 `hermes_cli/models.py` 中新增模型目錄和別名

步驟 4：在 `hermes_cli/runtime_provider.py` 中解析執行時資料

步驟 5：在 `hermes_cli/main.py` 中接線 CLI

步驟 6：保持輔助呼叫運作

`agent/auxiliary_client.py`

`agent/model_metadata.py`

步驟 7：若供應商是原生的，新增適配器和 `run_agent.py` 支援

新適配器檔案

`run_agent.py`

提示快取和供應商特定請求欄位

步驟 8：測試

步驟 9：即時驗證

步驟 10：更新使用者文件

OpenAI 相容供應商檢查清單

原生供應商檢查清單

常見陷阱

1. 將供應商加入認證但不加入模型解析

2. 忘記 `config["model"]` 可以是字串或字典

3. 假設需要內建供應商

4. 忘記輔助路徑

5. `run_agent.py` 中隱藏的原生供應商分支

6. 將 OpenRouter 專屬的調節旋鈕發送到其他供應商

7. 更新了 `hermes model` 但沒有更新 `hermes setup`

實作期間的良好搜尋目標

相關文件

新增平台適配器

心智模型

首先選擇實作路徑

路徑 A — OpenAI 相容供應商

路徑 B — 原生供應商

檔案檢查清單

每個內建供應商都需要的

原生/非 OpenAI 供應商額外需要的

快速路徑：簡單 API 金鑰供應商

完整路徑：OAuth 和複雜供應商

步驟 1：選擇一個標準供應商 ID

步驟 2：在 hermes_cli/auth.py 中新增認證中繼資料

步驟 3：在 hermes_cli/models.py 中新增模型目錄和別名

步驟 4：在 hermes_cli/runtime_provider.py 中解析執行時資料

步驟 5：在 hermes_cli/main.py 中接線 CLI

步驟 6：保持輔助呼叫運作

agent/auxiliary_client.py

agent/model_metadata.py

步驟 7：若供應商是原生的，新增適配器和 run_agent.py 支援

新適配器檔案

run_agent.py

提示快取和供應商特定請求欄位

步驟 8：測試

步驟 9：即時驗證

步驟 10：更新使用者文件

OpenAI 相容供應商檢查清單

原生供應商檢查清單

常見陷阱

1. 將供應商加入認證但不加入模型解析

2. 忘記 config["model"] 可以是字串或字典

3. 假設需要內建供應商

4. 忘記輔助路徑

5. run_agent.py 中隱藏的原生供應商分支

6. 將 OpenRouter 專屬的調節旋鈕發送到其他供應商

7. 更新了 hermes model 但沒有更新 hermes setup

實作期間的良好搜尋目標

相關文件

新增平台適配器

步驟 2：在 `hermes_cli/auth.py` 中新增認證中繼資料

步驟 3：在 `hermes_cli/models.py` 中新增模型目錄和別名

步驟 4：在 `hermes_cli/runtime_provider.py` 中解析執行時資料

步驟 5：在 `hermes_cli/main.py` 中接線 CLI

`agent/auxiliary_client.py`

`agent/model_metadata.py`

步驟 7：若供應商是原生的，新增適配器和 `run_agent.py` 支援

`run_agent.py`

2. 忘記 `config["model"]` 可以是字串或字典

5. `run_agent.py` 中隱藏的原生供應商分支

7. 更新了 `hermes model` 但沒有更新 `hermes setup`