本教程從零開始，記錄了在一臺(tái) Linux 服務(wù)器上安裝 Hermes Agent 并對(duì)接企業(yè)微信 AI Bot 的完整過程，包括遇到的所有坑和解決方案。

目錄

1. Hermes Agent 是什么
2. 環(huán)境要求
3. 第一步：克隆代碼
4. 第二步：創(chuàng)建 Python 虛擬環(huán)境并安裝依賴
5. 第三步：配置 LLM 模型
6. 第四步：配置企業(yè)微信 AI Bot
7. 第五步：?jiǎn)?dòng)網(wǎng)關(guān)
8. 遇到的問題與解決方案
9. 常用命令速查
10. 附錄：兩種企業(yè)微信模式對(duì)比

1. Hermes Agent 是什么

Hermes Agent 是 Nous Research 開發(fā)的開源 AI Agent，具有以下特點(diǎn)：

• 自學(xué)習(xí)閉環(huán)：從經(jīng)驗(yàn)中自動(dòng)創(chuàng)建技能，使用中持續(xù)改進(jìn)，跨會(huì)話記憶搜索
• 多平臺(tái)對(duì)接：Telegram、Discord、Slack、WhatsApp、Signal、企業(yè)微信、飛書、釘釘?shù)?/li>
• 多模型支持：OpenRouter（200+ 模型）、Anthropic Claude、OpenAI、智譜 GLM、Kimi、MiniMax 等，一條命令切換
• 可運(yùn)行在任何地方：本地機(jī)器、$5 VPS、Docker、云服務(wù)

本教程聚焦于 企業(yè)微信 AI Bot 對(duì)接方式，使用 WebSocket 長(zhǎng)連接，無需公網(wǎng) IP。

2. 環(huán)境要求

檢查你的環(huán)境：

python3 --version   # 確認(rèn) Python >= 3.11
which uv            # 檢查 uv 是否安裝（推薦的包管理器）

如果 uv 未安裝：

curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.bashrc

3. 第一步：克隆代碼

方式 A：淺克隆（推薦，下載快）

倉庫比較大（含文檔和資源文件），淺克隆只下載最新代碼，節(jié)省時(shí)間和空間：

cd ~
git clone --depth 1 https://github.com/NousResearch/hermes-agent.git
cd hermes-agent

方式 B：官方一鍵安裝腳本

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

坑 #1：完整克?。?code>git clone 不加 --depth 1）在國(guó)內(nèi)網(wǎng)絡(luò)環(huán)境下可能非常慢，倉庫超過 80MB。建議使用淺克隆。

4. 第二步：創(chuàng)建 Python 虛擬環(huán)境并安裝依賴

cd ~/hermes-agent

# 創(chuàng)建虛擬環(huán)境
uv venv venv

# 激活虛擬環(huán)境
source venv/bin/activate

# 安裝依賴（包含消息平臺(tái)、cron 定時(shí)任務(wù)、開發(fā)工具等）
uv pip install -e ".[messaging,cron,cli,pty,mcp,dev]"

坑 #2：PyPI 在國(guó)內(nèi)經(jīng)常超時(shí)（operation timed out）。解決方案：使用清華鏡像源：

坑 #3：阿里云鏡像源版本不全，會(huì)報(bào) No solution found 錯(cuò)誤。不要用阿里云鏡像，用清華源。

uv pip install -e ".[messaging,cron,cli,pty,mcp,dev]" \
  -i https://pypi.tuna.tsinghua.edu.cn/simple/ \
  --trusted-host pypi.tuna.tsinghua.edu.cn

驗(yàn)證安裝成功：

python -c "from gateway.platforms.wecom import check_wecom_requirements; print('OK:', check_wecom_requirements())"
# 輸出：OK: True

5. 第三步：配置 LLM 模型

Hermes 需要一個(gè) LLM 提供商來驅(qū)動(dòng)對(duì)話。支持多種方式：

方式 A：使用智譜 GLM（國(guó)內(nèi)推薦）

編輯項(xiàng)目根目錄下的 .env 文件：

# .env
GLM_API_KEY=你的智譜API密鑰

獲取密鑰：訪問 open.bigmodel.cn 注冊(cè)并創(chuàng)建 API Key。

然后編輯 ~/.hermes/config.yaml，設(shè)置模型和提供商：

model:
  default: glm-5-turbo        # 或 glm-4-plus、glm-4-flash 等
  provider: zai               # 智譜 GLM 的 provider 名

方式 B：使用 OpenRouter（國(guó)際推薦，200+ 模型）

# .env
OPENROUTER_API_KEY=sk-or-你的密鑰

# ~/.hermes/config.yaml
model:
  default: anthropic/claude-sonnet-4-6
  provider: auto
  base_url: https://openrouter.ai/api/v1

獲取密鑰：訪問 openrouter.ai/keys。

方式 C：使用 Anthropic Claude 直連

# .env
ANTHROPIC_API_KEY=sk-ant-你的密鑰

其他支持的提供商

運(yùn)行 hermes model 可以交互式選擇模型。

6. 第四步：配置企業(yè)微信 AI Bot

6.1 在企業(yè)微信管理后臺(tái)創(chuàng)建 AI Bot

1. 登錄 企業(yè)微信管理后臺(tái)
2. 進(jìn)入 應(yīng)用管理 → AI 助手（或搜索「AI Bot」）
3. 創(chuàng)建一個(gè)新的 AI Bot
4. 記錄下 Bot ID 和 Secret

