Hermes Agent 保姆级安装教程：从 0 到 1 搭建自己的 AI 微信机器人

最近折腾了一下 Hermes Agent，整体感觉是：它不只是一个终端聊天工具，更像一个可以接模型、接工具、接微信的 Agent 框架。

这篇文章把我完整跑通的过程记录下来，包含：

• Hermes Agent 安装
• 模型和 API Key 配置
• 联网搜索配置
• 微信机器人接入
• systemd 后台服务
• 常用验证命令
• 模型切换和一些踩坑点

我这里演示的是源码安装方式。官方一键脚本当然也能用，但国内服务器下载 GitHub、PyPI、uv、Node.js 依赖时，经常会比较慢。

项目地址

项目地址：

▼
text
复制代码
https://github.com/NousResearch/hermes-agent

官方文档：

▼
text
复制代码
https://hermes-agent.nousresearch.com/docs/zh-Hans/getting-started/installation

支持环境：

▼
text
复制代码
Linux / macOS / WSL2

官方安装方式

官方推荐的一键安装命令如下：

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

安装完成后，需要重新加载 shell 配置。

先看一下当前 shell：

▼
bash
复制代码
echo $SHELL

如果输出的是 bash，执行：

▼
bash
复制代码
source ~/.bashrc

如果输出的是 zsh：

▼
bash
复制代码
$ echo $SHELL
/bin/zsh

则执行：

▼
bash
复制代码
source ~/.zshrc

官方脚本慢，主要是因为后续会下载这些内容：

▼
text
复制代码
GitHub
PyPI
uv 依赖源
Rust 相关组件
Node.js 相关依赖

网络好的环境可以直接用官方脚本；如果下载经常超时，建议用下面的源码安装方式。

源码安装方式

如果 GitHub 下载慢，可以使用 GitCode 同步仓库：

▼
bash
复制代码
git clone https://gitcode.com/GitHub_Trending/he/hermes-agent.git

官方文档也可以一起打开备用：

▼
text
复制代码
https://hermes-agent.nousresearch.com/docs/

我建议把 Hermes Agent 放到固定目录，避免后面移动项目目录导致命令找不到。

这里统一放到 ~/.hermes 下面。

创建安装目录

▼
bash
复制代码
mkdir -p ~/.hermes

复制源码目录

如果项目下载在用户主目录下，可以执行：

▼
bash
复制代码
cp -r ~/hermes-agent ~/.hermes/hermes-agent

进入项目目录并执行安装脚本：

▼
bash
复制代码
cd ~/.hermes/hermes-agent && bash scripts/install.sh

安装完成后，运行 hermes 命令会进入配置向导。这里可以输入 1，进入快速设置模式。

最后重新加载环境变量：

▼
bash
复制代码
source ~/.zshrc

如果项目已经放在固定目录，比如 /root/hermes-agent，就不用再复制一遍：

▼
bash
复制代码
cd /root/hermes-agent
bash scripts/install.sh

复制到 ~/.hermes 不是必须步骤，只是方便后续管理和升级。确定源码目录不会被移动或删除的话，直接在当前目录执行安装脚本也可以。

scripts/install.sh 会自动处理 Python 依赖、虚拟环境、Node.js 等配置，正常情况下不用手动补依赖。

验证 Hermes 命令是否可用

安装完成后，先看版本和帮助信息：

▼
bash
复制代码
hermes --version
hermes --help

启动 Hermes：

▼
bash
复制代码
hermes

如果还没配置模型，启动后大概率会报错。

退出交互界面：

▼
bash
复制代码
exit

配置文件在哪里

Hermes 默认配置在：

▼
bash
复制代码
cat ~/.hermes/config.yaml

这里注意一点：Hermes 的默认模型不是从 .env 里读，而是从 ~/.hermes/config.yaml 里读。

我这里看到默认模型是：

▼
text
复制代码
默认模型：anthropic/claude-opus-4.6
Provider：auto
默认走 OpenRouter 接口

OpenRouter 是一个模型聚合平台，可以接 Claude、GPT、Gemini、DeepSeek、Qwen、GLM、Mistral、Llama 等模型。只要 OpenRouter 支持，Hermes 里一般也能配置。

