Hermes Agent 使用指南：从单兵作战到多智能体协同

本文档面向开发者，从最基础的单次对话讲起，逐步深入到多智能体协同、定时任务、跨平台部署等高级用法。所有示例均可直接运行。

目录

1. 安装与首次运行
2. 基础对话：和 Hermes 聊天
3. 工具系统：让 Agent 动手干活
4. Skills 技能系统：给 Agent 装配知识
5. 多智能体协同：子任务委派
6. 并行批处理：Batch Runner
7. 定时任务：Cron 调度
8. 代码沙箱：execute_code
9. 跨平台消息网关
10. Web Dashboard
11. IDE 集成：ACP 协议
12. 多 Profile 隔离
13. 实战案例集

1. 安装与首次运行

一键安装

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

支持 Linux、macOS、WSL2、Android (Termux)。安装后重启 shell：

source ~/.bashrc
hermes              # 启动交互式 CLI

从源码安装（开发者）

git clone --recurse-submodules https://github.com/NousResearch/hermes-agent.git
cd hermes-agent
 
uv venv .venv --python 3.11
source .venv/bin/activate
uv pip install -e ".[all,dev]"
 
# 配置
mkdir -p ~/.hermes/{cron,sessions,logs,memories,skills}
cp cli-config.yaml.example ~/.hermes/config.yaml
 
# 添加至少一个 LLM 提供商的 API Key
echo "OPENROUTER_API_KEY=sk-xxx" >> ~/.hermes/.env

初始化向导

hermes setup         # 交互式配置向导（推荐首次使用）
hermes model         # 选择 LLM 模型
hermes tools         # 配置启用的工具集
hermes doctor        # 诊断问题

2. 基础对话：和 Hermes 聊天

Hermes 的核心是一个对话循环：

用户消息 → 构建系统提示 → 调用 LLM
  ├── 如果 LLM 返回 tool_calls → 执行工具 → 把结果喂回 LLM → 继续循环
  └── 如果 LLM 返回文本 → 保存会话 → 返回给用户

CLI 模式

# 交互式聊天
hermes
 
# 单次提问（不进入交互模式）
hermes chat -q "用 Python 写一个快速排序"
 
# 指定模型
hermes chat -q "Hello" --model anthropic/claude-sonnet-4-6

常用 Slash 命令

在交互模式下，以 / 开头的命令控制会话：

TUI 模式（推荐）

hermes --tui       # 启动全功能终端 UI

TUI 提供：多行编辑、slash 命令自动补全、对话历史、工具执行实时流、session 管理。底层通过 stdio JSON-RPC 与 Python 后端通信。

3. 工具系统：让 Agent 动手干活

Hermes 不是只能聊天——它有 60+ 个内置工具，按 工具集（Toolset） 分组管理。

工具集概览

配置工具集

hermes tools                # 交互式配置
hermes config set terminal.toolsets "terminal,file,web,delegate"

在 config.yaml 中：

terminal:
  toolsets:
    - terminal
    - file
    - web
    - delegate
    - code_execution

工具是如何注册的

