> ## 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.

# Cursor

本文介绍如何将 StepFun 模型接入 Cursor，在 Chat / Agent 中完成代码生成、文件修改等开发任务。

## 接入条件

### Cursor 账号要求

需要有效的 **Cursor 付费订阅**（例如 Pro 或 Teams），用于启用 BYOK（Bring Your Own Key，自带 API Key）。**Free / Hobby 免费账号不能通过本文方式在 Cursor 内置 Chat / Agent 中调用 Step 模型。**

### 安装 Cursor

从 Cursor 官网下载并安装编辑器。建议使用 **Cursor 3.15.20 或更高版本**。

### 选择计费方式

* **普通 API（按量付费）**：确认账户有可用余额或额度，且具备所用模型的调用权限。
* **Step Plan（订阅额度）**：确认 [Step Plan 订阅](https://platform.stepfun.com/step-plan)有效、额度可用，且具备所用模型的调用权限。

### 获取 API Key

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

## 配置 Cursor

<Note>
  本配置用于 Chat / Agent；代码自动补全（Tab）仍使用 Cursor 内置模型。
</Note>

<Warning>
  **Override OpenAI Base URL** 是全局覆盖设置。开启后，走 OpenAI 协议的请求会统一发送至自定义端点。需要使用 Cursor 订阅内置模型时，请先[关闭 Override](#切回-cursor-内置模型)，再新建会话。
</Warning>

<Steps>
  <Step title="打开模型设置">
    打开 **Cursor Settings**，进入 **Models** 页面。也可以通过命令面板搜索 `Cursor Settings` 打开设置。
  </Step>

  <Step title="配置连接">
    在 Models 页面的连接配置区域填写以下内容（Base URL 以 Step Plan 为例）：

    | 字段 | 填写内容 |
    | - | - |
    | OpenAI API Key | `<STEP_API_KEY>` |
    | Use OpenAI API Key | `ON` |
    | Override OpenAI Base URL | `ON` |
    | Base URL | `https://api.stepfun.com/step_plan/v1` |

    在 **OpenAI API Key** 字段中填写 Step API Key，用于请求认证。

    <Note>
      根据计费方式选择 Base URL：

      <p>
        普通 API（按量付费）：`https://api.stepfun.com/v1`<br />
        Step Plan（订阅额度）：`https://api.stepfun.com/step_plan/v1`
      </p>

      Base URL 不包含 `/chat/completions`；Cursor 会自动追加该路径。
    </Note>
  </Step>

  <Step title="添加自定义模型">
    在 Models 页面添加自定义模型，**Model ID** 可填写 `step-5-preview`、`step-3.7-flash`、`step-3.5-flash-2603` 或 `step-3.5-flash`。

    [`step-5-preview`](/docs/zh/guides/models/step-5-preview) 的模型上下文窗口为 **1M tokens**。
  </Step>

  <Step title="选择模型并新建会话">
    打开 Chat 或 Agent 面板，选择刚添加的 Step 模型，并新建会话进行测试。
  </Step>
</Steps>

## 验证接入

### 文本连通

在新会话中输入：

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
请只回复 OK。
```

**预期结果**：返回 `OK`，且未出现 `401`、`403` 或协议错误。

### Agent 工具调用

在已安装 Python 的独立测试目录中，创建一个 `README.md` 文件，内容为 `Cursor Step Plan test`。在 Cursor 中打开该目录，使用选中了 Step 模型的新 **Agent** 会话，输入：

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
Read README.md in the current workspace.
Create a hello world script in Python named hello.py that prints exactly "Hello, world!".
Run the script with an available Python interpreter and report the command and output.
Do not modify README.md or any other files.
```

检查 Agent 提议的文件操作和命令后，再按需授权执行。

**预期结果**：

1. 会话中出现读取 `README.md`、创建 `hello.py` 和执行命令的真实工具调用记录。
2. 工作目录中实际生成 `hello.py`，可在编辑器中核对文件内容与变更。
3. 运行输出为 `Hello, world!`。

仅在对话中返回一段代码，不代表已完成 Agent 工具调用验证。

### 请求路由

在 [Step 开放平台](https://platform.stepfun.com)的用量或请求记录中，确认本次调用的模型 ID 与 Cursor 中的选择一致，计费通道与配置的普通 API 或 Step Plan Base URL 对应。

### 重启验证（可选）

完全退出并重新打开 Cursor，确认 Models 配置保留，并在新会话中使用同一模型重复文本连通测试。

## 切回 Cursor 内置模型

仅切换模型选择器，不会自动取消自定义 Base URL。

1. 在 **Cursor Settings → Models** 中关闭 **Override OpenAI Base URL**。
2. 按需关闭 **Use OpenAI API Key**。
3. 新建会话，选择要使用的 Cursor 内置模型。

## 常见问题

<AccordionGroup>
  <Accordion title="Q: 配置 API Key 后仍提示升级或达到用量上限怎么办？">
    先在 Cursor Dashboard 确认当前登录账号的订阅状态：

    * **Free / Hobby**：免费账号不支持 BYOK，请先满足 [Cursor 账号要求](#cursor-账号要求)。
    * **有效付费订阅**：确认使用的是已订阅的 Cursor 账号、自定义 Step 模型及新会话。团队账号还需确认管理员允许 BYOK，并检查团队的使用限制；Step 账户的模型权限及余额或订阅额度按[所选计费方式](#选择计费方式)检查。
  </Accordion>

  <Accordion title="Q: 配置后提示 Connection error 怎么办？">
    依次检查：

    1. **Override OpenAI Base URL** 已开启，Base URL 与计费方式一致：普通 API 使用 `https://api.stepfun.com/v1`，Step Plan 使用 `https://api.stepfun.com/step_plan/v1`。
    2. Base URL 没有误填 `/chat/completions` 等完整接口路径。
    3. API Key 有效，且 **Use OpenAI API Key** 已开启。
    4. Model ID 拼写正确，账号具备所选通道下的模型调用权限。
    5. 当前网络可访问 `https://api.stepfun.com`；若使用代理，同时检查代理配置。
  </Accordion>

  <Accordion title="Q: 配置后提示 401 Incorrect API key 怎么办？">
    检查以下项目：

    * Key 是否复制完整，是否包含多余空格或换行，是否已被撤销。
    * Key 是否来自当前中文站（`.com`）账号，是否误用了其他站点或服务商的密钥。
    * **Use OpenAI API Key** 是否为 `ON`。

    重新粘贴完整 Key 并启用开关后，新建会话重试。权限或额度问题请按[所选计费方式](#选择计费方式)检查账户状态。
  </Accordion>

  <Accordion title="Q: 配置后提示 model not found / BAD_MODEL_NAME 怎么办？">
    1. 确认 Model ID 填写正确，例如 `step-5-preview`，且账号具备所选通道下的模型调用权限。
    2. 确认 Override 已开启，Base URL 与所选计费方式一致。
    3. 在新建的 Chat / Agent 会话中选择该自定义模型。
  </Accordion>

  <Accordion title="Q: 为什么 Chat 可用，但 Agent 无法执行任务？">
    * 确认当前使用 **Agent** 模式，而不只是文本对话模式。
    * 确认选中的是自定义 Step 模型，不是 Auto，并用新会话重试最小 Agent 任务。
    * 检查 Cursor 是否在等待文件修改或终端命令授权；Python 示例还需要本机有可用的 Python 解释器。
    * 区分模型请求失败与工具执行失败：例如 Python 未安装或命令被拒绝，不代表模型连接失败。
  </Accordion>
</AccordionGroup>

若仍无法解决，联系[技术支持](/docs/zh/guides/contact-us)时提供 Cursor 版本、模型 ID、发生时间、脱敏后的错误信息和 Cursor Request ID。

获取 Cursor Request ID：在对应 Chat / Agent 会话右上角打开 **…** 菜单，选择 **Copy Request ID**。

## 相关文档

* [Step Plan 快速开始](/docs/zh/step-plan/quick-start)
* [Step 5 Preview 模型规格](/docs/zh/guides/models/step-5-preview)


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