但是 .env 里的 OPENROUTER_API_KEY 默认是注释状态，没有配置 Key。

所以启动失败的链路大概是：

▼
text
复制代码
读取 config.yaml
↓
默认模型是 claude-opus-4.6
↓
provider=auto
↓
尝试寻找 OPENROUTER_API_KEY
↓
没有找到
↓
No inference provider configured

因此界面上虽然显示了：

▼
text
复制代码
claude-opus-4.6

但模型实际还不能用。接下来需要配置 Provider、API Key 和模型。

运行配置向导

执行：

▼
bash
复制代码
hermes setup

这里会出现配置模式选择。

三个选项大概是这样：

选项	说明	适合场景
Quick Setup (Nous Portal)	使用 Nous 官方账号登录，OAuth 授权，自动配置模型，不用手动填 API Key	快速体验
Full Setup	手动选择 Provider、填写 API Key、选择模型，支持 OpenAI Compatible	推荐，适合长期使用
Blank Slate	不做向导配置，后续自己改配置文件	熟悉配置结构的人

我这里选择 Tencent TokenHub，因为我手里的国产模型免费额度基本用完了，腾讯云 TokenHub 还有一些额度。

按提示输入腾讯云 TokenHub 的密钥。

后面一些参数直接回车，使用默认值即可。

模型这里我选择 glm-5.2。

如果目标模型不在默认列表里，可以选择手动输入模型名。

选择命令运行环境

接下来会询问 Hermes 执行命令时使用什么运行环境。

常见选项如下：

选项	说明	推荐
Local	在当前服务器直接执行命令	⭐⭐⭐⭐⭐
Docker	在 Docker 容器中执行	⭐⭐⭐⭐
Modal	Modal 云沙箱	⭐⭐
SSH	远程机器执行	⭐⭐⭐
Daytona	云开发环境	⭐⭐
Singularity	HPC 集群环境	⭐

个人服务器或测试环境，直接保持默认的 Local 就行。

配置消息平台

这个步骤是配置 Hermes 的消息平台接入。也就是说，Hermes 不只能在终端里聊天，还可以接入微信、QQ、钉钉、飞书、Slack 等平台。

如果你只想在本机终端使用 hermes，这里一个都不用选，直接回车跳过。

常见平台如下：

平台	用途
WeChat	微信机器人
QQ Bot	QQ 机器人
Yuanbao	腾讯元宝接入
DingTalk	钉钉机器人
Feishu / Lark	飞书机器人
Discord	Discord Bot
Slack	Slack Bot
Teams	微软 Teams
Email	邮件收发
Signal	Signal Bot
LINE	Line Bot
ntfy	手机推送通知

我这里要测试微信机器人，所以选择 WeChat。用空格选中，Esc 取消。

确认配置微信机器人，选择 Y。

向导会给出一个链接，把它复制到本地电脑浏览器打开。

打开后用微信扫码。

配置微信私聊权限

扫码后会配置微信私聊权限，也就是谁可以通过微信私聊你的 Hermes。

首次安装建议选：

▼
text
复制代码
Use DM pairing approval (recommended)

这个选项比较稳：陌生人不能直接使用你的 Hermes，也不会莫名其妙消耗模型额度。

授权流程大概是：

▼
text
复制代码
微信用户私聊
↓
Hermes 收到请求
↓
管理员确认授权
↓
用户获得访问权限
↓
正常与 Hermes 对话

如果是公司内部部署，可以选择：

▼
text
复制代码
Only allow listed user IDs

然后把允许访问的用户写成白名单，例如：

▼
text
复制代码
wxid_admin
wxid_dev01
wxid_dev02

不太建议选择：

▼
text
复制代码
Allow all direct messages

这个选项会让所有添加机器人的用户都可以直接使用，个人部署时风险比较大。

几个选项对比如下：

