Hermes Agent 自訂 API：供應商、傳輸方式與首次呼叫檢查

Hermes Agent 自訂端點是以出站方式設定的，在 ~/.hermes/config.yaml 中以命名項目放在 providers: 底下，其中 api 是基礎 URL，而 transport 是傳輸協定。 這與 Hermes 自己的 API 伺服器不同，後者的方向相反。搜尋結果中兩者都被稱為「Hermes 自訂 API」，而且各自的官方文件頁面會針對相同查詢排名，因此請先確認方向。

本頁介紹的是 Hermes Agent，由 Nous Research 開發的開放原始碼代理程式。2026 年 9 月 21 日檢查 GitHub API 時，回傳了 archived: false、disabled: false、MIT 授權，以及同日的一次推送；最新發布版本是 Hermes Agent v0.21.3，於 2026 年 9 月 14 日標記為 v2026.9.14，不是預發布版本。本頁取得設定資訊的來源是該儲存庫與 hermes-agent.nousresearch.com。hermes-agent.org 涵蓋同一個專案，但網域位於 nousresearch.com 之外，並載入 Microsoft Clarity 分析工具（2026 年 9 月 21 日檢查）；它不是專案自己的介面，因此不要從中取得設定。這也不是 Hermes 3 或 Hermes 4（Nous 的開放權重模型系列），也不是同名的 JavaScript 引擎。

兩種方向相反、都稱為 Hermes 自訂 API 的功能

兩列內容均摘自 Hermes 自己的頁面，於 2026 年 9 月 21 日閱讀：供應商參考文件與 API 伺服器頁面。你自己的安裝有一個命名細節值得確認：API 伺服器頁面記錄 hermes gateway 是執行它的命令，而 CLI 參考文件 將 hermes gateway 描述為訊息服務管理器，並列出 run、start、stop 與 status 子命令。請執行 hermes gateway --help，不要自行猜測。以下內容全部是出站部分。

最低限度的出站設定

# ~/.hermes/config.yaml
providers:
  kunavo:
    api: https://api.kunavo.com/v1   # aliases accepted: base_url, url
    key_env: KUNAVO_API_KEY          # or inline api_key:, or key_cmd:
    transport: chat_completions      # set it by hand; see the transport section
    models:
      claude-sonnet-5:
        prompt_caching: true

model:
  default: claude-sonnet-5
  provider: custom:kunavo

KUNAVO_API_KEY=your-key

依供應商參考文件逐欄說明：設定金鑰為 providers.<name>，基礎 URL 欄位為 api（也接受 base_url 與 url 作為別名），認證憑證為 key_env，可使用內嵌的 api_key 或 key_cmd，傳輸協定為 transport。同一項目也接受 name、default_model、models、context_length、discover_models、extra_body、extra_headers、session_affinity_header、ssl_ca_cert / ssl_verify、catalog_provider 與 enabled: false。使用 model.provider: custom:kunavo 選取該項目，或在工作階段中途使用 /model custom:kunavo:<model-id>。

兩個命令不可互換。hermes model 必須在聊天工作階段外執行，是完整的供應商設定精靈，也是唯一能新增供應商或接收金鑰的功能。工作階段內的 /model 只會在現有項目之間切換。對於發出短期權杖的企業端點，key_cmd 是一個會將權杖輸出至 stdout 的命令，可直接輸出，或以含有 access_token 欄位的 JSON 輸出；Hermes 會執行該命令並將權杖快取到即將過期前，這比同一項目中的靜態 api_key 或 key_env 更合適。

請手動選取傳輸方式，不要將欄位留白

供應商參考文件列出自訂項目中 transport 可接受的三個值。文件也表示，hermes model 自訂端點精靈現在會明確詢問傳輸協定，並將答案儲存至 config.yaml；若欄位留白，則 URL 自動偵測「仍會作為備援」。文件明確說明的唯一偵測規則是：/anthropic 路徑對應至 anthropic_messages，而 Kunavo 基礎 URL 不符合；本頁讀到的其他頁面都未列出其餘啟發式規則，因此應寫入欄位，而不是推測其行為。Kunavo 提供 /v1/chat/completions、/v1/messages 與 /v1/responses，所以就文件上的對應而言，每種傳輸方式都有相符的路由。

