DeepSeek + 智谱 GLM · 钉钉 + 飞书 + 微信多平台接入

目录

1. 什么是 Hermes Agent？

2. 准备工作

3. 安装 Hermes

4. 初始化配置

5. 接入钉钉

6. 接入飞书

7. 配置 AI 模型

8. 配置 Gateway 开机自启

9. 安全加固

10. 常见问题与踩坑

11. 常用命令速查

1. 什么是 Hermes Agent？

Hermes 是一个开源的 AI Agent 平台，专注于将大语言模型与即时通讯平台深度集成。它本质上是一个消息网关 + AI 对话引擎，让 AI 能够通过钉钉、飞书、微信、Telegram 等平台与用户实时对话，同时具备完整的工具调用能力。

核心能力

• 多平台消息接入：钉钉、飞书、微信 Webhook、Telegram 等
• 多模型支持：DeepSeek、智谱 GLM、Ollama 本地模型等
• 工具调用：终端命令、文件读写、网页搜索、代码执行等
• 会话管理：上下文压缩、长期记忆、人设配置
• Gateway 守护进程：WebSocket 长连接，自动重连

架构概览

用户发送消息 → 钉钉/飞书/微信 → Hermes Gateway（WebSocket）→ Agent（LLM + 工具链）→ 回复用户

────────────────────────────────────────────────────────────

2. 准备工作

环境要求

• 操作系统：Windows 10/11（本文以 Windows 为例，Linux/macOS 类似）
• Python：3.10 ~ 3.13（不支持 Python 3.14）
• uv：最新版本（必须）
• 网络：能够访问 OpenAI API / DeepSeek API / 智谱 API
• 消息平台账号：需要管理员权限创建应用

安装 uv（必须）

Hermes 通过 uv 工具安装。uv 是 Rust 写的 Python 包管理器，比 pip 快 10~100 倍，且支持全局工具安装。

PowerShell

Windows PowerShell 安装：
irm https://astral.sh/uv/install.ps1 | iex

安装钉钉消息依赖（可选但建议）

Bash

pip install dingtalk-stream httpx

────────────────────────────────────────────────────────────

3. 安装 Hermes

uv 是 Hermes 唯一的安装方式。安装命令一行搞定：

Bash

uv tool install hermes-agent

验证安装：

Bash

hermes --version

安装完成后，Hermes 会创建一个配置文件目录 `~/.hermes/`（即 `C:/Users/你的用户名/.hermes/`），配置文件结构如下：

文件系统

~/.hermes/
  config.yaml     # 主配置文件（模型、工具、网关、压缩等）
  .env            # 密钥文件（API Key，分开存储更安全）
  SOUL.md         # Agent 人设/性格配置
  USER.md         # 用户信息
  MEMORY.md       # 长期记忆文件
  sessions/       # 会话数据目录
  logs/           # 运行日志目录
 

────────────────────────────────────────────────────────────

4. 初始化配置

运行交互式配置向导，程序会引导你完成初始配置：

Bash

hermes setup

向导会依次询问：

1. 选择 AI 模型提供商（DeepSeek / OpenAI / 智谱 / Ollama 等）
2. 输入 API Key
3. 选择要接入的消息平台（钉钉 / 飞书 / 微信）
4. 配置平台所需的凭证（Client ID、Secret 等）
5. 完成后自动写入 config.yaml

手动配置文件

如果不想用向导，可以直接编辑 `~/.hermes/.env` 文件，关键变量如下：

.env 文件示例

DEEPSEEK_API_KEY=sk-your-deepseek-key
ZAI_API_KEY=your-zhipu-key

FEISHU_APP_ID=cli_xxx
FEISHU_APP_SECRET=your-feishu-secret
FEISHU_CONNECTION_MODE=websocket

DINGTALK_CLIENT_ID=dingxxx
DINGTALK_CLIENT_SECRET=your-dingtalk-secret
DINGTALK_ALLOW_ALL_USERS=true

WEIXIN_ACCOUNT_ID=your-weixin-id
WEIXIN_TOKEN=your-weixin-token

然后查看当前配置：

Bash

hermes config show

查看运行状态：

Bash

hermes status

────────────────────────────────────────────────────────────

5. 接入钉钉

5.1 钉钉开放平台配置

第一步：在钉钉开放平台创建应用

