AI Agent - Hermes Agent 部署

程序员的记录

129人浏览 · 2026-06-30 15:23:15

程序员的记录 · 2026-06-30 15:23:15 发布

Hermes Agent 部署

Hermes Agent 部署指南

Hermes Agent 部署指南

1. 环境准备

系统要求

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

安装系统依赖

# Ubuntu/Debian
sudo apt update && sudo apt install -y python3 python3-pip python3-venv git curl

# CentOS/RHEL
sudo yum install -y python3 python3-pip git curl

2. 下载源码与安装

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

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

方式二：Git 源码安装

# 克隆仓库
git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent

# 用项目自带的 setup-hermes.sh（最简单）

# 安装 Python 依赖环境
sudo apt install python3 python3-pip python3-venv
python3 -m venv /opt/hermes-agent/venv
source /opt/hermes-agent/venv/bin/activate

# 安装（创建 venv + 安装依赖）
pip install -e .    # 开发模式安装（推荐）
# 或使用 uv
pip install uv && uv sync

# 验证安装
hermes --version

方式三：PyPI 安装

pip install hermes-agent
# 或
uv pip install hermes-agent

初始化配置

hermes setup

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

3. 配置 LLM 模型

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

获取 API Key

访问 https://dashscope.console.aliyun.com/
创建 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 开放平台

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

4.2 创建机器人应用

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

4.3 获取凭证

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

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

4.4 配置机器人权限

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

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

5. 配置 Hermes Gateway

5.1 设置凭证（.env）

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

# QQ BOT INTEGRATION
QQ_APP_ID=你的APP_ID
QQ_CLIENT_SECRET=你的APP_SECRET

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

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

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

5.3 配置说明

dm_policy / group_policy

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

限制用户（allowlist 模式）

platforms:
  qq:
    enabled: true
    extra:
      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 gateway install

# 管理命令
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 -u hermes-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. 验证交互

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

测试功能

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

9. 进阶配置

语音转文字（STT）

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

platforms:
  qq:
    enabled: true
    extra:
      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: true
    extra:
      dm_policy: "open"
  telegram:
    enabled: true
    extra:
      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，将：

async def connect(self) -> bool:

改为：

async def connect(self, *, is_reconnect: bool = False) -> bool:

3. 发消息后 Bot 无反应

检查：

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

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

# 确认 systemd 服务已安装
hermes gateway install

# 启用 linger（SSH 退出后服务不中断）
sudo loginctl enable-linger $USER

5. 网络无法连接 QQ API

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

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

完整配置文件示例

~/.hermes/config.yaml

model:
  default: qwen3.6-flash
  provider: alibaba
  base_url: https://dashscope.aliyuncs.com/compatible-mode/v1

agent:
  max_turns: 150
  reasoning_effort: medium

terminal:
  backend: local
  cwd: .
  timeout: 180

memory:
  memory_enabled: true
  user_profile_enabled: true

platforms:
  qq:
    enabled: true
    extra:
      markdown_support: true
      dm_policy: "open"
      group_policy: "open"

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

# LLM
DASHSCOPE_API_KEY=sk-xxxx-your-key

# QQ BOT
QQ_APP_ID=1904843353
QQ_CLIENT_SECRET=oY6RZT9crsfFbkfN

快速命令参考

# 安装
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

# 配置
hermes setup                           # 交互式配置
hermes config edit                     # 编辑 config.yaml
hermes config env-path                 # 查看 .env 路径

# Gateway
hermes gateway install                 # 安装服务
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                          # 健康检查

MCP技术社区

欢迎加入 MCP 技术社区！与志同道合者携手前行，一同解锁 MCP 技术的无限可能！

更多推荐

MCP 协议实战（下）：背后的机制与面试指南

MCP 协议解决了一个朴素的问题：大模型再聪明，没有手就干不了活。它不是什么高深的技术，只是一个标准化的协议。但正是这个标准化，让 AI 应用开发从一个"手工作坊"变成了"工业流水线"——写完一个 MCP Server，所有模型都能用。2026 年，MCP 已经从早期的概念验证进入了大规模落地阶段。现在学习 MCP，不算早，也绝不算晚，刚好是最合适的时机。系列文章MCP 协议实战（上）：什么是 M

MCP技术社区

系统稳定性层：大模型调用脆雪崩快的三个防护缺口

MCP技术社区

AI 替代传统 GUI：基于 MCP 的 OBCloud 工作流（11）

例如，当用户询问“牛肉怎么做才好吃”时，AI 能够准确地提供答案，而如果通过搜索引擎查找，用户可能需要浏览多个标题，甚至将多个来源的信息拼凑在一起才能找到满意的答案。结合AI技术，我们可以利用大模型替代传统的图形界面，帮助用户理解数据。尽管在实际工作中，遇到问题的概率相对较小，很多时候用户只是想检查当前运行的实例和数据库是否存在异常，但完成这样一套重复的操作仍会耗费大量时间。在官网查文档则可以视为

MCP技术社区

所有评论(0)

查看更多评论

程序员的记录

@qq_25439881

已为社区贡献1条内容

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 相关部分）

快速命令参考

所有评论(0)

温馨提示：您尚未绑定手机号

程序员的记录