Anthropic 這一列需要附帶說明，而不是給出肯定答案。Hermes 的 Azure Foundry 指南 表示，由於 Anthropic SDK 會將 /v1/messages 附加至每個請求，因此會從基底 URL 移除 /v1；但這句話位於 Azure 標題下，而供應商參考文件自己的範例（api: https://proxy.example.com/anthropic）從未說明 Hermes 對一般代理會附加什麼後綴。因此，上述兩個候選值都合理，其中一個可能因路徑中出現雙重 /v1 而導致 404。請檢查第一次呼叫實際記錄的請求路徑；基底 URL 文件說明了此傳輸方式中多數 404 背後混淆網址來源（origin）與 /v1 的陷阱。身分驗證是次要疑慮：Kunavo 的 Messages 路由 同時接受 Authorization: Bearer 與 x-api-key，因此 Anthropic SDK 對一般代理傳送的任何一種標頭都應該能被接受；但 Hermes 沒有記錄其選擇，因此「應該」才是誠實的說法。

本頁也無法回答的一個開放問題。Hermes 記錄了 GPT-5.x 系列模型名稱會靜默升級至 codex_responses，即使 config.yaml 仍為 chat_completions；但這句話位於 provider: azure-foundry 下方，表述方式則是模型名稱偵測。GPT slug 位於 provider: custom 時是否會觸發相同轉換，文件未說明。如果選擇 GPT 類模型，請記錄第一次呼叫實際前往的路由。

依傳輸方式區分，自訂端點不會自動取得的功能

這些都不是方案限制。根據專案自己的 首頁 FAQ，Hermes Agent「依 MIT 授權免費且開放原始碼」；providers: 字典也被記錄為一般設定，而非方案功能。它們是能力限制，且會依傳輸方式而異。

針對閘道的兩個備用方式。catalog_provider 接受 Hermes 供應商 ID 或 models.dev ID，讓項目中的模型繼承該目錄的中繼資料；這只用於查詢，請求仍會使用你的金鑰傳送至你的 api URL。discover_models: false 則完全略過 /models 探測，只使用你在項目中列出的模型；當探索結果雜亂或緩慢時，這就是修正方式。本頁未測試 Kunavo 的 /v1/models 回應是否符合 Hermes 的探測要求；若不符合，上下文偵測會退回 128K 預設值。這些設定背後的成本考量——輔助槽位、委派工作程序與快取連續性——已在 Hermes Agent 定價中說明，此處不再重複。

在移入實際工作前執行的驗證階梯

以下是由你執行、並附有預期觀察結果的步驟，不是 Kunavo 已取得的結果。 尚未執行 Hermes 連線 Kunavo 的任何測試，也沒有 Kunavo 的 Hermes 設定指南；本頁任何內容都不應解讀為已測試的整合。全程保留目前可用的工作路由。

1. 新增供應商，然後進行診斷。 hermes model 會新增供應商；文件將 hermes doctor 記錄為診斷設定與相依性問題的命令，而 CLI 參考文件記錄它會執行兩項自訂端點設定檢查：custom_providers 金鑰不是 YAML 清單，以及沒有相符 providers: 項目的舊式清單項目。兩者都只會發出警告，--fix 不會重寫它們。
2. 確認已載入金鑰，再開始產生費用。 hermes dump 會輸出可複製貼上的設定摘要，包括版本、供應商、模型，以及是否存在 API 金鑰。預期會看到你的模型 ID 與已存在的金鑰。hermes prompt-size 會離線執行，並回報系統提示與工具結構描述的位元組分解；這是每一回合在任何對話內容之前都會攜帶的固定部分。
3. 一個非串流文字回合。 預期會收到回覆，且請求已前往你預期的路徑。自訂端點若「可以運作」但回傳亂碼，便是 Hermes 快速入門指南疑難排解表中的一列；該表列出錯誤的基礎 URL、錯誤的模型名稱，或端點實際上不相容於 OpenAI，並要求你先在獨立用戶端中驗證端點。
4. 一個串流回合。 預期會收到逐步輸出的內容，而不是最後一次收到整個區塊。特定端點的串流框架是否符合 Hermes 的進度解析，本頁未進行測試。
5. 一個工具回合。 預期工具會執行。若呼叫被以文字列印出來，問題在伺服器端的工具呼叫支援，而不是傳輸方式。
6. 讀取計量器。 /usage 是工作階段內的權杖、費用與上下文面板。請將其與供應商帳戶實際記錄的費用核對；代理程式根據回報權杖自行計算的數字是估算值，不是帳本。請參閱 用量文件。

