全部教程
本页目录
Hermes 是什么#
一句话:装在本机的命令行 agent,能聊天、能调工具、能接消息平台、能定时跑。
它和另外两个的区别:
如果你要的是「每天早上八点自动整理一份日报发到群里」,这条路是对的。
装与升级#
安装方式按官方文档走。装完先确认三件事:
hermes --version # 版本、安装目录、Python 版本
hermes update # 升级到最新
hermes logs -f # 看实时日志(排错时最有用)验收:hermes --version 正常输出,hermes --help 能看到子命令列表。
第一步:跑 setup 向导#
不要一上来手写 config.yaml。先让向导生成一份能用的配置:
hermes setup向导会分几段问你:模型、语音、终端、gateway、工具、遥测、agent。第一遍可以只配模型,其他的跳过后再回来:
hermes setup model # 模型与 provider
hermes setup terminal # 终端工具
hermes setup gateway # 消息平台
hermes setup agent # agent 行为配完会写进:
~/.hermes/config.yaml先备份再手改
cp ~/.hermes/config.yaml ~/.hermes/config.yaml.bak。这份文件是纯 YAML,手改一个缩进错了,整个 agent 起不来。
第二步:config.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#
providers:
zhuge:
base_url: https://zhugeai.cn/v1
api_key: <你的key>
default_model: <模型ID>
models: '["<模型ID>"]'
model:
default: <模型ID>
provider: custom:zhuge两个细节:
provider前面要加custom:前缀,表示这是自定义 provider。models是JSON 字符串,不是 YAML 数组。写成 YAML 数组会在启动时报解析错。
验收:
hermes chat -q "只回复两个字:通了" --oneshot能回「通了」就对了。
key 放哪
示例里写在 config.yaml 里最省事,但这份文件容易在备份、同步、截图里泄露。 更好的做法是写进环境变量或用密钥管理,配置里只留引用。至少保证 ~/.hermes/ 不在任何 Git 仓库里。
第三步:三种用法#
1. 交互式#
hermes chat # 进对话
hermes chat -q "帮我看看这个项目的结构" # 带开场白进对话2. 一次性(适合脚本)#
hermes chat -q "把这份日志里的 ERROR 抽出来" --oneshot
hermes chat --query-file ./prompt.txt --oneshot > out.md--oneshot 是给脚本用的:问完就退,不留在交互界面。--query-file 比 -q 安全——文件里的引号、$()、反引号不会被 shell 解释。
3. 指定模型 / provider(临时覆盖)#
hermes chat -q "..." --provider custom:zhuge -m <模型ID>临时切模型这个能力很实用:日常用便宜的,遇到难题临时换强的。
第四步:接消息平台#
hermes gateway 是让 agent 接到 IM 上的那层。支持 Telegram、Discord、WhatsApp、Slack、微信等,具体看:
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;在对应平台发一句话,能收到回复。
第五步:定时任务#
hermes cron list # 看现有任务
hermes cron create # 建一个
hermes cron run <id> # 立刻跑一次(测试用)
hermes cron status
hermes cron runs # 历史执行记录建任务时想清楚三件事:
- 失败了怎么办——有没有重试、要不要通知。
- 产物放哪——不要写在临时目录,重启就没了。
- 要不要人确认——涉及发布、付款、删除的,必须留人工确认。
cron 的实际价值
定时任务最容易变成「设了但没人看」。要么让它把结果推到你会看的地方(群、邮件),要么别设。
第六步:Profile 与多身份#
hermes -p <profile名> chat # 用指定 profile 跑
hermes -p <profile名> gateway stop一个 profile 一套配置、一套会话、一套 gateway。典型用法:
| profile | 用途 | 权限 |
|---|---|---|
| 默认 | 日常 | 正常 |
ops | 定时任务 | 只读 + 特定脚本 |
bot | 对外机器人 | 不碰本地文件 |
第七步:Web 面板(可选)#
hermes dashboard # 默认端口 9119
hermes dashboard --status
hermes dashboard --stop面板能看会话、改配置、管 key。默认只监听本机,不要挂到公网。真要从外面访问,前面套一层带鉴权的反向代理,或者用内网穿透的白名单。
排错顺序#
固定成这个顺序,能省一半时间:
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 写成了数组 |
| 能启动但回复 401 | key 错 / provider 名和 model.provider 对不上 |
| gateway 一直重连 | bot token 错、或被别处占用 |
| cron 不触发 | 服务没起、或任务被 pause |
| 回复很慢 | 模型太大 / 上下文太长 / 网络 |
验收清单#
一句话#
Hermes 的配置全在 config.yaml 里,但真正的门槛是「敢不敢让它常驻」。 先用 ask 策略跑一周,摸清它的行为,再考虑放开。