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

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

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

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

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

项目地址

项目地址：

https://github.com/NousResearch/hermes-agent

官方文档：

https://hermes-agent.nousresearch.com/docs/zh-Hans/getting-started/installation

支持环境：

Linux / macOS / WSL2

官方安装方式

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

curl-fsSLhttps://hermes-agent.nousresearch.com/install.sh|bash

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

先看一下当前 shell：

echo$SHELL

如果输出的是 bash，执行：

source~/.bashrc

如果输出的是 zsh：

$echo$SHELL/bin/zsh

则执行：

source~/.zshrc

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

GitHub PyPI uv 依赖源 Rust 相关组件 Node.js 相关依赖

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

源码安装方式

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

gitclone https://gitcode.com/GitHub_Trending/he/hermes-agent.git

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

https://hermes-agent.nousresearch.com/docs/

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

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

创建安装目录

mkdir-p~/.hermes

复制源码目录

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

cp-r~/hermes-agent ~/.hermes/hermes-agent

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

cd~/.hermes/hermes-agent&&bashscripts/install.sh

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

最后重新加载环境变量：

source~/.zshrc

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

cd/root/hermes-agentbashscripts/install.sh

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

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

验证 Hermes 命令是否可用

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

hermes--versionhermes--help

启动 Hermes：

hermes

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

退出交互界面：

exit

配置文件在哪里

Hermes 默认配置在：

cat~/.hermes/config.yaml

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

我这里看到默认模型是：

默认模型：anthropic/claude-opus-4.6 Provider：auto 默认走 OpenRouter 接口

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

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

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

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

因此界面上虽然显示了：

claude-opus-4.6

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

运行配置向导

执行：

hermes setup

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

三个选项大概是这样：

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

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

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

模型这里我选择glm-5.2。

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

选择命令运行环境

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

常见选项如下：

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

配置消息平台

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

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

常见平台如下：

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

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

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

打开后用微信扫码。

配置微信私聊权限

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

首次安装建议选：

Use DM pairing approval (recommended)

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

授权流程大概是：

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

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

Only allow listed user IDs

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

wxid_admin wxid_dev01 wxid_dev02

不太建议选择：

Allow all direct messages

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

几个选项对比如下：

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

我这里的配置结果是：

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

配置 Home Channel

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

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

安装 Gateway 后台服务

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

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

/etc/systemd/system/hermes-gateway.service

并执行：

systemctlenablehermes-gateway systemctl start hermes-gateway

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

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

hermes gateway

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

选择服务运行方式

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

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

systemctl--userstatus hermes-gateway

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

systemctl status hermes-gateway

我这里选择：

System service

后续管理命令如下：

# 查看状态systemctl status hermes-gateway# 启动systemctl start hermes-gateway# 停止systemctl stop hermes-gateway# 重启systemctl restart hermes-gateway# 开机自启systemctlenablehermes-gateway

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

我这里直接输入：

root

然后选择Y启动服务。

配置工具能力

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

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

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

Terminal & Processes

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

lspwdps-efsystemctl status

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

File Operations

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

Memory

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

Cron Jobs

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

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

Computer Use

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

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

配置浏览器自动化

如果前面开启了：

✓ Browser Automation

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

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

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

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

例如：

帮我打开 github.com 搜索 hermes-agent 查看 Star 数量

Hermes 会调用本地 Chromium 执行。

两个容易卡住的扩展功能

Computer Use 安装超时

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

它的安装脚本在 GitHub：

https://raw.githubusercontent.com/trycua/cua/main/libs/cua-driver/scripts/install.sh

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

cua-driver installer download failed timed out after 120 seconds

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

Image Generation 登录 Nous Portal

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

Log in to Nous Portal now? [Y/n]:

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

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

n

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

配置 TTS

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

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

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

配置联网搜索

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

例如你在 Hermes 里输入：

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

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

常见搜索 Provider 如下：

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

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

出现下面提示时：

Loginto Nous Portal now?[Y/n]:

普通用户可以输入：

n

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

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

验证安装是否成功

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

检查环境

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

hermes doctor

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

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

hermes config

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

hermes dump

启动命令行助手

进入 Hermes 交互界面：

hermes

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

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

hermes chat-q"你好，请介绍一下你自己"

查看网关状态

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

systemctl status hermes-gateway

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

active (running)

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

hermes gateway status

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

hermes gateway run

查看网关日志

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

journalctl-uhermes-gateway-f

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

journalctl--user-uhermes-gateway-f

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

hermes logs

重新配置

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

hermes setup

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

修改模型

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

hermes model

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

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

hermes setup model

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

修改消息平台

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

hermes gateway setup

也可以用 setup 分段命令：

hermes setup gateway

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

systemctl restart hermes-gateway

修改工具配置

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

hermes tools

或者：

hermes setup tools

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

常用验证命令汇总

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

# 检查环境和依赖hermes doctor# 查看当前配置hermes config# 启动命令行助手hermes# 单次测试模型回复hermes chat-q"你好，请介绍一下你自己"# 查看 Gateway systemd 服务systemctl status hermes-gateway# 查看 Gateway 日志journalctl-uhermes-gateway-f# 查看 Hermes 自身日志hermes logs# 重新完整配置hermes setup# 修改模型hermes model hermes setup model# 修改消息平台hermes gateway setup hermes setup gateway# 修改工具配置hermes tools hermes setup tools

测试模型

进入 Hermes：

hermes

输入：

你好，请介绍一下你自己

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

TokenHub API 模型 推理服务

测试联网搜索

进入 Hermes 后输入：

帮我搜索 Spring Boot 最新版本

或者：

搜索 OpenAI 最近一周新闻

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

测试微信机器人

先看 Gateway 服务状态：

systemctl status hermes-gateway

如果显示：

active (running)

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

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

切换模型

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

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

执行：

hermes model

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

总结

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

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

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

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

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

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