每个工具文件（tools/*.py）在模块加载时调用 registry.register() 自注册：

# tools/my_tool.py
from tools.registry import registry
 
def my_tool(param: str, task_id: str = None) -> str:
    return json.dumps({"result": "..."})
 
registry.register(
    name="my_tool",
    toolset="my_toolset",
    schema={...},
    handler=lambda args, **kw: my_tool(**args, **kw),
    check_fn=lambda: bool(os.getenv("MY_API_KEY")),
)

model_tools.py 自动发现所有 tools/*.py 中包含 registry.register() 调用的文件，无需手动维护导入列表。

4. Skills 技能系统：给 Agent 装配知识

Skills 是 Hermes 最独特的特性——一种程序化的操作记忆，本质上是一组 Markdown 指令 + 辅助脚本，让 Agent 在特定领域更专业。

Skills vs Tools 的区别

经验法则：如果能用现有工具 + 指令完成，做 Skill；如果需要新的 Python 集成，做 Tool。

使用内置 Skills

# 在对话中直接使用
hermes
> 帮我搜索 arXiv 上关于 transformer 的最新论文
# Agent 会自动加载 arxiv-search skill
 
# 手动加载
/skill_view arxiv-search

Skill 的结构

skills/
├── research/
│   └── arxiv/
│       ├── SKILL.md          # 主指令文件（必需）
│       └── scripts/          # 辅助脚本（可选）
│           └── search_arxiv.py
├── devops/
│   └── docker/
│       ├── SKILL.md
│       └── references/
└── ...

创建自定义 Skill

在 ~/.hermes/skills/ 下创建目录和 SKILL.md：

---
# ~/.hermes/skills/my-deploy/SKILL.md
name: my-deploy
description: 部署项目到生产服务器
version: 1.0.0
metadata:
  hermes:
    tags: [deploy, devops]
    requires_toolsets: [terminal]
---
 
# 项目部署
 
## 触发条件
用户要求部署项目时加载此技能。
 
## 步骤
1. 运行测试：`cd /path/to/project && pytest tests/ -q`
2. 构建镜像：`docker build -t myapp:latest .`
3. 推送镜像：`docker push myregistry/myapp:latest`
4. 滚动更新：`kubectl rollout restart deployment/myapp`
 
## 检查
- `kubectl rollout status deployment/myapp --timeout=120s`
- 访问健康检查端点确认服务正常

创建后立即可用，无需重启：

> 帮我部署项目到生产环境
# Agent 会自动发现并加载 my-deploy skill

条件激活

Skill 可以声明在什么条件下出现：

metadata:
  hermes:
    fallback_for_toolsets: [web]      # 仅当 web 工具集不可用时才显示
    requires_toolsets: [terminal]     # 仅当 terminal 工具集可用时才显示

平台限制

platforms: [macos, linux]   # 仅在这些平台加载

5. 多智能体协同：子任务委派

这是 Hermes 最强大的能力之一——主 Agent 可以生成子 Agent来并行处理独立任务。子 Agent 拥有独立的上下文窗口、独立的工具集，完成后只将摘要返回给父 Agent。

架构图

                    ┌──────────────┐
                    │   主 Agent    │
                    │  (用户对话)    │
                    └──────┬───────┘
                           │ delegate_task
              ┌────────────┼────────────┐
              ▼            ▼            ▼
        ┌──────────┐ ┌──────────┐ ┌──────────┐
        │ 子 Agent  │ │ 子 Agent  │ │ 子 Agent  │
        │ 任务 A    │ │ 任务 B    │ │ 任务 C    │
        │ (terminal │ │ (web)    │ │ (file)   │
        └──────────┘ └──────────┘ └──────────┘
              │            │            │
              └────────────┼────────────┘
                           │ 返回摘要
                    ┌──────▼───────┐
                    │   主 Agent    │
                    │  汇总结果     │
                    └──────────────┘

关键设计

例子 1：简单的子任务委派

> 帮我分析这个项目：先用 terminal 运行测试，同时用 web 搜索这个框架的最佳实践，
> 然后综合给我建议。

# Hermes 会调用 delegate_task 工具：
{
  "tasks": [
    {
      "goal": "运行项目测试并报告结果",
      "context": "项目在 /root/agent/myproject",
      "toolsets": ["terminal", "file"]
    },
    {
      "goal": "搜索 Next.js 15 的性能优化最佳实践",
      "toolsets": ["web"]
    }
  ]
}

两个子 Agent 同时运行。完成后父 Agent 收到各自的摘要，综合分析后回复用户。

例子 2：Orchestrator 模式

子 Agent 本身也可以是一个编排者，进一步委派任务：

> 重构这个项目：先分析代码结构，然后分别重构 backend 和 frontend，
> 最后运行全部测试确保没有回归。

# 第一层委派（orchestrator 角色）
delegate_task({
  "goal": "重构项目：分析 → 分别重构前后端 → 测试",
  "role": "orchestrator",
  "toolsets": ["terminal", "file", "delegate"]
})

# orchestrator 子 Agent 内部会进一步委派：
delegate_task({
  "tasks": [
    {"goal": "重构 backend/", "toolsets": ["terminal", "file"]},
    {"goal": "重构 frontend/", "toolsets": ["terminal", "file"]}
  ]
})

层级关系：

主 Agent (depth 0)
  └─ orchestrator 子 Agent (depth 1)
       ├─ leaf 子 Agent: 重构 backend (depth 2)
       └─ leaf 子 Agent: 重构 frontend (depth 2)

例子 3：限制子 Agent 的工具集

只给子 Agent 它需要的最小工具集，降低风险：

> 帮我在三个数据库上同时跑迁移脚本

delegate_task({
  "tasks": [
    {
      "goal": "在 prod-db-1 上运行 migrate.py",
      "context": "DB_HOST=prod-db-1.internal",
      "toolsets": ["terminal"],
      "role": "leaf"
    },
    {
      "goal": "在 prod-db-2 上运行 migrate.py",
      "context": "DB_HOST=prod-db-2.internal",
      "toolsets": ["terminal"],
      "role": "leaf"
    },
    {
      "goal": "在 prod-db-3 上运行 migrate.py",
      "context": "DB_HOST=prod-db-3.internal",
      "toolsets": ["terminal"],
      "role": "leaf"
    }
  ]
})

配置委派行为

在 config.yaml 中：

delegation:
  max_concurrent_children: 3        # 最大并行子 Agent 数
  max_spawn_depth: 2                # 最大嵌套深度（0-3）
  max_iterations: 50                # 子 Agent 最大迭代次数
  child_timeout_seconds: 600        # 子 Agent 超时时间
  model: "anthropic/claude-haiku-4-5"   # 子 Agent 使用的模型（可以用便宜的）
  provider: "openrouter"            # 子 Agent 的 provider

实用技巧：给子 Agent 配一个更便宜的模型（如 Haiku），主 Agent 用更强大的模型（如 Opus/Sonnet），只在关键决策上花大 token。

6. 并行批处理：Batch Runner

当需要对大量输入运行同一个 Agent 任务时（例如生成训练数据、批量处理文件），使用 Batch Runner。

基本用法

python batch_runner.py \
  --dataset prompts.jsonl \
  --output-dir ./batch-output \
  --num-workers 4 \
  --model anthropic/claude-sonnet-4-6

输入格式

prompts.jsonl（每行一个 JSON 对象）：

{"prompt": "用 Python 实现快速排序", "id": "001"}
{"prompt": "用 Rust 实现快速排序", "id": "002"}
{"prompt": "用 Go 实现快速排序", "id": "003"}

工具集分布

可以为每个 Agent 实例随机采样不同的工具集：

# datagen-config-examples/trajectory_compression.yaml
distribution:
  toolsets:
    - [terminal, file]
    - [terminal, file, web]
    - [terminal, file, web, code_execution]

输出

每个 batch 生成一个 batch_N.jsonl，包含每条 prompt 的完整轨迹（对话历史、工具调用、推理过程）。

断点续跑

python batch_runner.py \
  --dataset prompts.jsonl \
  --output-dir ./batch-output \
  --resume               # 从上次中断处继续

7. 定时任务：Cron 调度

Hermes 内置了完整的 cron 调度系统，可以用自然语言定义定时任务，Agent 按计划自动执行。

创建定时任务

> 每天早上 9 点检查服务器状态并报告给我

# Hermes 会调用 create_job：
create_job({
  "name": "每日服务器检查",
  "schedule": "0 9 * * *",
  "prompt": "检查服务器状态：CPU、内存、磁盘、运行中的服务，汇总成简短报告",
  "deliver": "telegram"
})

调度格式

多目标投递

{
  "deliver": "origin,telegram,discord:123456789"
}

结果同时发送到任务来源平台、Telegram 和指定 Discord 频道。

任务链

一个定时任务的输出可以作为下一个任务的输入：

{
  "name": "日报",
  "prompt": "基于昨天的监控数据，生成今日运维报告",
  "context_from": ["server-check-daily"]
}

预检脚本

在 Agent 执行前先跑一个轻量脚本，如果判断无需执行则跳过（节省 LLM 调用费用）：

{
  "name": "代码审查",
  "schedule": "0 9 * * 1-5",
  "script": "check_pending_prs.py",
  "prompt": "审查所有待处理的 Pull Request"
}

check_pending_prs.py 输出 {"wakeAgent": false} 时，Agent 不会启动。

通过 Web Dashboard 管理

启动 dashboard 后，在 /cron 页面可视化创建、编辑、暂停、手动触发定时任务。

8. 代码沙箱：execute_code

execute_code 工具让 Agent 在一个沙箱化的 Python 子进程中运行代码，且子进程可以通过 RPC 回调使用 Agent 的工具。

基本用法

在对话中直接要求：

> 帮我分析这个 CSV 文件，画出销售趋势图

# Agent 会调用 execute_code：
execute_code({
  "code": "
import pandas as pd
import matplotlib.pyplot as plt
from hermes_tools import read_file

data = pd.read_csv('sales.csv')
data.groupby('month')['revenue'].sum().plot()
plt.savefig('trend.png')
print(f'分析完成，共 {len(data)} 条记录')
"
})

沙箱中的工具访问

子进程通过 hermes_tools 模块访问 Agent 工具（限白名单）：

from hermes_tools import web_search, read_file, write_file, terminal, search_files
 
# 在沙箱中调用搜索
results = web_search("python asyncio best practices")
content = read_file("/path/to/file.py")
 
# 把处理结果写入文件
write_file("output.json", json.dumps(data))

白名单工具：web_search, web_extract, read_file, write_file, search_files, patch, terminal。

安全机制

远程沙箱

当 Agent 运行在 Docker/SSH/Modal/Daytona 环境时，代码在对应的环境中执行，通过文件系统 RPC 通信：

Agent (本地)  ──传输脚本──>  远程环境 (Docker/Modal)
     ↑                            │
     └───── RPC (文件系统) ────────┘

9. 跨平台消息网关

Hermes 不只是一个 CLI 工具。通过 Gateway，它同时接入多个聊天平台，所有平台共享同一个 Agent 核心。

架构图

                    ┌─────────────────┐
                    │  GatewayRunner   │
                    │  (Python 异步)    │
                    └────────┬────────┘
                             │
         ┌───────────┬───────┼───────┬───────────┐
         ▼           ▼       ▼       ▼           ▼
    ┌─────────┐ ┌────────┐ ┌─────┐ ┌───────┐ ┌─────────┐
    │Telegram │ │Discord │ │Slack│ │WhatsApp│ │ Signal  │
    │ Adapter │ │Adapter │ │ Adp │ │Adapter │ │ Adapter │
    └────┬────┘ └───┬────┘ └──┬──┘ └───┬───┘ └────┬────┘
         │          │         │        │          │
         └──────────┴────┬────┴────────┴──────────┘
                         │
                    ┌────▼────┐
                    │ AIAgent │ (每个会话一个实例)
                    │ + Tools │
                    └─────────┘

支持 20+ 个平台：Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Mattermost, Email, SMS, WeChat/企业微信, 飞书, 钉钉, QQ Bot, Webhook, API Server 等。

启动网关

hermes gateway setup      # 交互式配置各平台
hermes gateway start      # 启动网关（常驻进程）

多平台同时在线

配置好多个平台后，它们同时运行。一个 GatewayRunner 管理所有平台适配器，每个用户会话有独立的 AIAgent 实例。

会话隔离

不同平台的用户拥有独立会话。同一个 Telegram 用户在不同群组中也是独立会话。

消息中断与排队

当 Agent 正在处理一条消息时，新消息的处理策略：

用户发新消息 → Gateway 检测到 Agent 正忙
  ├── interrupt 模式（默认）：中断当前任务，处理新消息
  ├── queue 模式：排队等待当前任务完成后处理
  └── reject 模式：拒绝新消息

跨平台对话连续性

从 Telegram 开始的对话，可以在 CLI 中继续：

# 列出所有会话（跨平台）
hermes sessions
 
# 恢复某个会话
hermes chat --resume <session_id>

语音消息

Telegram 和 Discord 支持语音消息——Agent 会自动转录（使用 Edge TTS / Whisper），然后正常处理。

10. Web Dashboard

Hermes 提供一个本地 Web 管理界面，集成所有管理功能。

启动

hermes dashboard              # 启动在 http://localhost:8787
hermes dashboard --tui        # 同时启用嵌入式聊天终端
hermes dashboard --port 3000  # 自定义端口

功能页面

嵌入式聊天原理

Dashboard 的 /chat 页面不是一个独立的聊天实现。它通过 PTY bridge 嵌入真正的 hermes --tui：

浏览器 (xterm.js)
  │ WebSocket (/api/pty)
  ▼
FastAPI 后端
  │ PtyBridge.spawn()
  ▼
hermes --tui (子进程)
  │ stdio JSON-RPC
  ▼
tui_gateway → AIAgent

这意味着 TUI 的所有功能（slash 命令、自动补全、会话管理）在 Dashboard 中完全一致。

Dashboard 插件系统

Dashboard 支持自定义插件，可以：

• 添加新的侧边栏导航项
• 添加新的路由和 React 组件
• 覆盖内置页面
• 注入到命名插槽（header、sidebar、overlay 等）

11. IDE 集成：ACP 协议

Hermes 实现了 Agent Client Protocol (ACP)，可以在 VS Code、Zed、JetBrains 等 IDE 中直接使用。

启动 ACP 服务

hermes-acp         # 启动 ACP 服务器
# 或
hermes mcp serve    # 启动 MCP 服务器（另一种 IDE 集成方式）

功能

• 列出会话、读取消息历史
• 发送消息、等待回复
• 轮询实时事件
• 管理权限审批请求
• 列出频道

配置 Claude Code 集成

在 Claude Code 的 MCP 配置中添加：

{
  "mcpServers": {
    "hermes": {
      "command": "hermes",
      "args": ["mcp", "serve"]
    }
  }
}

这样 Claude Code 就可以直接读取 Hermes 的对话历史、发送消息到各平台。

12. 多 Profile 隔离

Hermes 支持多个完全隔离的实例（Profile），每个 Profile 有独立的配置、API Key、记忆、会话、技能。

使用场景

• 工作和个人使用不同的模型和配置
• 不同项目使用不同的工具集和技能
• 多人共享同一台服务器

创建和使用 Profile

hermes -p work setup          # 配置 work profile
hermes -p personal setup      # 配置 personal profile
 
hermes -p work                # 以 work profile 启动
hermes -p personal            # 以 personal profile 启动
hermes -p work gateway start  # 以 work profile 启动网关

目录结构

~/.hermes/                     # 默认 profile
  ├── config.yaml
  ├── .env
  ├── state.db
  ├── sessions/
  └── ...
~/.hermes/profiles/work/       # work profile
  ├── config.yaml
  ├── .env
  ├── state.db
  └── ...
~/.hermes/profiles/personal/   # personal profile
  ├── config.yaml
  └── ...

代码中的 Profile 安全

在代码中始终使用 get_hermes_home() 获取路径，不要硬编码 ~/.hermes：

# 正确
from hermes_constants import get_hermes_home, display_hermes_home
config_path = get_hermes_home() / "config.yaml"
 
# 错误 — 会破坏多 Profile
config_path = Path.home() / ".hermes" / "config.yaml"

13. 实战案例集

案例 1：自动化代码审查流水线

# 设置定时任务：每个工作日早上检查待审查的 PR
> 设置一个 cron 任务：每个工作日早上 10 点检查 GitHub 上的待审查 PR，
> 对每个 PR 进行代码审查，把结果发到 Discord 的 #code-review 频道

# Agent 会创建：
create_job({
  "name": "每日代码审查",
  "schedule": "0 10 * * 1-5",
  "prompt": "检查 GitHub 上所有待审查的 PR，对每个进行代码审查...",
  "deliver": "discord:CODE_REVIEW_CHANNEL_ID",
  "toolsets": ["terminal", "web"]
})

案例 2：多智能体并行研究

> 我需要为新产品做市场调研。同时调研三个方面：
> 1. 竞品分析（搜索 web）
> 2. 技术可行性（分析本地代码库）
> 3. 用户反馈（搜索社交媒体）
> 最后综合报告给我。

# Agent 会委派三个并行子任务：
delegate_task({
  "tasks": [
    {
      "goal": "竞品分析：搜索并分析市场上类似产品",
      "toolsets": ["web"],
      "role": "leaf"
    },
    {
      "goal": "技术可行性：分析 /path/to/project 的架构",
      "toolsets": ["terminal", "file"],
      "role": "leaf"
    },
    {
      "goal": "用户反馈：搜索社交媒体上的用户需求",
      "toolsets": ["web"],
      "role": "leaf"
    }
  ]
})

# 三个子 Agent 并行工作，父 Agent 汇总报告

案例 3：跨平台 DevOps 助手

# 配置
hermes gateway setup    # 配置 Telegram + Discord
hermes model            # 选择 Opus 用于复杂决策
 
# 在 Telegram 中
> 检查生产环境状态
# Agent 通过 terminal 工具 SSH 到服务器，检查状态
 
> 部署 v2.3.1 到生产环境
# Agent 使用 my-deploy skill 执行部署流程
 
# 在 CLI 中查看所有平台的会话历史
hermes sessions
hermes chat --resume <session_id>

案例 4：数据管道自动化

> 每天凌晨 3 点执行以下流程：
> 1. 从 API 拉取最新数据
> 2. 清洗和转换
> 3. 如果有异常数据，发送告警到 Telegram
> 4. 生成日报发到飞书

create_job({
  "name": "数据管道",
  "schedule": "0 3 * * *",
  "prompt": "执行数据管道：拉取 → 清洗 → 检查异常 → 生成报告",
  "deliver": "telegram,feishu",
  "script": "check_data_api.py",
  "workdir": "/data/pipeline"
})

案例 5：使用 Orchestrator 进行大规模重构

> 重构整个 monorepo：
> - 每个服务单独一个子任务
> - 每个子任务只修改自己服务的代码
> - 最后跑集成测试

# 第一层：编排者分析项目结构
delegate_task({
  "goal": "分析 monorepo 结构，为每个服务创建重构计划",
  "role": "orchestrator",
  "toolsets": ["terminal", "file", "delegate"],
  "context": "项目在 /app/monorepo，包含 5 个微服务"
})

# 编排者会进一步委派：
delegate_task({
  "tasks": [
    {"goal": "重构 auth-service", "toolsets": ["terminal", "file"], "role": "leaf"},
    {"goal": "重构 user-service", "toolsets": ["terminal", "file"], "role": "leaf"},
    {"goal": "重构 order-service", "toolsets": ["terminal", "file"], "role": "leaf"},
    {"goal": "重构 payment-service", "toolsets": ["terminal", "file"], "role": "leaf"},
    {"goal": "重构 notification-service", "toolsets": ["terminal", "file"], "role": "leaf"}
  ]
})

附录

常用命令速查

hermes                          # 交互式聊天
hermes --tui                    # 终端 UI 模式
hermes chat -q "问题"           # 单次提问
hermes model                    # 切换模型
hermes tools                    # 配置工具
hermes setup                    # 设置向导
hermes gateway start            # 启动消息网关
hermes dashboard                # 启动 Web 控制台
hermes doctor                   # 诊断问题
hermes logs --follow            # 实时查看日志
hermes update                   # 自更新
hermes version                  # 查看版本

支持的 LLM 提供商

通过 hermes model 切换，无需改代码：

• OpenRouter（200+ 模型）
• OpenAI
• Anthropic (Claude)
• Google Gemini
• AWS Bedrock
• Mistral
• Ollama（本地模型）
• z.ai / GLM（智谱）
• Kimi / Moonshot
• MiniMax
• Hugging Face
• NVIDIA NIM
• Xiaomi MiMo
• 任何 OpenAI 兼容端点

配置文件位置

运行环境

Hermes 支持 6 种终端后端：