Hermes Agent 串接 MiniMax API 疑難排解指南

發布日期： 2026-04-11

標籤： Hermes Agent, MiniMax, AI, Telegram Bot, 教學

---

前言

前幾天在設定 Hermes Agent 串接 MiniMax API 時，遇到了一個很折騰的問題：明明 API Key 測試可以正常運作，但 Hermes 怎麼測都是 401 錯誤。

折騰了一個晚上，終於找到問題根源。這篇文就是要記錄下這個過程，幫助其他遇到同樣問題的人。

---

問題現象

在 Telegram Bot 傳訊息給 Hermes 時，出現這個錯誤：

⚠️ Error code: 401 - {'type': 'error', 'error': {'type': 'authentication_error', 'message': 'invalid api key'}}

但是！直接用 curl 測試 API 是可以正常運作的：

curl -X POST https://api.minimaxi.com/anthropic/v1/messages \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "anthropic-version: 2023-06-01" \
 -d '{"model":"MiniMax-M2.7","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}'

這個測試會成功，但 Hermes 就是一直 401。

---

問題根源

Hermes Agent 對 MiniMax 有兩個內建 Provider：

Provider 名稱	適用的 API Key	API Endpoint
minimax	MiniMax 國際版	api.minimax.io
minimax-cn	MiniMax 中國版	api.minimaxi.com

問題在於：從 MiniMax 官網拿到的 API Key 是中國版（api.minimaxi.com），但如果直接設定 minimax-cn，Hermes 還是會用錯誤的 endpoint。

看日誌就能發現問題：

🔌 Provider: minimax  Model: minimax-cn/MiniMax-M2.7
🌐 Endpoint: https://api.minimax.io/anthropic  ← 錯誤！應該是 api.minimaxi.com

Hermes 看到 Provider 名稱是 minimax-cn 時，應該要用中國版 endpoint，但不知道為什麼一直用國際版。

---

解決方案

既然內建的 Provider 有問題，那我們就自己設定 Custom Provider。

步驟 1：編輯 config.yaml

~/.hermes/config.yaml

把 model 區塊改成這樣：

model:
  provider: custom
  default: MiniMax-M2.7
  base_url: https://api.minimaxi.com/anthropic
  api_key: 你的API_KEY
  api_mode: anthropic_messages

步驟 2：重啟 Gateway

hermes gateway restart

步驟 3：測試

去 Telegram Bot 傳 /new 開新 session，然後說 hi。

---

關鍵重點

• API Key 測試可以過，但 Hermes 一直 401 → 通常是 Endpoint 設定錯誤
• MiniMax 中國版官網金鑰 → 只能用 api.minimaxi.com
• 內建 Provider 有問題 → 用 Custom Provider 最穩
• 直接設定 baseurl + apikey → 繞過內建 Provider 的問題

---

完整設定檔參考

# ~/.hermes/config.yaml

model:
  provider: custom
  default: MiniMax-M2.7
  base_url: https://api.minimaxi.com/anthropic
  api_key: sk-cp-xxxxxxxxxxxxxxx
  api_mode: anthropic_messages

# ~/.hermes/.env
MINIMAX_CN_API_KEY=sk-cp-xxxxxxxxxxxxxxx

---

後記

這個問題折騰了我好幾個小時，主要是一直以為是 API Key 本身有問題，沒想到是 Hermes 的 Provider 對應錯誤。

如果你也遇到類似的問題，先看日誌確認：

tail -100 ~/.hermes/logs/gateway.log | grep -i "endpoint\|error\|401"

看到 Endpoint: 後確認是否對應到正確的 API 網址。

希望這篇文能幫到遇到同樣問題的人！

---

有問題歡迎留言討論～