跳到主要內容

添加提供者

Hermes 已經可以通過自定義提供者路徑與任何兼容 OpenAI 的端點通信。除非你希望該服務獲得一流的用戶體驗，否則不要添加內置提供者：

  • 提供商特定的認證或令牌刷新機制
  • 經過篩選的模型目錄
  • 設置 / hermes model 菜單項
  • provider:model 語法的提供者別名
  • 需要適配器的非 OpenAI API 形式

如果該提供者僅僅是“另一個兼容 OpenAI 的基礎 URL 和 API 密鑰”，那麼命名的自定義提供者可能就足夠了。

心智模型​

一個內置提供者必須在多個層面保持一致：

  1. hermes_cli/auth.py 決定如何查找憑據。
  2. hermes_cli/runtime_provider.py 將憑據轉換為運行時數據：
    • provider
    • api_mode
    • base_url
    • api_key
    • source
  3. run_agent.py 使用 api_mode 來決定如何構建和發送請求。
  4. hermes_cli/models.py 和 hermes_cli/main.py 使提供者在 CLI 中顯示出來。（hermes_cli/setup.py 會自動委託給 main.py —— 無需在此處做任何更改。）
  5. agent/auxiliary_client.py 和 agent/model_metadata.py 保持輔助任務和令牌預算功能正常運行。

關鍵抽象是 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 中針對請求構建、分發、使用量提取、中斷處理和響應歸一化的分支
  • 適配器測試

文件清單​

每個內置提供者必需的文件​

  1. hermes_cli/auth.py
  2. hermes_cli/models.py
  3. hermes_cli/runtime_provider.py
  4. hermes_cli/main.py
  5. agent/auxiliary_client.py
  6. agent/model_metadata.py
  7. 測試文件
  8. 用戶文檔，位於 website/docs/ 下
提示

hermes_cli/setup.py 不需要修改。設置嚮導會自動將提供者/模型選擇委託給 main.py 中的 select_provider_and_model() —— 任何添加到該函數中的提供者都會自動在 hermes setup 中可用。

原生 / 非 OpenAI 提供者所需的額外文件​

  1. agent/<provider>_adapter.py
  2. run_agent.py
  3. 如果需要提供者 SDK，則需修改 pyproject.toml

第一步：選擇一個唯一的提供者 ID​

選擇一個唯一的提供者 ID，並在所有地方使用它。

倉庫中的示例：

  • 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、設置或運行時解析可能會靜默失敗。

第二步：在 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 / 認證存儲路徑：Nous、OpenAI Codex

在此階段需要回答的問題：

  • Hermes 應檢查哪些環境變量？優先級順序是什麼？
  • 提供者是否需要基礎 URL 覆蓋？
  • 是否需要端點探測或令牌刷新？
  • 當憑據缺失時，認證錯誤信息應如何提示？

如果提供者需要的功能超出“查找 API 密鑰”範圍，請添加專用的憑據解析器，而不是將邏輯塞入無關的分支中。

第三步：在 hermes_cli/models.py 中添加模型目錄和別名​

更新提供者目錄，使提供者能在菜單中使用，並支持 provider:model 語法。

典型修改：

  • _PROVIDER_MODELS
  • _PROVIDER_LABELS
  • _PROVIDER_ALIASES
  • list_available_providers() 中提供者的顯示順序
  • 如果提供者支持實時 /models 獲取，則修改 provider_model_ids()

如果提供者暴露了實時模型列表，優先使用它，並將 _PROVIDER_MODELS 作為靜態回退。

該文件也是使以下輸入正常工作的關鍵：

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

如果此處缺少別名，提供者可能認證成功，但在 /model 解析時仍會失敗。

第四步：在 hermes_cli/runtime_provider.py 中解析運行時數據​

resolve_runtime_provider() 是 CLI、網關、cron、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​

為該提供者的模型添加上下文長度，以確保令牌預算、壓縮閾值和限制保持合理。

第 7 步：如果提供者是原生的，添加適配器和 run_agent.py 支持​

