Claude Code

本文介绍如何在 Claude Code 中通过 Messages API 接入 Step 模型，配置 Step Plan、推理强度与 1M 上下文，并验证对话和工具调用。

接入条件

运行环境

macOS、Linux 或 Windows。Windows 可使用 PowerShell，也可在 WSL 中运行。
本文采用 npm 安装方式，需要 Node.js 22 或更高版本；已使用原生安装包安装 Claude Code 的用户可跳过 npm 安装。

使用 npm 安装前，确认 Node.js 与 npm 可用：

node -v
npm -v

订阅 Step Plan

确认 Step Plan 订阅有效、额度可用，且具备所用模型的调用权限。本文配置示例使用 Step Plan 通道。

获取 Step API Key

前往 Step 开放平台密钥管理页面创建 API Key。

配置步骤

安装 Claude Code

在终端中执行：

npm install -g @anthropic-ai/claude-code

安装完成后，验证版本：

claude --version

兼容性验证版本：Claude Code 2.1.209。安装命令获取最新版；模型别名解析和上下文管理可能因版本不同而变化。

创建配置文件

通过官方脚本快速配置
手动编辑配置文件

以下命令从 Step 官方仓库 stepfun-ai/Step-Cookbook 下载中文脚本，下载成功后才执行。macOS / Linux / WSL（Bash）请先安装 jq，脚本使用它更新 JSON 配置。

curl -fsSL https://raw.githubusercontent.com/stepfun-ai/Step-Cookbook/main/scripts/claude-key-setup/zh-CN/configure_claude.sh -o configure_claude.sh &&
  bash configure_claude.sh

Windows（普通 PowerShell）使用当前用户的普通 PowerShell 即可，无需管理员权限。

& {
  $ErrorActionPreference = "Stop"
  Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
  Invoke-WebRequest -Uri "https://raw.githubusercontent.com/stepfun-ai/Step-Cookbook/main/scripts/claude-key-setup/zh-CN/configure_claude.ps1" -OutFile "configure_claude.ps1"
  & .\configure_claude.ps1
}

接入 Step Plan 时，请在脚本菜单中选择 2，输入 API Key，并选择模型（默认 step-5-preview）。选择 1 会使用普通 API 通道。脚本会备份已有配置并替换整个 env 对象，保留 hooks、theme 等其他顶层字段；原 env 中的额外变量会被移除。

将以下字段合并到用户级配置文件 ~/.claude/settings.json，保留已有的 permissions、hooks 等设置。Windows 对应 %USERPROFILE%\.claude\settings.json；若设置了 CLAUDE_CONFIG_DIR，使用该目录下的 settings.json。文件不存在时先创建目录，再保存以下 JSON，将 YOUR_STEP_API_KEY 替换为实际密钥：

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "YOUR_STEP_API_KEY",
    "ANTHROPIC_BASE_URL": "https://api.stepfun.com/step_plan"
  },
  "model": "step-5-preview"
}

模型 ID 可填写 step-5-preview、step-3.7-flash、step-3.5-flash-2603 或 step-3.5-flash。

配置项说明

字段	位置	用途
`ANTHROPIC_AUTH_TOKEN`	`env`	Step API Key，用于请求认证。
`ANTHROPIC_BASE_URL`	`env`	配置为 `https://api.stepfun.com/step_plan`，Claude Code 自动追加 `/v1/messages`。
`model`	顶层	主会话模型；启动参数 `--model` 或环境变量 `ANTHROPIC_MODEL` 可覆盖此项。
`ANTHROPIC_DEFAULT_OPUS_MODEL` 等	`env`，可选	将内置模型档位映射到 Step 模型。
`CLAUDE_CODE_SUBAGENT_MODEL`	`env`，可选	设置子 Agent 模型。
`CLAUDE_CODE_MAX_CONTEXT_TOKENS`	`env`，可选	覆盖客户端对自定义模型的上下文窗口估计。
`CLAUDE_CODE_AUTO_COMPACT_WINDOW`	`env`，可选	设置自动压缩使用的窗口，不超过模型上下文窗口。

可选：将以下模型别名和子 Agent 配置合并到 env。任务显式指定的模型需单独核对。

{
  "ANTHROPIC_DEFAULT_SONNET_MODEL": "step-5-preview",
  "ANTHROPIC_DEFAULT_OPUS_MODEL": "step-5-preview",
  "ANTHROPIC_DEFAULT_HAIKU_MODEL": "step-5-preview",
  "ANTHROPIC_DEFAULT_FABLE_MODEL": "step-5-preview",
  "CLAUDE_CODE_SUBAGENT_MODEL": "step-5-preview"
}

