在 Claude Code 里配阶跃星辰：Base URL 与模型名怎么填

2026-08-25

数据截至 2026-08，价格与限额以各官网为准。本文只讲计费与接入机制，不列具体价格数字。

在 Claude Code 里接阶跃星辰，本质上只是往 ~/.claude/settings.json 的 env 段里塞两个变量：ANTHROPIC_AUTH_TOKEN 填 Step API Key，ANTHROPIC_BASE_URL 填 Step Plan 的专用地址，再用顶层 model 字段指定模型名。这三行 JSON 里被官方专门加了注意框的一处，是 Base URL 到底带不带 /v1——阶跃官方文档在这件事上给了两个不同的地址：OpenAI 兼容协议的工具填带 /v1 的那个，而 Claude Code 走的是 Anthropic Messages 协议，配置文件里要填不带 /v1 的那个，因为 Claude Code 会自己拼上 /v1/messages。另外一层是 Step Plan 通道和普通 API 通道的地址不是同一个，官方在常见问题里明写「使用错误地址会导致请求报错」。下面按官方文档给的顺序走一遍：先订阅再拿 Key，然后装工具、改配置、用 /status 自查，最后是报错对照表。

动手之前：Step Plan 订阅和 API Key 是两件事

阶跃官方的 Claude Code 接入指南把「订阅 Step Plan」单列成了前置条件，这一点值得先说清楚：Step Plan 是阶跃星辰开放平台推出的订阅制服务，官方的定位是让你在 OpenClaw、Claude Code、Trae、Cursor 这类编码工具与智能体平台里，以订阅形式调用阶跃的旗舰模型；订阅之后拿到的是专用 API Key，按月获得统一的模型调用额度。

所以顺序不能反。官方在快速开始页给的建议顺序是：先确认账号已订阅或已开通 Step Plan，再去创建 API Key，最后才接入具体工具。如果你的账号是被团队统一开通的，那可以直接跳到创建 Key 这一步。

Key 的获取入口在开放平台的接口密钥页。官方在这里给了一句很朴素但很关键的建议：建议在控制台新建一个 Key，并且不要把它硬编码进代码仓库，推荐用环境变量保存，或者放在本地配置文件里管理。这个提醒对 Claude Code 场景尤其实在——~/.claude/settings.json 本身就在用户目录下，不在项目仓库里，天然避开了误提交；但如果你图省事把配置写进项目级的配置文件再一起提交，那就是另一回事了。关于密钥这一层的通用做法，可以参考 API Key 安全管理的通用清单。

还有一点：如果你用的是企业组织下的项目 API Key，官方说明是「项目下 API Key 的使用方式与个人 API Key 一致，不需要额外传递组织或项目标识」——也就是说 Claude Code 这边的配置写法完全不变，差别只体现在费用从组织的 Credit 账户扣减，以及后面会讲到的那几个额度类错误标识上。

装 Claude Code：官方文档给了两条配置路径

环境这一层，官方列出支持 macOS、Linux 和 Windows，Windows 那条后面还专门加了括号，建议用 PowerShell 或 Windows Terminal。运行时依赖 Node.js，官方文档里写的是建议安装的最低版本（以官方文档当前版本为准），并给了各系统下用 Homebrew、nvm、系统包管理器、Chocolatey 安装的示例命令，装完用 node -v 和 npm -v 确认一下。

Claude Code 本体用 npm 全局安装 @anthropic-ai/claude-code，装完执行 claude --version 验证。

到了写配置这一步，官方文档给了两个并列的标签页：一个是「通过官方脚本快速配置」，macOS 与 Linux 下是下载一个 shell 脚本再执行，Windows 下是在 PowerShell 里拉取对应的 ps1 脚本；另一个是「手动编辑配置文件」。官方特别标注了 Windows 那条：必须在管理员模式的 PowerShell 下运行，否则脚本会提示并退出。

我更推荐手动那条路。倒不是脚本有什么问题，而是手动改一遍你才知道这套接入到底改了什么——它一共就改了三个键，出问题的时候你能自己定位，而不是重跑一遍脚本碰运气。

