Hermes Agent 入门：安装、配置与第一个工作流

TL;DR: 本教程将带你从零开始安装 Hermes Agent，掌握核心 CLI 命令，并构建你的第一个多角色 AI 工作流。你将学会如何配置 Hermes Bridge API、编写 YAML 工作流文件，并理解 Agent 协作的基本模式。全程包含可复现的终端命令和配置文件示例。

🎯 学习目标

完成本教程后，你将能够：

在 macOS/Linux 上安装并配置 Hermes Agent v0.8+
理解 Hermes Agent 的架构：Bridge API、Skill、Workflow
运行 5 个核心 CLI 命令：init, run, status, log, skill
创建第一个多角色工作流：代码审查 + 文档生成
诊断常见的安装和配置错误

📦 环境准备

系统要求

组件	最低版本	推荐版本
Python	3.10	3.12.3
Node.js	18.x	20.11.0
Docker	24.x	26.1.0
磁盘空间	2 GB	5 GB

注意：Hermes Agent 依赖 Docker 运行隔离的 Agent 容器。如果你使用 Colima 替代 Docker Desktop，请确保 Colima 版本 ≥ 0.7.0。

安装 Hermes Agent

# 使用官方安装脚本（推荐）
curl -sSL https://install.hermes-agent.dev | bash

# 验证安装
hermes --version
# 输出示例：Hermes Agent v0.8.3 (build 2026-06-10)

如果安装失败，检查 ~/.local/bin 是否在 $PATH 中：

export PATH="$HOME/.local/bin:$PATH"
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc

验证核心依赖

# 检查 Docker 运行状态
docker info | grep "Server Version"
# 输出：Server Version: 26.1.0

# 检查 Python 版本
python3 --version
# 输出：Python 3.12.3

🔧 配置 Hermes Agent

初始化配置文件

hermes init --provider openai

这会生成 ~/.hermes/config.yaml。我们打开并修改它：

# ~/.hermes/config.yaml
# Hermes Agent 全局配置

provider:
  name: openai
  model: gpt-4o-mini  # 成本优化选择，适合入门
  api_key: ${HERMES_OPENAI_API_KEY}  # 从环境变量读取

bridge:
  enabled: true
  port: 8080
  # Hermes Bridge API 允许外部工具监控 Agent 行为
  # 最新更新：v0.8.3 支持 Spanly 集成

workspace:
  dir: ~/hermes-workspace
  max_iterations: 50  # 单个 Agent 最大思考步数
  timeout: 300        # 工作流超时时间（秒）

logging:
  level: info
  file: ~/.hermes/logs/agent.log

为什么使用环境变量？ 避免在配置文件中硬编码 API Key。设置方式：

export HERMES_OPENAI_API_KEY="sk-your-key-here"
echo 'export HERMES_OPENAI_API_KEY="sk-your-key-here"' >> ~/.zshrc

验证配置

hermes status
# 输出示例：
# ✅ Provider: OpenAI (gpt-4o-mini)
# ✅ Bridge: Running on port 8080
# ✅ Docker: Available
# ⚠️  Workspace: /Users/you/hermes-workspace (not exists)

看到 workspace 警告是正常的，首次运行时会自动创建。

🚀 核心 CLI 命令实战

1. `hermes init` — 初始化项目

mkdir ~/hermes-demo && cd ~/hermes-demo
hermes init --template basic

这会创建以下结构：

hermes-demo/
├── workflow.yaml       # 工作流定义文件
├── skills/            # 自定义技能目录
│   └── hello.py       # 示例技能
└── .hermes.yaml       # 项目级配置（覆盖全局配置）

2. `hermes run` — 执行工作流

hermes run workflow.yaml

首次运行会下载基础镜像（约 500MB），后续执行只需 2-3 秒。

3. `hermes status` — 查看运行状态

hermes status --watch
# 实时显示 Agent 状态：
# ┌──────────┬──────────┬──────────┐
# │ Agent    │ Status   │ Progress │
# ├──────────┼──────────┼──────────┤
# │ reviewer │ running  │ 45%      │
# │ writer   │ waiting  │ 0%       │
# └──────────┴──────────┴──────────┘

4. `hermes log` — 调试工作流

hermes log --tail 50
# 显示最近 50 行日志，包含每个 Agent 的思考过程