首次接入先验证最小配置，再按需加入别名与子 Agent 设置。若后台任务仍请求内置模型名，请核对该任务显式指定的模型。同名变量同时出现在配置文件 env 和终端环境时，配置文件中的值会覆盖终端值。切换服务后，请一并检查用户配置、项目配置及 .zshrc / .bashrc 中的旧地址和密钥，保存后重新启动 Claude Code。

设置推理强度

step-5-preview 支持以下推理强度：

—effort	适用任务
`low`	简单任务，优先速度与较低 token 消耗。
`medium`	一般推理与多步骤任务。
`high`	复杂推理、规划与代码分析。

调用 Step 5 Preview 时，xhigh 和 max 由 Step 服务端映射为 high。Claude Code 通过 Messages API 的 output_config.effort 传入该设置。启动时指定本次会话的推理强度：

claude --model step-5-preview --effort medium

保存默认档位时，将 effortLevel 合并到 ~/.claude/settings.json 顶层，而不是 env：

{
  "effortLevel": "medium"
}

保存后重启 Claude Code。若设置未生效，检查 CLAUDE_CODE_EFFORT_LEVEL、启动参数及项目或组织设置。

开启 1M 上下文

step-5-preview 的模型上下文窗口为 1M tokens。若 /context 将其显示为未识别模型并按 200k 计算，将以下字段合并到 ~/.claude/settings.json，保留已有配置：

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "YOUR_STEP_API_KEY",
    "ANTHROPIC_BASE_URL": "https://api.stepfun.com/step_plan",
    "CLAUDE_CODE_MAX_CONTEXT_TOKENS": "1000000",
    "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "1000000"
  },
  "model": "step-5-preview"
}

说明：

CLAUDE_CODE_MAX_CONTEXT_TOKENS：告诉 Claude Code 按 1M 窗口计算用量。必须写纯数字 1000000，不要写成 1M 或 1000k。
CLAUDE_CODE_AUTO_COMPACT_WINDOW：将自动压缩窗口对齐到 1M。取值范围为 100000–1000000，同样只接受纯数字；客户端仍会预留输出与内部处理空间，可能在窗口填满前压缩。
保存后完全退出并重新启动 Claude Code，再输入 /context 确认窗口已接近 1M，而不再是 200k。
声明大于 200k 后，启动时可能出现「200K limit isn’t enforced」类提示，属于预期行为。

通过官方脚本接入时，脚本不会自动写入上述两个字段，需要手动补进 env。

启动 Claude Code

进入任意代码项目目录：

cd your-project

启动 Claude Code：

claude

首次启动时若出现 Do you want to use this API key?，选择 Yes 即可。

测试接入

验证客户端对话

保存配置，完全退出并重新启动 Claude Code。
输入 /status，核对模型、认证方式和配置来源。
发送「只回复 OK」，检查返回内容与流式输出。

验证 Agent 工具调用

在安装了 Python 的独立测试目录中，先创建一个输出 Hello, world! 的 hello.py，再向 Claude Code 发送：

读取当前目录中的 hello.py，把它改成接受命令行参数 name。
未传参数时输出 Hello, Step5；传入 Ada 时输出 Hello, Ada。
使用本机可用的 Python 解释器分别运行这两种情况，检查输出。
如果验证失败，根据报错修正后重新运行。不要修改其他文件。
完成后汇报文件变更、执行的命令和运行结果。

按权限提示批准必要操作，核对读取、修改、运行的工具记录及两次输出。随后继续提问，确认会话保留任务上下文。

核对用量与路由

在 Step 开放平台按请求时间、模型与响应 ID 核对调用记录，确认使用 Step Plan 通道及对应额度。

常见问题

Q: 修改配置后不生效怎么办？

重启后使用 /status 核对模型、认证与配置来源，依次检查项目配置、--model、ANTHROPIC_MODEL、CLAUDE_CONFIG_DIR 及组织设置。确认 settings.json 是有效 JSON。以下 Bash / jq 命令只显示相关配置和密钥是否存在，不输出密钥值：

jq '{model, base_url: .env.ANTHROPIC_BASE_URL, context_window: .env.CLAUDE_CODE_MAX_CONTEXT_TOKENS, compact_window: .env.CLAUDE_CODE_AUTO_COMPACT_WINDOW, has_auth_token: (.env.ANTHROPIC_AUTH_TOKEN != null), has_api_key: (.env.ANTHROPIC_API_KEY != null)}' "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/settings.json"

