Hermes Agent

在 ~/.hermes/config.yaml 中新增具名供應商，設定 api https://api.kunavo.com、transport anthropic_messages，並以 provider: custom:kunavo 選取後，Hermes Agent 就會透過 Messages 協定使用 Claude，並自行傳送快取標記及輸出上限。

# ~/.hermes/config.yaml
providers:
  kunavo:
    api: https://api.kunavo.com        # origin — the Anthropic SDK adds /v1/messages
    key_env: KUNAVO_API_KEY            # the variable's NAME; the key goes in ~/.hermes/.env
    transport: anthropic_messages
    models:
      claude-sonnet-5:
        context_length: 1000000
        prompt_caching: true
      claude-haiku-4-5:
        context_length: 200000
        prompt_caching: true

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

逐步操作

1. 在 /app/keys 建立金鑰並複製——金鑰只會顯示一次。
2. 將金鑰儲存在 Hermes 存放機密資訊的位置：hermes config set KUNAVO_API_KEY sk-kn-... 會將它寫入 ~/.hermes/.env。區塊中的 key_env 行會指定該變數；金鑰本身絕不會存入 config.yaml。
3. 將此區塊加入 ~/.hermes/config.yaml；使用 hermes config edit 開啟檔案。若已有 model: 區段，請替換其中的 default 和 provider，其餘內容保留不變。
4. 也可以讓精靈代為寫入：在終端機中、任何聊天工作階段之外執行 hermes model，選擇 Custom endpoint (self-hosted / VLLM / etc.)，並依提示輸入 API 基底 URL、金鑰、模型名稱、API 模式及上下文長度。
5. 啟動 hermes 並查看橫幅：其中會顯示模型及其上下文視窗，兩者都應與區塊中的設定相符。
6. 傳送兩則訊息，然後開啟 /usage 查看各輪使用的資源。若要在工作階段中切換模型，請使用 /model custom:kunavo:claude-opus-5-5。

已於 2026年10月5日 根據 Hermes Agent 的 AI 供應商頁面 進行確認。第三方設定會變動；如果這裡的欄位名稱不再與你看到的內容相符，應以該頁面為準，而不是本頁。

除錯用戶端前先驗證

一個請求就能判斷失敗原因是端點、金鑰還是設定檔。如果這裡回傳 JSON，則相同的基礎 URL 與金鑰在 Hermes Agent 中也能運作。

# Settles whether a failure is the endpoint, the key, or the client.
curl -sS https://api.kunavo.com/v1/messages \
  -H "Authorization: Bearer sk-kn-..." \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}'

欄位中應填入哪個模型 ID

每個文字模型都能以模型 ID 存取——即時清單位於 GET /v1/models，帶有價格的目錄位於模型頁面。費率是每 1M 權杖的美元價格，輸入／輸出。

OpenAI 相容通訊協定

同一把金鑰也能透過 /v1/chat/completions 呼叫其他所有模型系列；對此，Hermes 文件記載的最精簡格式就足夠——一個包含 provider: custom 和 base_url 的 model: 區塊，這也是 hermes model 所要求的格式：

# ~/.hermes/config.yaml — the bare form, for an OpenAI-compatible endpoint
model:
  default: gpt-6-sol
  provider: custom
  base_url: https://api.kunavo.com/v1    # this wire keeps /v1
  key_env: KUNAVO_API_KEY
  context_length: 1050000

基底 URL 在此保留 /v1，這是 Hermes 文件中本機伺服器範例使用的格式；context_length 則固定上下文視窗，讓 Hermes 不必自行偵測。若要同時設定兩種連線，請為此連線建立專屬名稱——transport: chat_completions——並透過 /model custom:<name>:<model> 切換。

各通訊協定的提示快取

