AI Agent - Hermes Agent 部署

Hermes Agent 部署

• Hermes Agent 部署指南
• • 目录
  • 1. 环境准备
  • • 系统要求
    • 安装系统依赖
  • 2. 下载源码与安装
  • • 方式一：Shell 安装脚本（推荐）
    • 方式二：Git 源码安装
    • 方式三：PyPI 安装
    • 初始化配置
  • 3. 配置 LLM 模型
  • • 获取 API Key
    • 配置 model 段
    • 配置 API Key
  • 4. 获取 QQ Bot 凭证
  • • 4.1 注册 QQ 开放平台
    • 4.2 创建机器人应用
    • 4.3 获取凭证
    • 4.4 配置机器人权限
  • 5. 配置 Hermes Gateway
  • • 5.1 设置凭证（.env）
    • 5.2 设置平台配置（config.yaml）
    • 5.3 配置说明
    • • dm_policy / group_policy
      • 限制用户（allowlist 模式）
  • 6. 启动 Gateway 服务
  • • 方式一：前台运行（调试用）
    • 方式二：安装为系统服务（推荐）
    • 6.1 验证连接
    • 6.2 查看日志
  • 7. 配对授权用户
  • • 默认行为
    • 跳过配对（开放模式）
    • 查看已配对用户
    • 撤销授权
  • 8. 验证交互
  • • 测试功能
  • 9. 进阶配置
  • • 语音转文字（STT）
    • Agent 配置
    • 记忆系统
    • 多平台并行
  • 10. 故障排查
  • • 常见问题
    • • 1. QQ Bot 连接失败
      • 2. QQAdapter.connect() 报错
      • 3. 发消息后 Bot 无反应
      • 4. Gateway 退出后无法自动重启
      • 5. 网络无法连接 QQ API
  • 完整配置文件示例
  • • ~/.hermes/config.yaml
    • ~/.hermes/.env（QQ 相关部分）
  • 快速命令参考

Hermes Agent 部署指南

---

目录

1. 环境准备
2. 下载源码与安装
3. 配置 LLM 模型
4. 获取 QQ Bot 凭证
5. 配置 Hermes Gateway
6. 启动 Gateway 服务
7. 配对授权用户
8. 验证交互
9. 进阶配置
10. 故障排查

---

1. 环境准备

系统要求

项目	要求
操作系统	Linux (推荐 Ubuntu 20.04+) / macOS / WSL2
Python	3.10+
Node.js	18+（TUI 界面需要，可选）
网络	能访问api.sgroup.qq.com（QQ Bot API）

安装系统依赖

# Ubuntu/Debiansudoaptupdate&&sudoaptinstall-ypython3 python3-pip python3-venvgitcurl# CentOS/RHELsudoyuminstall-ypython3 python3-pipgitcurl

---

2. 下载源码与安装

方式一：Shell 安装脚本（推荐）

curl-fsSLhttps://hermes-agent.nousresearch.com/install.sh|bash

方式二：Git 源码安装

# 克隆仓库gitclone https://github.com/NousResearch/hermes-agent.gitcdhermes-agent# 用项目自带的 setup-hermes.sh（最简单）# source ~/.bashrc# 安装 Python 依赖环境sudoaptinstallpython3 python3-pip python3-venv python3-mvenv /opt/hermes-agent/venvsource/opt/hermes-agent/venv/bin/activate# 安装（创建 venv + 安装依赖）pipinstall-e.# 开发模式安装（推荐）# 或使用 uvpipinstalluv&&uvsync# 验证安装hermes--version

方式三：PyPI 安装

pipinstallhermes-agent# 或uv pipinstallhermes-agent

初始化配置

hermes setup

交互式向导会引导你完成基础配置（模型、终端等）。

---

3. 配置 LLM 模型

Hermes 需要一个 LLM 后端来驱动对话。以阿里巴巴 DashScope（通义千问）为例：

获取 API Key

