快速上手与基础配置

经过上一章的安装部署，你的环境中已经准备好运行 Hermes Agent。本章将带你完成从初始化配置到完成第一个真实任务的完整流程。

初始化配置

安装完成后，第一步是运行初始化命令：

hermes-agent init

这个命令会在当前目录下创建一个 .hermes/ 隐藏目录，其中包含核心配置文件 config.yaml。让我们来看看这个初始化过程具体做了哪些事情：

1. 创建 .hermes/ 配置目录
2. 生成默认的 config.yaml 配置文件
3. 创建 .hermes/logs/ 日志目录，用于存储运行日志
4. 创建 .hermes/sessions/ 会话目录，用于保存对话历史
5. 可选地生成 .gitignore 示例文件

如果你想在不同的项目中使用不同的配置，可以在每个项目的根目录下分别执行 hermes-agent init。

配置文件详解

初始化完成后，打开 .hermes/config.yaml 可以看到如下内容：

# Hermes Agent 配置文件
model:
  provider: openai          # 模型提供商：openai / anthropic / ollama
  name: gpt-4o              # 模型名称
  api_key: ${OPENAI_API_KEY} # 从环境变量读取 API Key
  temperature: 0.7          # 生成温度，范围 0-2
  max_tokens: 4096          # 每次生成的最大 Token 数

tools:
  shell: true               # 允许执行 Shell 命令
  git: true                 # 允许操作 Git
  filesystem: true          # 允许读写文件
  web: false                # 允许访问网络

agent:
  max_steps: 50             # 单次任务最大执行步数
  max_retries: 3            # 工具调用失败重试次数
  verbose: false            # 是否输出详细日志
  interrupt_mode: gentle    # 打断模式：gentle / force

session:
  autosave: true            # 自动保存对话历史
  max_history: 100          # 保留的最大历史消息数

每个配置项的含义如下：

model 部分：控制 Agent 使用的语言模型。provider 指定模型提供商，name 指定具体模型版本。api_key 建议使用 ${VAR_NAME} 的方式引用环境变量，避免将密钥硬编码在配置文件中。temperature 控制输出的随机性，编程任务建议设置为 0.2 到 0.7 之间，数值越低输出越确定。max_tokens 限制单次生成的最大 Token 数，复杂任务可以适当调高到 8192 或更高。

tools 部分：控制 Agent 可以使用的工具。出于安全考虑，web 工具默认关闭，需要时再开启。

agent 部分：控制 Agent 的行为。max_steps 限制任务的最大执行步数，防止 Agent 陷入死循环。max_retries 控制在工具调用失败时的重试次数。interrupt_mode 定义打断行为，gentle 模式会在当前步骤完成后响应打断。

API Key 配置

Hermes Agent 支持多种模型提供商，配置 API Key 是使用前最重要的步骤。下表列出了主流提供商的环境变量配置方式：

推荐的方式是通过环境变量注入 API Key：

# 设置环境变量（临时，仅当前终端有效）
export OPENAI_API_KEY=sk-your-key-here

# 设置环境变量（写入 shell 配置文件，永久生效）
echo 'export OPENAI_API_KEY=sk-your-key-here' >> ~/.bashrc
source ~/.bashrc

# 或者使用 .env 文件（与 Docker 场景配合使用）
echo 'OPENAI_API_KEY=sk-your-key-here' > .env

环境变量配置完成后，config.yaml 中的 api_key: ${OPENAI_API_KEY} 会自动读取到对应的值。这种方式的好处是：API Key 不会出现在任何代码或配置文件中被提交到 Git，大大降低了密钥泄露的风险。

首次对话：从简单到复杂

配置完成后，我们来运行第一个任务。先从最简单的开始：

任务一：询问基本信息

hermes-agent "当前目录下有哪些文件？给我列出来"

Agent 会执行 ls 或 find 命令，然后整理输出结果。这个任务虽然简单，但验证了 Agent 的基本工作流程：理解指令 -> 选择工具 -> 执行 -> 返回结果。

任务二：创建一个简单的脚本

hermes-agent "帮我写一个 Python 脚本，功能是扫描当前目录下所有 .py 文件，统计每个文件中的代码行数、注释行数和空行数"

Agent 会进行任务规划，创建脚本文件，并执行它来验证结果。你可以观察 Agent 是如何自主完成从需求到可运行产出的全过程。

任务三：多步骤任务

hermes-agent "帮我初始化一个简单的 Flask Web 项目，包含以下功能：1）首页路由返回 Hello World；2）/health 健康检查接口；3）使用 SQLite 存储访问计数；4）添加 Dockerfile"

这个任务涉及多个子任务：创建项目结构、编写多个文件、安装依赖、编写 Docker 配置。Agent 会将其自动拆解为多个步骤依次执行。

基础调优参数说明

掌握几个关键参数的调整，可以显著改善 Hermes Agent 的使用体验：

temperature（温度）：控制输出的随机性和创造力。编程任务推荐 0.2 到 0.5 之间的低温度，以获得更确定和精确的代码输出。创意性任务（如编写文档、生成注释）可以提升到 0.7 到 0.9。

# 编程任务配置
model:
  temperature: 0.3
  max_tokens: 8192

max_steps（最大步数）：限制单次任务的最大执行步数。简单任务通常 5 到 10 步就能完成，复杂项目重构可能需要 30 到 50 步。设置合理的上限可以防止 Agent 在无解的问题上浪费资源。

agent:
  max_steps: 30
  max_retries: 2

max_retries（重试次数）：当工具调用失败时的重试次数。在网络不稳定的环境下可以适当调高，本地任务则可以调低以节省时间。

verbose（详细输出）：开启后可以看到 Agent 每一步的思考过程和工具调用细节，对调试非常有用。日常使用建议关闭。

# 命令行临时覆盖配置
hermes-agent --temperature 0.3 --max-steps 20 "帮我修复这个 bug"

常见问题排查

如果在首次使用中遇到问题，可以参考以下排查步骤：

1. API Key 未配置：报错信息提示认证失败时，检查 echo $OPENAI_API_KEY 是否输出了正确的密钥
2. 模型不可用：确认配置的模型名称与提供商支持列表一致，如 GPT-4o 需要 OpenAI API 有对应权限
3. 工具权限被拒绝：检查 config.yaml 中 tools 部分的相关功能是否设置为 true
4. Python 版本不兼容：使用 python --version 确认版本在 3.9 以上

本章小结

本章我们完成了从 hermes-agent init 初始化到完成真实任务的完整流程。学会了配置文件的结构和含义、API Key 的安全管理方式、以及几个关键调优参数的作用。在下一章中，我们将深入解析 Hermes Agent 的内部工作原理，了解 Agent 循环、规划引擎和工具调用机制的核心设计。