跳转到主要内容
Hermes-Agent 是由 Nous Research 开发的开源 AI Agent 框架，支持在终端环境中通过自然语言完成代码生成、文件编辑、任务自动化等开发任务。通过配置 OpenAI Compatible API，Hermes-Agent 可以接入 Step 模型，在命令行或消息平台中调用推理能力。 本文档介绍如何在 Hermes-Agent 中完成 Step API 的接入配置，并验证模型是否可用。

​
概述

Hermes-Agent 适合在服务器或本地终端中运行的 AI 编程助手。完成配置后，你可以通过终端 TUI 或 Telegram 等消息平台与 Agent 对话，让它执行代码生成、文件操作、定时任务等自动化工作。

​
前置条件

​
操作系统

Hermes-Agent 支持以下系统：
  • Linux（推荐 Ubuntu/Debian）
  • macOS
  • Windows（需使用 WSL2）

​
安装 Hermes-Agent

Hermes-Agent 提供一键安装脚本，自动完成依赖安装和配置。 通过安装脚本（推荐）： 
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
安装脚本会自动检测并安装以下组件：
  • uv（Python 包管理器）
  • Python 3.9+
  • Node.js（部分技能需要）
  • ripgrep、ffmpeg 等工具
安装完成后，重新加载 shell 配置： 
source ~/.bashrc   # Bash 用户
# 或
source ~/.zshrc    # Zsh 用户
验证安装： 
hermes --version
若返回版本号（如 Hermes Agent v0.6.0），则说明安装成功。

​
订阅 Step Plan

在开始配置前，请先确认当前账号已完成 Step Plan 订阅。只有在账号具备对应计划或调用权限后，后续模型调用与额度使用才会正常生效。 如需订阅或购买，请访问：Step Plan 订阅

​
获取 Step API Key

在 Step 开放平台 获取 API Key，用于身份认证和请求授权。建议通过控制台创建新的 Key，并避免将其硬编码进代码仓库。 推荐做法：
  • 使用环境变量保存 Key
  • 或通过本地配置文件管理 Key

​
配置步骤

Hermes-Agent 通过环境变量或配置文件读取 API 服务地址和认证信息。

​
方式一：环境变量配置（推荐）

Hermes-Agent 兼容 OpenAI 格式的 API，因此可以使用标准的 OPENAI_API_KEY 和 OPENAI_BASE_URL 环境变量。 打开终端，执行以下命令： 
# 设置 API Key
echo 'export OPENAI_API_KEY="你的Step API Key"' >> ~/.zshrc

# 设置 Base URL（Step Plan 用户）
echo 'export OPENAI_BASE_URL="https://api.stepfun.com/step_plan/v1"' >> ~/.zshrc

# 重新加载配置
source ~/.zshrc
说明：如果你的 Shell 是 Bash，请将 ~/.zshrc 替换为 ~/.bashrc。

​
方式二：配置文件修改

Hermes-Agent 的配置文件位于 ~/.hermes/config.yaml。 打开配置文件，找到 model 相关配置项，添加或修改以下内容： 
model:
  provider: openai
  api_key: "你的Step API Key"
  base_url: "https://api.stepfun.com/step_plan/v1"
  model: "<model_id>"
说明：本文示例中的 <model_id> 可填写为 step-3.5-flash-2603 或 step-3.5-flash。

​
选择模型

配置完成后，运行以下命令选择模型： 
hermes model
在交互界面中选择 OpenAI Compatible 提供商，并输入模型 ID：<model_id>。 也可以直接通过环境变量预设模型： 
echo 'export HERMES_DEFAULT_MODEL="<model_id>"' >> ~/.zshrc
source ~/.zshrc

​
测试接入

完成配置后，启动 Hermes-Agent 并发送测试消息： 
hermes
在对话界面中输入： 
hello
如果返回正常内容，说明 API 调用成功。

​
代码生成测试

输入： 
Create a hello world script in Python
预期返回类似结果： 
print("Hello, world!")

​
文件操作测试

输入： 
在当前目录创建一个名为 test.txt 的文件，内容为 "Hermes-Agent test"
如果 Agent 成功创建文件，则说明模型调用链路正常。

​
常见问题

​
模型列表为空或无法加载

如果 hermes model 命令中未显示 Step 相关模型，请检查：
  1. 环境变量是否正确设置（执行 echo $OPENAI_BASE_URL 验证）。
  2. 当前网络是否能访问 api.stepfun.com。
  3. API Key 是否具有 Step Plan 权限。
  4. Hermes-Agent 是否为最新版本（hermes update 升级）。

​
API Key 错误

如果出现以下报错： 
401 Incorrect API key
请检查：
  • Key 是否复制完整
  • Key 是否属于正确环境（Step Plan 对应 .com 域名）
  • Base URL 是否指向 Step Plan 端点

​
连接超时或失败

请检查：
  • OPENAI_BASE_URL 是否填写为 https://api.stepfun.com/step_plan/v1
  • 当前网络环境是否正常（如有代理需配置）
  • API 端点是否可访问（curl https://api.stepfun.com/step_plan/v1 测试连通性）

​
模型返回错误

请确认 Model ID 是否填写正确，例如： 
<model_id>
推荐模型：
  • step-3.5-flash-2603（Agent 优化版，推理更强）
  • step-3.5-flash（标准版，响应更快）

​
高级配置（可选）

​
启用工具调用

Hermes-Agent 支持自动工具调用。在 ~/.hermes/config.yaml 中启用： 
tools:
  enabled:
    - terminal
    - file
    - browser
    - code_execution

​
配置记忆系统

Hermes-Agent 的持久记忆存储在 ~/.hermes/memories/ 目录。你可以通过自然语言让 Agent 记住重要信息，这些记忆会在后续对话中自动召回。

​
消息网关（Telegram/Discord）

如需在手机上通过 Telegram 与 Hermes-Agent 对话，启动网关： 
hermes gateway start
首次运行会提示配置 TELEGRAM_BOT_TOKEN 和 TELEGRAM_ALLOWED_USERS，相关信息可在 Telegram 中通过 @BotFather 获取。

​
总结

完成环境变量或配置文件配置后，Hermes-Agent 即可通过 Step API 在终端或消息平台中执行代码生成、文件编辑、任务自动化等开发任务。建议先用最小示例（如 hello world）验证连通性，再逐步探索技能创建、记忆管理和定时任务等高级功能。