Hermes 安装、面板启用、微信绑定安装记录

这份文档是根据 2026-04-15 实际操作记录整理的复盘版，目标是下次在新机器上按同样步骤尽量一次装通。

适用范围：

安装 Hermes Agent
启用内置 Web 面板 dashboard
绑定个人微信 Weixin
避开昨天已经踩过的坑

当前这台机器在整理文档时的状态：

日期：2026-04-16
Hermes 版本：Hermes Agent v0.9.0 (2026.4.13)
Hermes 实际可执行文件：/root/.local/bin/hermes
实际指向：/root/.hermes/hermes-agent/venv/bin/hermes
Hermes 项目目录：/root/.hermes/hermes-agent

一、最终走通的安装路径 #

昨天试过多种装法，包含：

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

最后真正稳定可用、并且和当前机器状态一致的路径是：

1. 安装基础依赖 #

1yum install -y git curl python3-pip

如果系统用的是 dnf，就把 yum 换成 dnf。

2. 用官方脚本安装 Hermes #

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

安装完成后检查：

1which hermes
2readlink -f ~/.local/bin/hermes
3hermes --version

我这台机器当前结果是：

which hermes 指向 ~/.local/bin/hermes
readlink -f ~/.local/bin/hermes 指向 /root/.hermes/hermes-agent/venv/bin/hermes

如果不是这个结构，先不要往下配微信。

二、面板 Dashboard 启用方式 #

Hermes 的“面板”不是单独项目，直接就是内置命令：

1hermes dashboard

帮助信息里可以确认默认参数：

1hermes dashboard --help

默认是：

Host：127.0.0.1
Port：9119

1. 推荐启动方式 #

1hermes dashboard --no-open

如果是服务器，没有桌面环境，尽量加 --no-open。

2. 后台启动方式 #

1nohup hermes dashboard --no-open >/tmp/hermes-dashboard.log 2>&1 &

3. 昨天这里踩过的坑 #

安装完 Hermes 后，CLI 有了，但 dashboard 相关 Web 依赖不一定齐。

昨天补依赖时走过这些命令：

1/root/.local/share/hermes/venv/bin/python -m pip install -U "hermes-agent[web]"
2cd /root/.hermes/hermes-agent
3./venv/bin/python -m pip install -U ".[web]"
4cd /root/.hermes/hermes-agent
5./venv/bin/python -m pip install -U ".[all]"

最终应该以项目自带 venv 为准，也就是这个目录：

1cd /root/.hermes/hermes-agent
2./venv/bin/python -m pip install -U ".[web]"

如果装完 .[web] 还不稳，再补：

1./venv/bin/python -m pip install -U ".[all]"

结论：

不要优先折腾 ~/.local/share/hermes/venv
以 ~/.hermes/hermes-agent/venv 这套环境为准
hermes 实际就是跑这套 venv

三、模型提供方配置 #

昨天本来想走：

1hermes auth add openai-codex

但这条路实际踩坑了。

1. 踩坑结论 #

openai-codex 的 device-code 登录流当时直接返回了 403，日志里有明确记录：

codex device-code worker failed
deviceauth/usercode returned 403

所以昨天没有把 openai-codex OAuth 作为最终可用方案。

2. 最终落地方案 #

当前机器最后使用的是 custom provider，在 ~/.hermes/config.yaml 里直接配置：

1model:
2  default: gpt-5.4
3  provider: custom
4  base_url: <你的兼容 OpenAI 的接口地址>
5  api_key: <你的 key>
6  api_mode: codex_responses

这就是当前机器真实可用的方案。

3. 建议 #

下次安装时：

不要把 hermes auth add openai-codex 当主流程
先走 custom + base_url + api_key + api_mode: codex_responses
等后面确认官方 OAuth 恢复正常，再回头试 openai-codex

四、微信绑定流程 #

昨天绑定的是个人微信，不是企业微信。

Hermes 对应的是 Weixin，不是 WhatsApp，也不是 WeCom。

1. 先确认微信依赖 #

昨天检查过 Hermes 的 Python 环境里这两个依赖是齐的：

aiohttp
cryptography

如果新机器不确定，先执行：

1cd /root/.hermes/hermes-agent
2./venv/bin/python -m pip install -U aiohttp cryptography qrcode

qrcode 不是绝对必须，但装上后终端扫码体验更好。

2. 正确的微信配置命令 #

这里昨天也踩过一个命令认知坑。

正确的是：

1hermes gateway setup

不是：

1hermes setup gateway

hermes setup gateway 是总配置向导的子入口；昨天实际验证和微信绑定最直接可用的是 hermes gateway setup。

3. 绑定步骤 #

执行：

1hermes gateway setup

然后在交互里：

选择 Weixin
终端会拉起二维码登录流程
用手机微信扫码
手机确认登录
Hermes 自动保存账号信息

绑定成功后，至少会落下两类数据：

A. 账号文件 #

1~/.hermes/weixin/accounts/

昨天实际已经生成：

8a7c654cd325@im.bot.json
8a7c654cd325@im.bot.sync.json
8a7c654cd325@im.bot.context-tokens.json

说明微信绑定已经成功跑通过。

B. 环境变量 #

