Hermes Agent 安装与配置完整指南

YanDDDeat2026/5/7...大约 5 分钟

简介

Hermes Agent 是一个强大的 AI 助手框架，支持多种 LLM 模型提供商，可以集成 QQ、Telegram、Slack 等消息平台，实现智能对话、代码执行、文件操作等功能。本文将详细介绍 Hermes 的安装与配置流程。

适用场景

个人 AI 助手部署
QQ/Telegram 智能机器人
自动化任务执行
多平台消息聚合

一、环境准备

1.1 系统要求

Linux 服务器（推荐 Ubuntu 20.04+ 或 CentOS 7+）
至少 2GB 内存
网络通畅（可访问外部 API）

1.2 检查依赖

# 检查 Python 版本（需要 3.8+）
python3 --version

# 检查 pip
pip3 --version

二、安装 Hermes

2.1 创建安装目录

# 创建 Hermes 目录
mkdir -p ~/hermes
cd ~/hermes

2.2 下载并执行安装脚本

Hermes 提供了一键安装脚本，可以自动完成依赖安装：

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

注意

安装脚本会自动安装必要的 Python 依赖包，请确保网络通畅。如果下载失败，可以多次尝试或使用代理。

2.3 验证安装

# 检查 Hermes 是否安装成功
which hermes
# 输出类似：/home/yourname/.local/bin/hermes

# 查看版本
hermes --version

三、初始化配置

3.1 运行 setup 命令

hermes setup

这个命令会：

创建 ~/.hermes/ 配置目录
生成默认的 config.yaml 和 .env 文件
初始化必要的目录结构

3.2 配置目录结构

安装完成后，配置目录结构如下：

~/.hermes/
├── .env                 # 环境变量配置（API Keys）
├── config.yaml          # 主配置文件
├── skills/              # 技能插件目录
├── sessions/            # 会话记录目录
├── memories/            # 持久化记忆目录
├── logs/                # 日志目录
└── cron/                # 定时任务目录

四、配置 LLM 模型

Hermes 支持多种 LLM 提供商，以下介绍几种常用配置。

4.1 阿里云通义千问（推荐国内用户）

编辑 ~/.hermes/.env 文件：

vi ~/.hermes/.env

添加以下配置：

# 阿里云 DashScope API
HERMES_PROVIDER=alibaba
DASHSCOPE_API_KEY=your_dashscope_api_key_here
DASHSCOPE_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1

获取 API Key

访问阿里云 DashScope 控制台
创建 API Key
复制到配置文件中

同时需要修改 ~/.hermes/config.yaml：

model:
  default: glm-5
  provider: alibaba
  base_url: https://dashscope.aliyuncs.com/compatible-mode/v1

4.2 OpenRouter（多模型聚合）

# OpenRouter - 一个 API 访问多种模型
OPENROUTER_API_KEY=your_openrouter_api_key_here

4.3 其他提供商配置

更多 LLM 提供商配置

Google Gemini：

GOOGLE_API_KEY=your_google_api_key_here

智谱 AI（GLM）：

GLM_API_KEY=your_glm_api_key_here

Kimi / Moonshot：

KIMI_API_KEY=your_kimi_api_key_here
KIMI_BASE_URL=https://api.kimi.com/coding/v1

MiniMax：

MINIMAX_API_KEY=your_minimax_api_key_here

五、配置消息平台

5.1 QQ 机器人配置

QQ 机器人需要申请

需要到 QQ 开放平台申请机器人，获取 App ID 和 Client Secret。

编辑 ~/.hermes/.env：

# QQ 机器人配置
QQ_APP_ID=your_qq_app_id_here
QQ_CLIENT_SECRET=your_qq_client_secret_here

# 用户权限控制
QQ_ALLOW_ALL_USERS=false                          # 是否允许所有用户
QQ_ALLOWED_USERS=用户ID1,用户ID2                  # 允许的用户 ID 列表
QQBOT_HOME_CHANNEL=默认频道ID                     # 默认消息频道

5.2 Telegram 机器人配置

# Telegram 机器人
TELEGRAM_BOT_TOKEN=your_telegram_bot_token_here   # 从 @BotFather 获取
TELEGRAM_ALLOWED_USERS=用户ID1,用户ID2            # 允许的用户 ID
TELEGRAM_HOME_CHANNEL=默认频道ID                  # 默认频道

获取 Telegram Bot Token

在 Telegram 中搜索 @BotFather
发送 /newbot 创建新机器人
按提示设置名称，获取 Token

5.3 Slack 集成