选项	说明	推荐指数	适用场景
Use DM pairing approval (recommended)	用户首次私聊时需要管理员确认授权	⭐⭐⭐⭐⭐	个人用户、开发者、家庭使用
Allow all direct messages	所有微信用户都能直接对话	⭐⭐	开放测试环境
Only allow listed user IDs	只允许白名单用户访问	⭐⭐⭐⭐	企业内部、团队协作
Disable direct messages	禁止微信私聊 Hermes	⭐⭐⭐	只允许群聊或其他平台访问

下一步是微信群聊响应配置。

我这里的配置结果是：

配置项	当前选择	效果
私聊	Allow all direct messages	所有微信好友都可以直接与 Hermes 对话
群聊	Disable group chats	微信群消息 Hermes 不响应
微信接入	已配置	微信可以连接 Hermes

如果是正式使用，我更建议私聊选择审批模式，而不是全开放。

配置 Home Channel

后面会询问是否将当前微信账号设置为 Hermes 的 Home Channel。

Home Channel 可以理解为 Hermes 的主通知频道。后续某些状态通知、任务结果，可能会发到这里。

安装 Gateway 后台服务

接下来会询问是否将 Hermes Gateway 安装为 systemd 服务。

如果选择 Y，Hermes 会创建类似下面的服务文件：

▼
bash
复制代码
/etc/systemd/system/hermes-gateway.service

并执行：

▼
bash
复制代码
systemctl enable hermes-gateway
systemctl start hermes-gateway

这样服务器重启后，微信机器人会自动上线，Hermes Gateway 也会自动启动。

如果这里选择 n，每次服务器重启后都要手动启动：

▼
bash
复制代码
hermes gateway

长期挂微信机器人，建议安装成 systemd 服务。

选择服务运行方式

Hermes Gateway 后台服务有几种运行方式。

选项	说明	推荐
User service	当前用户级 systemd 服务，不需要 sudo 权限	⭐⭐⭐
System service	系统级 systemd 服务，开机自启，最稳定	⭐⭐⭐⭐⭐
Skip service install for now	暂不安装服务	⭐⭐

User service 适合个人电脑、开发机、笔记本：

▼
bash
复制代码
systemctl --user status hermes-gateway

System service 更适合云服务器、VPS、生产环境：

▼
bash
复制代码
systemctl status hermes-gateway

我这里选择：

▼
text
复制代码
System service

后续管理命令如下：

▼
bash
复制代码
# 查看状态
systemctl status hermes-gateway

# 启动
systemctl start hermes-gateway

# 停止
systemctl stop hermes-gateway

# 重启
systemctl restart hermes-gateway

# 开机自启
systemctl enable hermes-gateway

接下来会问 systemd 服务使用哪个 Linux 用户运行。

我这里直接输入：

▼
text
复制代码
root

然后选择 Y 启动服务。

配置工具能力

Hermes 的 Tools 配置界面里，带 ✓ 的表示启用，空白表示禁用。

官方默认开启了大部分 Agent 常用能力。

工具	功能	建议
Web Search & Scraping	联网搜索、网页抓取	✅ 开启
Browser Automation	浏览器自动操作	✅ 开启
Terminal & Processes	执行终端命令	✅ 开启
File Operations	文件读写、搜索、补丁	✅ 开启
Code Execution	执行代码	✅ 开启
Vision / Image Analysis	图片识别分析	✅ 开启
Video Analysis	视频分析	按需
Image Generation	AI 生成图片	✅ 开启
Video Generation	AI 生成视频	按需
X(Twitter) Search	搜索 X 平台内容	国内一般不用
Text-to-Speech	文本转语音	✅ 开启
Skills	技能管理	✅ 开启
Task Planning	任务规划	✅ 开启
Memory	长期记忆	✅ 开启
Context Engine	上下文引擎	新手可关闭
Session Search	搜索历史会话	✅ 开启
Clarifying Questions	自动追问补充信息	✅ 开启
Task Delegation	多 Agent 协作	✅ 开启
Cron Jobs	定时任务	✅ 开启
Home Assistant	智能家居控制	按需
Spotify	Spotify 音乐控制	按需
Yuanbao	腾讯元宝集成	按需
Computer Use	操作桌面系统	✅ 开启