写入 ~/.hermes/.env 的关键变量通常有：

1WEIXIN_ACCOUNT_ID=<你的 account_id>
2WEIXIN_TOKEN=<你的 token>
3WEIXIN_BASE_URL=https://ilinkai.weixin.qq.com
4WEIXIN_CDN_BASE_URL=https://novac2c.cdn.weixin.qq.com/c2c
5WEIXIN_DM_POLICY=allowlist
6WEIXIN_ALLOWED_USERS=<你的微信 user_id>
7WEIXIN_GROUP_POLICY=disabled

注意：

文档里不要直接抄旧机器的真实 TOKEN
迁移到新机器时，建议重新扫码生成

4. 我们昨天最终落地的权限策略 #

昨天最终不是完全开放，而是：

私聊：allowlist
允许用户：只放自己的微信 user_id
群聊：disabled

也就是只允许你自己的微信私聊这个 Hermes。

这是比较稳妥的默认方案。

5. 启动微信网关 #

1hermes gateway run

如果要装成服务长期运行：

1hermes gateway install
2hermes gateway start

当前机器已经存在：

1~/.hermes/gateway.pid

说明昨天网关确实启动过，而且日志里已经有真实的微信收发记录。

五、验证是否安装成功 #

下次装完后，按下面顺序检查。

1. Hermes 本体 #

1which hermes
2readlink -f ~/.local/bin/hermes
3hermes --version

2. Dashboard #

1hermes dashboard --help
2nohup hermes dashboard --no-open >/tmp/hermes-dashboard.log 2>&1 &

如果你有本地浏览器，访问：

1http://127.0.0.1:9119

如果是远程服务器，自己做 SSH 端口转发，不要直接暴露公网。

3. 微信配置 #

1ls ~/.hermes/weixin/accounts/
2grep '^WEIXIN_' ~/.hermes/.env

4. 微信网关日志 #

1tail -n 50 ~/.hermes/logs/agent.log

如果看到类似：

gateway.platforms.weixin
inbound
Sending response

就说明微信通道已经在正常工作。

六、昨天实际踩过的坑 #

1. `hermes auth add openai-codex` 不稳定 #

现象：

授权流没正常完成
日志报 deviceauth/usercode returned 403

处理：

暂时不要把它当主路径
改用 custom provider

2. Dashboard 依赖不一定自动带齐 #

现象：

Hermes 主命令可用
但面板相关能力不完整

处理：

1cd /root/.hermes/hermes-agent
2./venv/bin/python -m pip install -U ".[web]"

必要时：

1./venv/bin/python -m pip install -U ".[all]"

3. 很容易把命令记混 #

容易混的有三类：

hermes gateway setup
hermes setup gateway
hermes whatsapp

昨天这台机器的结论是：

个人微信绑定，优先用 hermes gateway setup
不要把 WhatsApp 当成微信

4. 一个 profile 只能激活一个微信号 #

这点昨天也确认过。

单个 Hermes profile 虽然可以保存多个微信账号文件，但运行时只会读取一个 WEIXIN_ACCOUNT_ID。

如果你以后要挂多个微信号，正确做法不是硬塞到同一个 .env，而是新建 profile：

1hermes profile create wx2 --clone
2hermes -p wx2 gateway setup
3hermes gateway run
4hermes -p wx2 gateway run

结论：

一个 profile = 一个活跃微信号
多个微信号同时在线 = 多个 profile + 多个 gateway 进程

七、下次最建议直接照抄的步骤 #

如果以后新机器重装，我建议直接按这个最短成功路径走。

1. 安装 Hermes #

1yum install -y git curl python3-pip
2curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
3which hermes
4readlink -f ~/.local/bin/hermes
5hermes --version

2. 补 Dashboard 依赖 #

1cd /root/.hermes/hermes-agent
2./venv/bin/python -m pip install -U ".[web]"

3. 配模型 #

编辑：

1vim ~/.hermes/config.yaml

写成：

1model:
2  default: gpt-5.4
3  provider: custom
4  base_url: <你的接口地址>
5  api_key: <你的 key>
6  api_mode: codex_responses

4. 启动面板 #

1nohup hermes dashboard --no-open >/tmp/hermes-dashboard.log 2>&1 &

5. 绑定微信 #

1hermes gateway setup

扫码确认后，再编辑：

1vim ~/.hermes/.env

建议至少保留：

1WEIXIN_ACCOUNT_ID=<你的 account_id>
2WEIXIN_TOKEN=<你的 token>
3WEIXIN_BASE_URL=https://ilinkai.weixin.qq.com
4WEIXIN_CDN_BASE_URL=https://novac2c.cdn.weixin.qq.com/c2c
5WEIXIN_DM_POLICY=allowlist
6WEIXIN_ALLOWED_USERS=<你的微信 user_id>
7WEIXIN_GROUP_POLICY=disabled

6. 启动微信网关 #

1hermes gateway run

八、建议补充 #

为了以后更省事，建议把这几个文件单独备份：

~/.hermes/config.yaml
~/.hermes/.env
~/.hermes/weixin/accounts/

但要注意：

WEIXIN_TOKEN
你的模型 api_key

都属于敏感信息，备份时最好加密存放。

last updated: 2026-04-16