Hermes Agent 安装部署完全指南

通过 WSL2 在 Windows 上部署 Hermes Agent，接入自定义 LLM 服务商与 QQ 机器人，打造你自己的 AI 智能助手。

什么是 Hermes Agent？

Hermes Agent 是由 Nous Research（知名 AI 研究实验室，Hermes 4 模型系列团队）开发的自进化 AI Agent 框架。与其他 Agent 工具不同，它具备以下核心能力：

闭环学习：自动从经验中创建技能，使用过程中自我改进，跨会话持久化记忆
多平台接入：支持 TG、Discord、Slack、WhatsApp、Signal、QQ 等 17+ 平台
模型无关：接入 OpenRouter（200+ 模型）、OpenAI、Google Gemini 或任何兼容 OpenAI API 的自定义端点
多终端后端：命令执行可在本地、Docker、SSH、Modal 云端等多种环境运行
跨平台对话：从 QQ 发送消息，Agent 在云端 VM 上工作，结果实时返回

Hermes Agent vs OpenClaw：为什么要选 Hermes？

在部署之前，有必要了解 Hermes Agent 与同类项目 OpenClaw 的核心差异。两者都是持久型 AI Agent 框架，但设计哲学截然不同。

设计哲学对比

维度	OpenClaw	Hermes Agent
设计哲学	"工具箱"——人主导配置与编排	"长期搭档"——自主学习、进化的 AI 伙伴
核心优势	广度连接、渠道覆盖、成熟生态	深度自治、自我进化、持久记忆
开发者	社区驱动	Nous Research（专业 AI 研究团队）
GitHub Stars	~354k（社区热度高）	~46k+（快速增长）

为什么推荐 Hermes Agent？

越用越聪明 — 这是 Hermes 最大的差异化优势。OpenClaw 的技能需要你手动寻找和安装，而 Hermes 的 Agent 会自动从经验中提炼技能并持续优化。使用时间越长，Agent 的能力越强
开箱即用的记忆系统 — Hermes 内置多层持久记忆，Agent 会跨会话记住你的偏好、工作环境和决策逻辑。OpenClaw 的记忆需要手动维护，Hermes 的记忆是自动生长的
更强的自治能力 — Hermes 的 Agent 中心架构让它具备更高的自主性：主动调用工具、管理上下文、调度子 Agent 并行工作。适合需要长期运行、复杂任务的场景
更灵活的后端支持 — 命令执行可路由到本地、Docker、SSH、Modal 云端等多种环境，适应不同场景的隔离需求
专业团队背书 — Nous Research 是知名 AI 研究实验室，Hermes 4 模型系列广受认可。 Hermes Agent 由专业的 AI 团队持续维护

什么时候该选 OpenClaw？

如果你更看重：

成熟的社区生态和大量现成技能
团队运营、多渠道统一管理
更轻量级的部署方案
对 AI 自治能力不敏感，更希望手动控制每个步骤

那么 OpenClaw 可能更适合你。

一句话总结：
Hermes 走深度进化路线，让 Agent 自己学会做事；OpenClaw 走广度连接路线，让人定义规则让 Agent 执行。

关于占位符 `[UserName]`

文档中的 [UserName] 表示你在安装 WSL2 时设置的 Linux 用户名（即 Ubuntu 初始化时输入的用户名）。

请将所有出现 [UserName] 的地方替换为你自己的实际用户名。 例如，如果你的用户名为 alice，则 /home/[UserName]/hermes-agent 应改为 /home/alice/hermes-agent。

⚠️ 特别注意：文档中的配置文件示例（如 systemd 服务文件）包含 [UserName] 占位符，创建时需要手动替换为你的实际用户名，否则服务将无法启动。

环境要求

项目	要求
操作系统	Windows 10/11（通过 WSL2 运行）
WSL2 发行版	Ubuntu 22.04 或更高版本
内存	建议 4GB+
网络	需要访问 GitHub 和 LLM API 端点

注意：Hermes Agent 官方明确指出："原生 Windows 支持仍处于实验阶段，请安装 WSL2 后在其中运行。" 因此本教程采用 WSL2 方式部署，这是 Windows 用户的推荐方案。

第一步：安装 WSL2