1. 访问 https://dashscope.console.aliyun.com/
2. 创建 API Key

配置 model 段

编辑~/.hermes/config.yaml：

model:default:qwen3.6-flash# 模型名称provider:alibaba# 提供商base_url:https://dashscope.aliyuncs.com/compatible-mode/v1

配置 API Key

编辑~/.hermes/.env：

DASHSCOPE_API_KEY=sk-xxxx-your-key-here

4. 获取 QQ Bot 凭证

4.1 注册 QQ 开放平台

1. 访问 https://q.qq.com/
2. 使用 QQ 账号登录
3. 完成开发者认证

4.2 创建机器人应用

1. 进入「应用管理」→「创建应用」
2. 选择「机器人」类型
3. 填写应用信息（名称、头像、描述）
4. 提交审核（通常几分钟到几小时）

4.3 获取凭证

审核通过后，在应用详情页找到：

字段	说明	示例
AppID	应用唯一标识	111xxxxxx
AppSecret	应用密钥	oxxxxxxx

4.4 配置机器人权限

在 QQ 开放平台的「机器人配置」页：

• 开启单聊（C2C）消息权限
• 开启群聊 @消息权限（如果需要群聊）
• 开启Markdown 消息（可选）

---

5. 配置 Hermes Gateway

5.1 设置凭证（.env）

在~/.hermes/.env末尾添加：

# QQ BOT INTEGRATIONQQ_APP_ID=你的APP_IDQQ_CLIENT_SECRET=你的APP_SECRET

5.2 设置平台配置（config.yaml）

在~/.hermes/config.yaml末尾添加：

platforms:qq:enabled:trueextra:markdown_support:true# 启用 QQ Markdown 消息dm_policy:"open"# 私聊策略：open | allowlist | disabledgroup_policy:"open"# 群聊策略：open | allowlist | disabled

5.3 配置说明

dm_policy / group_policy

值	含义
open	所有人可以私聊/群聊 Bot
allowlist	仅允许列表中的用户
disabled	完全禁用

限制用户（allowlist 模式）

platforms:qq:enabled:trueextra:dm_policy:"allowlist"allow_from:["user_openid_1","user_openid_2"]group_policy:"allowlist"group_allow_from:["group_openid_1"]

openid 可在 Bot 首次收到消息时从日志中获取。

---

6. 启动 Gateway 服务

方式一：前台运行（调试用）

hermes gateway run

方式二：安装为系统服务（推荐）

# 安装并启动hermes gatewayinstall# 管理命令hermes gateway start# 启动hermes gateway stop# 停止hermes gateway restart# 重启hermes gateway status# 查看状态

6.1 验证连接

hermes gateway status

期望输出包含：

✓ qqbot connected Gateway running with 1 platform(s)

6.2 查看日志

# 实时查看 gateway 日志tail-f~/.hermes/logs/gateway.log# 查看 systemd 日志journalctl--user-uhermes-gateway-f

期望看到：

[QQBot:<APP_ID>] Access token refreshed, expires in 7200s [QQBot:<APP_ID>] Gateway URL: wss://api.sgroup.qq.com/websocket [QQBot:<APP_ID>] WebSocket connected [QQBot:<APP_ID>] Ready, session_id=xxxxxxxx

---

7. 配对授权用户

默认行为

首次发消息时，QQ 会弹出一个配对码（如E2RXT2KV），需要管理员在服务器端批准：

hermes pairing approve qqbot<配对码>

示例：

hermes pairing approve qqbot E2RXT2KV# 输出：Approved! User xxx on qqbot can now use the bot~

跳过配对（开放模式）

如果不需要配对验证，在.env中设置：

GATEWAY_ALLOW_ALL_USERS=true

然后重启 gateway：

hermes gateway restart

查看已配对用户

hermes pairing list

撤销授权

hermes pairing revoke qqbot<user_id>

---

8. 验证交互

1. 打开 QQ，找到你的 Bot
2. 发送一条消息，如你好
3. Bot 应该会在几秒内回复

