Hermes接入stepfun阶跃星辰Step API教程(使用step-3.7-flash大模型)

本文介绍如何在 Hermes Agent（Nous Research） 中接入 StepFun Step Plan API（阶跃星辰），并完成终端环境下的模型调用与基础验证。

Hermes Agent 本质是一个运行在 CLI/TUI 环境中的 AI Agent 框架，支持代码生成、文件操作、自动化任务执行，并可通过 OpenAI 兼容接口接入第三方大模型服务。

---

一、整体架构说明

接入链路如下：

Hermes Agent
   ↓
OpenAI-compatible API
   ↓
StepFun Step Plan API
   ↓
step-3.7-flash / step-3.5-flash

核心关键点：

• Hermes 仅负责 Agent 调度与工具执行
• Step 提供推理模型能力
• 通过 base_url + api_key 完成兼容接入

---

二、前置条件

1. 系统要求

• Linux（Ubuntu / Debian 推荐）
• macOS
• Windows（需 WSL2）

---

2. 安装 Hermes Agent

一键安装方式：

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

安装内容包括：

• Python 3.9+
• uv 包管理器
• Node.js
• ripgrep / ffmpeg 等工具链

安装完成后：

source ~/.bashrc
# 或
source ~/.zshrc

验证：

hermes --version

---

3. Step Plan 订阅

必须确认账号已开通 Step Plan，否则无法调用模型：

👉 https://platform.stepfun.com/step-plan

---

4. 获取 API Key

路径：

👉 https://platform.stepfun.com/interface-key

建议：

• 不要写死在代码里
• 使用环境变量或配置文件管理

---

三、Hermes 接入 Step API（核心步骤）

Hermes 支持两种方式配置。

---

方式一：交互式配置（推荐）

初始化配置：

hermes setup

在向导中依次选择：

1. Provider：选择 StepFun Step Plan（China）
2. 输入 API Key
3. 选择模型（model_id）

---

方式二：手动配置 config.yaml

配置文件路径：

~/.hermes/config.yaml

修改内容如下：

model:
  provider: openai
  api_key: "你的Step API Key"
  base_url: "https://api.stepfun.com/step_plan/v1"
  model: "step-3.7-flash"

---

可用模型列表

模型	说明
step-3.7-flash	多模态能力更强
step-3.5-flash-2603	Agent优化版本
step-3.5-flash	低延迟基础版本

---

四、启动与验证

启动 Hermes：

hermes

进入交互模式后测试：

1. 基础测试

hello

正常应返回自然语言回复。

---

2. 代码生成测试

Create a hello world script in Python

预期输出：

print("Hello, world!")

---

3. 文件操作测试

在当前目录创建 test.txt，内容为 Hermes Agent test

如果成功创建文件，说明：

• API 调用正常
• 工具链正常
• Agent 执行链路正常

---

五、常见问题排查

1. 模型列表为空

检查：

• base_url 是否正确

  https://api.stepfun.com/step_plan/v1
  

• API Key 是否具备 Step Plan 权限

• 网络是否可访问 stepfun 域名

• Hermes 是否为最新版本：

  hermes update
  

---

2. 401 Unauthorized

典型原因：

• API Key 错误或复制不完整
• Key 属于非 Step Plan 环境
• base_url 配错（常见错误点）

---

3. 连接超时

排查方向：

• 是否需要代理
• DNS 是否异常
• 是否能 curl 通接口：

curl https://api.stepfun.com/step_plan/v1

---

4. 模型不可用

检查 model_id：

推荐优先使用：

• step-3.7-flash（推荐）
• step-3.5-flash-2603
• step-3.5-flash

---

六、高级配置（可选）

1. 启用工具能力

tools:
  enabled:
    - terminal
    - file
    - browser
    - code_execution

作用：

• 自动执行命令
• 文件读写
• 浏览器操作
• 代码运行

---

2. 本地记忆系统

存储路径：

~/.hermes/memories/

特点：

• 自动持久化上下文
• 跨会话记忆召回
• 用于长期任务建模

---

3. Telegram 网关

启动：

hermes gateway start

首次需要配置：

• TELEGRAM_BOT_TOKEN
• TELEGRAM_ALLOWED_USERS

用于实现：

• 手机远程控制 Agent
• 消息驱动任务执行

---

七、总结

Hermes Agent + Step API 的组合，本质上是：

• CLI Agent（Hermes）
• 推理模型（Step）
• 工具执行系统（Tools）

三者结合后可以实现：

• 本地自动化开发
• 文件系统操作
• 代码生成与执行
• 远程消息控制

建议流程：

1. 先验证 hello world
2. 再测试文件操作
3. 最后启用 tools + gateway

---