StepFun Step Plan API 接入 OpenClaw：从推理模型到图片 Skill 完整指南

手把手教你将 StepFun 的推理、语音、图像模型完整接入 OpenClaw 体系

2026-07-16 约 2117 字预计阅读 5 分钟

/images/Code-Art-Studio-images/stepfun-step-plan-openclaw-guide/stepfun-step-plan-openclaw-guide.webp

StepFun Step Plan API 接入 OpenClaw：从推理模型到图片 Skill 完整指南

这几天在给 OpenClaw 接入 StepFun 的 Step Plan API，一路从推理模型配到语音模型、再到图像模型的 skill 化方案，踩了几个不大不小的坑。这篇文章把全过程和配置要点整理出来，希望能给同样在折腾 OpenClaw 多模型接入的同学一些参考。

一、推理模型接入：最简单的部分

StepFun 的 Step Plan 推理模型群提供了多个版本，从轻量到旗舰一应俱全。好消息是 —— 它们走的是 OpenAI 兼容的 chat completions 协议，所以可以直接配置进 models.providers，不需要写任何脚本。

支持的模型列表

模型	特性
`step-3.7-flash`	最新旗舰推理
`step-3.5-flash-2603`	高性能推理
`step-3.5-flash`	标准推理
`step-router-v1`	智能路由

配置步骤

Step 1：在 models.providers 中注册 StepFun

{
  "models": {
    "providers": [
      {
        "provider": "stepfun",
        "api": "https://api.stepfun.com/step_plan/v1/chat/completions",
        "key": "$STEPFUN_API_KEY",
        "models": {
          "step-3.7-flash": {
            "maxTokens": 16384
          },
          "step-3.5-flash-2603": {
            "maxTokens": 16384
          },
          "step-3.5-flash": {
            "maxTokens": 16384
          },
          "step-router-v1": {
            "maxTokens": 16384
          }
        }
      }
    ]
  }
}

Step 2：给默认模型列表加别名

在 agents.defaults.models 中注册别名，方便在对话中快速调用：

{
  "agents": {
    "defaults": {
      "models": {
        "step-3.7-flash": "stepfun/step-3.7-flash",
        "step-3.5-flash-2603": "stepfun/step-3.5-flash-2603",
        "step-3.5-flash": "stepfun/step-3.5-flash"
      }
    }
  }
}

搞定。现在你就可以在对话中 /model step-3.7-flash 直接切到 StepFun 推理模型了。

二、语音模型的能力边界

StepFun 还有语音模型 stepaudio-2.5-chat，但它的情况要复杂一些。

哪个能直接用：stepaudio-2.5-chat 走的是标准 chat completions 协议，文本输入/文本输出，所以同样可以直接配进 models.providers。

哪个不能：stepaudio-2.5-tts（文本转语音）、stepaudio-2.5-asr（语音识别）、stepaudio-2.5-realtime（实时语音）走的是非标准端点，OpenClaw 的 models.providers 只有 text chat 协议适配器，没有 TTS/ASR 适配器，所以进不了 provider。

结论：如果你只需要文本对话能力，stepaudio-2.5-chat 可以直接用；如果需要语音合成或识别，得走更深的集成方案。

三、图像模型的 skill 化方案

这是最折腾的部分。StepFun 的图像模型 step-image-edit-2 走的是 /images/generations 和 /images/edits 端点，不是 chat completions，所以同样进不了 models.providers。

为什么不能走 provider

OpenClaw 的 models.providers 目前没有 image generation adapter —— 它只支持 text chat 协议的模型。所有非 chat 协议的模型（图像生成、TTS、ASR），都需要通过 skill 来封装。

解决方案：创建 step-image skill

参照之前 agnes-image skill 的模式，创建一个 step-image skill：

skill 目录结构：

~/.openclaw/skills/step-image/
├── SKILL.md          # 技能说明 + 使用示例
├── scripts/
│   └── step_image.py  # 核心脚本
└── references/
    └── api.md         # API 文档参考

脚本核心功能：

# scripts/step_image.py — 简化版
import requests, os, json

API_KEY = os.environ["STEPFUN_API_KEY"]
BASE_URL = "https://api.stepfun.com/v1"

def generate(prompt: str, size="1024x1024", output_dir="."):
    """文生图"""
    resp = requests.post(
        f"{BASE_URL}/images/generations",
        headers={"Authorization": f"Bearer {API_KEY}"},
        json={"model": "step-image-edit-2", "prompt": prompt, "size": size}
    )
    data = resp.json()
    # 下载并保存图片
    img_url = data["data"][0]["url"]
    # ... 下载 + PIL 后处理 ...