手动配置：三个键，一个都不能填错

配置文件位置是用户目录下的 ~/.claude/settings.json。文件不存在就先 mkdir -p ~/.claude 再 touch 出来。官方给的内容结构是这样：

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY",
    "ANTHROPIC_BASE_URL": "https://api.stepfun.com/step_plan"
  },
  "model": "<model_id>"
}

官方对这三项的说明是：ANTHROPIC_AUTH_TOKEN 填你的 Step API Key，ANTHROPIC_BASE_URL 填 Base URL，model 填模型 ID。保存之后，官方建议重新打开终端让配置生效。

注意 env 是个嵌套对象，model 是顶层键，不在 env 里面。这类 JSON 结构写错了不会有友好提示，Claude Code 只会表现成「配置像是没读到」。

Base URL 带不带 /v1：官方专门为它加了一条注意

阶跃官方在快速开始页把这件事拆得很清楚，值得原样记住：

Chat Completions API（OpenAI 兼容）的 Base URL 是 https://api.stepfun.com/step_plan/v1
Messages API（Anthropic 兼容）的 Base URL 是 https://api.stepfun.com/step_plan

官方在快速开始页专门加了一条注意：Claude Code 手动编辑配置文件时，ANTHROPIC_BASE_URL 应填 Messages API 对应的那个不带 /v1 的地址，因为 Claude Code 会在调用时自动拼接 /v1/messages。你要是自作主张补上 /v1，路径就变成了双份，官方错误码表里 404 对应的原因正是「请求路径不正确」。

第二层区别是通道。Step Plan 概述页写得很直白：订阅后要把 Base URL 配置为 Step Plan 专用地址 https://api.stepfun.com/step_plan/v1，并在后面用括号补了一句注意区别于普通 API 的 https://api.stepfun.com/v1。这里要留意一个容易读串的地方：概述页给的这个对照，是 OpenAI 兼容协议下的写法，两个地址都带 /v1，差别只在域名后多不多 step_plan 那一段；而 Claude Code 走的是 Anthropic Messages 协议，在此基础上还要把尾部的 /v1 去掉。换句话说，你要同时对两件事负责——路径里有没有 step_plan，以及协议对不对得上尾部的 /v1。官方在常见问题里把「Base URL 是否使用了专用地址」直接标成了常见问题点，排在第三方工具接入报错排查的第一条。

那么地址填错的后果是什么？官方在常见问题里给的是一句话：「使用错误地址会导致请求报错」；接入指南里也把「Base URL 指向错误接口」列进了 model does not exist 的可能原因。也就是说，官方描述的表现是请求失败，而不是悄悄换了一个地方扣钱——这两条通道之间的账目关系，官方另有明确说法：「两者是相互独立的体系」「两者使用不同的 Base URL，互不影响」，并且「使用 Step Plan 内功能消耗的是订阅自身的 Credit 额度，不会扣除账户余额」。Step Plan 这边是订阅制、以月度 Credit 额度提供用量，Credit 一次性发放到当月月池，月内任意时段消耗。把这两句话合起来读，实际的操作结论很朴素：地址错了你会先在终端里看到报错，而不是先在账单上看到异常，所以排查顺序应该是先修地址、再去核对用量。想系统看一眼调用花在哪，可以配合 API 成本监控的通用做法。

模型名填什么

官方文档在示例里用的是占位符 <model_id>，并在下面给了说明：本文示例中的 <model_id> 可填写为 step-3.7-flash、step-3.5-flash-2603 或 step-3.5-flash。快速开始页则给了一个更明确的建议：首次接入时推荐优先用 step-3.7-flash 完成验证。

