# Hermes Agent 多 Agent 实战：创建、部署与配置完整指南
Hermes Agent 是 Nous Research 开源的 AI Agent 框架，与 Claude Code（Anthropic）、Codex（OpenAI）属于同一类别——通过工具调用与系统交互的自主编码与任务执行 Agent。它支持任何 LLM Provider（OpenRouter、Anthropic、OpenAI、DeepSeek、本地模型等 20+ Provider），运行于 Linux、macOS 和 WSL。
**官方文档：** https://hermes-agent.nousresearch.com/docs/
—
## 一、整体架构与核心概念
Hermes Agent 的多 Agent 系统建立在以下几个核心概念之上：
### 1.1 Profile（配置文件）
Profile 是独立的 Hermes 主目录。每个 Profile 拥有自己的 config.yaml、.env、SOUL.md、会话、记忆、技能和状态数据库。通过 Profile，你可以在同一台机器上运行多个独立 Agent——例如一个代码助手、一个个人 Bot、一个研究 Agent——互不干扰。
“`bash
hermes profile create coder # 创建 Profile
coder setup # 配置 API Keys
coder chat # 开始对话
“`
Profile 数据目录结构：
“`
~/.hermes/profiles/
├── config.yaml # 主配置
├── .env # API Keys 和 Bot Tokens
├── SOUL.md # Agent 人格与指令
├── sessions/ # 会话历史
├── memories/ # 持久化记忆存储
├── skills/ # 已安装技能
├── cron/ # 定时任务定义
└── logs/ # 运行日志
“`
### 1.2 Subagent（子 Agent）
通过 delegate_task 工具，主 Agent 可以生成独立的子 Agent 实例。每个子 Agent 拥有：
– **隔离的上下文**：独立的对话历史和终端会话
– **受限的工具集**：仅能使用分配的工具
– **独立的 LLM 推理循环**：完整的思维链推理能力
– **仅返回摘要**：中间工具调用不会进入主 Agent 上下文
### 1.3 Orchestrator（编排器）
默认情况下，子 Agent 是 **leaf（叶子）** 类型，无法继续委托。设置为 **orchestrator（编排器）** 类型的子 Agent 可以继续生成自己的 Worker，形成多层树状结构。
—
## 二、安装与基础配置
### 2.1 一键安装（Linux / macOS / WSL2）
“`bash
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
“`
安装程序自动处理所有依赖项：uv（快速 Python 包管理器）、Python 3.11、Node.js v22、ripgrep、ffmpeg。
### 2.2 安装后配置
“`bash
source ~/.bashrc # 或 source ~/.zshrc
hermes # 开始聊天！
“`
常用配置命令：
“`bash
hermes model # 选择 LLM Provider 和模型
hermes tools # 配置启用的工具集
hermes gateway setup # 设置消息平台（Telegram、Discord 等）
hermes config set # 设置单个配置值
hermes setup # 运行完整配置向导
“`
### 2.3 支持的 Provider（20+）
| Provider | 认证方式 | 密钥环境变量 |
|—|—|—|
| OpenRouter | API Key | OPENROUTER_API_KEY |
| Anthropic | API Key | ANTHROPIC_API_KEY |
| DeepSeek | API Key | DEEPSEEK_API_KEY |
| Google Gemini | API Key | GOOGLE_API_KEY |
| xAI / Grok | API Key | XAI_API_KEY |
| Hugging Face | Token | HF_TOKEN |
| MiniMax | API Key | MINIMAX_API_KEY |
| Nous Portal | OAuth | hermes auth |
| OpenAI Codex | OAuth | hermes auth |
—
## 三、创建 Agent
### 3.1 创建 Profile（独立 Agent）
“`bash
# 空白 Profile（仅绑定技能）
hermes profile create mybot
# 克隆当前配置（相同 API Keys，但全新会话和记忆）
hermes profile create work –clone
# 克隆全部（完整快照，包含所有记忆和会话）
hermes profile create backup –clone-all
# 从指定 Profile 克隆
hermes profile create work –clone –clone-from coder
“`
### 3.2 Profile 命令别名
创建 Profile 后，自动获得命令别名：
“`bash
coder chat # 与 coder Agent 对话
coder setup # 配置 coder 的设置
coder gateway start # 启动 coder 的 Gateway
coder doctor # 检查 coder 的健康状态
coder skills list # 列出 coder 的技能
coder config set model.default anthropic/claude-sonnet-4
“`
### 3.3 使用 -p 标志显式指定 Profile
“`bash
hermes -p coder chat
hermes –profile=coder doctor
hermes chat -p coder -q “hello” # 任意位置均可
“`
### 3.4 设置默认 Profile
“`bash
hermes profile use coder # 设置默认
hermes chat # 现在默认针对 coder
hermes profile use default # 切回默认
“`
—
## 四、启动与运行
### 4.1 交互式 CLI 聊天
“`bash
hermes
“`
### 4.2 单次查询（非交互式）
“`bash
hermes chat -q “解释 Docker 的多阶段构建”
“`
### 4.3 使用 Session 恢复对话
“`bash
hermes –resume
hermes –continue # 恢复最近会话
“`
### 4.4 启动 Gateway（后台服务模式）
Gateway 支持 15+ 消息平台：Telegram、Discord、Slack、WhatsApp、Signal、Email、SMS、Matrix、Home Assistant 等。
“`bash
# 前台运行
hermes gateway run
# 安装为后台服务
hermes gateway install
# 控制服务
hermes gateway start
hermes gateway stop
hermes gateway restart
hermes gateway status
“`
### 4.5 Profile + Gateway 多实例
推荐模式：**一个容器（或进程）对应一个 Profile**，每个 Profile 运行独立的 Gateway：
“`bash
hermes-work gateway start # 工作 Profile
assistant gateway start # 助手 Profile
“`
—
## 五、生产环境部署
### 5.1 Docker 单容器部署
“`bash
# 创建数据目录
mkdir -p ~/.hermes
# 交互式设置（首次）
docker run -it –rm -v ~/.hermes:/opt/data nousresearch/hermes-agent setup
# 后台运行 Gateway
docker run -d –name hermes –restart unless-stopped -v ~/.hermes:/opt/data -p 8642:8642 nousresearch/hermes-agent gateway run
“`
### 5.2 Docker Compose 多 Profile 部署
**推荐方案：一个容器对应一个 Profile，完全隔离。**
“`yaml
services:
hermes-work:
image: nousresearch/hermes-agent:latest
container_name: hermes-work
restart: unless-stopped
volumes:
– ~/.hermes-work:/opt/data
ports:
– “8643:8642”
hermes-personal:
image: nousresearch/hermes-agent:latest
container_name: hermes-personal
restart: unless-stopped
volumes:
– ~/.hermes-personal:/opt/data
ports:
– “8644:8642”
“`
启动：docker compose up -d，查看日志：docker compose logs -f
### 5.3 资源限制
“`bash
docker run -d –name hermes –restart unless-stopped –memory=4g –cpus=2 –shm-size=1g -v ~/.hermes:/opt/data nousresearch/hermes-agent gateway run
“`
| 资源 | 最小 | 推荐 |
|—|—|—|
| 内存 | 1 GB | 2–4 GB |
| CPU | 1 核 | 2 核 |
| 磁盘 | 500 MB | 2+ GB |
### 5.4 升级
“`bash
docker pull nousresearch/hermes-agent:latest
docker rm -f hermes
docker run -d –name hermes –restart unless-stopped -v ~/.hermes:/opt/data nousresearch/hermes-agent gateway run
“`
—
## 六、核心配置参数详解
### 6.1 config.yaml 关键配置
“`yaml
# ~/.hermes/config.yaml
model:
default: anthropic/claude-sonnet-4
provider: openrouter
agent:
max_turns: 90
tool_use_enforcement: true
terminal:
backend: local
cwd: /path/to/project
delegation:
max_iterations: 50
max_concurrent_children: 3
max_spawn_depth: 1
child_timeout_seconds: 600
model: google/gemini-flash-2.0
provider: openrouter
memory:
memory_enabled: true
user_profile_enabled: true
display:
skin: default
tool_progress: true
show_reasoning: medium
“`
### 6.2 delegation 配置详解
| 参数 | 默认值 | 说明 |
|—|—|—|
| max_iterations | 50 | 每个子 Agent 的最大工具调用轮次 |
| max_concurrent_children | 3 | 并行子 Agent 数量（>=1，无硬上限） |
| max_spawn_depth | 1 | 委托层级深度（1=扁平，2=可嵌套编排器） |
| child_timeout_seconds | 600 | 子 Agent 静默超时（10分钟） |
| model | 继承父级 | 子 Agent 使用的模型（可设更便宜的模型） |
| provider | 继承父级 | 子 Agent 使用的 Provider |
| orchestrator_enabled | true | 是否允许 Orchestrator 子 Agent |
—
## 七、实战案例：GitHub PR 自动审查 Agent
这是一个完整的多 Agent 实战案例：自动监控 GitHub 仓库、审查 PR、发送通知。
### 7.1 架构图
“`
┌───────────────────────────────────────────────────────────────────┐
│ │
│ Cron Timer ──▶ Hermes Agent ──▶ GitHub API ──▶ Review │
│ (every 2h) + gh CLI (PR diffs) delivery │
│ + skill (Telegram, │
│ + memory Discord, │
│ local) │
│ │
└───────────────────────────────────────────────────────────────────┘
“`
### 7.2 前提条件
“`bash
# 安装 GitHub CLI
brew install gh # macOS
sudo apt install gh # Ubuntu/Debian
# 认证
gh auth login
“`
### 7.3 创建审查技能
“`bash
mkdir -p ~/.hermes/skills/code-review
“`
创建 ~/.hermes/skills/code-review/SKILL.md：
“`markdown
—
name: code-review
description: Review pull requests for bugs, security issues, and code quality
—
# Code Review Skill
## Review Guidelines
Review every PR against these criteria：
1. **Correctness** — Does the code do what it claims?
2. **Security** — SQL injection, XSS, authentication bypass?
3. **Edge Cases** — Null checks, empty inputs, boundary conditions?
4. **Performance** — N+1 queries, unnecessary allocations?
5. **Testing** — Are there tests? Do they cover the happy path AND failure cases?
## Output Format
Provide a structured review:
– **Severity**: Critical / High / Medium / Low
– **File & Line**: Specific location
– **Issue**: What the problem is
– **Suggestion**: How to fix it
## Review Process
1. Run gh pr diff PR_NUMBER –repo REPO to fetch the diff
2. Read through all changed files
3. Check for the issues listed above
4. Return structured findings with specific line numbers
“`
### 7.4 创建定时 Cron 任务
“`bash
hermes cron create “0 */2 * * *” “Check for new open PRs and review them.
Repos to monitor:
– myorg/backend-api
– myorg/frontend-app
Steps:
1. Run: gh pr list –repo REPO –state open –limit 5 –json number,title,author,createdAt
2. For each new PR, run: gh pr diff NUMBER –repo REPO
3. Review each diff using the code-review skill guidelines
4. Deliver findings via configured channel” –name pr-review
“`
### 7.5 其他常用调度策略
| 调度表达式 | 说明 |
|—|—|
| 0 */2 * * * | 每 2 小时 |
| 0 9,13,17 * * 1-5 | 工作日每天 9点、13点、17点 |
| 0 9 * * 1 | 每周一早上汇总 |
| 30m | 每 30 分钟（高频仓库） |
### 7.6 手动触发
“`bash
hermes cron run pr-review
“`
—
## 八、监控与运维
### 8.1 查看运行中的子 Agent（/agents）
“`bash
hermes /agents
“`
TUI 提供实时树状视图，显示：
– 正在运行和已完成的子 Agent
– 每个分支的成本、Token 消耗、文件修改统计
– 终止和暂停控制
– 每个子 Agent 的逐轮历史
### 8.2 日志查看
“`bash
docker logs –tail 50 hermes
docker stats hermes
“`
### 8.3 健康检查
“`bash
hermes gateway status
hermes doctor
“`
### 8.4 Session 管理
“`bash
hermes sessions list
hermes sessions prune –older-than 30 days
hermes sessions stats
“`
—
## 九、最佳实践
### 9.1 何时使用 delegate_task vs execute_code
| 因素 | delegate_task | execute_code |
|—|—|—|
| 推理能力 | 完整 LLM 推理循环 | 仅 Python 代码执行 |
| 上下文 | 全新隔离对话 | 无对话，仅脚本 |
| 工具访问 | 所有非阻塞工具 + 推理 | 7 个工具（via RPC），无推理 |
| 并行性 | 默认 3 个并行子 Agent | 单脚本 |
| 适用场景 | 需要判断力的复杂任务 | 机械性数据处理 |
| Token 成本 | 较高（完整 LLM 循环） | 较低（仅返回 stdout）|
**经验法则**：子任务需要推理、判断或多步问题解决时使用 delegate_task；需要机械性数据处理或脚本化工作流时使用 execute_code。
### 9.2 工具集选择
| 工具集模式 | 适用场景 |
|—|—|
| [terminal, file] | 代码工作、调试、文件编辑、构建 |
| [web] | 研究、事实核查、文档查找 |
| [terminal, file, web] | 全栈任务（默认） |
| [file] | 只读分析，无需执行 |
| [terminal] | 系统管理、进程管理 |
### 9.3 子 Agent 上下文传递黄金法则
❌ 错误 — 子 Agent 完全不知道上下文：
“`
delegate_task(goal=”Fix the error”)
“`
✅ 正确 — 传递所有必要信息：
“`
delegate_task(
goal=”Fix the TypeError in api/handlers.py”,
context=(
“Project at /home/user/webapp. ”
“Auth module files: src/auth/login.py, src/auth/jwt.py. ”
“Error: TypeError: process_request() receives None. ”
“Focus on: SQL injection, JWT validation, password handling”
)
)
“`
### 9.4 避免并发写入
同一时间**不要**让两个 Gateway 容器（或进程）操作同一个 Profile 数据目录。Session 文件和记忆存储不支持并发写入。
### 9.5 深度层级与成本
设置 max_spawn_depth: 3 且 max_concurrent_children: 3 时，树状结构最多达到 3×3×3 = **27 个并发叶子 Agent**。每增加一层都会成倍增加开销，谨慎提升 max_spawn_depth。
—
**参考资料：**
– 官方文档：https://hermes-agent.nousresearch.com/docs/
– GitHub 仓库：https://github.com/NousResearch/hermes-agent
