> ## Documentation Index
> Fetch the complete documentation index at: https://platform.stepfun.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Code

本文介绍如何在 Claude Code 中通过 [Messages API](/docs/zh/api-reference/chat/messages-create) 接入 Step 模型，配置 Step Plan、推理强度与 1M 上下文，并验证对话和工具调用。

## 接入条件

### 运行环境

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

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

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
node -v
npm -v
```

### 订阅 Step Plan

确认 [Step Plan 订阅](https://platform.stepfun.com/step-plan)有效、额度可用，且具备所用模型的调用权限。本文配置示例使用 Step Plan 通道。

### 获取 Step API Key

前往 [Step 开放平台密钥管理](https://platform.stepfun.com/interface-key)页面创建 API Key。

## 配置步骤

### 安装 Claude Code

在终端中执行：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
npm install -g @anthropic-ai/claude-code
```

安装完成后，验证版本：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
claude --version
```

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

### 创建配置文件

<Tabs>
  <Tab title="通过官方脚本快速配置">
    以下命令从 Step 官方仓库 `stepfun-ai/Step-Cookbook` 下载中文脚本，下载成功后才执行。

    macOS / Linux / WSL（Bash）

    请先安装 `jq`，脚本使用它更新 JSON 配置。

    ```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
    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 即可，无需管理员权限。

    ```powershell theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
    & {
      $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` 中的额外变量会被移除。
  </Tab>

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

    ```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
    {
      "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`。任务显式指定的模型需单独核对。

    ```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
    {
      "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。
  </Tab>
</Tabs>

### 设置推理强度

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

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

调用 Step 5 Preview 时，`xhigh` 和 `max` 由 Step 服务端映射为 `high`。Claude Code 通过 Messages API 的 `output_config.effort` 传入该设置。

启动时指定本次会话的推理强度：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
claude --model step-5-preview --effort medium
```

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

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "effortLevel": "medium"
}
```

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

### 开启 1M 上下文

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

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "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

进入任意代码项目目录：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
cd your-project
```

启动 Claude Code：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
claude
```

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

## 测试接入

### 验证客户端对话

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

### 验证 Agent 工具调用

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

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

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

### 核对用量与路由

在 [Step 开放平台](https://platform.stepfun.com)按请求时间、模型与响应 ID 核对调用记录，确认使用 Step Plan 通道及对应额度。

## 常见问题

<AccordionGroup>
  <Accordion title="Q: 修改配置后不生效怎么办？">
    重启后使用 `/status` 核对模型、认证与配置来源，依次检查项目配置、`--model`、`ANTHROPIC_MODEL`、`CLAUDE_CONFIG_DIR` 及组织设置。确认 `settings.json` 是有效 JSON。

    以下 Bash / jq 命令只显示相关配置和密钥是否存在，不输出密钥值：

    ```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
    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"
    ```
  </Accordion>

  <Accordion title="Q: 返回 401 invalid_api_key 怎么办？">
    将有效的 Step API Key 填入 `ANTHROPIC_AUTH_TOKEN`，检查密钥是否输入错误、被撤销或属于其他站点。若同时设置 `ANTHROPIC_API_KEY`，不要仅更新它而保留旧的 `ANTHROPIC_AUTH_TOKEN`。

    曾通过 `/login` 登录其他账号时，先使用 `/status` 核对凭据来源；需要退出该登录态时，执行 `/logout` 后重启，再验证 Step 配置。
  </Accordion>

  <Accordion title="Q: 如何单独检查 Messages API 连通性？">
    先通过 curl 检查端点、密钥和模型。以下命令适用于 Bash / Zsh；Windows 可在 WSL 或 Git Bash 中运行。

    ```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
    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`，应提高输出预算后重试。
  </Accordion>

  <Accordion title="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` 查看日志。
  </Accordion>

  <Accordion title="Q: 后台任务或子 Agent 报模型错误怎么办？">
    检查 `ANTHROPIC_DEFAULT_HAIKU_MODEL`、`ANTHROPIC_DEFAULT_FABLE_MODEL`、`CLAUDE_CODE_SUBAGENT_MODEL` 及任务中显式指定的模型，确认它们使用可用的 Step 模型 ID。相关字段见上文配置项说明。
  </Accordion>

  <Accordion title="Q: /context 仍显示 200k 怎么办？">
    确认正在使用 `step-5-preview`，配置目录正确，且 `env` 中的 `CLAUDE_CODE_MAX_CONTEXT_TOKENS` 和 `CLAUDE_CODE_AUTO_COMPACT_WINDOW` 均为 `"1000000"`。完全退出并重启后再检查。官方脚本默认不写入这两项。
  </Accordion>

  <Accordion title="Q: 返回 model does not exist 怎么办？">
    核对模型 ID、当前账号权限、目标通道以及子任务模型。客户端提示不识别自定义模型，不等于服务端拒绝该模型；以具体请求错误为准。
  </Accordion>

  <Accordion title="Q: 返回 402 quota_exceeded 怎么办？">
    先确认请求通道。Step Plan 通道检查订阅和 Credit；普通 API 通道检查账户余额或额度。
  </Accordion>
</AccordionGroup>

若仍需帮助，请提供客户端版本、错误信息、发生时间、脱敏配置及请求 ID，通过[技术支持](/docs/zh/guides/contact-us)进一步排查。

## 相关文档

* [Messages API](/docs/zh/api-reference/chat/messages-create)
* [Step 5 Preview](/docs/zh/guides/models/step-5-preview)
* [Step Plan 概述](/docs/zh/step-plan/overview)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.