我这里基本保持默认。几个能力可以重点看一下。

Terminal & Processes

开启后，模型可以执行终端命令，例如：

▼
bash
复制代码
ls
pwd
ps -ef
systemctl status

这是 Agent 最核心的能力之一。

File Operations

开启后可以读取文件、修改文件、批量替换代码、生成补丁。写代码、改配置时很有用。

Memory

开启后，Hermes 可以记住项目、常用命令和偏好配置。它更像长期记忆，不是每次对话都从零开始。

Cron Jobs

这个功能挺适合服务器场景，例如：

▼
text
复制代码
每天早上 8 点推送服务器状态
每天检查磁盘空间
每天汇总 Git 提交

Computer Use

类似 Claude Computer Use，可以打开浏览器、点击按钮、输入内容、操作桌面。

不过如果你只是部署在 Linux 云服务器上，这个能力大部分时候用不上。

配置浏览器自动化

如果前面开启了：

▼
text
复制代码
✓ Browser Automation

Hermes 会继续让你选择浏览器自动化的 Provider。

选项	说明	是否收费	推荐
Local Browser	本机 Chromium 浏览器	免费	⭐⭐⭐⭐⭐
Nous Subscription	Nous 官方云浏览器	订阅	⭐⭐⭐
Camofox	反检测 Firefox 浏览器	免费	⭐⭐⭐
Browser Use	Browser Use 云服务	付费	⭐⭐
Browserbase	Browserbase 云浏览器	付费	⭐⭐
Firecrawl	Firecrawl 云抓取服务	付费	⭐⭐
Skip	跳过配置	-	⭐⭐⭐

普通用户直接选默认的 Local Browser 就可以。

后面 Hermes 就可以完成这类任务：

▼
text
复制代码
打开网页
登录网站
点击按钮
填写表单
滚动页面
抓取内容
截图

例如：

▼
text
复制代码
帮我打开 github.com
搜索 hermes-agent
查看 Star 数量

Hermes 会调用本地 Chromium 执行。

两个容易卡住的扩展功能

Computer Use 安装超时

Hermes 会尝试安装 cua-driver，用来实现桌面自动化能力。

它的安装脚本在 GitHub：

▼
text
复制代码
https://raw.githubusercontent.com/trycua/cua/main/libs/cua-driver/scripts/install.sh

国内服务器可能会遇到下载超时：

▼
text
复制代码
cua-driver installer download failed
timed out after 120 seconds

如果你只是用 Hermes 做模型对话、代码执行、文件操作、联网搜索和微信机器人，这个失败一般不影响核心功能。

Image Generation 登录 Nous Portal

配置图片生成时，Hermes 可能会询问：

▼
text
复制代码
Log in to Nous Portal now? [Y/n]:

Nous Portal 是 Nous 官方云服务，用来接图片生成、云浏览器等高级能力。

如果暂时不需要 AI 绘图，可以输入：

▼
text
复制代码
n

先跳过，后续需要再单独配置。

配置 TTS

这个步骤是配置 Text-to-Speech，也就是文本转语音。

如果开启，Hermes 的文字回复可以转换成语音播放，或者发送语音消息。

提供商	类型	是否收费	特点	推荐
Microsoft Edge TTS	云端	免费	音质不错，无需 API Key	⭐⭐⭐⭐⭐
Nous Subscription	云端	订阅	Nous 官方服务	⭐⭐⭐
OpenAI TTS	云端	付费	OpenAI 官方语音	⭐⭐⭐⭐
xAI TTS	云端	付费	Grok 语音	⭐⭐⭐
ElevenLabs	云端	付费	行业顶级拟真语音	⭐⭐⭐⭐⭐
Mistral Voxtral	云端	付费	多语言支持较好	⭐⭐⭐
Google Gemini TTS	云端	付费	Gemini 语音能力	⭐⭐⭐
KittenTTS	本地	免费	轻量级，本地运行	⭐⭐⭐
Piper	本地	免费	支持 40+ 种语言	⭐⭐⭐⭐
Skip	跳过	-	后续再配置	⭐⭐⭐