使用 Anthropic 通訊協定時，Hermes 會自行附加快取標記。對於自訂供應商，Hermes 的模型設定頁面記載了上方區塊所使用的開關，也就是模型上的 prompt_caching: true，並說明標記配置會依傳輸方式而定：anthropic_messages 使用原生區塊，OpenAI 相容通訊協定則使用封套配置。Kunavo 的 /v1/messages 會原樣轉送收到的請求主體，不會自行新增任何斷點，因此在這種通訊協定下，標記若不是由 Hermes 加入，就不會有任何標記。

對於自訂端點，Hermes 文件未明確說明的是快取存留時間。文件針對透過原生 Anthropic API、OpenRouter 和 Nous Portal 使用 Claude 的情況，說明了 prompt_caching.cache_ttl（5m、1h 或 auto），但未提及其他端點。Kunavo 會轉送收到的任何標記，並以相同費率計算快取寫入費用，因此請從自己的用量資料判斷：暫停十分鐘後的下一輪對話若仍顯示快取讀取，就表示先前保留的是存留時間為一小時的快取項目。

在 OpenAI 相容連線上，只要提示夠長、可進行快取，Kunavo 就會自行為 Claude 模型設定快取斷點——分別位於系統提示詞、工具定義和對話結尾處，無論用戶端是否傳送標記皆如此。GPT 模型則由供應商以隱式方式進行快取。

無論由哪一端設定快取斷點，費用計算方式都相同。在 Claude Sonnet 5 上，快取讀取費率為每 1M 個 token $0.14，新輸入則為 $1.40；快取寫入費率為 $1.75，也就是 Claude 在輸入費率上加收的寫入溢價；若項目要求快取保留一小時，仍按相同費率計費。快取項目保留五分鐘，每次讀取都會續期，因此代理的費用與模型的關聯較小，主要取決於下一次請求是否在這段期間內送達。各模型的快取費率請見提示快取頁面。

Hermes 有一項行為帶來的費用高於任何費率：其文件指出，在工作階段中途切換模型、自動啟用備援或輪替憑證，都會重設提示快取，因此下一則訊息會以完整輸入價格重新讀取整段對話。請在長時間工作階段開始前選好模型。

常駐代理程式的每日費用

在 Hermes 中，沒有人輸入內容時仍會計費的項目，就是你排定的工作，以及每次對話觸發的旁支工作。Hermes 的 cron 文件指出，每次排程執行都會啟動新的工作階段，因此每次觸發時，完整提示——包括指示、工具架構和附加技能——都會計費。提示大小取決於你的設定，因此表格直接列出假設值：每次執行 20,000 個 token，每 30 分鐘執行一次，即每天 48 次。請依照自己的數據替換這兩項數值。

有三項設定會影響這個數字，且都來自 Hermes 自身的文件。排程工作會使用每個工作的專屬模型；若未設定，則使用 cron.model；若仍未設定，則使用主要模型——因此 hermes config set cron.model claude-haiku-4-5 可讓所有未指定模型的工作避開高價方案。若工作指令碼輸出 {"wakeAgent": false}，該次執行就會略過模型；不使用代理程式的工作也不會呼叫模型。至於旁支工作——壓縮、標題和視覺理解——都會使用主要模型，除非 auxiliary 將它們導向其他模型：

# ~/.hermes/config.yaml — what decides the cost of an unattended day
compression:
  threshold_tokens: 256000         # compact here, not at half of a 1M window

auxiliary:
  compression:
    provider: kunavo               # the named entry above
    model: claude-haiku-4-5        # summaries on the cheapest tier
  title_generation:
    provider: kunavo
    model: claude-haiku-4-5

對大型上下文視窗來說，threshold_tokens 這項設定最重要。壓縮預設會在使用到一半的上下文長度時開始；Hermes 文件指出，此設定可為單次呼叫的費用設定固定上限。

代理實際運作時數是帳單的另一半，而這部分由快取決定。連續發出 100 個請求，每次都重新傳送包含 100,000 個 token 的上下文，並額外加入 2,000 個新 token，且回傳 800 個輸出 token。在 Claude Sonnet 5，上下文從快取讀取時，費用約為 $2.31；若每個請求都將其計為全新輸入，費用則約為 $14.84。工作相同，模型相同；差別在於是否設有斷點，以及請求間隔是否少於五分鐘。

