Hermes 是什么#

一句话:装在本机的命令行 agent,能聊天、能调工具、能接消息平台、能定时跑。

它和另外两个的区别:

HermesDSHWorkBuddy
形态命令行 + 可选 Web 面板桌面应用 + Web桌面应用
强项自动化、定时、接 IM本机文件工作台、插件文档与办公
适合服务器 / 常驻个人电脑人在电脑前

如果你要的是「每天早上八点自动整理一份日报发到群里」,这条路是对的。

装与升级#

安装方式按官方文档走。装完先确认三件事:

bash
hermes --version     # 版本、安装目录、Python 版本
hermes update        # 升级到最新
hermes logs -f       # 看实时日志(排错时最有用)

验收:hermes --version 正常输出,hermes --help 能看到子命令列表。

第一步:跑 setup 向导#

不要一上来手写 config.yaml。先让向导生成一份能用的配置:

bash
hermes setup

向导会分几段问你:模型、语音、终端、gateway、工具、遥测、agent。第一遍可以只配模型,其他的跳过后再回来:

bash
hermes setup model      # 模型与 provider
hermes setup terminal   # 终端工具
hermes setup gateway    # 消息平台
hermes setup agent      # agent 行为

配完会写进:

text
~/.hermes/config.yaml

先备份再手改

cp ~/.hermes/config.yaml ~/.hermes/config.yaml.bak。这份文件是纯 YAML,手改一个缩进错了,整个 agent 起不来。

第二步:config.yaml 的结构#

不用全记,记住这几段就够:

yaml
model:                 # 默认用哪个模型、哪个 provider
  default: <模型ID>
  provider: custom:zhuge

providers:             # 每个 provider 一组连接信息
  zhuge:
    base_url: https://zhugeai.cn/v1
    api_key: <你的key>
    default_model: <模型ID>
    models: '["<模型ID>", "<另一个模型ID>"]'

fallback_providers:    # 主 provider 挂了自动换
  - provider: qwen
    model: <模型ID>

agent:                 # 最大轮数、推理强度、人设
  max_turns: 30

approvals:             # 危险操作要不要问
  mode: ask

skills:                # 技能开关
  disabled: []

cron:                  # 定时任务用的模型
  model: <模型ID>

接诸葛:加一个 provider#

yaml
providers:
  zhuge:
    base_url: https://zhugeai.cn/v1
    api_key: <你的key>
    default_model: <模型ID>
    models: '["<模型ID>"]'

model:
  default: <模型ID>
  provider: custom:zhuge

两个细节:

  1. provider 前面要加 custom: 前缀,表示这是自定义 provider。
  2. models 是JSON 字符串,不是 YAML 数组。写成 YAML 数组会在启动时报解析错。

验收:

bash
hermes chat -q "只回复两个字:通了" --oneshot

能回「通了」就对了。

key 放哪

示例里写在 config.yaml 里最省事,但这份文件容易在备份、同步、截图里泄露。 更好的做法是写进环境变量或用密钥管理,配置里只留引用。至少保证 ~/.hermes/ 不在任何 Git 仓库里。

第三步:三种用法#

1. 交互式#

bash
hermes chat              # 进对话
hermes chat -q "帮我看看这个项目的结构"   # 带开场白进对话

2. 一次性(适合脚本)#

bash
hermes chat -q "把这份日志里的 ERROR 抽出来" --oneshot
hermes chat --query-file ./prompt.txt --oneshot > out.md

--oneshot 是给脚本用的:问完就退,不留在交互界面。--query-file 比 -q 安全——文件里的引号、$()、反引号不会被 shell 解释。

3. 指定模型 / provider(临时覆盖)#

bash
hermes chat -q "..." --provider custom:zhuge -m <模型ID>

临时切模型这个能力很实用:日常用便宜的,遇到难题临时换强的。

第四步:接消息平台#

hermes gateway 是让 agent 接到 IM 上的那层。支持 Telegram、Discord、WhatsApp、Slack、微信等,具体看:

bash
hermes gateway setup      # 配平台
hermes gateway install    # 装成后台服务(launchd / systemd)
hermes gateway start
hermes gateway status
hermes gateway list       # 看所有 profile 的 gateway 状态

三条经验:

  • 先用 hermes gateway run 前台跑一遍,能看到日志、能立刻发现 token 配错。跑通了再 install 成服务。
  • install 之后不要再用 run,两个实例会抢同一个连接。
  • 一个平台一个 bot token,别复用。

验收:hermes gateway status 显示 running;在对应平台发一句话,能收到回复。

第五步:定时任务#

bash
hermes cron list          # 看现有任务
hermes cron create        # 建一个
hermes cron run <id>      # 立刻跑一次(测试用)
hermes cron status
hermes cron runs          # 历史执行记录

建任务时想清楚三件事:

  1. 失败了怎么办——有没有重试、要不要通知。
  2. 产物放哪——不要写在临时目录,重启就没了。
  3. 要不要人确认——涉及发布、付款、删除的,必须留人工确认。

cron 的实际价值

定时任务最容易变成「设了但没人看」。要么让它把结果推到你会看的地方(群、邮件),要么别设。

第六步:Profile 与多身份#

bash
hermes -p <profile名> chat        # 用指定 profile 跑
hermes -p <profile名> gateway stop

一个 profile 一套配置、一套会话、一套 gateway。典型用法:

profile用途权限
默认日常正常
ops定时任务只读 + 特定脚本
bot对外机器人不碰本地文件

第七步:Web 面板(可选)#

bash
hermes dashboard            # 默认端口 9119
hermes dashboard --status
hermes dashboard --stop

面板能看会话、改配置、管 key。默认只监听本机,不要挂到公网。真要从外面访问,前面套一层带鉴权的反向代理,或者用内网穿透的白名单。

排错顺序#

固定成这个顺序,能省一半时间:

bash
hermes --version          # 1. 装没装好
hermes chat -q "hi" --oneshot   # 2. 模型通不通
hermes gateway status     # 3. 平台连没连上
hermes logs -f            # 4. 实时看它在干嘛
hermes logs errors        # 5. 只看错误
现象大概率原因
启动就报 YAML 错config.yaml 缩进或引号问题;models 写成了数组
能启动但回复 401key 错 / provider 名和 model.provider 对不上
gateway 一直重连bot token 错、或被别处占用
cron 不触发服务没起、或任务被 pause
回复很慢模型太大 / 上下文太长 / 网络

验收清单#

一句话#

Hermes 的配置全在 config.yaml 里,但真正的门槛是「敢不敢让它常驻」。 先用 ask 策略跑一周,摸清它的行为,再考虑放开。