第 5 章

快速上手：10分钟运行第一个 Hermes Agent

第五章：快速上手：10分钟运行第一个 Hermes Agent

章节导语

理论已经足够充分，是时候动手了。本章是一份精确的操作手册：从环境检查、安装、首次配置，到运行你的第一个真实任务，全程预计耗时10分钟。我们会提供 macOS、Linux 和 WSL2（Windows）三个平台的完整命令序列，以及一份详尽的故障排查指南。本章末尾有一份"安装成功验证检查单"，帮你确认一切就绪。

5.1 环境要求

在开始安装之前，请确认你的环境满足以下要求：

硬件要求

组件	最低配置	推荐配置
CPU	双核 2GHz	四核 3GHz+
内存	4GB RAM	8GB+ RAM
磁盘	2GB 可用空间	10GB+（用于本地模型）
网络	稳定互联网连接	低延迟连接（使用云端 API 时）

本地模型用户注意：如果你计划使用本地 Hermes 模型而非云端 API，硬件要求会显著更高：

Hermes 3 8B：需要 8GB+ VRAM（GPU）或 16GB+ RAM（CPU 推理）

Hermes 4 70B：需要 40GB+ VRAM 或 80GB+ RAM

软件依赖

# 检查 Python 版本（需要 3.9+）
python3 --version
# 应输出：Python 3.9.x 或更高版本

# 检查 pip
pip3 --version

# 检查 Git
git --version

5.2 macOS 安装（推荐方式）

步骤一：安装 Homebrew（如未安装）

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

步骤二：安装 Python 3.11

brew install [email protected]

# 验证
python3.11 --version
# 应输出：Python 3.11.x

步骤三：创建虚拟环境（强烈推荐）

# 创建项目目录
mkdir ~/hermes-workspace && cd ~/hermes-workspace

# 创建虚拟环境
python3.11 -m venv hermes-env

# 激活虚拟环境
source hermes-env/bin/activate

# 提示符应变为 (hermes-env) $

步骤四：安装 Hermes Agent

# 安装最新版本
pip install hermes-agent

# 安装特定版本（如需要）
pip install hermes-agent==0.8.2

# 验证安装
hermes --version
# 应输出：hermes-agent 0.8.x

步骤五：初始化配置

# 运行配置向导
hermes init

# 向导会依次询问：
# 1. 选择默认 LLM 提供商（OpenAI/Anthropic/NousResearch/Ollama）
# 2. 输入 API Key
# 3. 选择默认工具集
# 4. 配置数据存储路径（Skill 库等）

配置向导示例输出：

Hermes Agent 初始化向导
========================

请选择默认 LLM 提供商：
1. NousResearch（Hermes 4）[推荐]
2. OpenAI（GPT-4）
3. Anthropic（Claude）
4. Ollama（本地模型）

你的选择 [1]: 1

请输入 NousResearch API Key：
（在 https://api.nousresearch.com 注册获取）
API Key: nous-xxxxxxxxxxxxxxxx

✓ API Key 验证成功

配置数据存储路径（默认：~/.hermes）：
[按回车使用默认路径]

✓ 初始化完成！配置已保存到 ~/.hermes/config.yaml

运行 'hermes chat' 开始使用，或 'hermes run "你的任务"' 执行任务

5.3 Linux 安装

Ubuntu / Debian

# 更新包管理器
sudo apt-get update

# 安装 Python 3.11 和相关工具
sudo apt-get install -y python3.11 python3.11-venv python3.11-dev pip3

# 创建并激活虚拟环境
mkdir ~/hermes-workspace && cd ~/hermes-workspace
python3.11 -m venv hermes-env
source hermes-env/bin/activate

# 安装 Hermes
pip install hermes-agent

# 初始化
hermes init

CentOS / RHEL / Fedora

# Fedora
sudo dnf install python3.11 python3.11-devel

# CentOS/RHEL 需要 EPEL
sudo yum install epel-release
sudo yum install python3.11

# 后续步骤与 Ubuntu 相同
python3.11 -m venv ~/hermes-workspace/hermes-env
source ~/hermes-workspace/hermes-env/bin/activate
pip install hermes-agent
hermes init

使用 pipx（隔离安装，推荐系统级使用）

# 安装 pipx
pip install pipx
pipx ensurepath

# 使用 pipx 安装 Hermes（隔离环境，无需手动管理 venv）
pipx install hermes-agent

# 直接使用，无需激活环境
hermes --version

5.4 WSL2（Windows 子系统 for Linux）安装

前提：安装 WSL2

# 在 Windows PowerShell（管理员）中执行
wsl --install

# 重启后，默认安装 Ubuntu
# 打开 Ubuntu 终端

在 WSL2 中安装

# 更新 Ubuntu
sudo apt-get update && sudo apt-get upgrade -y

# 安装 Python 3.11
sudo apt-get install -y python3.11 python3.11-venv python3.11-dev

# 创建工作目录（在 Linux 文件系统中，非 /mnt/c/）
mkdir ~/hermes-workspace && cd ~/hermes-workspace

