OpenClaw更换stepfun/step-3.5-flash模型报错：Unknown model 解决（核心：漏加前缀）

摘要：本文聚焦OpenClaw更换stepfun/step-3.5-flash:free模型时，高频报错「Unknown model」的核心解决方法------忘记给主模型ID添加「modelstudio/」前缀，精简实操步骤，新手可快速上手。

关键词：OpenClaw；stepfun/step-3.5-flash；Unknown model；modelstudio前缀

一、前言

使用OpenClaw 2026.3.13版本，更换OpenRouter免费模型stepfun/step-3.5-flash:free时，频繁出现「Unknown model」报错，排查后发现核心原因：主模型ID未添加「modelstudio/」前缀，整理极简解决步骤如下。

环境说明：

OpenClaw版本：2026.3.13
模型：stepfun/step-3.5-flash:free（OpenRouter）
系统：Windows 10/11（PowerShell操作）

二、核心报错及根源（重点）

核心报错：Unknown model: stepfun/step-3.5-flash:free

报错截图：

【截图位置1：粘贴该报错的PowerShell完整截图，包含「Agent failed before reply: Unknown model: stepfun/step-3.5-flash:free」】

错误根源（唯一关键）：忘记给主模型ID添加「modelstudio/」前缀。

核心规则（必记）：

OpenRouter官方模型ID：stepfun/step-3.5-flash:free（必须带「:free」，不可删）；
OpenClaw主模型ID：必须在官方ID前加「modelstudio/」，即 modelstudio/stepfun/step-3.5-flash:free，否则无法识别。

三、极简解决步骤（3步搞定）

步骤1：停止网关，避免冲突

powershell 复制代码

# 停止OpenClaw网关
openclaw gateway stop
# 强制杀死残留进程（确保完全关闭）
taskkill /f /im openclaw.exe

操作截图：

【截图位置2：粘贴PowerShell执行上述命令的截图】

步骤2：修改配置文件（核心：添加前缀）

配置文件路径：C:\Users\Administrator\.openclaw\openclaw.json（替换Administrator为你的用户名）

打开命令：

powershell 复制代码

notepad %userprofile%\.openclaw\openclaw.json

重点修改1处（其他内容不变）：找到「agents.defaults.model.primary」，添加「modelstudio/」前缀：

json 复制代码

"agents": {
  "defaults": {
    "model": {
      "primary": "modelstudio/stepfun/step-3.5-flash:free"  // 关键：添加前缀
    },
    "workspace": "C:\\Users\\Administrator\\.openclaw\\workspace"
  }
}

配置修改截图：

【截图位置3：粘贴记事本截图，框选修改后的主模型ID，突出「modelstudio/」前缀】

保存文件并关闭。

步骤3：重启网关，验证成功

powershell 复制代码

# 重启网关
openclaw gateway restart
# 验证配置（输出正确前缀ID即成功）
openclaw config get agents.defaults.model.primary

验证成功：输出「modelstudio/stepfun/step-3.5-flash:free」，启动网关无报错。

操作截图：

【截图位置4：粘贴PowerShell重启+验证的截图，框选验证结果】

启动网关验证：

powershell 复制代码

openclaw gateway run

启动成功截图：

【截图位置5：粘贴网关启动成功截图，无Unknown model报错】

四、常见踩坑（仅1个核心坑）

核心踩坑：主模型ID漏加「modelstudio/」前缀 → 解决：按步骤2添加前缀，无需修改其他配置。

五、总结

OpenClaw更换stepfun/step-3.5-flash:free模型，报错「Unknown model」的核心原因就是忘加「modelstudio/」前缀，无需复杂操作，3步修改配置即可解决，新手可直接照搬。

六、需要截图的位置汇总（共5处）

截图1：Unknown model: stepfun/step-3.5-flash:free 报错截图；
截图2：执行停止网关、杀死进程命令的截图；
截图3：配置文件修改截图，框选带前缀的主模型ID；
截图4：重启网关+验证配置的截图，框选验证结果；
截图5：网关启动成功、无报错的截图。

（注：文档部分内容可能由 AI 生成）