nano ~/.hermes/.env

添加：

XIAOMI_API_KEY=tp-xxxxxx你的tokenplan的key
XIAOMI_BASE_URL=https://token-plan-cn.xiaomimimo.com/anthropic

坑點(diǎn)提醒： XIAOMI_BASE_URL 這個(gè)環(huán)境變量必須寫！Hermes 通過它來確定小米的 API 地址。如果只在 config.yaml 里寫 base_url 而不設(shè)這個(gè)環(huán)境變量，Hermes 還是會(huì)用默認(rèn)地址，導(dǎo)致你的 Token Plan key 認(rèn)證失?。?01 Invalid API Key）。

第二步：創(chuàng)建 Profile

mkdir -p ~/.hermes/profiles/xiaomimimo
nano ~/.hermes/profiles/xiaomimimo/config.yaml

寫入：

model:
  provider: xiaomi
  default: mimo-v2.5-pro
  api_key: tp-xxxxxx你的tokenplan的key
  base_url: https://token-plan-cn.xiaomimimo.com/anthropic

第三步：修復(fù)域名識(shí)別（重要！）

Hermes 默認(rèn)只識(shí)別 api.xiaomimimo.com 和 xiaomimimo.com，不認(rèn)識(shí) token-plan-cn.xiaomimimo.com。需要手動(dòng)添加：

nano ~/.hermes/hermes-agent/agent/model_metadata.py

搜索 "xiaomimimo.com": "xiaomi",（按 Ctrl+W 搜索），在它下面加一行：

    "token-plan-cn.xiaomimimo.com": "xiaomi",

改完后這幾行應(yīng)該是：

    "api.xiaomimimo.com": "xiaomi",
    "xiaomimimo.com": "xiaomi",
    "token-plan-cn.xiaomimimo.com": "xiaomi",

第四步：如果要作為全局默認(rèn)模型

nano ~/.hermes/config.yaml

確保 model: 部分是：

model:
  max_tokens: 16384
  default: mimo-v2.5-pro
  provider: xiaomi
  base_url: https://token-plan-cn.xiaomimimo.com/anthropic
  api_key: tp-xxxxxx你的tokenplan的key

4.4 配置方式三：小米 MiMo 按量計(jì)費(fèi)

適用場景：你在小米平臺(tái)注冊后獲得的默認(rèn) API key（sk- 開頭）。

第一步：設(shè)置 .env

nano ~/.hermes/.env

添加：

XIAOMI_API_KEY=sk-xxxxxx你的按量計(jì)費(fèi)key
XIAOMI_BASE_URL=https://api.xiaomimimo.com/v1

第二步：創(chuàng)建 Profile

mkdir -p ~/.hermes/profiles/xiaomimimo
nano ~/.hermes/profiles/xiaomimimo/config.yaml

寫入：

model:
  provider: xiaomi
  default: mimo-v2.5-pro
  api_key: sk-xxxxxx你的按量計(jì)費(fèi)key
  base_url: https://api.xiaomimimo.com/v1

按量計(jì)費(fèi)用的是 OpenAI 兼容協(xié)議（/v1 結(jié)尾），和 Token Plan 的 Anthropic 兼容協(xié)議（/anthropic 結(jié)尾）不一樣，不要搞混！

4.5 使用不同的 Profile

hermes -p marketing      # 用 Claude 代理配置啟動(dòng)
hermes -p xiaomimimo     # 用小米 MiMo 配置啟動(dòng)
hermes                   # 用全局默認(rèn)配置啟動(dòng)

在 WebUI 里可以直接在底部欄切換 profile，不需要命令行。

4.6 驗(yàn)證配置是否正確

配置完后，用 curl 測試一下能不能通：

測試 Claude 代理：

curl -s -o /dev/null -w '%{http_code}' -X POST 'https://你的代理地址/v1/messages' \
  -H 'x-api-key: 你的key' \
  -H 'anthropic-version: 2023-06-01' \
  -H 'content-type: application/json' \
  -d '{"model":"claude-opus-4-6","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}'

測試小米 Token Plan：

curl -s -o /dev/null -w '%{http_code}' -X POST 'https://token-plan-cn.xiaomimimo.com/anthropic/v1/messages' \
  -H 'x-api-key: 你的tp-開頭的key' \
  -H 'anthropic-version: 2023-06-01' \
  -H 'content-type: application/json' \
  -d '{"model":"mimo-v2.5-pro","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}'