这里有个和 Claude Code 关系不大但值得知道的细节：阶跃的智能路由模型 step-router-v1，官方说明是仅可通过 Step Plan 通道调用，系统会在两个后端模型之间自动路由；而且这个模型在该通道下有一组额外的字段约束，比如 model 只接受它自己的名字、消息内容里的图像块与文档块不支持、tools 里的 web_search 不支持、output_config.effort 字段会被忽略、max_tokens 有上限（具体数值以官方文档当前版本为准）。这些约束在纯代码任务里未必碰得到，但一旦你在 Claude Code 里贴图让它看截图，就会撞上官方为图像块/文档块标注的返回：unsupported_content_type。同一个错误标识，官方也用在 tools 里传了 web_search 的场景；而填错模型名走的是另一条，官方标的是 HTTP 400 request_params_invalid。

验证：先 /status，再来一个最小任务

配置完进任意项目目录，跑 claude 启动。官方提到首次启动时可能出现一句关于是否使用该 API key 的确认提示，选 Yes 即可。

进去之后官方给的第一步是执行 /status 查看当前配置状态，需要确认三件事：API Key 已加载、Base URL 正确、默认模型名称正确。这一步别跳——它不需要发起一次真实的模型调用，就能把「配置到底读进去没有」当场看清楚，而且这三项正好一一对应 settings.json 里的三个键，哪一项显示不对，就回去改哪一行。

确认无误后，官方给的验证指令是让它写一个最小的 Python hello world 文件。判据也说得很清楚：如果 Claude Code 成功创建文件并写入了代码，就说明模型接入成功。用一个会落盘的任务而不是纯聊天来验证，是有道理的：聊天只验证了对话通路，创建文件同时验证了工具调用链路能跑通。

报错对照：四类返回分别指向什么

官方在接入指南的「常见问题」里给了几组典型报错，配合平台的错误码表看会更完整。

模型不存在。报错文本形如 model does not exist。官方给的三个可能原因是：模型名称填写错误、当前账号没有该模型权限、Base URL 指向了错误的接口。第三条值得单独拎出来说：官方在这里把「应为 https://api.stepfun.com/step_plan」直接写进了原因说明，也就是说模型名报错未必真是模型名的锅，先回头看一眼 Base URL 往往更省事。

API Key 无效。报错形如 401 invalid_api_key。官方列的原因是：Key 输入错误、Key 已过期或被删除、Key 与当前 API 域名不匹配。最后这条只有官方这一句原文，没有更细的解释：官方文档里没有找到「Step Plan 与普通 API 是两把不同的密钥」这样的说明——接入指南和快速开始页给的 Key 创建入口是同一个开放平台接口密钥页，概述页也只说「订阅后通过专用 API Key 接入」。所以遇到这条别急着去申请第二把 Key，先按快速开始页常见检查项的第一条核对：「API Key 是否填写正确且属于正确环境」，再对照上面那条把 Base URL 和协议对上号。平台错误码表里 401 的统一解释是「认证无效」，处理方式是确保使用正确的 API 密钥。

配额不足。报错形如 402 quota_exceeded，官方的解释是当前账户调用额度已用完，需要补充余额或升级套餐。错误码表里 402 对应「余额不足」。如果你用的是企业组织下的项目 Key，402 还有一个更具体的错误标识 insufficient_credit，含义是组织的 Credit 账户余额不足，官方给的处理路径是由主账号补充。

429 要看错误标识。这条官方讲得很细，因为两件性质完全不同的事共用了同一个状态码：额度上限与速率限制返回的状态码同为 429，所以收到 429 时必须靠错误标识区分。组织场景下的两个标识分别是 project_credit_limit_exceeded（项目达到当期 Credit 上限）和 member_project_credit_limit_exceeded（成员在该项目内达到当期上限），官方给的解法都是由主账号调高上限，或者等下月 1 号重置。而普通的 429，错误码表里的描述是请求发送太快超过了速率限制，处理方式是稍候重试。别看到 429 就无脑加退避重试——如果它是额度上限那一类，重试多久都不会自己好。429 的通用处理姿势可以看 429 该怎么处理。

顺带一提，Step Plan 在限流这件事上有个官方明确的例外：常见问题里写了 Step Plan 不适用开放平台按累计充值金额划分的阶梯限速，用量由所订阅档位的月度 Credit 额度管理。

