Hermes Agent 部署Hermes Agent 部署指南目录1. 环境准备系统要求安装系统依赖2. 下载源码与安装方式一Shell 安装脚本推荐方式二Git 源码安装方式三PyPI 安装初始化配置3. 配置 LLM 模型获取 API Key配置 model 段配置 API Key4. 获取 QQ Bot 凭证4.1 注册 QQ 开放平台4.2 创建机器人应用4.3 获取凭证4.4 配置机器人权限5. 配置 Hermes Gateway5.1 设置凭证.env5.2 设置平台配置config.yaml5.3 配置说明dm_policy / group_policy限制用户allowlist 模式6. 启动 Gateway 服务方式一前台运行调试用方式二安装为系统服务推荐6.1 验证连接6.2 查看日志7. 配对授权用户默认行为跳过配对开放模式查看已配对用户撤销授权8. 验证交互测试功能9. 进阶配置语音转文字STTAgent 配置记忆系统多平台并行10. 故障排查常见问题1. QQ Bot 连接失败2. QQAdapter.connect() 报错3. 发消息后 Bot 无反应4. Gateway 退出后无法自动重启5. 网络无法连接 QQ API完整配置文件示例~/.hermes/config.yaml~/.hermes/.envQQ 相关部分快速命令参考Hermes Agent 部署指南目录环境准备下载源码与安装配置 LLM 模型获取 QQ Bot 凭证配置 Hermes Gateway启动 Gateway 服务配对授权用户验证交互进阶配置故障排查1. 环境准备系统要求项目要求操作系统Linux (推荐 Ubuntu 20.04) / macOS / WSL2Python3.10Node.js18TUI 界面需要可选网络能访问api.sgroup.qq.comQQ Bot API安装系统依赖# Ubuntu/Debiansudoaptupdatesudoaptinstall-ypython3 python3-pip python3-venvgitcurl# CentOS/RHELsudoyuminstall-ypython3 python3-pipgitcurl2. 下载源码与安装方式一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.# 开发模式安装推荐# 或使用 uvpipinstalluvuvsync# 验证安装hermes--version方式三PyPI 安装pipinstallhermes-agent# 或uv pipinstallhermes-agent初始化配置hermes setup交互式向导会引导你完成基础配置模型、终端等。3. 配置 LLM 模型Hermes 需要一个 LLM 后端来驱动对话。以阿里巴巴 DashScope通义千问为例获取 API Key访问 https://dashscope.console.aliyun.com/创建 API Key配置 model 段编辑~/.hermes/config.yamlmodel:default:qwen3.6-flash# 模型名称provider:alibaba# 提供商base_url:https://dashscope.aliyuncs.com/compatible-mode/v1配置 API Key编辑~/.hermes/.envDASHSCOPE_API_KEYsk-xxxx-your-key-here4. 获取 QQ Bot 凭证4.1 注册 QQ 开放平台访问 https://q.qq.com/使用 QQ 账号登录完成开发者认证4.2 创建机器人应用进入「应用管理」→「创建应用」选择「机器人」类型填写应用信息名称、头像、描述提交审核通常几分钟到几小时4.3 获取凭证审核通过后在应用详情页找到字段说明示例AppID应用唯一标识111xxxxxxAppSecret应用密钥oxxxxxxx4.4 配置机器人权限在 QQ 开放平台的「机器人配置」页开启单聊C2C消息权限开启群聊 消息权限如果需要群聊开启Markdown 消息可选5. 配置 Hermes Gateway5.1 设置凭证.env在~/.hermes/.env末尾添加# QQ BOT INTEGRATIONQQ_APP_ID你的APP_IDQQ_CLIENT_SECRET你的APP_SECRET5.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 | disabled5.3 配置说明dm_policy / group_policy值含义open所有人可以私聊/群聊 Botallowlist仅允许列表中的用户disabled完全禁用限制用户allowlist 模式platforms:qq:enabled:trueextra:dm_policy:allowlistallow_from:[user_openid_1,user_openid_2]group_policy:allowlistgroup_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_idxxxxxxxx7. 配对授权用户默认行为首次发消息时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_USERStrue然后重启 gatewayhermes gateway restart查看已配对用户hermes pairing list撤销授权hermes pairing revoke qqbotuser_id8. 验证交互打开 QQ找到你的 Bot发送一条消息如你好Bot 应该会在几秒内回复测试功能你好 → 基本对话 帮我写一个 Python 冒泡排序 → 代码生成 今天天气怎么样 → 工具调用需 web 工具集9. 进阶配置语音转文字STTQQ 自带腾讯 ASR免费也可接入其他 STTplatforms:qq:enabled:trueextra:stt:provider:zai# zai (GLM-ASR) / openai (Whisper)baseUrl:https://open.bigmodel.cn/api/coding/paas/v4apiKey:***model:glm-asrAgent 配置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:opentelegram:enabled:trueextra:token:your-telegram-bot-token10. 故障排查常见问题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-is/async def connect(self) - bool:/async def connect(self, *, is_reconnect: bool False) - bool:/\$(python3-cimport gateway.platforms.qqbot.adapter; print(gateway.platforms.qqbot.adapter.__file__))或直接编辑gateway/platforms/qqbot/adapter.py将asyncdefconnect(self)-bool:改为asyncdefconnect(self,*,is_reconnect:boolFalse)-bool:3. 发消息后 Bot 无反应检查Gateway 是否正在运行hermes gateway statusQQ 是否已连接看日志中是否有✓ qqbot connected用户是否已配对hermes pairing list查看错误日志tail -50 ~/.hermes/logs/gateway.log4. Gateway 退出后无法自动重启# 确认 systemd 服务已安装hermes gatewayinstall# 启用 lingerSSH 退出后服务不中断sudologinctl enable-linger$USER5. 网络无法连接 QQ API# 测试网络连通性curl-vhttps://api.sgroup.qq.com/如果超时检查防火墙或代理设置。完整配置文件示例~/.hermes/config.yamlmodel: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:opengroup_policy:open~/.hermes/.envQQ 相关部分# LLMDASHSCOPE_API_KEYsk-xxxx-your-key# QQ BOTQQ_APP_ID1904843353QQ_CLIENT_SECREToY6RZT9crsfFbkfN快速命令参考# 安装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 qqbotCODE# 批准用户hermes pairing list# 查看已配对hermes pairing revoke qqbotID# 撤销授权# 日志tail-f~/.hermes/logs/gateway.log# 实时日志hermes doctor# 健康检查