測試小米按量計(jì)費(fèi)：

curl -s -o /dev/null -w '%{http_code}' -X POST 'https://api.xiaomimimo.com/v1/chat/completions' \
  -H 'Authorization: Bearer 你的sk-開頭的key' \
  -H 'content-type: application/json' \
  -d '{"model":"mimo-v2.5-pro","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}'

返回 200 就說明配置正確。如果返回 401 說明 key 無效，402 說明余額不足。

4.7 已知問題及修復(fù)

問題一：小米模型名稱 bug（503 錯(cuò)誤）

如果你用小米的 mimo-v2.5-pro 模型遇到 503 錯(cuò)誤（日志顯示請求的是 mimo-v2-5-pro），那是因?yàn)?Hermes 代碼中沒有把小米加入"保留點(diǎn)號(hào)"白名單，把版本號(hào)里的點(diǎn)變成了橫杠。

修復(fù)方法：

nano ~/.hermes/hermes-agent/run_agent.py

搜索 "alibaba", "minimax", "minimax-cn",（按 Ctrl+W 搜索），把這行改成：

"alibaba", "minimax", "minimax-cn", "xiaomi",

保存退出，重啟 hermes 即可。

問題二：Token Plan 報(bào) 401 Invalid API Key

最常見原因：沒有設(shè)置 XIAOMI_BASE_URL 環(huán)境變量。

Hermes 的小米 provider 通過 XIAOMI_BASE_URL 環(huán)境變量來確定 API 地址。即使你在 config.yaml 里寫了 base_url，如果 .env 里沒有這個(gè)變量，Hermes 還是會(huì)用默認(rèn)地址。你的 Token Plan key 在默認(rèn)地址上是無效的，所以報(bào) 401。

修復(fù)： 確保 .env 里有：

XIAOMI_BASE_URL=https://token-plan-cn.xiaomimimo.com/anthropic

問題三：余額不足（402 錯(cuò)誤）

• 按量計(jì)費(fèi)：去小米平臺(tái)充值
• Token Plan：檢查套餐是否到期或額度用完（在 https://platform.xiaomimimo.com 查看）

第五步：對(duì)接飛書機(jī)器人

讓 Hermes 變成你的飛書機(jī)器人，在飛書里直接跟 AI 聊天。

5.1 在飛書開放平臺(tái)創(chuàng)建機(jī)器人

1. 打開 https://open.feishu.cn/app
2. 點(diǎn)擊「創(chuàng)建企業(yè)自建應(yīng)用」
3. 填寫應(yīng)用名稱（比如「我的AI助手」）
4. 創(chuàng)建完成后，記下：
   • App ID（類似 cli_a9799aead7b89bd5）
   • App Secret（類似 3PAp4f3YVuJtmI6XpFevKcTranQU1Z7q）

5.2 配置機(jī)器人權(quán)限

在飛書開放平臺(tái)的應(yīng)用設(shè)置中：

1. 「添加應(yīng)用能力」→ 添加「機(jī)器人」
2. 「權(quán)限管理」→ 開通以下權(quán)限：
   • im:message （接收消息）
   • im:message:send_as_bot （發(fā)送消息）
3. 「事件訂閱」→ 選擇 WebSocket 模式（推薦，不需要公網(wǎng)服務(wù)器）
4. 發(fā)布應(yīng)用（版本管理 → 創(chuàng)建版本 → 申請發(fā)布）

5.3 在 Hermes 中配置飛書

編輯 .env 文件：

nano ~/.hermes/.env

添加以下內(nèi)容：

# 飛書配置
FEISHU_APP_ID=你的App_ID
FEISHU_APP_SECRET=你的App_Secret
FEISHU_DOMAIN=feishu
FEISHU_CONNECTION_MODE=websocket
FEISHU_ALLOW_ALL_USERS=false
FEISHU_ALLOWED_USERS=
FEISHU_GROUP_POLICY=open
FEISHU_HOME_CHANNEL=你的App_ID

保存退出。

5.4 啟動(dòng) Gateway（消息網(wǎng)關(guān)）

hermes gateway run

看到類似這樣的輸出就成功了：

[Lark] connected to wss://msg-frontier.feishu.cn/ws/v2?...

5.5 配對(duì)你的飛書賬號(hào)

