Hermes Agent 使用与启动指南

Hermes Agent 使用与启动指南

1. 先说结论：这个项目怎么用

这个项目有 6 种主要使用方式：

1. 终端 CLI

   • 最传统的交互方式。

2. TUI

   • 更完整的终端 UI，支持流式状态、补全、队列、提示框。

3. 消息平台网关

   • Telegram / Discord / Slack / WhatsApp / Signal / Matrix / Email 等。

4. 编辑器 ACP

   • 让编辑器以协议方式连接 Hermes。

5. Web Dashboard

   • 浏览器里管理配置、密钥、会话状态。

6. 研究/批处理模式

   • 批量运行数据集、保存轨迹、做训练数据生成。

2. 官方推荐运行环境

从仓库文档与脚本看，推荐环境是：

• Linux
• macOS
• WSL2
• Termux

需要注意：

• README.md明确写了“原生 Windows 不推荐，建议 WSL2”。
• 但仓库同时又提供了scripts/install.ps1和 Windows 兼容依赖，说明项目在逐步补原生 Windows 能力。
• 如果你追求最稳定，仍然建议使用 WSL2 或 Linux。

3. 依赖与前提

Python

• pyproject.toml要求Python >= 3.11

Node

以下功能需要 Node 环境：

• 浏览器工具
• TUI 前端开发
• Web Dashboard 前端开发

根package.json要求：

• node >= 20

配置文件位置

用户侧配置默认放在：

• ~/.hermes/config.yaml
• ~/.hermes/.env

Hermes 运行时很多状态也在HERMES_HOME下保存。

4. 安装方式

4.1 普通用户安装

Linux / macOS / WSL2：

curl-fsSLhttps://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh|bashsource~/.bashrc hermes

Windows PowerShell：

irmhttps://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1|iex

4.2 本地克隆仓库后的开发安装

官方推荐的开发安装脚本：

gitclone https://github.com/NousResearch/hermes-agent.gitcdhermes-agent ./setup-hermes.sh ./hermes

4.3 手动开发安装

Unix/WSL 路径：

uv venv venv--python3.11sourcevenv/bin/activate uv pipinstall-e".[all,dev]"

如果你在当前这份仓库中按开发规范工作，仓库说明要求先激活虚拟环境再执行 Python：

sourcevenv/bin/activate

如果你是 PowerShell 原生环境，等价命令通常是：

.\venv\Scripts\Activate.ps1

5. 首次配置怎么做

最直接的方式是：

hermes setup

这个向导会引导你配置：

• 模型与 Provider
• 终端后端
• Agent 行为
• 消息平台
• 工具配置

也可以拆开做：

hermes model hermes tools hermes configset...

6. 如何启动项目

6.1 启动交互式 CLI

最常用启动方式：

hermes

或：

hermes chat

作用：

• 启动传统终端聊天界面。
• 适合日常使用和开发调试。

6.2 启动 TUI

hermes--tui

特点：

• 前端在ui-tui/
• 后端在tui_gateway/
• TUI 会启动 Python 子进程python -m tui_gateway.entry

如果 TUI 前端依赖没装，需要先：

cdui-tuinpminstall

6.3 启动消息网关

先配置：

hermes gateway setup

然后前台运行：

hermes gateway run

或者简写：

hermes gateway

如果要作为服务管理，还可以：

hermes gatewayinstallhermes gateway start hermes gateway status hermes gateway stop

适合场景：

• 挂 Telegram / Discord / Slack / WhatsApp 等。

6.4 启动 Web Dashboard

真实 CLI 子命令是：

hermes dashboard

例如：

hermes dashboard --no-open hermes dashboard--port9119

说明：

• 后端是hermes_cli/web_server.py
• 前端源码在web/
• 生产构建会被打到hermes_cli/web_dist/

注意一个文档漂移点：

• web/README.md里仍写的是python -m hermes_cli.main web --no-open
• 但当前 CLI 实现里真实命令是dashboard

6.5 启动 ACP 服务

hermes acp

或直接：

hermes-acp

适合编辑器集成。

6.6 直接以脚本方式运行 Agent

python run_agent.py--help

或者安装后：

hermes-agent--help

这种方式更偏底层调试，不是普通用户首选入口。

6.7 启动批处理

python batch_runner.py--help

示例：

python batch_runner.py--dataset_file=data.jsonl--batch_size=10--run_name=my_run

7. 如何实际使用这个项目

7.1 最小可用路径

如果你只想尽快跑起来：

1. 安装 Hermes
2. 配置一个模型 Provider
3. 执行hermes
4. 直接开始对话

7.2 编程代理使用

典型流程：

1. 进入你的项目目录
2. 启动hermes或hermes --tui
3. 让 Agent 读代码、查文件、修改文件、运行命令

这个场景下的关键能力是：

• read_file
• search_files
• write_file
• patch
• terminal
• delegate_task
• execute_code

7.3 消息机器人使用

典型流程：

1. hermes gateway setup
2. 配置对应平台 Token / Secret
3. hermes gateway run
4. 在 Telegram/Discord 等平台里直接发消息给机器人

7.4 自动化使用

典型流程：

1. 启动网关或至少确保本地 Hermes 可用
2. 配置 cron
3. 用自然语言任务生成定时任务

常见命令：

hermescronlist hermescronstatus

8. 常用命令汇总

9. 开发者常用命令

9.1 测试

仓库明确要求优先使用：

scripts/run_tests.sh

而不是直接pytest。

例如：

scripts/run_tests.sh scripts/run_tests.sh tests/gateway/ scripts/run_tests.sh tests/agent/test_x.py::test_y

9.2 TUI 前端开发

cdui-tuinpminstallnpmrun dev

9.3 Web Dashboard 前端开发

后端：

hermes dashboard --no-open

前端：

cdwebnpminstallnpmrun dev

9.4 文档站开发

cdwebsitenpminstallnpmstart

10. 启动路径建议

如果你是不同角色，建议这样启动：

普通用户

hermes setup hermes

代码开发者

sourcevenv/bin/activate hermes--tui

机器人/通知场景

hermes gateway setup hermes gateway run

运维/管理视角

hermes dashboard

11. 使用建议

• 想最快上手，用hermes。
• 想获得更强终端交互体验，用hermes --tui。
• 想做机器人或远程会话，用hermes gateway run。
• 想做配置管理和会话概览，用hermes dashboard。
• 想把 Hermes 接进编辑器，用hermes acp。