Hermes Agent 接入指南 - StepFun 开放平台文档中心

Hermes Agent 是由 Nous Research 开发的开源 AI Agent 框架，支持在终端环境中通过自然语言完成代码生成、文件编辑、任务自动化等开发任务。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 的配置向导

如果你是首次安装或希望重新运行引导流程：打开终端，执行以下命令：

hermes setup

在引导过程中：

当提示选择模型提供商时，选择 StepFun Step Plan后选择China。
填入你在第一步获取的 API Key。
选择你想要用的 Model ID。

方式二：配置文件修改

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.7-flash、step-3.5-flash-2603 或 step-3.5-flash。

选择模型

配置完成后，运行以下命令选择模型：

hermes model

测试接入

完成配置后，启动 Hermes Agent 并发送测试消息：

hermes

在对话界面中输入：

hello

如果返回正常内容，说明 API 调用成功。

代码生成测试

输入：

Create a hello world script in Python

预期返回类似结果：

print("Hello, world!")

文件操作测试

输入：

在当前目录创建一个名为 test.txt 的文件，内容为 "Hermes Agent test"

如果 Agent 成功创建文件，则说明模型调用链路正常。

常见问题

模型列表为空或无法加载

如果 hermes model 命令中未显示 Step 相关模型，请检查：

当前网络是否能访问 api.stepfun.com。
Base URL 是否填写为 https://api.stepfun.com/step_plan/v1。
API Key 是否具有 Step Plan 权限。
Hermes Agent 是否为最新版本（hermes update 升级）。

API Key 错误

如果出现以下报错：

401 Incorrect API key

请检查：

Key 是否复制完整
Key 是否属于正确环境（Step Plan 对应 .com 域名）
Base URL 是否指向 Step Plan 端点

连接超时或失败

请检查：

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

模型返回错误

请确认 Model ID 是否填写正确，例如：

<model_id>

推荐模型：

step-3.7-flash（多模态推理旗舰，支持图片和视频理解）
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）验证连通性，再逐步探索技能创建、记忆管理和定时任务等高级功能。

​概述

​前置条件

​操作系统

​安装 Hermes Agent

​订阅 Step Plan

​获取 Step API Key

​配置步骤

​方式一：通过 Hermes Agent 的配置向导

​方式二：配置文件修改

​选择模型

​测试接入

​代码生成测试

​文件操作测试

​常见问题

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

​API Key 错误

​连接超时或失败

​模型返回错误

​高级配置（可选）

​启用工具调用

​配置记忆系统

​消息网关（Telegram/Discord）

​总结

概述