5. `hermes skill` — 管理技能

# 列出可用技能
hermes skill list
# 输出：
# ┌──────────────┬──────────────────────────────┐
# │ Skill Name   │ Description                  │
# ├──────────────┼──────────────────────────────┤
# │ code-review  │ 静态代码分析与审查            │
# │ doc-gen      │ 生成 Markdown 文档            │
# │ slide-maker  │ 生成 HTML 幻灯片（最新）      │
# └──────────────┴──────────────────────────────┘

# 安装社区技能
hermes skill install spanly-mcp
# Spanly 集成：实时可视化 Agent 在 MCP Server 内的操作

🧩 第一个多角色工作流

我们将构建一个 代码审查 + 文档生成 的工作流，演示两个 Agent 如何协作。

工作流文件：`workflow.yaml`

# workflow.yaml
# 多角色工作流：Code Reviewer → Technical Writer

version: "1.0"
name: "Code Review Pipeline"

agents:
  - name: reviewer
    role: "Senior Code Reviewer"
    model: gpt-4o-mini
    skills:
      - code-review
    instructions: |
      你是一位资深代码审查专家。
      审查用户提供的代码文件，输出：
      1. 代码质量评分（1-10）
      2. 发现的 3 个主要问题
      3. 改进建议（含代码示例）
      使用 Markdown 格式输出。

  - name: writer
    role: "Technical Writer"
    model: gpt-4o-mini
    skills:
      - doc-gen
    instructions: |
      你是一位技术文档专家。
      基于 reviewer 的输出，生成：
      1. 代码文档（函数说明、参数、返回值）
      2. 使用示例
      3. 常见错误处理
      输出为规范的 Markdown 文档。

workflow:
  steps:
    - agent: reviewer
      input:
        file: "src/calculator.py"  # 要审查的代码文件
      output: review_result

    - agent: writer
      input:
        review: ${review_result}  # 引用上一步输出
      output: documentation

  artifacts:
    - name: code_review.md
      source: ${review_result}
    - name: documentation.md
      source: ${documentation}

准备被审查的代码：`src/calculator.py`

# src/calculator.py
# 一个简单的计算器，包含一些常见问题

def divide(a, b):
    if b != 0:
        return a / b
    # 问题1：没有返回错误信息，调用者无法区分除零和其他错误
    
def add(a, b):
    result = a + b
    # 问题2：没有类型检查，传入字符串会崩溃
    return result

def complex_calc(x):
    # 问题3：未使用的变量
    unused_var = 42
    return x ** 2 + 3 * x + 1

执行工作流

hermes run workflow.yaml

预期输出

步骤 1：Reviewer 输出（部分）

## 代码审查报告

### 总体评分：5/10

### 主要问题

1. **除零错误处理不完整**（严重性：高）
   - 函数 `divide()` 在 `b == 0` 时返回 `None`
   - 建议：抛出 `ValueError`
   ```python
   def divide(a, b):
       if b == 0:
           raise ValueError("除数不能为零")
       return a / b

缺少类型注解（严重性：中）
- 所有函数缺少类型提示
- 建议：添加类型注解
```
def add(a: float, b: float) -> float:
```
未使用的变量（严重性：低）
- complex_calc() 中的 unused_var
- 建议：删除或使用 _ 前缀


**步骤 2：Writer 输出（部分）**

```markdown
# Calculator 模块文档

## 函数参考

### `divide(a, b)`
- **参数**: `a` (float) - 被除数, `b` (float) - 除数
- **返回值**: float - 商
- **异常**: `ValueError` - 当 b 为 0 时
- **示例**: `divide(10, 2)` → `5.0`

### `add(a, b)`
- **参数**: `a` (float), `b` (float)
- **返回值**: float - 和
- **注意**: 当前版本未做类型检查，传入字符串会抛出 `TypeError`

⚠️ 常见陷阱与解决方案

陷阱 1：API Key 未设置

错误信息：

Error: OpenAI API key not found. Set HERMES_OPENAI_API_KEY environment variable.

解决方案：

# 检查是否设置
echo $HERMES_OPENAI_API_KEY

# 如果为空，重新设置
export HERMES_OPENAI_API_KEY="sk-..."

陷阱 2：Docker 权限不足

错误信息：

Permission denied while trying to connect to the Docker daemon socket

