AI Agent - Hermes Agent 部署

程序员的记录2026-07-01 21:10

Hermes Agent 部署

  • [Hermes Agent 部署指南](#Hermes Agent 部署指南)
    • 目录
    • [1. 环境准备](#1. 环境准备)
    • [2. 下载源码与安装](#2. 下载源码与安装)
      • [方式一：Shell 安装脚本（推荐）](#方式一：Shell 安装脚本（推荐）)
      • [方式二：Git 源码安装](#方式二：Git 源码安装)
      • [方式三：PyPI 安装](#方式三：PyPI 安装)
      • 初始化配置
    • [3. 配置 LLM 模型](#3. 配置 LLM 模型)
      • [获取 API Key](#获取 API Key)
      • [配置 model 段](#配置 model 段)
      • [配置 API Key](#配置 API Key)
    • [4. 获取 QQ Bot 凭证](#4. 获取 QQ Bot 凭证)
      • [4.1 注册 QQ 开放平台](#4.1 注册 QQ 开放平台)
      • [4.2 创建机器人应用](#4.2 创建机器人应用)
      • [4.3 获取凭证](#4.3 获取凭证)
      • [4.4 配置机器人权限](#4.4 配置机器人权限)
    • [5. 配置 Hermes Gateway](#5. 配置 Hermes Gateway)
      • [5.1 设置凭证（.env）](#5.1 设置凭证（.env）)
      • [5.2 设置平台配置（config.yaml）](#5.2 设置平台配置（config.yaml）)
      • [5.3 配置说明](#5.3 配置说明)
        • [dm_policy / group_policy](#dm_policy / group_policy)
        • [限制用户（allowlist 模式）](#限制用户（allowlist 模式）)
    • [6. 启动 Gateway 服务](#6. 启动 Gateway 服务)
    • [7. 配对授权用户](#7. 配对授权用户)
    • [8. 验证交互](#8. 验证交互)
    • [9. 进阶配置](#9. 进阶配置)
    • [10. 故障排查](#10. 故障排查)
      • 常见问题
        • [1. QQ Bot 连接失败](#1. QQ Bot 连接失败)
        • [2. QQAdapter.connect() 报错](#2. QQAdapter.connect() 报错)
        • [3. 发消息后 Bot 无反应](#3. 发消息后 Bot 无反应)
        • [4. Gateway 退出后无法自动重启](#4. Gateway 退出后无法自动重启)
        • [5. 网络无法连接 QQ API](#5. 网络无法连接 QQ API)
    • 完整配置文件示例
    • 快速命令参考

Hermes Agent 部署指南

目录

  1. 环境准备
  2. 下载源码与安装
  3. [配置 LLM 模型](#配置 LLM 模型)
  4. [获取 QQ Bot 凭证](#获取 QQ Bot 凭证)
  5. [配置 Hermes Gateway](#配置 Hermes Gateway)
  6. [启动 Gateway 服务](#启动 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）

安装系统依赖

bash 复制代码 
# 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 安装脚本（推荐）

bash 复制代码 
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

方式二：Git 源码安装

bash 复制代码 
# 克隆仓库
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 安装

bash 复制代码 
pip install hermes-agent
# 或
uv pip install hermes-agent

初始化配置

bash 复制代码 
hermes setup

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

3. 配置 LLM 模型

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

获取 API Key

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

配置 model 段

编辑 ~/.hermes/config.yaml：

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

配置 API Key

编辑 ~/.hermes/.env：

bash 复制代码 
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 末尾添加：

bash 复制代码 
# QQ BOT INTEGRATION
QQ_APP_ID=你的APP_ID
QQ_CLIENT_SECRET=你的APP_SECRET

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

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

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 模式）
yaml 复制代码 
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 服务

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

bash 复制代码 
hermes gateway run

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

bash 复制代码 
# 安装并启动
hermes gateway install

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

6.1 验证连接

bash 复制代码 
hermes gateway status

期望输出包含：

复制代码 
✓ qqbot connected
Gateway running with 1 platform(s)

6.2 查看日志

bash 复制代码 
# 实时查看 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），需要管理员在服务器端批准：

bash 复制代码 
hermes pairing approve qqbot <配对码>

示例：

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

跳过配对（开放模式）

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

bash 复制代码 
GATEWAY_ALLOW_ALL_USERS=true

然后重启 gateway：

bash 复制代码 
hermes gateway restart

查看已配对用户

bash 复制代码 
hermes pairing list

撤销授权

bash 复制代码 
hermes pairing revoke qqbot <user_id>

8. 验证交互

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

测试功能

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

9. 进阶配置

语音转文字（STT）

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

yaml 复制代码 
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 配置

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

记忆系统

yaml 复制代码 
memory:
  memory_enabled: true               # 跨会话记忆
  user_profile_enabled: true         # 用户画像

多平台并行

可以同时启用多个平台：

yaml 复制代码 
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。修复方法：

bash 复制代码 
# 找到 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，将：

python 复制代码 
async def connect(self) -> bool:

改为：

python 复制代码 
async def connect(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 退出后无法自动重启
bash 复制代码 
# 确认 systemd 服务已安装
hermes gateway install

# 启用 linger（SSH 退出后服务不中断）
sudo loginctl enable-linger $USER
5. 网络无法连接 QQ API
bash 复制代码 
# 测试网络连通性
curl -v https://api.sgroup.qq.com/

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

完整配置文件示例

~/.hermes/config.yaml

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

bash 复制代码 
# LLM
DASHSCOPE_API_KEY=sk-xxxx-your-key

# QQ BOT
QQ_APP_ID=1904843353
QQ_CLIENT_SECRET=oY6RZT9crsfFbkfN

快速命令参考

bash 复制代码 
# 安装
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                          # 健康检查
热门推荐
012026 年 AI 编程工具终极横评：Cursor vs Claude Code vs Copilot vs Windsurf022026年6月AI大模型全景报告：GPT-5.6、Claude Opus 4.8、Gemini 3.5，中美AI三足鼎立谁主沉浮？032026年6月AI行业全景：从百模大战到Agent元年，这30天发生了什么？04GitHub 镜像站点05Trae国际版与国内版深度测评：AI原生IDE的双生花06【AI】2026 年具身智能模型和世界模型总结07Claude Code、Codex、Cursor三分天下：2026年AI编程Agent生态全景剖析08飞书长连接_事件订阅（接收消息，审批任务状态变更）092026 AI 编程工具终极实战指南：Cursor vs Claude Code vs Copilot，开发者该怎么选？102026年AI架构实战：彻底解决OpenAI接口超时与封号，Python调用GPT-5.2/Sora2企业级架构详解（附源码+压测报告）