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

# Cursor

> 通过 HaiRoute 网关接入 Cursor

Cursor 支持在聊天模型路径中使用自定义 OpenAI 兼容 API Key 与 Base URL。按下面的编号流程配置后，你可以在 Cursor 的聊天能力里尝试使用 HaiRoute 提供的模型。

## 协议说明

Cursor 的自定义 API Key 路径只支持 OpenAI 兼容模式，不支持 Anthropic Messages 协议。因此本文档只覆盖 OpenAI 模式，Base URL 固定为 `https://api.hairoute.ai/v1`。

<Note>
  Cursor 这条接入链路以图形界面操作为主，Windows、macOS、Linux 的核心步骤通常一致。不同系统下如果菜单位置、窗口标题或按钮文案略有差异，请以当前版本实际 UI 为准，但 `API Key`、`Base URL` 和 `Model ID` 的填写逻辑不变。
</Note>

## 配置步骤

1. 先准备好 HaiRoute API Key，并确认目标模型已经在 HaiRoute 中可用。
2. 打开 Cursor，进入 **Settings** > **Cursor Settings** > **Models**。
3. 在 **OpenAI API Key** 中填入你的 HaiRoute API Key。
4. 打开 **Override OpenAI Base URL**，填入 `https://api.hairoute.ai/v1`。
5. 如果要使用的模型已在 Cursor 模型列表中，直接在聊天面板或模型选择器中选择它即可，不需要重复添加。Base URL 覆盖后，这些模型的聊天请求也会通过 HaiRoute。
6. 只有要使用的模型不在 Cursor 列表中时，才在同一页面的 **Add or search model** 输入 HaiRoute 模型 ID（例如 `gpt-5.4`），并点击 **Add Custom Model** 添加。
7. 保存设置后，切换到要使用的模型。

<img src="https://mintcdn.com/hai-token/ZxhHVxNWRBJLH9vT/images/cursor/PixPin_2026-07-16_18-53-42.png?fit=max&auto=format&n=ZxhHVxNWRBJLH9vT&q=85&s=dfc3a2c3657e364ada8879826799a2e1" alt="在 Cursor 中添加自定义模型" width="1542" height="1118" data-path="images/cursor/PixPin_2026-07-16_18-53-42.png" />

## 验证步骤

1. 在 Cursor 中打开任意项目，然后打开 AI 聊天面板。
2. 选择要使用的模型；它可以是 Cursor 现有模型，也可以是刚添加的自定义模型。
3. 发送一个简单问题，例如“请解释当前文件的作用”。
4. 如果可以正常返回结果，说明 Cursor 的聊天模型路径已经可以使用你填写的 HaiRoute 配置。

## 补充说明

<Note>
  这里推荐填写的 Base URL 是 `https://api.hairoute.ai/v1`。这表示你在 Cursor 中使用的是 OpenAI 兼容接入方式，而不是某个单独接口地址。
</Note>

<Warning>
  Cursor 官方对自定义 API Key 的明确支持重点在聊天模型路径。Tab 补全等其他能力仍可能继续使用 Cursor 自带模型，因此不要把这份配置理解为“Cursor 的所有 AI 能力都已经切到 HaiRoute”。
</Warning>

| 字段                       | 推荐填写值                                                               |
| ------------------------ | ------------------------------------------------------------------- |
| OpenAI API Key           | 你的 HaiRoute API Key                                                 |
| Override OpenAI Base URL | `https://api.hairoute.ai/v1`                                        |
| Model ID                 | 仅当目标模型不在 Cursor 列表中时，在 **Add or search model** 中按 HaiRoute 模型列表原样填写 |

Base URL 覆盖生效后，Cursor 列表中已有模型的聊天请求也会通过 HaiRoute。只有目标模型不在列表中时，才需要在 **Add or search model** 手动输入模型 ID 并添加。

<Tip>
  这里要填写的是 HaiRoute 首页或模型列表中的**模型编号（model ID）**，例如 `gpt-5.4`，不是展示给用户看的模型名称。复制模型名称通常没有用，容易导致 `model not found`。
</Tip>

## 常见问题

| 问题                                                                 | 解决方案                                                                                                      |
| ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------- |
| 提示接口地址错误                                                           | 请确认 Base URL 是 `https://api.hairoute.ai/v1`。如果缺少 `/v1`，Cursor 发起 OpenAI 兼容请求时通常会报错。                       |
| 提示 `401` 或鉴权失败                                                     | Cursor 走的是 OpenAI 兼容 Bearer 鉴权，请确认实际发送的是 `Authorization: Bearer YOUR_API_KEY`。                            |
| 提示 `model not found`                                               | 请确认你在 Cursor 中填写的模型 ID 与 HaiRoute 模型列表中的模型 ID 完全一致，模型名区分大小写，也不要自行增删前缀。                                    |
| 提示 `The model xxx does not work with your current plan or api key` | 这类提示通常优先表示 `Cursor` 当前账号套餐或自定义模型权限不足，而不一定是 HaiRoute 接口异常。若你当前使用免费版，请先确认该套餐是否支持自定义模型或 BYOK；如果不支持，需要升级后再继续。 |
| 已保存配置但请求仍未通过 HaiRoute                                              | 请重新选择一次模型，必要时重启 Cursor 后再测试，避免继续使用旧的模型或缓存配置。                                                              |

## 下一步

* 查看 [获取 API Key](/docs/zh/quickstart/get-api-key)
* 查看 [OpenAI 格式 API 文档](/docs/zh/api-reference/chat/openai-format)
* 查看 [模型列表](/docs/zh/api-reference/models/list-models)