如果你还没有安装 WSL2，请以管理员身份打开 PowerShell 或 CMD，运行：

wsl --install

这条命令会自动完成以下操作：

启用 Windows 的 WSL 和虚拟机平台功能
下载并安装默认的 Ubuntu 发行版
设置 WSL2 作为默认版本

安装完成后重启计算机。重启后会出现 Ubuntu 终端，设置用户名和密码。

验证 WSL2 安装

打开 PowerShell，运行：

wsl -l -v

正常输出应如下：

  NAME            STATE           VERSION
* Ubuntu-22.04    Running         2

确保 VERSION 列为 2，表示使用的是 WSL2 架构。

进入 WSL2 环境

wsl

进入后你会看到 Linux 命令提示符，例如 [UserName]@DESKTOP-XXXX:~$。

第二步：一键安装 Hermes Agent

Hermes Agent 提供了官方一键安装脚本，自动完成 uv 安装、Python 3.11、Git、Node.js、依赖安装、前端构建、环境变量配置等所有步骤。

在 WSL2 终端中运行：

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

安装命令

安装命令2

Hermes Agent 一键安装脚本运行过程

脚本会自动完成以下操作：

检测操作系统（Linux/macOS/Termux）
安装或校验 uv、Python 3.11、Git、Node.js
安装可选工具：ripgrep（搜索）、ffmpeg（音频功能）
克隆仓库源码
创建 Python 虚拟环境并安装依赖
安装前端 Node.js 模块（TUI、Web Dashboard 等）
创建 ~/.hermes/ 数据目录和默认配置
启动交互式配置向导

安装完成后重新加载 shell 环境变量：

source ~/.local/bin/env

验证安装：

hermes --version

正常输出应显示版本号和 Python 版本：

Hermes Agent v0.10.0 (2026.4.16)
Project: /home/[UserName]/hermes-agent
Python: 3.11.15

注意：脚本会自动将 hermes-agent 克隆到 ~/.hermes/hermes-agent/ 目录。
如果你想把代码放在自定义位置（如 ~/hermes-agent/），可以跳过此步，手动执行克隆和安装：
git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent
uv venv venv --python 3.11 && source venv/bin/activate
uv pip install -e ".[all]"

第三步：配置 LLM 推理后端

Hermes Agent 提供了交互式配置向导，无需手动编辑文件。

3.1 配置模型和提供商

运行内置的模型配置命令：

hermes model

模型设置

Hermes Model 配置界面

按照向导提示：

选择 Custom（自定义 OpenAI 兼容端点）
输入你的 API Base URL（如 https://api.openai.com/）
输入 API Key
选择或输入要使用的模型名称

向导会自动写入 ~/.hermes/config.yaml 和 ~/.hermes/.env。

3.2 完整交互配置（可选）

如果你希望一次性完成所有配置（终端、工具、记忆等），可以运行：

hermes setup

hermes setup

Hermes Setup 交互式配置界面

该命令会引导你完成：模型、终端后端、工具、Agent 行为、显示等各项设置。

第四步：配置 QQ Bot 消息平台

使用 Hermes 内置的网关平台配置向导：

hermes gateway setup

app

Hermes gateway setup 配置界面

按照向导提示：

选择 QQ Bot 平台
输入 QQ AppID
输入 QQ ClientSecret
设置允许的用户范围

配置完成后会自动写入 ~/.hermes/config.yaml。

第五步：启动 QQ Bot 网关

完成配置后，启动消息网关：

cd ~/hermes-agent
source venv/bin/activate
export HERMES_HOME="$HOME/.hermes"

# 前台启动（调试用）
hermes gateway run

如果看到如下输出，说明网关启动成功：

┌─────────────────────────────────────────────────┐
│           ⚕ Hermes Gateway Starting...          │
├─────────────────────────────────────────────────┤
│  Messaging platforms + cron scheduler            │
│  Press Ctrl+C to stop                           │
└─────────────────────────────────────────────────┘

后台运行

确认前台启动正常后，按 Ctrl+C 停止，然后改为后台运行：

# 后台启动，日志写入 ~/.hermes/logs/
nohup hermes gateway run --replace > /dev/null 2>&1 &
echo $! > ~/.hermes/gateway.pid