测试功能

你好 → 基本对话 帮我写一个 Python 冒泡排序 → 代码生成 今天天气怎么样 → 工具调用（需 web 工具集）

---

9. 进阶配置

语音转文字（STT）

QQ 自带腾讯 ASR（免费），也可接入其他 STT：

platforms:qq:enabled:trueextra:stt:provider:"zai"# zai (GLM-ASR) / openai (Whisper)baseUrl:"https://open.bigmodel.cn/api/coding/paas/v4"apiKey:***model:"glm-asr"

Agent 配置

agent:max_turns:150# 最大对话轮次reasoning_effort:medium# 推理力度：none/low/medium/high

记忆系统

memory:memory_enabled:true# 跨会话记忆user_profile_enabled:true# 用户画像

多平台并行

可以同时启用多个平台：

platforms:qq:enabled:trueextra:dm_policy:"open"telegram:enabled:trueextra:token:"your-telegram-bot-token"

---

10. 故障排查

常见问题

1. QQ Bot 连接失败

QQ startup failed: QQ_APP_ID and QQ_CLIENT_SECRET are required

解决：检查~/.hermes/.env中是否配置了QQ_APP_ID和QQ_CLIENT_SECRET。

2. QQAdapter.connect() 报错

QQAdapter.connect() got an unexpected keyword argument 'is_reconnect'

解决：这是已知 bug。修复方法：

# 找到 adapter.py 文件sed-i's/async def connect(self) -> bool:/async def connect(self, *, is_reconnect: bool = False) -> bool:/'\$(python3-c"import gateway.platforms.qqbot.adapter; print(gateway.platforms.qqbot.adapter.__file__)")

或直接编辑gateway/platforms/qqbot/adapter.py，将：

asyncdefconnect(self)->bool:

改为：

asyncdefconnect(self,*,is_reconnect:bool=False)->bool:

3. 发消息后 Bot 无反应

检查：

1. Gateway 是否正在运行：hermes gateway status
2. QQ 是否已连接：看日志中是否有✓ qqbot connected
3. 用户是否已配对：hermes pairing list
4. 查看错误日志：tail -50 ~/.hermes/logs/gateway.log

4. Gateway 退出后无法自动重启

# 确认 systemd 服务已安装hermes gatewayinstall# 启用 linger（SSH 退出后服务不中断）sudologinctl enable-linger$USER

5. 网络无法连接 QQ API

# 测试网络连通性curl-vhttps://api.sgroup.qq.com/

如果超时，检查防火墙或代理设置。

---

完整配置文件示例

~/.hermes/config.yaml

model:default:qwen3.6-flashprovider:alibababase_url:https://dashscope.aliyuncs.com/compatible-mode/v1agent:max_turns:150reasoning_effort:mediumterminal:backend:localcwd:.timeout:180memory:memory_enabled:trueuser_profile_enabled:trueplatforms:qq:enabled:trueextra:markdown_support:truedm_policy:"open"group_policy:"open"

~/.hermes/.env（QQ 相关部分）

# LLMDASHSCOPE_API_KEY=sk-xxxx-your-key# QQ BOTQQ_APP_ID=1904843353QQ_CLIENT_SECRET=oY6RZT9crsfFbkfN

---

快速命令参考

# 安装curl-fsSLhttps://hermes-agent.nousresearch.com/install.sh|bash# 配置hermes setup# 交互式配置hermes config edit# 编辑 config.yamlhermes config env-path# 查看 .env 路径# Gatewayhermes gatewayinstall# 安装服务hermes gateway start/stop/restart# 控制服务hermes gateway status# 查看状态# 配对hermes pairing approve qqbot<CODE># 批准用户hermes pairing list# 查看已配对hermes pairing revoke qqbot<ID># 撤销授权# 日志tail-f~/.hermes/logs/gateway.log# 实时日志hermes doctor# 健康检查

---