6.2 配置連接參數(shù)

在項(xiàng)目根目錄的 .env 文件中添加：

# .env
WECOM_BOT_ID=你的Bot_ID
WECOM_SECRET=你的Secret
WECOM_HOME_CHANNEL=你的用戶ID    # 可選，cron 定時(shí)任務(wù)的默認(rèn)發(fā)送目標(biāo)

WebSocket URL 默認(rèn)是 wss://openws.work.weixin.qq.com，國(guó)內(nèi)直連，無需修改。

注意：也可以選擇在 ~/.hermes/config.yaml 中配置，效果相同：

.env 中的值會(huì)覆蓋 config.yaml，所以只需配置一處。

platforms:
  wecom:
    enabled: true
    extra:
      bot_id: "你的Bot_ID"
      secret: "你的Secret"
      websocket_url: "wss://openws.work.weixin.qq.com"
      dm_policy: "open"        # 私聊策略：open（所有人可用）
      group_policy: "open"     # 群聊策略

6.3 驗(yàn)證配置

hermes doctor

檢查輸出中 WeCom 部分是否顯示配置正確。

7. 第五步：?jiǎn)?dòng)網(wǎng)關(guān)

# 確保在項(xiàng)目目錄且虛擬環(huán)境已激活
source venv/bin/activate

# 啟動(dòng)網(wǎng)關(guān)
hermes gateway

hermes gateway 會(huì)以交互式菜單啟動(dòng)，你可以選擇前臺(tái)運(yùn)行或安裝為后臺(tái)服務(wù)。

注意：hermes gateway start 嘗試通過 systemd 啟動(dòng)后臺(tái)服務(wù)，在沒有安裝 systemd 服務(wù)單元的系統(tǒng)上會(huì)報(bào)錯(cuò) Unit hermes-gateway.service not found。首次使用直接運(yùn)行 hermes gateway 即可。

啟動(dòng)成功后，日志中應(yīng)看到類似：

[WeCom] Connected via WebSocket to wss://openws.work.weixin.qq.com
[WeCom] Authentication successful

然后在企業(yè)微信中找到你的 AI Bot，發(fā)送消息即可對(duì)話。

快捷啟動(dòng)腳本

創(chuàng)建 start.sh：

#!/bin/bash
cd ~/hermes-agent
source venv/bin/activate
hermes gateway

chmod +x start.sh
./start.sh

8. 遇到的問題與解決方案

問題 1：Git 克隆速度極慢

現(xiàn)象：git clone 下載到 70-80MB 后幾乎停滯，等待超過 10 分鐘未完成。

原因：倉庫較大（含文檔資源），GitHub 在國(guó)內(nèi)直連不穩(wěn)定。

解決：使用淺克隆 git clone --depth 1，只下載最新版本，速度提升數(shù)倍。

問題 2：PyPI 超時(shí)

現(xiàn)象：

error: Request failed after 3 retries
  Caused by: Failed to fetch: `https://pypi.org/simple/yarl/`
  Caused by: operation timed out

解決：使用清華鏡像源：

uv pip install -e ".[messaging,...]" \
  -i https://pypi.tuna.tsinghua.edu.cn/simple/ \
  --trusted-host pypi.tuna.tsinghua.edu.cn

問題 3：阿里云鏡像版本不全

現(xiàn)象：

No solution found when resolving dependencies:
  Because there are no versions of openai...

原因：阿里云 PyPI 鏡像同步不完整，缺少 openai>=2.21.0 等新版本包。

解決：改用清華源，同步更及時(shí)。

問題 4：hermes gateway start 報(bào)錯(cuò)找不到 systemd 服務(wù)

現(xiàn)象：

Failed to start hermes-gateway.service: Unit hermes-gateway.service not found.
subprocess.CalledProcessError: Command '['systemctl', '--user', 'start', 'hermes-gateway']' returned non-zero exit status 5.

原因：hermes gateway start 會(huì)嘗試通過 systemd 管理后臺(tái)服務(wù)，但首次使用時(shí)服務(wù)單元尚未安裝。

解決：直接使用 hermes gateway 啟動(dòng)即可。如果確實(shí)需要 systemd 后臺(tái)服務(wù)，先運(yùn)行 hermes gateway install 安裝服務(wù)單元，再使用 hermes gateway start。

9. 常用命令速查

10. 附錄：兩種企業(yè)微信模式對(duì)比

Hermes 內(nèi)置了 兩種 企業(yè)微信對(duì)接模式：

如果需要使用自建應(yīng)用回調(diào)模式，在 .env 中配置：

WECOM_CALLBACK_CORP_ID=你的企業(yè)ID
WECOM_CALLBACK_CORP_SECRET=你的應(yīng)用Secret
WECOM_CALLBACK_AGENT_ID=應(yīng)用AgentId
WECOM_CALLBACK_TOKEN=接收消息的Token
WECOM_CALLBACK_ENCODING_AES_KEY=消息加解密密鑰
WECOM_CALLBACK_HOST=0.0.0.0
WECOM_CALLBACK_PORT=8645

參考鏈接

• 官方文檔：hermes-agent.nousresearch.com
• GitHub 倉庫：github.com/NousResearch/hermes-agent
• Discord 社區(qū)：discord.gg/NousResearch
• 智譜 GLM API：open.bigmodel.cn
• OpenRouter：openrouter.ai
• 企業(yè)微信管理后臺(tái)：work.weixin.qq.com