# 创建虚拟环境
python3.11 -m venv hermes-env
source hermes-env/bin/activate

# 安装
pip install hermes-agent

# 初始化
hermes init

WSL2 性能注意：将项目文件放在 WSL2 的 Linux 文件系统（~/）而非 Windows 挂载目录（/mnt/c/）下，可获得显著更好的文件 I/O 性能。

5.5 首次配置详解

配置文件结构

Hermes 的配置存储在 ~/.hermes/config.yaml：

# ~/.hermes/config.yaml
version: "1.0"

# LLM 模型配置
model:
  provider: "nousresearch"        # 提供商
  name: "hermes-4"                # 模型名称
  api_key: "nous-xxxxxxxxxxxx"    # API Key（建议用环境变量）
  temperature: 0.1                # 低温度，结果更稳定
  max_tokens: 4096                # 每次 LLM 调用的最大 token

# 工具配置
tools:
  enabled: "all"                  # 启用所有工具
  sandbox_code_execution: true    # 沙箱执行代码
  allowed_file_paths:             # 文件访问权限
    - "~/Documents"
    - "~/Downloads"
    - "/tmp"

# 学习系统配置
learning:
  skill_library_path: "~/.hermes/skills"  # Skill 库路径
  auto_extract_skills: true               # 自动提炼 Skill
  skill_confidence_threshold: 0.8         # 置信度阈值

# 上下文管理
context:
  compression_enabled: true       # 启用双重压缩
  max_context_tokens: 32768       # 最大上下文 token 数
  compression_trigger: 0.8        # 达到 80% 时触发压缩

# 安全设置
security:
  require_confirmation_for:       # 需要确认的操作
    - "email"
    - "webhook"
    - "file_delete"
  forbidden_operations:           # 禁止的操作
    - "system_format"
    - "sudo"

使用环境变量管理敏感信息（推荐）

# 在 ~/.bashrc 或 ~/.zshrc 中添加
export HERMES_API_KEY="nous-xxxxxxxxxxxx"
export OPENAI_API_KEY="sk-xxxxxxxxxxxx"
export ANTHROPIC_API_KEY="sk-ant-xxxxxxxxxxxx"

# 修改 config.yaml 使用环境变量
# model:
#   api_key: "${HERMES_API_KEY}"

5.6 运行第一个对话

交互式聊天模式

# 启动交互式聊天
hermes chat

# 输出：
# Hermes Agent v0.8.x
# 使用模型：hermes-4 (NousResearch)
# 工具已加载：42个
# Skill 库：0个技能（新安装）
# 
# 输入你的任务，或 'help' 查看命令，'/quit' 退出
# 
# > 

# 试试第一个简单任务：
> 搜索"大语言模型 2025年最新进展"，给我一个200字的中文摘要

# Hermes 会：
# 1. 调用 web_search 工具
# 2. 处理搜索结果
# 3. 生成摘要
# 4. 将此次 Skill 提炼并保存

单次任务模式（非交互）

# 执行单次任务
hermes run "帮我分析 Python 的 asyncio 和 threading 的区别，
           用表格形式对比，并给一个真实场景的选择建议"

# 带文件输入
hermes run --input /path/to/document.pdf \
  "分析这份文档，提取关键数据点，生成摘要"

# 指定输出文件
hermes run "生成一份关于量子计算的简介" \
  --output /tmp/quantum_intro.md

# 调试模式（显示每一步的工具调用）
hermes run --debug \
  "搜索 Hermes 4 的技术参数并整理成表格"

你的第一个完整任务示例

# 一个展示 Hermes 多步骤能力的完整示例
hermes run """
任务：竞品快速调研

请完成以下步骤：
1. 搜索"AI Agent 框架 2025"相关信息
2. 找出主流框架（至少5个）
3. 对比它们的核心特性（编程语言、主要功能、开源协议）
4. 生成一个 Markdown 格式的对比表格
5. 将结果保存到 ~/Desktop/agent_comparison.md

"""

预期输出（约2-3分钟后）：

[Hermes Agent 执行日志]
─────────────────────────────────────
步骤 1/5：搜索相关信息
  → 调用 web_search("AI Agent框架 2025最新")
  → 获取 12 条结果
  ✓ 完成（3.2s）

步骤 2/5：识别主流框架
  → 分析搜索结果
  → 识别框架：LangChain, AutoGen, CrewAI, Hermes, OpenHands, Dify
  ✓ 完成（1.1s）

步骤 3/5：收集详细信息
  → 调用 web_search × 6（每个框架单独搜索）
  → 调用 web_scraper（获取 GitHub 页面数据）
  ✓ 完成（18.4s）

步骤 4/5：生成对比表格
  → 整理数据，生成 Markdown 格式
  ✓ 完成（2.3s）

步骤 5/5：保存文件
  → 调用 file_writer
  → 文件已保存：~/Desktop/agent_comparison.md
  ✓ 完成（0.1s）

─────────────────────────────────────
任务完成！总耗时：25.1s
Skill 提炼：已从本次任务提炼 2 个新技能
  - "多框架对比研究流程"
  - "GitHub 开源项目数据提取"

