跳到主要內容

提供者運行時解析

Hermes 使用一個跨以下組件共享的提供者運行時解析器：

  • CLI
  • 網關
  • 定時任務
  • ACP
  • 輔助模型調用

主要實現：

  • hermes_cli/runtime_provider.py — 憑據解析，_resolve_custom_runtime()
  • hermes_cli/auth.py — 提供者註冊表，resolve_provider()
  • hermes_cli/model_switch.py — 共享的 /model 切換流程（CLI + 網關）
  • agent/auxiliary_client.py — 輔助模型路由

如果你正在嘗試添加一個新的第一類推理提供者，請同時閱讀本頁和 添加提供者。

解析優先級​

從整體上看，提供者解析遵循以下順序：

  1. 顯式 CLI/運行時請求
  2. config.yaml 中的模型/提供者配置
  3. 環境變量
  4. 提供者特定的默認值或自動解析

這一順序至關重要，因為 Hermes 將保存的模型/提供者選擇視為正常運行的“真理來源”。這可以防止舊的 shell 環境變量導出靜默覆蓋用戶在 hermes model 中最後選擇的端點。

提供者​

當前支持的提供者類別包括：

  • AI Gateway（Vercel）
  • OpenRouter
  • Nous Portal
  • OpenAI Codex
  • Copilot / Copilot ACP
  • Anthropic（原生）
  • Google / Gemini
  • 阿里巴巴 / DashScope
  • DeepSeek
  • Z.AI
  • Kimi / Moonshot
  • MiniMax
  • MiniMax 中國
  • Kilo Code
  • Hugging Face
  • OpenCode Zen / OpenCode Go
  • 自定義（provider: custom）—— 用於任何 OpenAI 兼容端點的第一類提供者
  • 命名自定義提供者（config.yaml 中的 custom_providers 列表）

運行時解析的輸出​

運行時解析器返回如下數據：

  • provider
  • api_mode
  • base_url
  • api_key
  • source
  • 提供者特定的元數據，如過期/刷新信息

為何如此重要​

該解析器是 Hermes 能夠在以下場景間共享認證/運行時邏輯的主要原因：

  • hermes chat
  • 網關消息處理
  • 在全新會話中運行的定時任務
  • ACP 編輯器會話
  • 輔助模型任務

AI Gateway​

在 ~/.hermes/.env 中設置 AI_GATEWAY_API_KEY，並使用 --provider ai-gateway 運行。Hermes 會從網關的 /models 端點獲取可用模型，並篩選出支持工具使用的語言模型。

OpenRouter、AI Gateway 與自定義 OpenAI 兼容基礎 URL​

Hermes 包含邏輯，以避免在存在多個提供者密鑰時（例如 OPENROUTER_API_KEY、AI_GATEWAY_API_KEY 和 OPENAI_API_KEY）將錯誤的 API 密鑰洩露給自定義端點。

每個提供者的 API 密鑰都限定於其自身的基礎 URL：

  • OPENROUTER_API_KEY 僅發送至 openrouter.ai 端點
  • AI_GATEWAY_API_KEY 僅發送至 ai-gateway.vercel.sh 端點
  • OPENAI_API_KEY 用於自定義端點，並作為回退

Hermes 還區分：

  • 用戶明確選擇的真實自定義端點
  • 當未配置自定義端點時使用的 OpenRouter 回退路徑

這種區分在以下場景中尤為重要：

  • 本地模型服務器
  • 非 OpenRouter / 非 AI Gateway 的 OpenAI 兼容 API
  • 切換提供者而無需重新運行設置
  • 保存在配置中的自定義端點，即使當前 shell 中未導出 OPENAI_BASE_URL 也能繼續工作

原生 Anthropic 路徑​

Anthropic 已不再僅通過 OpenRouter 實現。

