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

# Cursor

> 在 Cursor 中配置 4096bytes 自定义模型

Cursor 可以通过 OpenAI 兼容配置接入 4096bytes。配置完成后，你可以在 Cursor Chat 或 Agent 中选择 4096bytes 的模型。

<Warning>
  Cursor 的自定义 API Key 通常只影响你在聊天或 Agent 中选择的模型。Cursor Tab、补全、索引、后台任务等功能可能仍由 Cursor 自身服务处理。具体范围以 Cursor 当前版本展示为准。
</Warning>

## 准备工作

* 已完成 [创建账号](/quickstart/create-account)。
* 已完成 [获取 API Key](/quickstart/get-api-key)。
* 已安装 Cursor，并确认可以打开 **Settings**。
* 已准备好 4096bytes 的 API Key、Base URL 和模型名。

建议为 Cursor 单独创建一个 API Key，例如 `cursor-desktop` 或 `cursor-work`。这样后续更容易查看消耗来源，也方便单独停用。

## 安装客户端

如果你还没有安装 Cursor，请打开 [Cursor 下载页](https://cursor.com/downloads)，按你的系统选择 macOS、Windows 或 Linux 安装包。

<Steps>
  <Step title="下载安装包">
    从 Cursor 官方下载页选择当前电脑对应的版本。macOS 注意区分 Apple Silicon 和 Intel，Windows 注意区分 x64 和 ARM64。
  </Step>

  <Step title="启动 Cursor">
    安装完成后先打开一次 Cursor，确认编辑器可以正常启动。
  </Step>

  <Step title="打开设置">
    进入 **Settings**，确认可以看到模型、AI 或供应商相关设置，再继续配置 4096bytes。
  </Step>
</Steps>

## 打开模型设置

<Steps>
  <Step title="打开 Cursor 设置">
    在 Cursor 中打开 **Settings**。不同版本入口可能略有差异，常见位置是左下角齿轮图标、命令面板里的 **Cursor Settings**，或菜单中的 **Cursor > Settings**。
  </Step>

  <Step title="进入模型页面">
    进入 **Models**、**AI** 或模型供应商相关页面。找到 OpenAI API Key、自定义 API 或 Override Base URL 相关配置。
  </Step>

  <Step title="启用 OpenAI 兼容配置">
    如果页面中有开关，请启用 OpenAI API Key 或自定义 OpenAI 配置。4096bytes 在 Cursor 中按 OpenAI 兼容供应商填写。
  </Step>
</Steps>

## 填写接入信息

在 Cursor 的 OpenAI 兼容配置区域填写下面字段。

| Cursor 字段                             | 填写内容                         |
| ------------------------------------- | ---------------------------- |
| `OpenAI API Key`、`API Key`            | 你在 4096bytes 控制台创建的 API Key。 |
| `Override OpenAI Base URL`、`Base URL` | `https://api.4096bytes.com`。 |
| `Model name`、`Custom model`           | 控制台展示的模型名。                   |

Base URL 填写根地址即可，不要手动拼接 `/v1/chat/completions`、`/v1/responses` 或其他完整接口路径。

<Warning>
  API Key 会保存在本机 Cursor 配置中。不要在共享电脑上配置个人 Key，也不要把设置页面截图发给他人。
</Warning>

## 添加模型名

<Steps>
  <Step title="添加自定义模型">
    在 Cursor 的模型列表中点击 **Add model**、**Add custom model** 或类似按钮。
  </Step>

  <Step title="填写模型名">
    输入控制台展示的模型名。模型名需要完整一致，大小写、连接符和版本号都不要改。
  </Step>

  <Step title="保存设置">
    保存 API Key、Base URL 和模型名。如果 Cursor 提供 **Verify** 或测试按钮，可以先点击测试。
  </Step>
</Steps>

如果你不确定模型名，回到控制台查看当前可用模型。不要直接复制其他用户截图中的模型名。

## 选择并测试模型

保存后，打开 Cursor Chat 或 Agent，在模型选择器中切换到刚添加的 4096bytes 模型。

可以先发送一个低风险问题：

```text theme={null}
请用一句话说明当前项目的用途，不要修改任何文件。
```

如果模型能正常回复，说明 Cursor 已经可以通过 4096bytes 发起请求。接下来再在真实项目中使用。

## 使用建议

* 为 Cursor 单独创建 API Key，不要和 Codex、Claude Code 共用同一个 Key。
* 第一次配置时先用短问题测试，确认模型、Key 和 Base URL 都正确。
* 如果你同时配置了多个供应商，发送消息前确认当前会话选择的是 4096bytes 模型。
* 如果团队多人使用，建议为每个人或每台设备分配不同 Key，方便排查异常消耗。

## 常见排查

<AccordionGroup>
  <Accordion title="Cursor 里找不到新模型">
    确认模型名已经添加到模型列表，并重启 Cursor。部分版本需要重新打开 Chat 面板后才会刷新模型选择器。
  </Accordion>

  <Accordion title="提示模型不存在">
    回到控制台复制模型名，确认没有多余空格、大小写错误或版本号缺失。
  </Accordion>

  <Accordion title="提示认证失败">
    检查 API Key 是否完整。确认没有把旧 Key、已删除 Key 或带换行的 Key 粘贴进去。
  </Accordion>

  <Accordion title="请求地址错误">
    Base URL 填写 `https://api.4096bytes.com`。不要填写完整接口路径，也不要把其他客户端的地址格式直接复制过来。
  </Accordion>

  <Accordion title="Cursor 仍然走官方模型">
    在 Chat 或 Agent 的模型选择器中手动切换到 4096bytes 模型。自定义 API Key 不一定覆盖 Cursor 的所有内置功能。
  </Accordion>

  <Accordion title="请求失败但配置看起来正确">
    检查账户余额、Key 额度限制、模型是否在当前分组可用，以及网络是否能访问 `https://api.4096bytes.com`。
  </Accordion>
</AccordionGroup>