Claude Code 接入指南 - StepFun 开放平台文档中心

Claude Code 是一个运行在终端中的 AI 编码助手，可以通过自然语言命令完成代码生成、调试、重构和工程管理等任务。通过配置 API 接口，Claude Code 可以将模型调用请求转发到自定义 AI 服务。本文档介绍如何在 Claude Code 中完成 Step API 的接入配置，并验证模型是否可用。

概述

Claude Code 适合偏终端工作流的开发者。完成配置后，可以直接在本地项目中通过自然语言驱动编码任务。

前置条件

操作系统

Claude Code 支持以下系统：

macOS
Linux
Windows（建议使用 PowerShell 或 Windows Terminal）

Node.js 环境

Claude Code 依赖 Node.js 运行，建议安装 Node.js >= 18。不同系统的安装方式示例：

macOS：使用 Homebrew 或 nvm
Linux：使用系统包管理器或 nvm
Windows：使用 Node 官方安装包或 Chocolatey

示例命令：

brew install node
nvm install 18
sudo apt install nodejs npm
choco install nodejs

安装完成后，运行以下命令确认环境：

node -v
npm -v

订阅 Step Plan

在开始配置前，请先确认当前账号已完成 Step Plan 订阅。只有在账号具备对应计划或调用权限后，后续模型调用与额度使用才会正常生效。如需订阅或购买，请访问：Step Plan 订阅

获取 Step API Key

在调用模型前，需要先在 Step 开放平台获取有效的 Step API Key。建议通过控制台创建新的 Key，并避免将其硬编码进代码仓库。推荐做法：

使用环境变量保存 Key
或通过本地配置文件管理 Key

配置步骤

安装 Claude Code

在终端中执行：

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

安装完成后，验证版本：

claude --version

创建配置文件

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

以下命令从公开仓库 Zgh332358/claude-key-setup 下载中文脚本，下载失败时会停止，避免继续运行本地已有的旧脚本。

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
chmod +x configure_claude.sh
bash configure_claude.sh

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

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
irm 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、MCP 等设置。将密钥和模型占位符替换为自己的值。若设置了 CLAUDE_CONFIG_DIR，请使用该目录下的对应配置文件。配置文件位置：

~/.claude/settings.json

如果文件不存在，可以先创建目录和文件：

mkdir -p ~/.claude
touch ~/.claude/settings.json

最小配置，严格 JSON，不含注释：

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

参数说明：

ANTHROPIC_AUTH_TOKEN：填写有效的 Step API Key。Claude Code 使用该字段做认证，不要只更新 ANTHROPIC_API_KEY。
ANTHROPIC_BASE_URL：填写 Step Plan 的配置 Base URL https://api.stepfun.com/step_plan。不要填入完整的 /v1/messages 请求地址；Claude Code 会自动追加 /v1/messages。
model：填写 <MODEL_ID>。请选择当前账号在 Step Plan 下可用、且适合 Claude Code 的模型。文档列出的模型仅为已验证示例，不构成全部可用模型名单；预览模型以当前账号可用列表为准。

已验证示例（请按当前账号权限替换）：step-5-preview、step-3.7-flash、step-3.5-flash-2603、step-3.5-flash。

切换过模型服务？请检查旧配置。此前配置的接口地址、模型或密钥可能仍在生效。请检查终端环境变量、项目配置和启动参数，并在保存配置后，完全退出并重新启动 Claude Code。

可选：将内置模型别名映射到所选模型。以下字段需合并至 env，不能保证覆盖显式指定了其他模型的插件或子任务。请按当前 Claude Code 版本验证后再使用。

{
  "ANTHROPIC_DEFAULT_SONNET_MODEL": "<MODEL_ID>",
  "ANTHROPIC_DEFAULT_OPUS_MODEL": "<MODEL_ID>",
  "ANTHROPIC_DEFAULT_HAIKU_MODEL": "<MODEL_ID>",
  "ANTHROPIC_DEFAULT_FABLE_MODEL": "<MODEL_ID>"
}

首次接入请先完成上方最小配置并验证，再按需加入这些别名。

设置推理强度

step-5-preview 支持 low、medium、high 三档推理强度，最高为 high。在 Claude Code 中接入 Step 5 Preview 时，选择 xhigh 或 max 均按 high 执行，不会启用更高的推理档位。 Claude Code 的选项与 Step 5 Preview 实际执行档位的对应关系如下。请求字段值通过 Claude Code 2.1.209 的 --model step-5-preview 抓包验证，执行档位依据 Step 服务端映射规则：

Claude Code 的 `--effort` 值	请求中的 `output_config.effort`	Step 5 Preview 实际执行档位	接入建议
`low`	`low`	`low`	简单任务，优先速度与较低 token 消耗
`medium`	`medium`	`medium`	一般推理与多步骤任务，建议从此档开始
`high`	`high`	`high`	复杂推理、规划与代码分析

xhigh、max 到 high 的映射由 Step 服务端处理。上述 Claude Code 版本会原样发送这两个值，因此请求中看到 xhigh 或 max，不代表模型在使用高于 high 的档位。该映射说明仅适用于本文的 Claude Code 接入 Step 5 Preview 场景，不应直接套用到其他模型。

完成上方 API Key 与 Base URL 配置后，可在启动时指定本次会话的档位：

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

如需保存默认档位，将以下字段合并到 ~/.claude/settings.json 的顶层，不要放入 env，也不要覆盖已有配置：

{
  "effortLevel": "medium"
}

