在 Cherry Studio 和 Zed 里配阶跃星辰：Base URL 与模型 ID 怎么填
数据截至 2026-08，价格与限额以各官网为准。本文只讲计费与接入机制，不列具体价格数字。
把阶跃星辰接进 Cherry Studio 和 Zed，本质上只有三个字段要填：Base URL、API Key、模型 ID。真正会卡住人的是第一个——阶跃有两套地址，Step Plan 订阅走的是专用地址 https://api.stepfun.com/step_plan/v1，普通按量调用走的是 https://api.stepfun.com/v1，官方常见问题里专门写了一条：使用错误地址会导致请求报错。Cherry Studio 的模型服务列表里虽然内置了「阶跃星辰」这个 Provider，但 API 地址那一栏仍然要按官方接入指南手动填成专用地址；Zed 那边则是走 OpenAI Compatible 的自定义 Provider，字段名叫 API URL，填的是同一个值。剩下的步骤两边都很短：Cherry Studio 靠 API 密钥右侧的「检测」按钮验证，Zed 靠在 Agent Panel 里发一句话验证。
动手之前：订阅状态和 API Key 是两回事
Cherry Studio 和 Zed 两份接入指南的「前置条件」写法几乎一样，都把两件事分开列：先确认账号已完成 Step Plan 订阅，再去创建 API Key。官方对订阅这一步的措辞是，只有在账号具备对应计划或调用权限后，后续的模型调用与额度使用才会正常生效。
这个顺序不是客套。快速开始页给的建议顺序同样是「先确认已订阅或开通 Step Plan，再创建 API Key，最后接入具体工具」。意思很明确：你手上有一把格式正确的 Key，不代表这把 Key 背后挂着可用的额度。如果账号是由团队统一开通的，官方说可以直接跳过订阅这一步进入下一环。
API Key 在阶跃开放平台的接口密钥页面创建。官方在快速开始页给了一句很具体的建议：在控制台创建一个新的 API Key，妥善保存，不要直接写入代码仓库。这句话对桌面客户端场景尤其值得听——你在客户端里配好一把 Key 之后，很容易顺手把同一把 Key 再复制进项目代码，那就等于给自己埋了一颗随时会被推上远端的雷。这两份接入指南只写了「填入 API Key」，客户端把这个值存在哪、以什么形式存，官方文档里没有找到相关说明，所以稳妥的做法是按「这把 Key 一旦泄露该怎么办」来准备，而不是指望客户端替你兜底：给客户端单独建一把 Key，不要和线上服务、代码仓库共用同一把，出问题时可以只吊销这一把而不牵连其他环境。密钥怎么分环境、怎么轮换，可以对照API Key 安全管理的通用做法再收一遍口。
Cherry Studio：选 Provider、改地址、再手动加模型
官方指南把 Cherry Studio 定位成「在统一桌面工作台中完成多模型对话和开发辅助任务」的客户端，支持 macOS、Windows、Linux 三个系统，建议用最新版本。安装包从 Cherry Studio 官网下载。
官方把配置写成了先后衔接的两段：前四步是选 Provider、填 Key、改地址、保存配置，第五步才是添加模型。两段都做完，客户端里才会真正出现一个可选的 Step 模型。
第一段是加 Provider：打开模型配置界面，在模型服务列表里选择「阶跃星辰」，输入 Step API Key，然后在 API 地址栏输入 https://api.stepfun.com/step_plan/v1，保存配置。注意这一栏是需要你自己填的，内置 Provider 条目本身并不等于地址已经对了。
第二段是加模型。Cherry Studio 需要你点「+添加」，在弹出的窗口里填三个字段：
- 模型 ID：填具体的模型标识，官方在这份指南里给出的示例取值是
step-3.7-flash（另有两个 flash 系列取值同样列在示例说明里） - 模型名称：可填写便于识别的名称
- 分组名称：可填写便于归类的名称
填完点「添加模型」保存。三栏的官方措辞值得对着看一遍：模型 ID 那一栏官方给的是具体的模型标识取值，模型名称和分组名称两栏官方只写了「可填写便于识别的名称」「可填写便于归类的名称」，没有给出任何取值约束。这两栏到底会不会参与实际请求，官方文档里没有找到相关说明；照文档的字面要求填就行，别拿它们当模型标识来试。
验证方式是点击 API 密钥右侧的「检测」。官方的判据很直白：如果提示成功，则表明设置成功；如果出现错误，则需要检查 API key 和 base url 是否设置正确。注意文档给的是「两项一起查」，并没有把这两种情况拆开告诉你是哪一项出了问题，所以真报错时还是得自己两头核一遍。
Zed：命令面板进设置，按 OpenAI Compatible 加 Provider
Zed 的定位在官方指南里写得是「高性能代码编辑器，内置 AI Assistant 能力，并支持通过 OpenAI Compatible API 调用第三方大模型」。官方给它安排的接入路径也就是这一条：配置自定义 API Endpoint，在 LLM Providers 里新增一个 Provider。表单里的 Provider Name 官方注明是自定义名称、可以任意填，这也从侧面说明这条路径是按「自己起名的第三方服务」来走的。Zed 里是否另有现成的阶跃星辰条目，这份指南没有提及。
入口不在图形化的设置面板，而在命令面板。按 Cmd+Shift+P 调出命令面板，输入并执行 agent: open settings，在打开的界面里找到 LLM Providers 区域，点右侧的「+ Add Provider」，表单里填四项：
- Provider Name：官方示例写的是
Stepfun，并注明这是自定义名称，可以任意填 - API URL：
https://api.stepfun.com/step_plan/v1 - API Key：在 Step 平台获取的那把
- Model Name：填模型标识
填完点「Save Provider」保存。
Zed 这份指南在验证环节给的步骤比 Cherry Studio 细，分了三级：先在 Agent Panel 里发一句 hello，能返回正常内容就说明 API 调用通了；再让它写一个 Python hello world 程序，验证代码生成；最后在代码文件里选中一段代码，输入 Explain this code，能收到解释结果就说明模型调用链路正常。三步的差别就写在步骤本身里：前两步都是在 Agent Panel 里直接输入文字，第三步多了一个前置动作——要先在代码文件中选中一段代码再提问。所以真出问题时，前两步过了第三步没过，和三步全都不过，指向的范围是不一样的，别只跑第一步就当配好了。
两个客户端在模型 ID 上的说明并不完全一致
有个细节值得提前说破，免得你在两边填了同一个值却只有一边能跑：Cherry Studio 那份指南和 Zed 那份指南，在 <model_id> 的示例说明里列出的可填取值并不完全相同，Cherry Studio 页给的取值比 Zed 页多一个。至于这个差异是能力差异还是文档更新节奏差异，官方文档里没有找到相关说明，所以别自行脑补结论。
比较稳的做法是照官方快速开始页来：那一页明确写了「推荐验证模型」是 step-3.7-flash，并且在通用配置项清单里也把 Model 或 Model ID 一栏写成填这个值。先用推荐的验证模型把链路打通，确认 Key、地址、客户端三方都没问题之后，再换成你实际想用的模型。这样一旦换完报错，你至少能确定问题出在模型标识而不是别的环节。Step Plan 支持哪些模型以官方模型列表为准，会随时间扩展。
报错怎么定位：先分清是地址、是 Key、还是额度
阶跃的错误码表里，几类返回值指向的原因区分得比较清楚，对照着看能省很多时间。
401 是认证无效，错误码表给的处理方式就是确保使用正确的 API 密钥；异常处理页说得更细一点：这可能是由于你使用了错误的 API 密钥，需要仔细检查所使用的密钥是否正确。快速开始页的常见检查项把这一条写成「API Key 是否填写正确且属于正确环境」，后半句是容易被跳过的——Step Plan 概览里的说法是订阅后获取专用 API Key，至于普通 API 的密钥能不能直接用在 Step Plan 地址上，官方文档里没有找到相关说明，所以别默认手头任意一把 Key 都通用，按订阅后拿到的那把来填。
404 是请求路径不正确，官方给的处理是参照文档修复请求路径信息；异常处理页还补了一句：如果检查修复后仍返回 404，可以进一步查看文档中关于路径结构和层级的说明。要说明的是，官方并没有把某个具体错误码和「Base URL 填错」对应起来，所以别指望靠错误码反推是不是地址写错了。官方给的排查方式是不看错误码直接查地址——FAQ 里「第三方工具接入报错怎么办」那条的排查顺序，第一步就是确认 Base URL 是否使用了专用地址，并直接在括号里标注这是常见问题点。
429 是请求的资源超限。官方在异常事件处理建议里给的做法是设定一定的 delay 时间后再次请求。需要注意的是，同为 429，在企业套餐的项目密钥调用场景下还可能是额度上限触顶而不是速率超限，官方明确要求以错误标识区分这两种情况，并列出了 project_credit_limit_exceeded、member_project_credit_limit_exceeded 这两个标识；402 对应的 insufficient_credit 则是组织 Credit 账户余额不足。个人订阅场景不涉及这套项目级标识。429 的通用退避写法可以参考429 的通用处理思路。
451 是请求内容或响应内容未审核通过，官方建议前置添加安全审核能力，让用户更早感知输入问题。
Zed 那份指南自己也带了三条常见问题：无法连接 API 时查 API URL、API Key、当前网络是否可访问 API Endpoint；模型返回错误时确认 Model Name 是否填写正确；AI 无响应时重新检查 API URL、API Key、Model Name 三项并重启 Zed。快速开始页的常见检查项还多补了一条容易被忽略的——工具是否已经保存配置并完成重启。
如果自查完还是定位不了，官方故障排查页要求联系时提供两样东西：返回响应头 Header 中的 X-Trace-Id 字段，以及生成结果里的 id（官方示例指的就是返回 JSON 顶层那个 id 字段）。这两个值一个在响应头、一个在响应体，图形客户端会不会把它们展示出来，官方文档里没有找到相关说明；比较省事的办法是用命令行按官方示例复现一次同样的请求，把响应头和响应体一起抓下来再提交。
额度这一层：Credit 月池和限速是两套东西
Step Plan 的计费单位是 Credit，官方说明是调用任意模型时用量都会换算为 Credit，从当月额度中扣减。额度一次性发放到当月「月池」，月内任意时段消耗，月末清零、不结转到下一周期。当月用尽后可以加购加油包补充，加油包有独立的周期，与套餐到期时间相互独立。
有一条扣费顺序值得记住：账户里同时存在月池 Credit 和加油包 Credit 时，按到期时间先后消耗，优先扣减先到期的那份。所以加油包不是「备用油箱」，它和月池谁先被烧掉取决于到期日排序。
还有一条和客户端使用者直接相关：官方 FAQ 明确写了 Step Plan 不适用开放平台那套按累计充值金额划分的阶梯限速，用量由所订阅档位的月度 Credit 额度管理。另外，Step Plan 订阅与账户余额是相互独立的两个体系，用 Step Plan 内功能消耗的是订阅自身的 Credit，不会扣账户余额。这两条合起来解释了一个容易困惑的现象：账户里有余额，不代表 Step Plan 场景下的调用就能继续。具体档位和价格一律以官方定价页为准，本文不列。
三个值得单独拎出来的坑
第一个是 Base URL。除了普通地址和 Step Plan 专用地址这一层区别之外，阶跃还按协议分了两套：OpenAI 兼容的 Chat Completions 用带 /v1 的那个，Anthropic 兼容的 Messages 用不带 /v1 的 https://api.stepfun.com/step_plan。Cherry Studio 和 Zed 这两个客户端在官方指南里填的都是带 /v1 的 OpenAI 兼容形态。至于兼容层到底覆盖到哪些接口，可以对照OpenAI 兼容的常见断点心里有个数。
第二个是「配置保存了但没生效」。快速开始页把「是否已经保存配置并完成重启」单独列为检查项，Zed 的常见问题里也把重启写进了 AI 无响应的处理步骤。改完配置先重启一次，再判断是不是真的配错了。
第三个是拿模型 ID 当变量试。两份指南里的 <model_id> 是占位符，紧跟着的说明行才给了实际可填的取值；Zed 那份指南在「模型返回错误」这条常见问题里，示例位置放的同样是 <model_id> 这个占位符。把尖括号连同里面的字样原样粘进 Model Name，服务端收到的就不是一个有效的模型标识——具体会返回哪个错误码，官方文档里没有找到相关说明，官方给的处理办法只有一句：确认 Model Name 是否填写正确。所以看到模型侧报错，先回去核一遍这一栏填的是不是真实取值，再去怀疑模型本身。