跳转到主要内容
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 提供一键安装脚本,自动完成依赖安装和配置。 通过安装脚本(推荐):
安装脚本会自动检测并安装以下组件:
  • uv(Python 包管理器)
  • Python 3.9+
  • Node.js(部分技能需要)
  • ripgrep、ffmpeg 等工具
安装完成后,重新加载 shell 配置:
验证安装:
若返回版本号(如 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 的配置向导

如果您是首次安装或希望重新运行引导流程: 打开终端,执行以下命令:
在引导过程中:
  1. 当提示选择模型提供商时,选择 StepFun Step Plan后选择China。
  2. 填入您在第一步获取的 API Key。\
  3. 选择您想要用的 Model ID。

方式二:配置文件修改

Hermes Agent 的配置文件位于 ~/.hermes/config.yaml。 打开配置文件,找到 model 相关配置项,添加或修改以下内容:
说明:<model_id> 请填写当前账号在 Step Plan 下可用的模型。已验证示例:step-5-preview、step-3.7-flash、step-3.5-flash-2603、step-3.5-flash。文档列出的模型不构成全部可用名单。

选择模型

配置完成后,运行以下命令选择模型:

测试接入

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

代码生成测试

输入:
预期返回类似结果:

文件操作测试

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

常见问题

模型列表为空或无法加载

如果 hermes model 命令中未显示 Step 相关模型,请检查:
  1. 当前网络是否能访问 api.stepfun.com。
  2. Base URL 是否填写为 https://api.stepfun.com/step_plan/v1。
  3. API Key 是否具有 Step Plan 权限。
  4. Hermes Agent 是否为最新版本(hermes update 升级)。

API Key 错误

如果出现以下报错:
请检查:
  • Key 是否复制完整
  • Key 是否属于正确环境(Step Plan 对应 .com 域名)
  • Base URL 是否指向 Step Plan 端点

连接超时或失败

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

模型返回错误

请确认 Model ID 是否填写正确,例如:
推荐模型(已验证示例,请按当前账号权限替换):
  • step-5-preview(新一代旗舰多模态强推理,支持图片和视频理解)
  • step-3.7-flash(高速多模态推理模型)
  • step-3.5-flash-2603(Agent 优化版,推理更强)
  • step-3.5-flash(标准版,响应更快)

高级配置(可选)

启用工具调用

Hermes Agent 支持自动工具调用。在 ~/.hermes/config.yaml 中启用:

配置记忆系统

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

消息网关(Telegram/Discord)

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

总结

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