以實際測量值說明規模，而非推測：在 Kunavo 使用常駐代理程式的帳戶中，活躍日的費用中位數為 $12.67，第 90 百分位數的活躍日費用約為 $163。這些金額是截至 2026年10月5日 已計費的費用，採用各日當時適用的費率。樣本群體不大，因此請將這些數字視為範圍的寬度，而非對你的代理程式的預測。

餘額用盡時

Kunavo 採預付制：每次呼叫都從錢包扣款，而在您睡覺時持續工作的代理也會在您睡覺時耗盡錢包餘額。若錢包餘額不足以負擔某個請求，該請求會在任一通訊協定上以 HTTP 402 和代碼 insufficient_balance 遭拒，且不會收取任何費用。拒絕發生在錢包餘額歸零之前：每個請求都會先預留其最壞情況下的費用，也就是提示內容加上允許產生的最大回覆，因此代理要求的輸出上限越高，其請求就越早開始遭拒。錯誤訊息會以 balance_usd 和 needed_usd 說明餘額不足的金額。

Hermes Agent 遇到供應商無法處理請求時，會使用 備援鏈：在 config.yaml 中設定 fallback_providers，透過 hermes fallback 管理，並逐輪嘗試。其文件列出主要模型遇到速率限制、伺服器錯誤、驗證失敗和 404 時會觸發備援；並指出 HTTP 402 屬於容量錯誤，會讓旁支工作改用備援鏈中的下一個供應商。文件沒有說明未設定備援時，遇到 HTTP 402 的輪次會如何處理。請按最直接的解讀做好準備——該輪會失敗，排程工作也會跟著失敗——並記得，若某一輪確實改用備援，就會從空的提示快取開始。

有兩項設定可避免無人值守的代理程式陷入這種狀況，兩者用途不同：

• 自動儲值，位於 儲值與帳單。儲存一張卡片，並設定三個數值：低於多少餘額時要儲值、每次要加多少，以及每月上限。之後，只要某次呼叫使餘額低於門檻，錢包就會在幾秒內自動補足。錢包餘額不足時送達的請求會等待該筆扣款完成，接著獲得處理，而非遭到拒絕。若無法扣款（例如卡片遭拒或已達每月上限），或單一請求預留的金額超過儲值後錢包持有的餘額，仍會回傳 402。此功能需要使用付款卡或 Link；Alipay、WeChat Pay、Pix 和其他當地付款方式無法用於自動扣款。
• API 金鑰的每月支出上限，位於 API 金鑰。為代理程式建立專屬金鑰，並設定該金鑰在一個日曆月內可支出的最高金額。超過此金額後，該金鑰發出的呼叫會以 402 遭拒，且不會扣款；其他金鑰則不受影響，仍可正常使用。這能為失控的迴圈設下支出上限，而錢包無法做到這一點，因為所有金鑰共用同一個錢包。

設定自動儲值門檻時，請高於單次請求的預留金額；設定儲值金額時，請以代理程式一天的費用為基準，而非最低金額：最低儲值金額為 $10，上文所列常駐代理程式的每日費用中位數為 $12.67。自動儲值的限制請見帳單頁面，完整錯誤主體請見錯誤頁面。

相關指南

• Hermes Agent 自訂 API — 說明為何對外供應商不是對內 API 伺服器、transport 欄位的用途，以及首次呼叫時應執行的檢查。
• Hermes Agent 費用——除了 token 費率之外，執行它還有哪些費用。
• Hermes 上下文壓縮逾時——摘要程序停滯時錯誤代表什麼，以及如何復原。
• Hermes 與 OpenClaw 比較——另一個代理程式的相同設定方式，請參閱 OpenClaw 頁面。