第一次在飛書上給機(jī)器人發(fā)消息，機(jī)器人會(huì)回復(fù)一個(gè)配對(duì)碼，類似：

Hi~ I don't recognize you yet!
Here's your pairing code: K4UUPYM4
Ask the bot owner to run:
    hermes pairing approve feishu K4UUPYM4

在 WSL 中另開一個(gè)終端（或按 Ctrl+C 停掉 gateway 再執(zhí)行），運(yùn)行：

hermes pairing approve feishu 你收到的配對(duì)碼

看到 Approved! 就配對(duì)成功了。之后在飛書上給機(jī)器人發(fā)消息就能正常聊天了。

5.6 讓 Gateway 后臺(tái)運(yùn)行

前臺(tái)運(yùn)行的話關(guān)掉終端就斷了。用 nohup 讓它后臺(tái)跑：

nohup hermes gateway run > ~/.hermes/gateway.log 2>&1 &

查看運(yùn)行狀態(tài)：

hermes gateway status

停止運(yùn)行：

kill $(ps aux | grep 'hermes gateway' | grep -v grep | awk '{print $2}')

常用命令速查表

啟動(dòng)類

配置類

管理類

聊天中的命令（在 hermes 對(duì)話中輸入）

常見問題

Q: WSL 重啟后 Hermes 和 WebUI 都沒了？

A: 數(shù)據(jù)不會(huì)丟，但進(jìn)程需要重新啟動(dòng)：

# 啟動(dòng) WebUI
cd ~/hermes-webui && python3 bootstrap.py --no-browser

# 啟動(dòng) Gateway（飛書等）
hermes gateway run

Q: 安裝時(shí) ripgrep 和 ffmpeg 失??？

A: 先更新 apt 源再裝：

sudo apt-get update
sudo apt-get install -y ripgrep ffmpeg

這兩個(gè)是可選的，不裝也不影響核心功能。

Q: API 連不上（走代理的情況）？

A: 確認(rèn) .env 文件中的 BASE_URL 設(shè)置正確。不同代理的路徑格式可能不同：

• https://你的代理地址
• https://你的代理地址/v1
• https://你的代理地址/anthropic

Q: 小米模型報(bào) 503？

A: 參考第四步的「已知問題：小米模型名稱 bug」修復(fù)。

Q: sudo hermes 提示 command not found？

A: hermes 裝在用戶目錄下，sudo 找不到。不要用 sudo，直接運(yùn)行 hermes 就行。Gateway 也用 hermes gateway run 而不是 systemd 服務(wù)。

Q: 飛書機(jī)器人收不到消息？

A: 檢查以下幾點(diǎn)：

1. Gateway 是否在運(yùn)行（hermes gateway run）
2. 飛書應(yīng)用是否已發(fā)布上線
3. 是否已配對(duì)（hermes pairing approve feishu 配對(duì)碼）
4. WebSocket 模式是否已開啟

Q: 怎么讓多個(gè) profile 同時(shí)對(duì)接飛書？

A: Gateway 默認(rèn)用全局配置。如果想指定 profile：

hermes -p xiaomimimo gateway run

第六步：在飛書中操作項(xiàng)目（進(jìn)階用法）

Hermes 不只是聊天，還可以通過飛書遠(yuǎn)程操作你的代碼項(xiàng)目——讀文件、寫文件、跑命令，就像一個(gè)遠(yuǎn)程編程助手。

飛書中可用的命令

在飛書聊天框里直接輸入這些斜杠命令：

設(shè)置工作目錄（讓 Hermes 能操作你的項(xiàng)目）

Gateway 啟動(dòng)時(shí)會(huì)用配置中的 terminal.cwd 作為工作目錄。改成你的項(xiàng)目路徑，Hermes 就能在飛書里直接操作你的代碼了：

nano ~/.hermes/config.yaml

找到 terminal 部分，修改 cwd：

terminal:
  cwd: /home/p/你的項(xiàng)目路徑

比如你的項(xiàng)目在 /home/p/myproject，就改成：

terminal:
  cwd: /home/p/myproject

保存后重啟 gateway 生效。

你也可以直接在飛書對(duì)話中讓 Hermes 用 cd 命令切換目錄，不一定非要改配置。

WebUI vs 飛書 功能對(duì)比

用指定 Profile 啟動(dòng)飛書 Gateway