如果提供者不是標準的聊天補全接口，請將提供者特定的邏輯隔離到 agent/<provider>_adapter.py 中。

保持 run_agent.py 專注於編排。它應調用適配器輔助函數，而不是在文件中各處直接構建提供者請求負載。

原生提供者通常需要在以下位置進行修改：

新的適配器文件​

典型職責包括：

  • 構建 SDK / HTTP 客戶端
  • 解析令牌數
  • 將 OpenAI 風格的對話消息轉換為提供者的請求格式
  • 如有必要，轉換工具模式
  • 將提供者響應規範化為 run_agent.py 所期望的格式
  • 提取使用情況和結束原因數據

run_agent.py​

搜索 api_mode 並審計每個分支點。至少需驗證：

  • __init__ 選擇了新的 api_mode
  • 客戶端構建對提供者有效
  • _build_api_kwargs() 知道如何格式化請求
  • _api_call_with_interrupt() 能正確分派到對應的客戶端調用
  • 中斷 / 客戶端重建路徑正常工作
  • 響應驗證能接受提供者的響應結構
  • 結束原因提取正確
  • 令牌使用量提取正確
  • 回退模型激活能平滑切換到新提供者
  • 摘要生成和記憶清理路徑仍能正常工作

同時在 run_agent.py 中搜索 self.client.。任何假設標準 OpenAI 客戶端存在的代碼路徑，在原生提供者使用不同客戶端對象或 self.client = None 時都可能出錯。

提示緩存和提供者特定請求字段​

提示緩存和提供者特定的選項很容易出現迴歸。

樹中已有的示例：

  • Anthropic 有原生提示緩存路徑
  • OpenRouter 接收提供者路由字段
  • 並非每個提供者都應接收每個請求端選項

添加原生提供者時，請再次確認 Hermes 僅發送提供者實際理解的字段。

第 8 步：測試​

至少覆蓋保護提供者連接的測試。

常見位置：

  • tests/test_runtime_provider_resolution.py
  • tests/test_cli_provider_resolution.py
  • tests/test_cli_model_command.py
  • tests/test_setup_model_selection.py
  • tests/test_provider_parity.py
  • tests/test_run_agent.py
  • 對於原生提供者，添加 tests/test_<provider>_adapter.py

對於僅文檔示例，具體文件集可能不同。重點是覆蓋：

  • 認證解析
  • CLI 菜單 / 提供者選擇
  • 運行時提供者解析
  • Agent 執行路徑
  • 提供者:模型解析
  • 任何適配器特定的消息轉換

使用 xdist 禁用運行測試：

source venv/bin/activate
python -m pytest tests/test_runtime_provider_resolution.py tests/test_cli_provider_resolution.py tests/test_cli_model_command.py tests/test_setup_model_selection.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 兼容提供者檢查清單​

如果提供者符合標準聊天補全接口，請使用此清單。

  • 在 hermes_cli/auth.py 中添加 ProviderConfig
  • 在 hermes_cli/auth.py 和 hermes_cli/models.py 中添加別名
  • 在 hermes_cli/models.py 中添加模型目錄
  • 在 hermes_cli/runtime_provider.py 中添加運行時分支
  • 在 hermes_cli/main.py 中添加 CLI 配線（setup.py 會自動繼承）
  • 在 agent/auxiliary_client.py 中添加輔助模型
  • 在 agent/model_metadata.py 中添加上下文長度
  • 更新運行時 / CLI 測試
  • 更新用戶文檔

原生提供者檢查清單​

當提供者需要新的協議路徑時，請使用此清單。

  • 完成 OpenAI 兼容提供者檢查清單中的所有項目
  • 在 agent/<provider>_adapter.py 中添加適配器
  • 在 run_agent.py 中支持新的 api_mode
  • 中斷 / 重建路徑正常工作
  • 使用量和結束原因提取正常工作
  • 回退路徑正常工作
  • 添加適配器測試
  • 通過實時煙霧測試

常見陷阱​

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.