Q: 返回 401 invalid_api_key 怎么办？

将有效的 Step API Key 填入 ANTHROPIC_AUTH_TOKEN，检查密钥是否输入错误、被撤销或属于其他站点。若同时设置 ANTHROPIC_API_KEY，不要仅更新它而保留旧的 ANTHROPIC_AUTH_TOKEN。曾通过 /login 登录其他账号时，先使用 /status 核对凭据来源；需要退出该登录态时，执行 /logout 后重启，再验证 Step 配置。

Q: 如何单独检查 Messages API 连通性？

先通过 curl 检查端点、密钥和模型。以下命令适用于 Bash / Zsh；Windows 可在 WSL 或 Git Bash 中运行。

export STEP_API_KEY="YOUR_STEP_API_KEY"

curl --silent --show-error --fail-with-body \
  --write-out '\nHTTP %{http_code}\n' \
  https://api.stepfun.com/step_plan/v1/messages \
  -H "Authorization: Bearer ${STEP_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "step-5-preview",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Reply only with OK."}]
  }'

通过条件：HTTP 200，响应 type 为 message，content 中有包含 OK 的 text 块。若只有 thinking 块，且 stop_reason 为 max_tokens，应提高输出预算后重试。

Q: 地址错误或 curl 成功但 Claude Code 失败怎么办？

Claude Code 在 ANTHROPIC_BASE_URL 后自动追加 /v1/messages。按下表检查地址：

ANTHROPIC_BASE_URL	请求路径	说明
`https://api.stepfun.com/step_plan`	`/step_plan/v1/messages`	Step Plan Messages 通道。
`https://api.stepfun.com/step_plan/v1`	`/step_plan/v1/v1/messages`	重复 `/v1`，地址错误。
`https://api.stepfun.com/step_plan/v1/messages`	`/step_plan/v1/messages/v1/messages`	重复接口路径，地址错误。
`https://api.stepfun.com`	`/v1/messages`	普通按量付费 API，不使用 Step Plan 额度。

若 curl 正常而客户端失败，检查项目配置或用户配置是否覆盖了终端变量。需要进一步排查时，使用 claude --debug 查看日志。

Q: 后台任务或子 Agent 报模型错误怎么办？

检查 ANTHROPIC_DEFAULT_HAIKU_MODEL、ANTHROPIC_DEFAULT_FABLE_MODEL、CLAUDE_CODE_SUBAGENT_MODEL 及任务中显式指定的模型，确认它们使用可用的 Step 模型 ID。相关字段见上文配置项说明。

Q: /context 仍显示 200k 怎么办？

确认正在使用 step-5-preview，配置目录正确，且 env 中的 CLAUDE_CODE_MAX_CONTEXT_TOKENS 和 CLAUDE_CODE_AUTO_COMPACT_WINDOW 均为 "1000000"。完全退出并重启后再检查。官方脚本默认不写入这两项。

Q: 返回 model does not exist 怎么办？

核对模型 ID、当前账号权限、目标通道以及子任务模型。客户端提示不识别自定义模型，不等于服务端拒绝该模型；以具体请求错误为准。

Q: 返回 402 quota_exceeded 怎么办？

先确认请求通道。Step Plan 通道检查订阅和 Credit；普通 API 通道检查账户余额或额度。

若仍需帮助，请提供客户端版本、错误信息、发生时间、脱敏配置及请求 ID，通过技术支持进一步排查。

工具接入

迁移

文本与推理

请求与上下文

Agent 与工具

文件与知识

视觉理解

语音

开发工具

示例与 Cookbook

错误与排障

接入条件

运行环境

订阅 Step Plan

获取 Step API Key

配置步骤

安装 Claude Code

创建配置文件

配置项说明

设置推理强度

开启 1M 上下文

启动 Claude Code

测试接入

验证客户端对话

验证 Agent 工具调用

核对用量与路由

常见问题

相关文档

​接入条件

​运行环境

​订阅 Step Plan

​获取 Step API Key

​配置步骤

​安装 Claude Code

​创建配置文件

​配置项说明

​设置推理强度

​开启 1M 上下文

​启动 Claude Code

​测试接入

​验证客户端对话

​验证 Agent 工具调用

​核对用量与路由

​常见问题

​相关文档

接入条件

运行环境

订阅 Step Plan

获取 Step API Key

配置步骤

安装 Claude Code

创建配置文件

配置项说明

设置推理强度

开启 1M 上下文

启动 Claude Code

测试接入

验证客户端对话

验证 Agent 工具调用

核对用量与路由

常见问题

相关文档