驗證階梯的成本，以及工作階段中途切換的成本

假設上述六個步驟總共傳送 26,000 個輸入權杖並接收 1,150 個輸出權杖——三次呼叫各自包含固定的系統提示與工具結構描述，另有一次重新傳送工具結果。此假設僅供說明；hermes prompt-size 會以位元組分解回報你自己的固定提示，比本頁猜測的數字更接近實際。費率是即時的 Kunavo 目錄每百萬權杖價格。

這是依目錄費率進行的範例權杖計算，不是實際測得的 Hermes 任務，也不是帳單上限。不包含快取寫入、外部工具與稅費。這個數字的重點在於它很小：驗證路由的成本遠低於在一週排程工作後才發現設定錯誤。

第二個數字就是 /model 命令隱藏的數字。提示快取以處理請求的模型為索引，因此任何對話中途的模型變更，都會使下一則訊息以完整輸入價格重新讀取整個對話，而不是使用快取費率；Hermes 將快取費率描述為便宜約 75% 至 90%。對於使用 Claude Sonnet 5、長度為 120,000 權杖的對話，每百萬權杖的 $1.40 與 $0.14 快取讀取費率之間的差額，單一回合約為 $0.151；偶爾一次微不足道，但形成習慣後就不再如此。Kunavo 的目錄金額是計費下限，而不是上限：上游回報費用時，帳單會取目錄成本與上游成本乘以適用加成兩者中較高者。最低金額是 $10 的預付儲值，無須訂閱。請參閱 計費。

再次撤銷設定

Hermes 記錄了復原路徑，因此試用的風險很低。項目上的 enabled: false 會隱藏它，但不會刪除它。config.yaml 的時間點副本會在 hermes setup 或 hermes migrate 重寫檔案之前寫入 backups/config/config.yaml.<reason>.<timestamp>，以及每次解析時寫入；完全相同的重複副本會略過，每個原因只保留最新的五份。若檔案之後解析失敗，Hermes 會提供最新的良好副本，而不是內建預設值。設定參考文件也將 model.base_url 註記為「在切換供應商時清除」，因此文件所述的行為是切換回內建供應商會捨棄過時的基礎 URL，而不是將其留在檔案中；請事後檢查寫入的值，不要自行假設。

三個陷阱來自較舊的教學文章。舊式頂層 custom_providers: 清單仍可運作，而 hermes update 會自動將其遷移至 providers: 字典，其中舊式 model 會變成 default_model，舊式 api_mode 會變成 transport。LLM_MODEL 位於 .env 中，現在已徹底移除；config.yaml 是唯一真實來源。此外，兩個目前的官方頁面以兩種方式記錄 OPENAI_BASE_URL：供應商參考文件表示它僅對 openai-api 供應商有效，而環境變數參考文件則將它列為自訂端點的基礎 URL。這項歧異尚未解決，因此請在 config.yaml 中設定端點，不要依賴該環境變數作為路由。

如果你是在選擇供應商，而不是接線，OpenAI 相容 API說明相容介面包含與不包含的內容，Hermes 與 OpenClaw則比較兩個代理程式。準備使用已儲值的金鑰測試此路由時，請建立 Kunavo 帳戶。

常見問題

Hermes Agent 文件——供應商參考文件、API 伺服器頁面、模型設定頁面、設定頁面、CLI 參考文件、斜線命令參考文件、快速入門指南與專案首頁——於 2026 年 9 月 21 日閱讀。儲存庫狀態與最新版本於同日透過 GitHub API 核對。Kunavo 的三條 API 路由已在其自身原始碼中確認。所有美元金額都是以即時目錄費率計算的範例權杖費用，不是實際測得的任務成本。Hermes 設定內容來自原始文件；尚未執行 Hermes 連線 Kunavo 的任何測試。