# 查看进程
cat ~/.hermes/gateway.pid

# 查看实时日志
tail -f ~/.hermes/logs/agent.log

停止网关

# 方法 1：通过 PID 文件
kill $(cat ~/.hermes/gateway.pid)

# 方法 2：强制终止
pkill -f "hermes gateway"

第六步：配置 QQ 机器人

6.1 在 QQ 开放平台创建应用

访问 QQ 开放平台，登录你的 QQ 开发者账号
进入「机器人」→「创建机器人」
填写机器人名称、头像、简介
选择「公域机器人」或「私域机器人」（根据需求选择）
记录 AppID 和 ClientSecret

6.2 配置机器人能力

在 QQ 开放平台的机器人管理页面：

进入「开发设置」→「机器人能力」
确保开启「消息能力」→「接收消息」
配置「消息回调」或使用 WebSocket 模式（Hermes 使用 WebSocket 模式）
确认「事件订阅」中已订阅以下事件：

C2C_MESSAGE_CREATE（单聊消息）
GROUP_AT_MESSAGE_CREATE（群 @ 消息）
DIRECT_MESSAGE_CREATE（频道私信）

6.3 验证 QQ Bot 连接

完成 hermes gateway setup 配置后，重启网关使配置生效：

pkill -f "hermes gateway"
nohup hermes gateway run --replace > /dev/null 2>&1 &

查看网关日志确认 QQ 是否连接成功：

grep -i "qq\|qqbot\|connected\|websocket" ~/.hermes/logs/agent.log | tail -20

连接成功后，你也可以检查网关状态文件：

cat ~/.hermes/gateway_state.json

正常输出应显示平台状态为 "connected"：

{
  "gateway_state": "running",
  "platforms": {
    "qqbot": {
      "state": "connected",
      "error_code": null,
      "error_message": null
    }
  }
}

连接成功后，你可以在 QQ 中向机器人发送消息了。

6.4 日志文件说明

Hermes Agent 的日志文件位于 ~/.hermes/logs/ 目录：

文件	用途
`agent.log`	主日志文件，记录所有平台连接、模型调用、工具执行等信息
`errors.log`	错误日志，仅记录异常和警告

常用日志查看命令：

# 查看最近日志
tail -30 ~/.hermes/logs/agent.log

# 实时跟踪日志
tail -f ~/.hermes/logs/agent.log

# 只查看错误
tail -f ~/.hermes/logs/errors.log

# 搜索 QQ 相关日志
grep -i "qq\|qqbot" ~/.hermes/logs/agent.log | tail -20

第七步：启动 Web 管理面板

Hermes Agent 内置了一个基于浏览器的 Web 管理面板（Web Dashboard），可以在图形化界面中管理配置、查看会话、分析用量和管理定时任务。

启动面板

cd ~/hermes-agent && source venv/bin/activate
hermes dashboard

启动后会自动打开浏览器，默认访问地址为：

http://127.0.0.1:9119

注意：在 WSL2 中，自动打开浏览器可能不生效。如果浏览器没有自动打开，请在 Windows 浏览器中访问 http://localhost:9119（WSL2 端口自动转发）。

自定义端口和绑定地址

# 自定义端口
hermes dashboard --port 8080

# 绑定所有网络接口（警告：同一网络上的任何人都可以访问）
hermes dashboard --host 0.0.0.0

# 不自动打开浏览器
hermes dashboard --no-open

面板功能概览

Web 管理面板提供以下页面：

页面	功能
Status	Agent 版本、网关状态、活跃会话、最近会话列表
Config	可视化表单编辑 `config.yaml`，支持 150+ 配置字段
API Keys	管理 `.env` 文件中的 API 密钥和凭证
Sessions	浏览和搜索所有 Agent 会话，支持 FTS5 全文检索
Logs	查看 Agent、Gateway 和错误日志，支持过滤和实时刷新
Analytics	Token 用量、费用估算、会话统计
Cron	创建和管理定时任务
Skills	浏览、搜索和启用/禁用技能

Web Dashboard 管理面板

web

Web Dashboard 管理面板界面

安全提醒

面板默认绑定 127.0.0.1，仅限本机访问。不要在生产环境中绑定 0.0.0.0，否则同一网络上的任何人都可以查看和修改你的 API 密钥。面板没有内置认证机制。