改了配置不生效。官方给的排查顺序是三条：Claude Code 是否已完全重启、配置文件 JSON 格式是否正确、终端环境变量是否已经刷新。顺序别打乱：前两条是本地就能自查的静态问题，第三条才需要动终端会话。JSON 格式这一条尤其值得认真对待，因为 settings.json 写坏了不会有友好提示，表现出来只会是「配置像是没读到」。

顺手把 StepSearch MCP 挂上

既然已经在 Claude Code 里了，阶跃的官方 MCP Server 可以一并配掉。官方说明是：Step Plan 支持 MCP，首个官方 MCP Server 是 StepSearch，提供 web_search 与 web_fetch 两个工具，可在 Claude Code、Cline、OpenCode 等兼容 MCP 的客户端中使用。它是基于 HTTP 协议的远程服务，官方注明无需本地安装。

Claude Code 这边官方给了一条一键安装命令（claude mcp add 加上 http 类型、服务 URL 和一个带 Bearer 前缀的 Authorization 头），也给了手动写 ~/.claude.json 的 mcpServers 段的等价配置。注意这个文件和前面的 ~/.claude/settings.json 不是同一个。

官方文档里还附了一个挺实用的用法：在项目的 .claude/agents/ 目录下建一个搜索专用 Sub-Agent 定义文件，把 tools 限定为那两个 MCP 工具，再在项目 CLAUDE.md 里写清什么时候该调用它——官方给的判断标准是，涉及最新版本、安全漏洞、定价限额这类模型知识覆盖不到的实时信息时才用，模型能直接回答的基础语法和选型问题就别浪费一次搜索。

计费上要注意两点，官方写得很明确：web_search 按开放平台网络搜索的计价方式收费（具体单价见官方定价页），并与 Step Plan 的其他用量一并消耗 Credit 额度；web_fetch 不单独计费。也就是说搜索不是白送的，它和你的编码调用共用同一个月池。限流方面官方说的是以 QPM / QPH / 并发控制为主，并对单用户增加必要限频。

排查上，官方对「访问令牌无效」给的三条是：确认 Key 完整复制没有多余空格、确认 Key 已激活且余额充足、检查 Authorization 头格式是否正确——需要包含 Bearer 前缀，注意那个空格。这个空格问题在手写 JSON 配置时格外容易中招。

最后：老套餐用户先看一眼升级公告

如果你的 Claude Code 之前就已经接过阶跃、最近却开始不对劲，别急着改配置，先去看升级公告。官方说明是 Step Plan 已升级为 Credit 月池计费，新套餐叫 Token Plan；旧版 Coding Plan 当前周期权益不受影响，已开启自动续费的可以继续按旧套餐自动续订，未开启自动续费的到期后需要升级才能继续用。官方还标了一条硬约束：升级至 Token Plan 是单向操作，确认后不可回退，而且 Coding Plan 一旦到期未续或被取消，就无法重新订购。

计费模型本身的差别也值得知道：旧套餐按请求次数计、按时段或周限额，额度用尽即切断；新套餐以 Credit 为统一单位按月发放，月内任意时段消耗、月末清零不结转，用尽后可以加购加油包补充，加油包有自己独立的有效周期。这个「月末清零」的设计意味着，把重活拖到月底集中做，和均摊到全月做，成本感受是不一样的。

真要按一个顺序收尾的话：先确认订阅状态 → 建新 Key → 写 settings.json 三个键 → 重点检查 Base URL 没多带 /v1、也没漏掉 step_plan 那一段 → 重启终端 → /status 自查 → 最小任务验证。这七步里第四步值得多花两分钟：Base URL 这件事，官方在快速开始页专门加了注意框、在概述页用括号做了对照、又在常见问题的排查清单里排到第一条，是全篇被重复强调次数最多的一项。如果你还在同时评估别家的 Anthropic 兼容通道，可以对照看看用 Anthropic SDK 接入 MiniMax 的官方接法——同样是 Messages 协议，各家在 base_url 拼接约定上的差异，是迁移时值得逐字比对一遍的地方。