當提供者解析選擇 anthropic 時，Hermes 使用：

  • api_mode = anthropic_messages
  • 原生 Anthropic Messages API
  • agent/anthropic_adapter.py 進行轉換

原生 Anthropic 的憑據解析現在優先使用可刷新的 Claude Code 憑據，而非複製的環境變量令牌（當兩者都存在時）。實際上這意味著：

  • 當 Claude Code 憑據文件包含可刷新認證時，被視為首選來源
  • 手動設置的 ANTHROPIC_TOKEN / CLAUDE_CODE_OAUTH_TOKEN 值仍可作為顯式覆蓋
  • Hermes 在調用原生 Messages API 前會預先刷新 Anthropic 憑據
  • Hermes 在重建 Anthropic 客戶端後，若遇到 401 錯誤仍會重試一次，作為回退路徑

OpenAI Codex 路徑​

Codex 使用獨立的 Responses API 路徑：

  • api_mode = codex_responses
  • 專用的憑據解析與認證存儲支持

輔助模型路由​

以下輔助任務可使用其自身的提供者/模型路由，而非主對話模型：

  • 視覺處理
  • 網頁提取摘要
  • 上下文壓縮摘要
  • 會話搜索摘要
  • 技能中心操作
  • MCP 幫助器操作
  • 記憶清除

當輔助任務配置大模型提供商為 main 時，Hermes 通過與正常聊天相同的共享運行時路徑進行解析。實際上這意味著：

  • 基於環境變量的自定義端點仍可工作
  • 通過 hermes model / config.yaml 保存的自定義端點也可工作
  • 輔助路由能夠區分真實保存的自定義端點與 OpenRouter 回退路徑

回退模型​

Hermes 支持配置的回退模型/提供者對，允許在主模型遇到錯誤時進行運行時故障轉移。

內部工作原理​

  1. 存儲：AIAgent.__init__ 將 fallback_model 字典存儲，並設置 _fallback_activated = False。

  2. 觸發點：_try_activate_fallback() 在 run_agent.py 的主重試循環中被調用三次：

    • 在無效 API 響應（None choices、缺少內容）達到最大重試次數後
    • 在非可重試的客戶端錯誤（HTTP 401、403、404）發生時
    • 在瞬態錯誤（HTTP 429、500、502、503）達到最大重試次數後

  3. 激活流程（_try_activate_fallback）：

    • 如果已激活或未配置，立即返回 False
    • 調用 auxiliary_client.py 中的 resolve_provider_client() 構建帶有正確認證的新客戶端
    • 確定 api_mode：codex_responses 用於 openai-codex，anthropic_messages 用於 anthropic，其餘情況為 chat_completions
    • 就地替換：self.model、self.provider、self.base_url、self.api_mode、self.client、self._client_kwargs
    • 對 anthropic 回退：構建原生 Anthropic 客戶端，而非 OpenAI 兼容客戶端
    • 重新評估提示緩存（在 OpenRouter 上，Claude 模型啟用提示緩存）
    • 設置 _fallback_activated = True —— 防止再次觸發
    • 重置重試計數為 0，並繼續循環

  4. 配置流程：

    • CLI：cli.py 讀取 CLI_CONFIG["fallback_model"] → 傳遞給 AIAgent(fallback_model=...)
    • 網關：gateway/run.py._load_fallback_model() 讀取 config.yaml → 傳遞給 AIAgent
    • 驗證：provider 和 model 鍵都必須非空，否則回退功能被禁用

不支持回退的功能​

  • 子 Agent 委派（tools/delegate_tool.py）：子 Agent 繼承父 Agent 的提供者，但不繼承回退配置
  • 定時任務（cron/）：使用固定提供者運行，無回退機制
  • 輔助任務：使用其自身獨立的提供者自動檢測鏈（參見上方“輔助模型路由”）

測試覆蓋​

詳見 tests/test_fallback_model.py，涵蓋所有支持的提供者、單次調用語義以及邊緣情況的全面測試。