def edit(image_path: str, prompt: str, output_dir="."):
    """图生图（编辑）"""
    with open(image_path, "rb") as f:
        resp = requests.post(
            f"{BASE_URL}/images/edits",
            headers={"Authorization": f"Bearer {API_KEY}"},
            files={"image": f, "prompt": (None, prompt)}
        )
    # ... 处理响应 ...

凭证管理

所有 step-image 相关的 API 调用通过 STEPFUN_API_KEY 环境变量 读取凭证，与推理模型共用同一套 Key，无需额外配置。

四、踩坑实录

一路配置下来，踩了四个坑，每个都值得记一笔。

坑 1：URL 路径必须带 /v1

第一次配置时我把 endpoint 写成了：

"api": "https://api.stepfun.com/step_plan/chat/completions"

返回 404。检查 StepFun 文档才发现，完整路径是：

"api": "https://api.stepfun.com/step_plan/v1/chat/completions"

教训：多模态平台的 API 路径层级比标准 OpenAI 复杂，配之前最好先 curl 确认一遍端点。

坑 2：JSON 响应可能被额外文本污染

调用图像生成 API 时，返回的响应里可能包含额外文本（比如 "Saved: ..."），直接 response.json() 会抛异常。

解决方案：从响应文本中截取第一个 { 到最后一个 } 之间的部分，再解析 JSON：

text = resp.text
# 截取 JSON 部分（处理额外文本污染）
json_start = text.find("{")
json_end = text.rfind("}") + 1
clean_json = json.loads(text[json_start:json_end])

坑 3：图片尺寸与请求不一致

请求的尺寸和实际生成的尺寸经常对不上。比如请求 1600×900，返回的实际图片可能是 1312×736。这不是 bug，是 API 特性 —— 模型按自己的 native 分辨率生成，然后缩放到请求尺寸。

解决方案：拿到图片后用 PIL 强制 Resize 到目标尺寸，再导出为 WebP：

from PIL import Image
img = Image.open(downloaded_path)
img_resized = img.resize((1600, 900), Image.LANCZOS)
img_resized.save(final_path, "WEBP", quality=95)

坑 4：config.patch 对 protected path 拒绝

OpenClaw 的 config.patch 命令会对某些 protected 路径拒绝写入。如果发现 config.patch 不生效，直接 edit 配置文件：

# 如果 config.patch 拒绝写入，直接编辑
nano ~/.openclaw/config.json  # 或直接 edit 工具

当然，编辑前记得备份。

五、踩坑总结快速参考

问题	症状	解决方案
URL 缺 /v1	404 Not Found	补全 `/v1/` 路径段
JSON 被污染	json.loads 抛异常	截取 `{...}` 范围再解析
尺寸不精确	实际尺寸≠请求尺寸	PIL resize + WebP 导出
config.patch 拒绝	patch 不生效	直接 edit 配置文件

六、下一步：skill 的 OpenClaw 注册

step-image skill 写好后，需要在 OpenClaw 中注册才能被 agent 使用：

openclaw skill install ~/.openclaw/skills/step-image/

然后在 agent 的 skills 配置中开启：

{
  "agents": {
    "defaults": {
      "skills": ["step-image"]
    }
  }
}

以后在对话中就可以让 agent 调用 step-image 生成和编辑图片了。

以上就是 StepFun Step Plan API 接入 OpenClaw 的全过程。推理模型一路绿灯直达，语音模型部分可用，图像模型值得做一个专属 skill。如果你也在折腾 OpenClaw 的模型接入，希望这些踩坑经验能帮你省点时间。

参考来源

–全文完–

若你有故事想讲、有困惑想聊、或是想找个人说说心里话，甚至只是吐槽发泄一下情绪，都欢迎来找我聊聊：　　　《内容已折叠，点击展开》

希望我写的每一个字，成为我自己和某个人活下去、拼下去的力量。　　　　　　　　　　　　　　　　　　　　　《内容已折叠，点击展开》

“技术终归是工具，而我们一次次认真把问题理顺，守住的其实不只是页面样式和代码输出，还有那一点不愿被混乱打败的心气，是每一个深夜仍愿点灯前行的人。”

转载请注明来自https://oklife.me。