常用操作

与 Agent 对话

通过 CLI（直接在终端）：

cd ~/hermes-agent && source venv/bin/activate
hermes

hermes

Hermes 终端交互演示

进入交互模式后直接输入问题，Agent 会调用工具来完成任务。

通过 QQ Bot：

在你的 QQ 中搜索并添加机器人好友，直接发送消息即可。

切换模型

hermes model

或使用命令：

hermes model set --provider custom --model gpt-4o

查看系统状态

hermes doctor

更新 Hermes

cd ~/hermes-agent && source venv/bin/activate
hermes update

管理记忆

Agent 会自动管理记忆文件：

~/.hermes/memories/MEMORY.md — Agent 的环境笔记
~/.hermes/memories/USER.md — 用户画像和偏好

进阶：系统服务化（可选）

如果你希望 QQ Bot 在 WSL2 启动时自动运行，可以创建一个 systemd 服务：

# 在 WSL2 中创建服务文件
sudo tee /etc/systemd/system/hermes-gateway.service << EOF
[Unit]
Description=Hermes Agent Gateway
After=network-online.target

[Service]
Type=simple
User=[UserName]
WorkingDirectory=/home/[UserName]/hermes-agent
ExecStart=/bin/bash -c 'source /home/[UserName]/.local/bin/env && source venv/bin/activate && export HERMES_HOME=/home/[UserName]/.hermes && exec hermes gateway run --replace'
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target
EOF

# 启用并启动服务
sudo systemctl daemon-reload
sudo systemctl enable hermes-gateway
sudo systemctl start hermes-gateway

# 查看状态
sudo systemctl status hermes-gateway

注意：WSL2 中的 systemd 需要 WSL2 版本 2.0+ 并在 /etc/wsl.conf 中启用 [boot] systemd=true。

Hermes 常用命令速查

全局选项

hermes --version          # 显示版本
hermes --tui              # 启动 TUI 界面（React 风格的终端界面）
hermes -p <profile>       # 指定使用哪个配置文件
hermes -r <session>       # 恢复指定会话
hermes --yolo             # 跳过危险命令确认

聊天与 Agent

hermes                     # 进入交互式聊天
hermes chat -q "你的问题"   # 一次性提问（非交互）
hermes -q "你的问题"        # 简写形式
hermes --tui               # 启动 TUI 界面

模型管理

hermes model               # 交互式选择/添加模型和提供商
/model                     # 在聊天中切换模型（仅限已配置的提供商）
/model claude-sonnet-4     # 切换到指定模型
/model custom:gpt-4o       # 切换到自定义端点的模型
/model claude-sonnet-4 --global  # 切换并保存为默认模型

网关管理

hermes gateway run         # 前台运行网关（推荐 WSL2 使用）
hermes gateway stop        # 停止网关
hermes gateway restart     # 重启网关
hermes gateway status      # 查看网关状态
hermes gateway install     # 安装为系统服务（systemd）
hermes gateway uninstall   # 移除系统服务

配置与诊断

hermes doctor              # 诊断配置问题
hermes doctor --fix        # 尝试自动修复
hermes config show         # 显示当前配置
hermes config edit         # 编辑 config.yaml
hermes config set agent.max_turns 100  # 设置单个配置项
hermes dump                # 输出完整配置摘要（适合粘贴求助）
hermes dump --show-keys    # 显示脱敏后的 API 密钥前缀

日志查看

hermes logs                # 查看最近 50 行 agent.log
hermes logs -f             # 实时跟踪 agent.log
hermes logs errors -f      # 实时跟踪错误日志
hermes logs gateway -n 100 # 查看最近 100 行网关日志
hermes logs --level WARNING --since 1h  # 最近 1 小时的警告信息

会话管理

hermes sessions list       # 列出最近会话
hermes sessions browse     # 交互式浏览和恢复会话
hermes sessions prune      # 清理旧会话
hermes sessions delete <session-id>   # 删除指定会话

技能管理

hermes skills browse       # 浏览可用技能
hermes skills search "关键词"  # 搜索技能
hermes skills list         # 列出已安装技能
hermes skills update       # 更新已安装技能
hermes skills config       # 启用/禁用技能