解决方案：

# 将当前用户加入 docker 组
sudo usermod -aG docker $USER
newgrp docker  # 立即生效

陷阱 3：工作流超时

症状：工作流在 max_iterations 步后停止，输出不完整。

解决方案：

# 在 workflow.yaml 中增加迭代限制
agents:
  - name: reviewer
    max_iterations: 100  # 默认为 50

🔍 使用 Hermes Bridge API 监控

Hermes Agent v0.8 引入的 Bridge API 允许外部工具实时查看 Agent 内部状态。

启动监控

# 启动 Bridge 服务（默认在后台运行）
hermes bridge start

# 使用 curl 查看当前工作流状态
curl http://localhost:8080/api/v1/workflows/active

集成 Spanly

# 安装 Spanly MCP 技能
hermes skill install spanly-mcp

# 启动 Spanly 可视化界面
hermes spanly start --port 3000

现在打开 http://localhost:3000，你会看到 Agent 的思考过程、工具调用和状态转换的实时可视化。

📚 关键要点

配置优先：正确设置 ~/.hermes/config.yaml 和 API Key 是成功的第一步
工作流是核心：YAML 定义 Agent 角色、技能和协作顺序
技能复用：code-review 和 doc-gen 是内置技能，可直接使用
调试三件套：status（状态）、log（日志）、bridge（API）
安全第一：始终使用环境变量管理 API Key，不要硬编码

❓ 常见问题

Q: Hermes Agent 和 AutoGPT 有什么区别？ A: Hermes Agent 专注于多角色工作流编排，每个 Agent 有明确定义的角色和职责，通过 YAML 配置协作逻辑。AutoGPT 更偏向单一 Agent 的自主任务分解。

Q: 可以在 Windows 上运行吗？ A: 官方支持 macOS 和 Linux。Windows 用户建议使用 WSL2（Ubuntu 22.04+），并确保 Docker Desktop 配置为 WSL2 后端。

Q: 工作流执行失败，如何重试？ A: 使用 hermes run workflow.yaml --resume 从失败步骤继续执行，避免重复计算。

Q: 如何自定义技能？ A: 在 skills/ 目录下创建 Python 文件，实现 execute(context) 函数。我们将在本系列 Part 3 中详细讲解。

Q: Hermes Bridge API 是否必须开启？ A: 不是。Bridge 主要用于调试和监控，生产环境可以关闭以节省资源。在配置文件中设置 bridge.enabled: false。

🔮 下期预告

在 Part 2 中，我们将深入 Hermes Agent 工作流引擎，学习：

条件分支（if/else）和并行执行
自定义技能开发（Python SDK）
与 MCP Server 集成（数据库查询、文件操作）
性能调优：减少 Token 消耗 40% 的技巧

行动建议：现在就用本文的示例代码运行你的第一个工作流，在评论区分享你的输出截图。遇到问题？在 Hermes Agent Discord 的 #beginner-help 频道提问。

本文基于 Hermes Agent v0.8.3。查看官方文档获取最新 API 参考。

Have questions? Join our Discord community or follow us on X.

Hermes Deep Dive — Complete Developer Guide

Hermes Agent 入门：安装、配置与第一个工作流

🎯 学习目标

📦 环境准备

系统要求

安装 Hermes Agent

验证核心依赖

🔧 配置 Hermes Agent

初始化配置文件

验证配置

🚀 核心 CLI 命令实战

1. hermes init — 初始化项目

2. hermes run — 执行工作流

3. hermes status — 查看运行状态

4. hermes log — 调试工作流

5. hermes skill — 管理技能

🧩 第一个多角色工作流

工作流文件：workflow.yaml

准备被审查的代码：src/calculator.py

执行工作流

预期输出

⚠️ 常见陷阱与解决方案

陷阱 1：API Key 未设置

陷阱 2：Docker 权限不足

陷阱 3：工作流超时

🔍 使用 Hermes Bridge API 监控

启动监控

集成 Spanly

📚 关键要点

❓ 常见问题

🔮 下期预告

1. `hermes init` — 初始化项目

2. `hermes run` — 执行工作流

3. `hermes status` — 查看运行状态

4. `hermes log` — 调试工作流

5. `hermes skill` — 管理技能

工作流文件：`workflow.yaml`

准备被审查的代码：`src/calculator.py`