背景

Hermes 是一款開源的 AI 代理框架，支持多種模型提供商。硅基流動（SiliconFlow）是國內(nèi)提供高性價比 API 服務的平臺，尤其以 DeepSeek 系列模型受到開發(fā)者青睞。然而，將 Hermes 與硅基流動的自定義端點對接時，我遇到了一些典型問題。本文記錄了我從安裝、配置到最終成功調(diào)用的完整過程，希望能為遇到類似問題的朋友提供一份可操作的參考。

環(huán)境準備

• 操作系統(tǒng)：macOS / Linux / WSL2（本文以 macOS 為例）
• 已注冊硅基流動賬號，并獲取 API Key（格式以 sk- 開頭）
• 已安裝 Node.js 22+ 與 Git
• 終端能正常訪問硅基流動 API 地址 https://api.siliconflow.cn/v1

第一步：安裝 Hermes

官方推薦的一鍵安裝命令：

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
source ~/.bashrc   # 或 source ~/.zshrc

安裝完成后，會自動啟動配置向?qū)?。如果之前使用過類似工具（如 OpenClaw），Hermes 會詢問是否遷移數(shù)據(jù)——我選擇了遷移，因為 OpenClaw 中已經(jīng)配置好了硅基流動的 API Key 和模型。

第二步：配置自定義端點（硅基流動）

Hermes 的快速設置只包含預設的官方提供商，沒有“硅基流動”選項。因此需要手動選擇 Custom endpoint。

在向?qū)У奶峁┥踢x擇環(huán)節(jié)，向下滾動并選擇 Custom endpoint (enter URL manually)（或類似選項），然后填寫：

• Base URL：https://api.siliconflow.cn/v1
• API Key：粘貼你的硅基流動 API Key
• Model name：例如 Pro/deepseek-ai/DeepSeek-R1（注意大小寫和前綴）
• API 兼容模式：選擇 Auto-detect 或 Chat Completions 均可

完成這些后，向?qū)４媾渲玫?~/.hermes/config.yaml。

第三步：遭遇“401 API key is invalid”錯誤

運行 hermes 嘗試對話時，出現(xiàn)了如下錯誤：

??  API call failed: AuthenticationError [HTTP 401]
   ?? Provider: custom  Model: Pro/deepseek-ai/DeepSeek-R1
   ?? Endpoint: https://api.siliconflow.cn/v1
   ?? Error: HTTP 401: Error code: 401 - Api key is invalid

關鍵信息：相同的 API Key 在 OpenClaw 中能正常工作，說明 Key 本身有效且賬戶權限正常。問題出在 Hermes 的配置格式上。

排查過程

檢查 API Key 是否被正確讀取
嘗試用環(huán)境變量強制指定：SILICONFLOW_API_KEY="你的key" hermes。結(jié)果仍然 401，說明不是環(huán)境變量問題。

查看 ~/.hermes/config.yaml 內(nèi)容
發(fā)現(xiàn)兩個致命錯誤：

model:
  default: Pro/deepseek-ai/DeepSeek-R1
  provider: custom          # ? 錯誤1：應為 custom:hermes
  base_url: https://api.siliconflow.cn/v1   # ? 錯誤2：不應在此處定義
  api_key: sk-重復了兩次的key   # ? 錯誤3：密鑰被粘貼了兩遍
custom_providers:
  - name: hermes
    base_url: https://api.siliconflow.cn/v1
    api_key: sk-重復了兩次的key   # 同樣錯誤
    model: Pro/deepseek-ai/DeepSeek-R1

問題分析：

• Hermes 要求 model.provider 必須是 custom:名稱 形式，其中 名稱 對應 custom_providers 中某個條目的 name。寫單純的 custom 會導致 Hermes 忽略 custom_providers 配置。
• model 層級不應該包含 base_url 和 api_key，這些字段只應出現(xiàn)在 custom_providers 中。
• API Key 被重復粘貼，實際發(fā)送的 Authorization header 變成了無效字符串。

第四步：修復配置文件

編輯 ~/.hermes/config.yaml：

open -e ~/.hermes/config.yaml

修正后的關鍵片段：

model:
  default: Pro/deepseek-ai/DeepSeek-R1
  provider: custom:hermes          # ? 正確：custom:名稱
  # 刪除 base_url 和 api_key 行
custom_providers:
  - name: hermes
    base_url: https://api.siliconflow.cn/v1
    api_key: sk-你的正確且未重復的密鑰   # ? 只粘貼一次
    model: Pro/deepseek-ai/DeepSeek-R1

保存文件后，重新運行 hermes。

第五步：驗證成功

輸入 你好，得到模型回復：

你好，bruce_xiaowei！我是你的AI助手……

同時注意到一個輔助警告：

? Auxiliary title generation failed: HTTP 401

這是因為 Hermes 嘗試用另一個未配置的模型為會話自動生成標題，不影響正常對話?？赏ㄟ^將 auxiliary.title_generation.provider 設為 none 來消除。

踩坑總結(jié)與建議

安全提醒

• 絕對不要在公開場合（包括博客、截圖、Issue）暴露你的 API Key。本文示例中的 Key 已經(jīng)廢棄。
• 如果不慎泄露，請立即登錄硅基流動控制臺刪除該 Key 并生成新 Key。
• 推薦使用環(huán)境變量 SILICONFLOW_API_KEY 并在配置中引用 ${env.SILICONFLOW_API_KEY}，而非明文寫在 config.yaml 中。

最終效果

現(xiàn)在你可以愉快地使用 Hermes 調(diào)用硅基流動的各種模型了。常用命令：

• hermes：啟動交互對話
• hermes model：更換模型或提供商
• hermes doctor：診斷配置問題
• hermes doctor --fix：嘗試自動修復部分問題

擴展：如何更換模型？

硅基流動提供了豐富的模型庫。登錄 模型中心 找到你需要的模型 ID（如 Qwen/Qwen2.5-7B-Instruct），然后：

hermes model
# 選擇你的 custom provider，輸入新的模型名

或直接編輯 ~/.hermes/config.yaml，修改 custom_providers[].model 字段。

結(jié)語

配置自定義 API 端點時常會遇到小坑，但只要理解配置文件的映射關系，就能迎刃而解。希望這篇實戰(zhàn)記錄能幫助你節(jié)省時間，順利跑通 Hermes + 硅基流動的組合。如果你有更好的配置技巧，歡迎交流討論。

以上就是為Hermes配置硅基流動API的完整實戰(zhàn)的詳細內(nèi)容，更多關于Hermes配置硅基流動API的資料請關注腳本之家其它相關文章！

最新評論