学习指南 / 第二章
第二章

快速跑通项目

🎧 语音播放

在 15 分钟内让 Hermes-Agent 运行起来

🎯 本章目标

  • 完成环境准备和安装
  • 配置 API 密钥
  • 成功运行第一个对话

📚 前置条件

  • Python 3.10+
  • uv 包管理器（推荐）或 pip
  • LLM API 密钥（OpenAI / Anthropic / Local）

💡 学完收获

  • 能够本地运行 Hermes-Agent
  • 理解基本配置方法
  • 为后续学习打下实践基础

2.1 安装 Hermes-Agent

使用官方安装脚本（推荐）：

Terminal
# 官方安装脚本（Linux/macOS/WSL2/Android Termux）
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

# 验证安装
hermes --version

# 查看帮助
hermes --help
💡 支持平台

Linux、macOS、WSL2、Android Termux。Windows 需要安装 WSL2。

2.2 运行时目录结构

Hermes-Agent 安装后，会在 ~/.hermes/ 创建运行时目录：

~/.hermes/
~/.hermes/
├── .env                    # 环境变量（API 密钥）
├── config.yaml             # 主配置文件
├── skills/                 # 用户技能目录
├── sessions/               # 会话数据
├── memories/               # 记忆存储
├── state.db                # SQLite 主数据库
├── logs/                   # 日志文件
├── cache/                  # 缓存目录
├── skills/                 # 技能目录
├── checkpoints/            # 检查点
├── cron/                   # 定时任务
├── gateway_state.json      # 网关状态
├── auth.json               # 认证信息
└── ...
⚠️ 重要

~/.hermes/ 是运行时配置目录，不是源码目录。源码在 /root/hermes-agent/。

2.3 配置 API 密钥

编辑 ~/.hermes/.env 文件：

~/.hermes/.env
# 方式一：OpenAI
OPENAI_API_KEY=sk-...

# 方式二：Anthropic (Claude)
ANTHROPIC_API_KEY=sk-ant-...

# 方式三：Nous Portal / OpenRouter
OPENAI_API_KEY=sk-...
OPENAI_BASE_URL=https://portal.nousresearch.com/v1

# 方式四：MiniMax（示例）
OPENAI_API_KEY=xxx
OPENAI_BASE_URL=https://api.minimaxi.com/anthropic

# 可选：搜索 API
SEARCH_API_KEY=...
SERPER_API_KEY=...
⚠️ 安全提醒

不要把 .env 文件提交到 Git！已自动加入 .gitignore。

2.4 主配置文件

~/.hermes/config.yaml 包含所有配置项：

~/.hermes/config.yaml
# 默认模型配置
model:
  default: MiniMax-M2.7
  provider: minimax-cn
  base_url: https://api.minimaxi.com/anthropic

# Agent 配置
agent:
  max_turns: 90              # 最大对话轮次
  gateway_timeout: 1800      # 超时时间（秒）

# 启用的工具集
toolsets:
  - hermes-cli

# 个性化角色（可选）
# personalities:
#   helpful: "You are a helpful assistant..."
#   catgirl: "You are Neko-chan, nya~!"

2.5 交互式设置

使用 setup 向导完成配置：

Terminal
# 运行完整设置向导
hermes setup

# 或单独设置各模块
hermes model          # 选择模型
hermes tools          # 配置工具
hermes config set     # 设置配置项

2.6 启动 CLI 模式

安装和配置完成后，启动 Hermes：

Terminal
# 启动 CLI
hermes

# 或指定模型
hermes --model anthropic/claude-opus-4-6

# 查看帮助
hermes --help

你应该看到类似输出：

输出示例
☤ Hermes-Agent v0.8.0
─────────────────────────────
模型: MiniMax-M2.7 (minimax-cn)
工具: hermes-cli
─────────────────────────────
输入消息开始对话，输入 /help 查看命令。
输入 /quit 或 Ctrl+C 退出。

🟢 就绪

2.7 常用命令

在 CLI 中可以使用以下命令：

命令功能
/help显示帮助
/new开始新对话
/model [name]查看或切换模型
/tools [list]查看可用工具
/personality [name]切换人格
/compress压缩上下文
/usage查看 token 使用量
/retry重试上一次
/undo撤销上一次
/quit退出

2.8 第一个对话

试着和 Hermes 对话：

hermes
# 输入：
你好，你是谁？

# 输出：
你好！我是 Hermes-Agent，一个由 Nous Research 开发的 AI 助手。
我可以帮你完成各种任务，比如：
• 搜索网页获取信息
• 读写文件和执行命令
• 回答问题和进行对话
有什么我可以帮你的吗？

2.9 常见问题

⚠️ 问题：No API key found

检查 ~/.hermes/.env 文件是否存在且格式正确。

格式应该是：KEY=VALUE，每行一个，不要用引号包裹。

⚠️ 问题：Module not found

重新安装：curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

⚠️ 问题：hermes: command not found

运行 source ~/.bashrc 或重启终端让 PATH 生效。

📚 本章总结

本章重点：

  • 安装：官方安装脚本一键安装
  • 配置：~/.hermes/.env 存放 API 密钥
  • 配置：~/.hermes/config.yaml 主配置
  • 启动：hermes
  • 命令：/help, /model, /tools

一句话记忆点： 安装 Hermes 就是三步：装脚本、配密钥、启动

延伸思考

  1. 对比：使用 MiniMax API 和使用本地模型有什么优劣？
  2. 思考：hermes CLI 启动时加载了哪些模块？
  3. 为什么 Hermes 要区分 .env 和 config.yaml？