1. 登录 open-dev.dingtalk.com
2. 进入"应用开发" → "企业内部开发"
3. 点击"创建应用"，填写应用名称和描述
4. 创建完成后，在"基础信息"中获取 AppKey（即 Client ID）和 AppSecret（即 Client Secret）
5. 在"消息推送"中，开启"Stream 模式"（推荐）或"HTTP 模式"
6. 如果用 Stream 模式，需要配置消息订阅地址（格式：https://你的域名/callback/dingtalk）

5.2 Hermes 配置

在 `.env` 中添加钉钉凭证：

.env

DINGTALK_CLIENT_ID=ding5xxxxxx
DINGTALK_CLIENT_SECRET=yz3xxxxxxxxxxxxxxxx
DINGTALK_ALLOW_ALL_USERS=true

运行钉钉平台安装命令（会自动写入 config.yaml）：

Bash

hermes gateway install dingtalk

或者手动在 config.yaml 的 platforms 中添加 dingtalk（不推荐，容易格式出错）。

5.3 验证钉钉接入

重启 Gateway 后检查状态：

Bash

hermes gateway restart
hermes status

看到 `DingTalk ✓ configured` 即表示接入成功。可以向机器人发一条消息测试回复。

────────────────────────────────────────────────────────────

6. 接入飞书

6.1 飞书开放平台配置

1. 登录 open.feishu.cn
2. 进入"开发者后台" → "创建企业自建应用"
3. 填写应用名称和图标
4. 在"凭证与基础信息"中获取 App ID 和 App Secret
5. 在"事件订阅"中，选择"使用长连接接收事件"（WebSocket 模式，无需公网地址）
6. 添加需要订阅的事件，如"接收消息"（im.message.receive_v1）
7. 在"权限管理"中申请相关权限（发消息、读用户信息等）

6.2 Hermes 配置

.env

FEISHU_APP_ID=cli_aa8xxxxxxxx
FEISHU_APP_SECRET=U5unxxxxxxxxxxxxxxxx
FEISHU_CONNECTION_MODE=websocket
FEISHU_GROUP_POLICY=open

安装飞书平台：

Bash

hermes gateway install feishu

────────────────────────────────────────────────────────────

7. 配置 AI 模型

7.1 DeepSeek（主模型）

DeepSeek 是默认主模型，配置最简单。在 `.env` 中写入 API Key：

.env

DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxx

config.yaml 中设置：

config.yaml

model:
  provider: deepseek
  model: deepseek-chat
  context_length: 200000

7.2 智谱 GLM（备用模型）

配置在 `custom_providers` 下，注意格式是 YAML 列表，不是字典（容易出错）：

config.yaml

custom_providers:
  - name: zhipu-glm
    model: glm-4.5-air
    api_key: ${ZAI_API_KEY}

`.env` 中添加：

.env

ZAI_API_KEY=your-zhipu-api-key

⚠️ 注意：智谱的环境变量名是 `ZAI_API_KEY`，不是 `ZHIPU_API_KEY`。写错变量名模型不会生效。

7.3 Ollama 本地模型（离线）

如果本地装了 Ollama，可以用离线模型，不消耗 API 额度：

config.yaml

custom_providers:
  - name: ollama-local
    api: http://localhost:11434
    model: qwen2.5:7b

然后在 config.yaml 中切换默认模型：

config.yaml

model:
  provider: ollama-local
  model: qwen2.5:7b

────────────────────────────────────────────────────────────

8. 配置 Gateway 开机自启

在 Windows 上，`hermes gateway install` 不是注册成 Windows 服务，而是创建一个"任务计划程序"任务，在用户登录时自动运行。

8.1 安装任务计划

Bash

hermes gateway install

这会创建：

• 任务名称：Hermes_Gateway
• 触发器：用户登录时
• 执行脚本：C:/Users/用户名/.hermes/gateway-service/Hermes_Gateway.cmd
• 权限：HighestAvailable（最高可用权限）

8.2 消除 CMD 启动弹窗（关键！）

默认情况下任务计划会弹出一个 CMD 窗口。需要修改为无窗口模式：

PowerShell（管理员）

# 查看当前任务配置
Get-ScheduledTask -TaskName "Hermes_Gateway" | Get-ScheduledTaskInfo

# 修改为无窗口模式（pythonw.exe + Hidden）
$action = New-ScheduledTaskAction -Execute "Python路径\pythonw.exe" -Argument "-m hermes_cli.main gateway run --replace"
$principal = New-ScheduledTaskPrincipal -UserId "你的用户名" -LogonType ServiceAccount -RunLevel Highest
$settings = New-ScheduledTaskSettingsSet -Hidden -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries -StartWhenAvailable
Register-ScheduledTask -TaskName "Hermes_Gateway" -Action $action -Principal $principal -Settings $settings -Force