# Slack 集成
SLACK_BOT_TOKEN=xoxb-your-slack-bot-token
SLACK_APP_TOKEN=xapp-your-slack-app-token
SLACK_ALLOWED_USERS=用户ID列表

六、安装 Gateway 系统服务

Gateway 是 Hermes 的后台服务，需要以系统服务方式运行。

6.1 安装 Gateway 服务

# 进入配置模式
hermes setup gateway

# 安装系统服务（替换 your_username 为你的用户名）
sudo /home/your_username/.local/bin/hermes gateway install --system --run-as-user your_username

6.2 启动 Gateway

# 启动服务
sudo /home/your_username/.local/bin/hermes gateway start --system

# 查看服务状态
sudo systemctl status hermes-gateway

6.3 Gateway 管理命令

# 查看状态
sudo systemctl status hermes-gateway

# 停止服务
sudo systemctl stop hermes-gateway

# 重启服务
sudo systemctl restart hermes-gateway

# 或使用 hermes 命令
hermes restart

七、高级配置

7.1 终端工具配置

编辑 ~/.hermes/config.yaml：

terminal:
  backend: local          # 本地执行模式
  timeout: 180            # 命令超时时间（秒）
  cwd: .                  # 工作目录

终端后端选项

local: 本地直接执行（默认）
docker: Docker 容器隔离
ssh: 远程 SSH 执行
modal: Modal 云平台

7.2 浏览器自动化配置

需要 Browserbase 账号：

# Browserbase 配置
BROWSERBASE_API_KEY=your_browserbase_api_key
BROWSERBASE_PROJECT_ID=your_project_id
BROWSERBASE_PROXIES=true

7.3 语音功能配置

# OpenAI 语音（Whisper STT + TTS）
VOICE_TOOLS_OPENAI_KEY=your_openai_api_key

# 或使用 Groq（免费 Whisper）
GROQ_API_KEY=your_groq_api_key

八、配置 Skills（技能插件）

Hermes 支持技能插件系统，可以扩展功能。

8.1 查看 Skills 目录

ls ~/.hermes/skills/

8.2 Skills 配置

编辑 ~/.hermes/config.yaml，添加技能：

toolsets:
  - hermes-cli           # 基础 CLI 工具
  - web                  # 网络搜索
  - terminal             # 终端执行
  - file                 # 文件操作
  - browser              # 浏览器自动化

九、常见问题排查

9.1 服务无法启动

# 查看详细日志
journalctl -u hermes-gateway -f

# 检查配置文件
cat ~/.hermes/.env
cat ~/.hermes/config.yaml

9.2 API 调用失败

检查以下几点：

API Key 是否正确配置
网络是否能访问 API 地址
API Key 是否有余额/额度

9.3 QQ 机器人无法响应

检查：

QQ_APP_ID 和 QQ_CLIENT_SECRET 是否正确
QQ_ALLOWED_USERS 是否包含你的用户 ID
Gateway 服务是否正常运行

十、完整配置示例

完整 .env 配置示例

# =============================================================================
# LLM 提供商配置（阿里云通义千问）
# =============================================================================
HERMES_PROVIDER=alibaba
DASHSCOPE_API_KEY=sk-your-dashscope-api-key
DASHSCOPE_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1

# =============================================================================
# QQ 机器人配置
# =============================================================================
QQ_APP_ID=1234567890
QQ_CLIENT_SECRET=your_client_secret_here
QQ_ALLOW_ALL_USERS=false
QQ_ALLOWED_USERS=ABC123DEF456
QQBOT_HOME_CHANNEL=ABC123DEF456

# =============================================================================
# 终端配置
# =============================================================================
TERMINAL_TIMEOUT=180
TERMINAL_LIFETIME_SECONDS=300

# =============================================================================
# 浏览器配置（可选）
# =============================================================================
BROWSERBASE_PROXIES=true
BROWSERBASE_ADVANCED_STEALTH=false
BROWSER_SESSION_TIMEOUT=300
BROWSER_INACTIVITY_TIMEOUT=120

# =============================================================================
# 调试选项
# =============================================================================
WEB_TOOLS_DEBUG=false
VISION_TOOLS_DEBUG=false

十一、总结

Hermes Agent 是一个功能强大的 AI 助手框架，通过本文的详细配置，你可以：

部署个人 AI 助手 - 在服务器上运行，随时可用
集成消息平台 - QQ、Telegram、Slack 多平台支持
执行复杂任务 - 代码运行、文件操作、网页浏览
扩展技能系统 - 通过 Skills 插件扩展功能