如果没有语音需求，保持默认或跳过即可。

配置联网搜索

接下来是 Web Search，也就是 Hermes 执行联网搜索时使用哪个搜索服务。

例如你在 Hermes 里输入：

▼
text
复制代码
帮我搜索 Spring Boot 3 最新版本
帮我查一下 OpenAI 最近发布了什么
帮我总结这个网站内容

Hermes 就会调用这里配置的搜索能力。

常见搜索 Provider 如下：

搜索引擎	类型	是否收费	功能	推荐
Nous Subscription	官方托管	订阅	搜索 + 网页提取	⭐⭐⭐
Firecrawl Self-Hosted	自建	免费	搜索 + 抓取	⭐⭐⭐⭐
Brave Search	官方 API	免费额度	仅搜索	⭐⭐⭐⭐⭐
DuckDuckGo (ddgs)	开源	免费	仅搜索	⭐⭐⭐⭐⭐
Exa	商业服务	付费	语义搜索	⭐⭐⭐⭐
Firecrawl	商业服务	付费	搜索 + 抓取	⭐⭐⭐
Parallel	商业服务	付费	搜索 + 内容提取	⭐⭐⭐
SearXNG	自建	免费	聚合搜索	⭐⭐⭐⭐
Tavily	商业服务	付费	Agent 专用搜索	⭐⭐⭐⭐
xAI Web Search	xAI	付费	Grok 联网搜索	⭐⭐⭐
Skip	跳过	-	后续配置	⭐⭐⭐

Hermes 已经内置免费的 DuckDuckGo 搜索能力。如果只是日常搜索，可以直接跳过高级搜索服务。

后面会询问是否登录 Nous Portal，使用官方托管的 Firecrawl 搜索服务。

出现下面提示时：

▼
bash
复制代码
Log in to Nous Portal now? [Y/n]:

普通用户可以输入：

▼
text
复制代码
n

这样无需额外账号，也能使用基础联网搜索。

方案	是否需要账号	是否收费	推荐
DuckDuckGo（内置）	不需要	免费	⭐⭐⭐⭐⭐
Nous Subscription	需要	订阅	⭐⭐

配置完成后会看到成功提示。

验证安装是否成功

安装完成后，不要急着关终端。建议按下面这组命令检查一遍，基本能覆盖环境、模型、网关、日志和后续重新配置。

检查环境

先跑官方推荐的诊断命令：

▼
bash
复制代码
hermes doctor

这个命令会检查依赖、配置、安装方式、环境变量等问题。如果缺少组件，通常会直接给出修复建议。

如果想看当前配置，可以执行：

▼
bash
复制代码
hermes config

如果是排查问题、准备发 issue 或找人帮忙，也可以导出一份脱敏摘要：

▼
bash
复制代码
hermes dump

启动命令行助手

进入 Hermes 交互界面：

▼
bash
复制代码
hermes

能正常进入对话界面，并且输入一句话后模型有回复，说明模型 Provider、API Key 和推理服务基本没问题。

如果只想跑一次命令，也可以用：

▼
bash
复制代码
hermes chat -q "你好，请介绍一下你自己"

查看网关状态

如果前面把 Gateway 安装成了 systemd 服务，优先看系统服务状态：

▼
bash
复制代码
systemctl status hermes-gateway

看到类似下面的状态，就说明服务正在运行：

▼
text
复制代码
active (running)

也可以用 Hermes 自带的 gateway 命令查看：

▼
bash
复制代码
hermes gateway status

如果你是在 WSL、Docker 或 Termux 里运行，官方更推荐前台运行 Gateway：

▼
bash
复制代码
hermes gateway run

查看网关日志

微信机器人收不到消息、扫码后掉线、Gateway 起不来时，先看日志：

▼
bash
复制代码
journalctl -u hermes-gateway -f

如果你使用的是用户级 systemd 服务，则查看：

▼
bash
复制代码
journalctl --user -u hermes-gateway -f

Hermes 也提供了自己的日志命令，可以用来查看 agent、gateway 和错误日志：

▼
bash
复制代码
hermes logs