定时任务

hermes cron list           # 列出定时任务
hermes cron create         # 创建新任务
hermes cron pause <job>    # 暂停任务
hermes cron resume <job>   # 恢复任务
hermes cron run <job>      # 立即执行任务

其他实用命令

hermes status              # 显示 Agent 运行状态
hermes tools               # 交互式配置各平台工具
hermes insights --days 7   # 查看最近 7 天用量统计
hermes backup              # 备份配置到 zip 文件
hermes backup --quick      # 快速备份（仅关键文件）
hermes import backup.zip   # 从备份恢复
hermes update              # 更新 Hermes 到最新版本
hermes debug share         # 上传调试报告并获取分享链接
hermes completion bash     # 生成 Bash 自动补全脚本

聊天中的斜杠命令

在交互式聊天中输入：

命令	功能
`/quit`	退出聊天
`/model`	切换模型
`/reload`	重新加载 `.env`（修改 API 密钥后无需重启）
`/compress`	手动压缩上下文
`/tokens`	显示当前 token 用量
`/summary`	总结当前对话
`/help`	显示所有可用命令

常见问题

Q: WSL2 中提示找不到 `hermes` 命令

确保已激活虚拟环境：

source ~/hermes-agent/venv/bin/activate

Q: QQ Bot 连接失败

确认 AppID 和 ClientSecret 正确无误
检查网络是否能访问 QQ 开放平台 API
确认机器人已在 QQ 开放平台完成创建和审核
查看 Agent 日志：tail -f ~/.hermes/logs/agent.log

注意：QQ WebSocket 会周期性重连（约 1-2 分钟一次），这是正常行为。
只要日志显示 "Reconnected" 和 "Session resumed"，就表示连接正常。

Q: API 调用超时

检查 OPENAI_BASE_URL 是否正确，末尾需要带 /：

OPENAI_BASE_URL=https://api.openai.com/

Q: 如何更换终端执行后端

编辑 config.yaml 中的 terminal.backend：

terminal:
  backend: "local"     # 可选: local, docker, ssh, modal

总结

通过以上步骤，你已经完成了：

✅ WSL2 环境安装
✅ Hermes Agent 一键安装（官方脚本）
✅ LLM 端点配置（hermes model）
✅ QQ Bot 平台配置（hermes gateway setup）
✅ 网关后台运行
✅ Web 管理面板访问

现在你可以随时通过 QQ 与你的 AI 助手对话了！

posted @ 2026-04-20 16:59 yejinxing 阅读(999) 评论(0) 收藏举报

刷新页面返回顶部

yejinxing

Hermes Agent 安装部署完全指南

Hermes Agent 安装部署完全指南

什么是 Hermes Agent？

Hermes Agent vs OpenClaw：为什么要选 Hermes？

设计哲学对比

为什么推荐 Hermes Agent？

什么时候该选 OpenClaw？

关于占位符 [UserName]

环境要求

第一步：安装 WSL2

验证 WSL2 安装

进入 WSL2 环境

第二步：一键安装 Hermes Agent

第三步：配置 LLM 推理后端

3.1 配置模型和提供商

3.2 完整交互配置（可选）

第四步：配置 QQ Bot 消息平台

第五步：启动 QQ Bot 网关

后台运行

停止网关

第六步：配置 QQ 机器人

6.1 在 QQ 开放平台创建应用

6.2 配置机器人能力

6.3 验证 QQ Bot 连接

6.4 日志文件说明

第七步：启动 Web 管理面板

启动面板

自定义端口和绑定地址

面板功能概览

安全提醒

常用操作

与 Agent 对话

切换模型

查看系统状态

更新 Hermes

管理记忆

进阶：系统服务化（可选）

Hermes 常用命令速查

全局选项

聊天与 Agent

模型管理

网关管理

配置与诊断

日志查看

会话管理

技能管理

定时任务

其他实用命令

聊天中的斜杠命令

常见问题

Q: WSL2 中提示找不到 hermes 命令

Q: QQ Bot 连接失败

Q: API 调用超时

Q: 如何更换终端执行后端

总结

公告

关于占位符 `[UserName]`

Q: WSL2 中提示找不到 `hermes` 命令