关键改动：

• 用 `pythonw.exe` 替代 `python.exe`（无窗口版本）
• LogonType 设为 ServiceAccount（后台服务账户）
• Settings 加上 `-Hidden`（任务计划程序中隐藏）

8.3 手动管理 Gateway

Bash

hermes gateway start     # 启动
hermes gateway stop      # 停止
hermes gateway restart   # 重启
hermes status            # 查看状态（显示 PID 即在运行）

────────────────────────────────────────────────────────────

9. 安全加固

Hermes 默认配置有安全风险，建议按以下步骤加固。

9.1 API Key 安全存储

✅ 正确做法：Key 放在 .env 文件，config.yaml 中引用环境变量：

config.yaml

# .env（密钥文件）
DEEPSEEK_API_KEY=sk-xxxxxxxx

# config.yaml（配置）
model:
  api_key: ${DEEPSEEK_API_KEY}  # 不写死，留空让 Hermes 从 .env 读取

# 或直接留空，Hermes 会自动从 .env 读取
model:
  api_key: ""

❌ 错误做法：把 Key 直接写在 config.yaml 的明文中。

9.2 限制调用权限

默认 `allow_all_users: true` 意味着任何知道 Token 的人都能调用 Hermes。建议修改：

安全配置

# config.yaml
gateway:
  allow_all_users: false
  allowed_users:
    - your-user-id-here

# 或在 .env 中
GATEWAY_ALLOW_ALL_USERS=false

9.3 Windows 配置文件编码

⚠️ 重要：用 Python 或文本编辑器（VS Code）写配置文件，不要用 PowerShell 的 `echo` 或 `Set-Content`。PowerShell 默认写入 UTF-16 编码（带空字节），Hermes 读入时会报错 `ValueError: embedded null character`。

正确做法（Python）：

Python

# 用 Python 写 .env，UTF-8 无 BOM
with open(r"C:\Users\用户名\.hermes\.env", "w", encoding="utf-8") as f:
    f.write("DEEPSEEK_API_KEY=sk-xxx\n")
    f.write("ZAI_API_KEY=yyy\n")
 

────────────────────────────────────────────────────────────

10. 常见问题与踩坑

问题 1：症状：hermes status 报 "ValueError: embedded null character"

原因：.env 文件被 PowerShell 写成了 UTF-16 编码（带空字节）。
修复：用 Python 重写 .env 文件（指定 encoding="utf-8"）。

问题 2：症状：智谱 GLM 模型不生效，hermes status 显示未配置

原因1：.env 中变量名写错，写成了 ZHIPU_API_KEY，实际应为 ZAI_API_KEY。
原因2：config.yaml 中 custom_providers 格式写成字典了，应为 YAML 列表。

问题 3：症状：hermes status 报 "invalid continuation byte"

原因：config.yaml 文件编码损坏（被 PowerShell Set-Content 破坏）。
修复：从备份文件恢复，或用 Python 重写 config.yaml。

问题 4：症状：钉钉机器人不回复消息

原因1：Gateway 未运行 → `hermes gateway start`。
原因2：钉钉 Stream 模式配置有误 → 检查 Client ID/Secret。
原因3：钉钉应用未发布/未添加机器人到群。

问题 5：症状：hermes 不再回复（Gateway 停止）

原因：Gateway 进程崩溃或被系统结束。
修复：`hermes gateway start`，检查 logs/ 目录下的错误日志。

问题 6：症状：Hermes 回复很慢

原因：模型 API 延迟高 / 网络问题。
修复：检查 API Key 额度；配置备用模型；检查网络。

────────────────────────────────────────────────────────────

11. 常用命令速查

hermes setup  —  交互式配置向导

hermes status  —  查看运行状态、API Key、平台连接

hermes doctor  —  完整诊断检查

hermes doctor --fix  —  自动修复可修复项

hermes config show  —  查看当前完整配置

hermes config edit  —  编辑配置文件（交互式）

hermes model  —  切换默认模型（交互式）

hermes gateway start  —  启动 Gateway

hermes gateway stop  —  停止 Gateway

hermes gateway restart  —  重启 Gateway

hermes gateway install feishu  —  安装飞书平台

hermes gateway install dingtalk  —  安装钉钉平台

hermes auth  —  配置第三方 OAuth（Gemini、MiniMax 等）