保存后重新启动 Claude Code。如果实际档位与配置不一致，检查 CLAUDE_CODE_EFFORT_LEVEL 环境变量、启动时的 --effort、会话内选择及项目或组织设置。本文只验证 Step 5 Preview，其他模型的支持范围请查对应模型文档。 Claude Code 使用 Messages 协议，对应字段为 output_config.effort，不是 Chat Completions 协议的 reasoning_effort。更多说明见推理模型最佳实践和 Claude Code 推理强度设置。

开启 1M 上下文

Claude Code 无法识别 step-5-preview 等 Step 模型 ID，会按未识别模型处理，默认上下文为 200k tokens。输入 /context 时可能看到 200k tokens 和 default for an unrecognized model。这不是模型能力上限，而是 Claude Code 的客户端默认值。 step-5-preview 的上下文窗口为 1M tokens。要在 Claude Code 中使用 1M 窗口，请将以下字段合并进 ~/.claude/settings.json 的 env（与已有 Key、Base URL 并存），并把 model 设为 step-5-preview：

{
  "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，查看当前模型、认证方式及加载的配置来源。不同版本展示内容可能不同；该页面不是完整的请求审计记录。若已开启 1M 上下文，再输入 /context，确认窗口不是 200k。
发送「只回复 OK」，验证基础对话。
在临时测试目录中要求创建一个最小 hello.py，并按客户端权限提示批准必要操作，验证工具调用。操作被用户拒绝应标为未完成验证，而非 API 故障。
在控制台查看对应请求的通道和用量记录；如信息不足，携带 request ID 联系支持确认。

/status

确认以下信息与预期一致：

认证方式已加载 Step API Key（ANTHROPIC_AUTH_TOKEN）
配置 Base URL 为 https://api.stepfun.com/step_plan
当前模型为您填写的 <MODEL_ID>（推荐验证示例：step-5-preview）
若已开启 1M 上下文，/context 显示的窗口接近 1M，而不是 200k tokens

基础对话示例：

只回复 OK

工具调用示例（请在临时测试目录中执行）：

write a minimal python hello world program into hello.py

常见问题

修改配置后不生效

请完全退出并重新启动 Claude Code，然后输入 /status 查看当前模型、认证方式和配置来源。若与预期不一致，请按以下顺序排查：

检查项目配置与启动参数是否覆盖了用户级 ~/.claude/settings.json。
检查 ANTHROPIC_MODEL 是否覆盖配置文件中的 model。
若设置了 CLAUDE_CONFIG_DIR，确认编辑的是该目录下的配置文件。
校验 settings.json 为可解析的严格 JSON。
对组织强制设置，请联系管理员。

API Key 无效

报错示例：

401 invalid_api_key

接入 Step 时，请将有效的 Step API Key 填入 ANTHROPIC_AUTH_TOKEN。如果同时配置了 ANTHROPIC_API_KEY，Claude Code 会优先使用 ANTHROPIC_AUTH_TOKEN；仅更新 ANTHROPIC_API_KEY，可能仍在使用旧密钥。请确认 ANTHROPIC_AUTH_TOKEN 已更新，并重新启动 Claude Code。其他可能原因：

API Key 输入错误、已过期或被删除
账号、组织或网关策略拒绝该请求，请按实际错误信息处理

地址错误

Claude Code / Anthropic SDK 的 Step Plan 配置 Base URL 为 https://api.stepfun.com/step_plan，完整请求地址为 POST https://api.stepfun.com/step_plan/v1/messages。请对照完整 URL，排除重复 /v1、重复 /messages。不要通过删除 /step_plan 来「修复」套餐接入，因其会切换到普通 API 通道。

`/context` 显示 200k

Claude Code 不识别 Step 模型 ID，未声明窗口时会按 200k 处理。请确认 ~/.claude/settings.json 的 env 中已写入 CLAUDE_CODE_MAX_CONTEXT_TOKENS 和 CLAUDE_CODE_AUTO_COMPACT_WINDOW，值均为 "1000000"，然后完全退出并重新启动 Claude Code。官方脚本默认不会写入这两项。

模型不存在

报错示例：

model does not exist

请检查实际使用的模型、当前账号授权、目标通道和子任务模型；以服务端返回为准。客户端不识别自定义模型的提示不等于服务端拒绝。文档中的示例模型不构成全部可用名单。

配额不足

报错示例：

402 quota_exceeded

请先确认请求实际进入的通道，再按后端错误处理：Step Plan 订阅状态或 Credit 问题，请查看套餐或加油包；普通 API 余额不足，请查看账户余额。不要把两类额度问题都当成「充值或升级套餐」。

仍需帮助？

请提供客户端版本、错误信息、发生时间及脱敏后的配置；如有 request ID，请一并提供。请勿发送完整 API Key。

总结

完成配置后，Claude Code 即可在终端中通过 Step Plan 通道发起模型调用，用于代码生成、调试和开发流程自动化。建议先用 /status、基础对话和最小工具任务分别验证，再进入真实项目使用。

​概述

​前置条件

​操作系统

​Node.js 环境

​订阅 Step Plan

​获取 Step API Key

​配置步骤

​安装 Claude Code

​创建配置文件

​设置推理强度

​开启 1M 上下文

​启动 Claude Code

​测试接入

​常见问题

​修改配置后不生效

​API Key 无效

​地址错误

​/context 显示 200k

​模型不存在

​配额不足

​仍需帮助？

​总结

概述

前置条件

操作系统

Node.js 环境

订阅 Step Plan

获取 Step API Key

配置步骤

安装 Claude Code

创建配置文件

设置推理强度

开启 1M 上下文

启动 Claude Code

测试接入

常见问题

修改配置后不生效

API Key 无效

地址错误

`/context` 显示 200k

模型不存在

配额不足

仍需帮助？

总结