5.7 常见安装问题排查

问题一：`hermes` 命令未找到

# 原因：PATH 未正确配置
# 解决：
which hermes  # 查看安装位置

# 如果使用 venv，确认已激活：
source ~/hermes-workspace/hermes-env/bin/activate

# 如果使用 pipx，刷新 PATH：
pipx ensurepath
source ~/.bashrc  # 或 ~/.zshrc

问题二：API Key 验证失败

# 检查 API Key 是否正确设置
hermes config show | grep api_key

# 测试 API 连接
hermes test connection

# 如果是环境变量，检查是否生效
echo $HERMES_API_KEY

# 重新配置
hermes config set --api-key "your-key-here"

问题三：Python 版本冲突

# 查看当前 Python 版本
python3 --version

# 如果版本低于 3.9，明确使用 python3.11
python3.11 -m pip install hermes-agent
python3.11 -m hermes init

# 或者用 pyenv 管理多 Python 版本
brew install pyenv
pyenv install 3.11.9
pyenv global 3.11.9

问题四：网络连接超时

# 检查网络连通性
curl -s https://api.nousresearch.com/v1/models

# 如果需要代理
export HTTPS_PROXY="http://your-proxy:port"
hermes test connection

# 配置 Hermes 使用代理
hermes config set --proxy "http://your-proxy:port"

问题五：工具执行权限不足

# 检查当前工具权限配置
hermes tools permissions

# 添加文件访问权限
hermes config set --allowed-paths "/home/user/data,/tmp"

# 启用 bash 执行（默认禁用，需要显式授权）
hermes config set --enable-bash-execution true

5.8 安装成功验证检查清单

运行以下检查，确认安装完全成功：

#!/bin/bash
# Hermes 安装验证脚本
echo "=== Hermes Agent 安装验证 ==="

# 1. 版本检查
echo -n "1. 版本检查... "
hermes --version > /dev/null 2>&1 && echo "✓ 通过" || echo "✗ 失败"

# 2. 配置检查
echo -n "2. 配置检查... "
hermes config validate > /dev/null 2>&1 && echo "✓ 通过" || echo "✗ 失败"

# 3. API 连接测试
echo -n "3. API 连接测试... "
hermes test connection > /dev/null 2>&1 && echo "✓ 通过" || echo "✗ 失败"

# 4. 工具加载测试
echo -n "4. 工具加载测试... "
TOOL_COUNT=$(hermes tools list 2>/dev/null | wc -l)
[ "$TOOL_COUNT" -gt 20 ] && echo "✓ 通过（${TOOL_COUNT}个工具）" || echo "✗ 失败"

# 5. 基础任务测试
echo -n "5. 基础任务测试... "
RESULT=$(hermes run "用一句话回答：今天是什么季节的说明这只是测试" 2>/dev/null)
[ -n "$RESULT" ] && echo "✓ 通过" || echo "✗ 失败"

# 6. Skill 库初始化
echo -n "6. Skill 库检查... "
[ -d ~/.hermes/skills ] && echo "✓ 通过" || echo "✗ 失败"

echo ""
echo "验证完成！如果所有项目都显示 ✓，Hermes 安装成功。"

# 运行验证脚本
bash hermes_verify.sh

预期全部通过的输出：

=== Hermes Agent 安装验证 ===
1. 版本检查... ✓ 通过
2. 配置检查... ✓ 通过
3. API 连接测试... ✓ 通过
4. 工具加载测试... ✓ 通过（42个工具）
5. 基础任务测试... ✓ 通过
6. Skill 库检查... ✓ 通过

验证完成！如果所有项目都显示 ✓，Hermes 安装成功。

本章小结

完成本章的操作后，你已经：

满足了环境要求，了解了最低硬件和软件依赖
完成了三平台安装（macOS/Linux/WSL2），选择了适合你的方式
理解了配置文件结构，知道如何调整关键参数
运行了第一个任务，亲眼见证了 Hermes 的多步骤自主执行
掌握了故障排查，知道常见问题的解决方向
通过了安装验证，确认系统已就绪

你现在已经站在 Hermes 的起跑线上，接下来的章节将带你深入理解其工作原理、优化使用策略，以及构建更复杂的 Agent 应用。

思考题

在安装过程中，哪个步骤最让你困惑或花费时间最多？这个难点是环境配置问题、文档问题，还是本章内容可以改进的地方？
你运行的第一个任务产生了什么样的结果？Hermes 的表现超出预期的地方是什么？不足的地方是什么？
查看 Hermes 运行后生成的 Skill 库（~/.hermes/skills/），里面已经保存了什么？这些初始 Skill 让你对 Hermes 的学习机制有了什么新的理解？
如果你要将 Hermes 部署给你团队的其他人使用，安装和配置流程中最需要文档化的部分是什么？

下一章：学习路径与本书导读——根据你的角色（使用者/开发者/部署者），找到最适合你的学习路线

本章评分

4.9 / 5 (92 评分)