飛書中不能動(dòng)態(tài)切換 profile，但可以在啟動(dòng)時(shí)指定：

# 用小米模型對(duì)接飛書
hermes -p xiaomimimo gateway run

# 用 Claude 對(duì)接飛書
hermes -p marketing gateway run

實(shí)際使用場景舉例

在飛書中你可以這樣跟 Hermes 說：

• "幫我看看 src/main.py 的代碼"
• "把 config.json 里的 debug 改成 false"
• "跑一下測試 pytest tests/"
• "幫我寫一個(gè)新的 API 接口"
• "看看 git log 最近提交了什么"

Hermes 會(huì)在你指定的工作目錄下執(zhí)行這些操作，就像你坐在電腦前一樣。

重要文件位置

第七步：性能優(yōu)化與多 Agent 協(xié)作（進(jìn)階）

7.1 解決"干著干著就停了"的問題

如果你發(fā)現(xiàn) Hermes 在生成長內(nèi)容時(shí)突然停掉（特別是用小米 MiMo 模型時(shí)），原因是默認(rèn)輸出 token 上限太低（4096），生成到一半就被截?cái)嗔恕?/p>

修復(fù)方法：增大 max_tokens

nano ~/.hermes/config.yaml

在 model: 部分添加 max_tokens：

model:
  max_tokens: 16384
  default: mimo-v2.5-pro
  provider: xiaomi

16384 對(duì)于大多數(shù)任務(wù)足夠了。如果還是不夠，可以改成 32768。

7.2 顯示思考過程

默認(rèn)配置下 Hermes 不展示 AI 的推理過程，看起來就是一直在 "thinking" 但你不知道它在干什么。

修復(fù)方法：開啟 show_reasoning

在 ~/.hermes/config.yaml 中找到 display 部分，改成：

display:
  show_reasoning: true

這樣就能在對(duì)話中看到模型的思考過程了。

7.3 多 Agent 協(xié)作（讓多個(gè) AI 一起干活）

Hermes 支持 orchestrator 編排模式：一個(gè)主 Agent 把復(fù)雜任務(wù)拆分成多個(gè)子任務(wù)，分配給多個(gè)子 Agent 并行執(zhí)行。

相關(guān)配置（在 ~/.hermes/config.yaml 中）：

delegation:
  model: claude-opus-4-6          # 編排器用的模型（建議用聰明的）
  provider: anthropic             # 編排器的 provider
  orchestrator_enabled: true      # 開啟編排器
  max_concurrent_children: 3      # 最多3個(gè)子agent同時(shí)工作
  max_spawn_depth: 1              # 子agent嵌套層級(jí)
  max_iterations: 50              # 每個(gè)子agent最多執(zhí)行50輪
  child_timeout_seconds: 600      # 子agent超時(shí)時(shí)間（秒）

推薦配置策略：

這樣性價(jià)比最高：編排器用 Claude 來規(guī)劃，子任務(wù)用便宜/免費(fèi)的模型來執(zhí)行。

怎么觸發(fā)多 Agent：

在對(duì)話中給 Hermes 一個(gè)復(fù)雜的多步驟任務(wù)，比如：

• "幫我做一個(gè)完整的項(xiàng)目，包括前端、后端和數(shù)據(jù)庫設(shè)計(jì)"
• "請拆解這個(gè)任務(wù)，用多個(gè)子agent并行完成"
• "同時(shí)分析這三個(gè)文件的代碼質(zhì)量"

Hermes 的 orchestrator 會(huì)自動(dòng)判斷是否要拆分，并行執(zhí)行子任務(wù)。

7.4 推理深度調(diào)整

如果覺得模型回答太淺，可以調(diào)整 reasoning_effort：

agent:
  reasoning_effort: high    # 可選值：low / medium / high

• low：快速回答，適合簡單問題
• medium：默認(rèn)值，平衡速度和質(zhì)量
• high：深度思考，適合復(fù)雜推理任務(wù)

相關(guān)鏈接

• Hermes Agent GitHub: https://github.com/NousResearch/hermes-agent
• Hermes WebUI GitHub: https://github.com/nesquena/hermes-webui
• Hermes 官方文檔: https://hermes-agent.nousresearch.com/docs/
• 飛書開放平臺(tái): https://open.feishu.cn/app
• 小米 MiMo 平臺(tái): https://platform.xiaomimimo.com