重新配置

如果配置过程中选错了，或者后面想重新走一遍完整向导，执行：

▼
bash
复制代码
hermes setup

官方文档里也提供了按模块重新配置的方式。比如只改模型、消息平台或工具，不需要完整走一遍安装向导。

修改模型

官方推荐的模型配置命令是：

▼
bash
复制代码
hermes model

它会进入 Provider 和模型选择器，可以新增 Provider、输入 API Key、选择模型。

也可以直接跳到 setup 向导里的模型配置部分：

▼
bash
复制代码
hermes setup model

注意区分一下：hermes model 是终端里的完整模型配置向导；聊天过程中的 /model 只是在已经配置好的模型之间切换。

修改消息平台

如果后面想重新配置微信、QQ、钉钉、飞书、Slack 等消息平台，可以执行：

▼
bash
复制代码
hermes gateway setup

也可以用 setup 分段命令：

▼
bash
复制代码
hermes setup gateway

如果 Gateway 服务已经在运行，改完配置后建议重启一次：

▼
bash
复制代码
systemctl restart hermes-gateway

修改工具配置

如果想重新选择 Web Search、Browser Automation、Terminal、File Operations、Memory、Cron Jobs 等工具能力，执行：

▼
bash
复制代码
hermes tools

或者：

▼
bash
复制代码
hermes setup tools

修改完工具后，再进入 Hermes 测一下搜索、文件操作或终端命令，确认工具开关符合预期。

常用验证命令汇总

最后把常用命令放在一起，后面排查时可以直接复制。

▼
bash
复制代码
# 检查环境和依赖
hermes doctor

# 查看当前配置
hermes config

# 启动命令行助手
hermes

# 单次测试模型回复
hermes chat -q "你好，请介绍一下你自己"

# 查看 Gateway systemd 服务
systemctl status hermes-gateway

# 查看 Gateway 日志
journalctl -u hermes-gateway -f

# 查看 Hermes 自身日志
hermes logs

# 重新完整配置
hermes setup

# 修改模型
hermes model
hermes setup model

# 修改消息平台
hermes gateway setup
hermes setup gateway

# 修改工具配置
hermes tools
hermes setup tools

测试模型

进入 Hermes：

▼
bash
复制代码
hermes

输入：

▼
text
复制代码
你好，请介绍一下你自己

如果能正常回复，说明这几项已经跑通：

▼
text
复制代码
TokenHub API
模型
推理服务

测试联网搜索

进入 Hermes 后输入：

▼
text
复制代码
帮我搜索 Spring Boot 最新版本

或者：

▼
text
复制代码
搜索 OpenAI 最近一周新闻

如果能返回搜索结果，说明 DuckDuckGo 搜索能力已经正常工作。

测试微信机器人

先看 Gateway 服务状态：

▼
bash
复制代码
systemctl status hermes-gateway

如果显示：

▼
text
复制代码
active (running)

就可以直接给刚绑定的微信 Bot 发消息。

收到回复，说明模型、Gateway、微信接入这条链路已经打通。

切换模型

Agent 任务比较耗 Token。尤其是联网搜索、网页总结、工具调用多的任务，一次下来消耗会比较明显。

如果当前模型额度不够，可以切换到其他还有额度的模型。

执行：

▼
bash
复制代码
hermes model

如果需要恢复之前的会话，也可以在界面里选择历史会话。

总结

这次完整跑下来，Hermes Agent 的核心链路基本就是：

▼
text
复制代码
安装 Hermes
↓
配置模型 Provider 和 API Key
↓
开启 Tools
↓
配置 Web Search
↓
接入微信
↓
安装 Gateway 后台服务
↓
测试模型、搜索、微信消息

如果只是本机体验，装完 Hermes、配好模型就够了。

如果想把它当微信机器人长期挂在服务器上，建议把 Gateway 配成 systemd 服务，并且认真设置私聊权限，避免被别人随便调用消耗额度。

Hermes Agent 相关命令还有很多，后面可以继续看官方文档。

欢迎关注我的公众号【兮动人】，每天分享技术文章和实战经验。