Cursor 配置 OpenAI API Key 和 Base URL
简答：在 Cursor 的 Settings → Models 中填写 API Key：官方 OpenAI API 通常只需开启并保存 OpenAI Key；第三方 OpenAI 兼容接口还要打开 Override OpenAI Base URL，并填写服务商提供的接口根地址。Base URL 通常到 /v1 为止，不要填 /chat/completions 或重复 /v1；最后用准确的模型 ID测试 Chat 或 Agent。
定义：Cursor 的 OpenAI API Key 是调用 OpenAI 或 OpenAI 兼容模型的凭据，Base URL 是请求使用的接口根地址，模型 ID 则决定后端实际调用哪个模型。
先看三行速查卡：Key、Base URL 和模型 ID怎么填
填了 Key 却报 404，常见原因不是 Key 本身，而是 Base URL 多写了请求路径，或模型 ID 与接口实际接受的值不一致。本文截至 2026年10月24日整理，本站为第三方 AI API 接入指南站，与 Cursor、OpenAI 无隶属关系。
| 配置项 | 正确示例 | 不要这样填 | 检查方法 |
|---|---|---|---|
| 官方 OpenAI Base URL | https://api.openai.com/v1 | https://api.openai.com/v1/chat/completions | 官方 Key 通常不需要手动覆盖 Base URL，使用默认地址 |
| 第三方兼容接口 Base URL | https://api.example.com/v1 | https://api.example.com/v1/v1 | 按服务商文档确认版本路径是否已包含在地址中 |
| 模型 ID | 服务商实际返回的模型 id | 模型展示名称或旧别名 | 请求 /v1/models 或查看服务商模型列表 |
Cursor 官方文档确认，配置入口是 Settings → Models，填写提供商的 API Key 后保存，支持的模型会出现在模型选择器中；自定义 API Key 只适用于聊天模型，Tab 补全继续使用 Cursor 内置模型。可查看Cursor 官方 API Key 文档。
如果接的是官方 OpenAI API，OpenAI 帮助中心给出的流程是创建 API Key、进入 Cursor 的 Models 设置、保存或验证 Key、启用模型，再在 Chat 或 Agent 中选择它。ChatGPT 订阅不包含 OpenAI API 用量，API 请求按 API 账户单独计费，具体以OpenAI 关于 Cursor 的说明为准。
完整配置顺序：从获取 Key 到恢复默认设置
- 先确认接口类型。官方 OpenAI API 使用 OpenAI 签发的 API Key；第三方 OpenAI 兼容接口使用该服务商签发的 Key，不能把 ChatGPT 登录凭据或其他服务商的 Key 混用。
- 准备模型信息。第三方接口至少要确认 API Key、Base URL 和模型 ID。模型 ID 应以服务商接口返回值或文档为准，不要根据旧教程中的模型名称猜测。
- 打开配置入口。在 Cursor 中进入
Settings → Models，找到 API Keys 或 OpenAI 相关设置。不同版本可能显示Save、自动保存或Verify；没有 Verify 按钮不一定是配置失败，近期版本可能已移除该按钮，可直接保存后测试。相关说明见Cursor 支持回复。 - 填写官方 OpenAI Key。在 OpenAI API Key 字段粘贴 OpenAI API Key，打开
Use OpenAI API Key，保存后启用模型。官方 OpenAI API 通常不需要开启 Base URL 覆盖，默认地址为https://api.openai.com/v1。 - 填写兼容接口。在 OpenAI API Key 字段填入兼容服务签发的 Key，打开
Use OpenAI API Key和Override OpenAI Base URL，再填写服务商提供的接口根地址。通常应填到版本路径，例如https://api.example.com/v1，不要填完整的/chat/completions。 - 添加并启用模型。如果当前版本提供 Add Custom Model 或类似入口，填写后端实际接受的模型 ID。模型名中的大小写、短横线、斜杠和版本后缀都可能影响路由。
- 先做最小测试。打开新的 Chat 或 Agent 会话，选择目标模型，发送简短提示词。不要一开始就测试超长上下文、工具调用或复杂 Agent 任务。
- 恢复默认配置。测试官方 OpenAI API 时，关闭
Override OpenAI Base URL并移除兼容接口地址；测试 Cursor 自有模型时，也应关闭相关 Key 覆盖，再重新打开会话验证。
可以把整套顺序记成：获取对应 Key → 进入 Settings → Models → 开启 Use OpenAI API Key → 需要时填写 Base URL → 添加准确模型 ID → Chat/Agent 最小测试 → 关闭覆盖并恢复默认。
Base URL 到底填 /v1 还是 /chat/completions
Base URL 应填写客户端拼接请求路径时使用的接口根地址，而不是某一次请求的完整路径。官方 OpenAI 的模型列表请求示例使用 https://api.openai.com/v1/models，因此对应的版本根地址是 https://api.openai.com/v1；可参考OpenAI List models 文档。
| 地址类型 | 示例 | 结论 |
|---|---|---|
| 版本根地址 | https://api.example.com/v1 | 通常是 Cursor 自定义 Base URL 应填写的形式 |
| 重复版本路径 | https://api.example.com/v1/v1 | 通常会导致 404，应删除重复的 /v1 |
| 完整聊天路径 | https://api.example.com/v1/chat/completions | 不要直接填入 Base URL，除非服务商明确要求这种特殊路由 |
| 只有域名 | https://api.example.com | 是否正确取决于服务商是否把版本路径放在后续路由中，不能凭经验判断 |
服务商的兼容层可能使用不同路径，因此最终判定方法是：先查看服务商文档，再用独立 HTTP 请求验证模型列表或最小聊天请求。如果文档同时给出 Base URL 和完整 Endpoint，Cursor 中优先填写前者。
Cursor 官方说明所有请求都会经过 Cursor 服务器完成最终提示词构建，API Key 也会随请求发送到其后端。基于这一点可以推断，指向你本机的 localhost、局域网地址或仅在本地网络可访问的 Base URL，通常无法被 Cursor 后端直接访问；应使用目标接口可从 Cursor 服务端访问的地址。该路由机制可在Cursor API Key 文档中核对。
先脱离 Cursor 验证 Key、Base URL 和模型 ID
如果 Cursor 报 401、404 或 Model Not Found，先不要同时修改三个字段。先在本机独立验证接口本身，再回到 Cursor，可以把问题分成凭据、地址和模型三类。
- 把 Key 放入环境变量，不要把真实 Key 写进命令历史、项目文件或截图。下面的
YOUR_API_KEY只是占位符。 - 先请求模型列表。官方 OpenAI 接口可用
curl https://api.openai.com/v1/models -H "Authorization: Bearer $OPENAI_API_KEY"；第三方兼容接口则把域名替换为其 Base URL。 - 在返回结果中查找准确的
id，再将该值填入 Cursor 的自定义模型字段。 - 如果模型列表成功但 Cursor 失败，重点检查 Cursor 是否开启了
Use OpenAI API Key、Override OpenAI Base URL，以及团队是否允许个人 API Key。 - 测试结束后清理环境变量，并在服务商控制台检查用量或请求记录。
OpenAI 的模型列表接口明确返回模型的 id 字段，该字段可用于后续 API 请求。不要把模型的展示名称、网页标题或自定义备注当成模型 ID。
版本、团队权限和功能边界排查
| 现象 | 更可能的原因 | 处理方法 |
|---|---|---|
| API Key 或 Base URL 输入框无法输入 | 某些 Cursor 版本存在界面回归 | Cursor 社区曾记录 3.15.6 在 Windows x64 上出现输入框无法键入或粘贴的问题；支持回复建议先打开开关，再用 Tab 键移动到输入框，或暂时回退到已知可用版本。当前版本是否仍受影响应先更新并复测，具体记录见Cursor 社区回归报告。 |
| 看不到 API Keys 区域 | 团队启用了 Restrict Personal API Keys | Cursor 社区支持人员说明，该设置会隐藏 Settings → Models 下的 API Keys 区域；联系团队管理员检查个人 API Key 和 OpenAI BYOK 权限。 |
自定义模型名称以 claude- 开头却被判定为模型不存在 | Cursor 可能按模型名前缀选择提供商 Key 槽位 | 确认团队已启用 OpenAI 个人 API Key，并使用后端实际接受、且不会被错误路由到其他提供商槽位的模型名；参考Cursor 社区关于自定义模型的支持说明。 |
| Tab 或自动补全仍未使用自己的 Key | BYOK 的功能范围限制 | Cursor 官方说明，自定义 API Key 仅用于聊天模型，Tab 补全继续使用 Cursor 内置模型。 |
| Auto、Cloud 或 Background Agents 没有走自己的 Key | 这些功能不属于 Cursor 的通用 BYOK 覆盖范围 | OpenAI 帮助中心列明，BYOK 不适用于 Tab、Auto、Cloud 或 Background Agents、Automations、Cursor CLI、Cursor API 和 SDK；需按当前产品提供的认证方式使用。 |
| 团队用户遇到月度用量或 Token Rate 提示 | 团队侧仍可能存在 Cursor 使用限制 | Cursor 官方文档明确说明，Teams 和 Enterprise 计划在符合条件的自带 Key 请求上仍可能适用 Cursor Token Rate；不要把 BYOK 理解为绕过所有团队限制，按团队后台和官方说明核对。 |
401、404、429、超时和流式中断怎么判断
| 错误或现象 | 优先判断 | 处理步骤 |
|---|---|---|
| 400 或 unsupported_parameter | 请求字段、模型能力或兼容层协议不匹配 | 先看返回体中的 error.message、error.param 和 error.code，确认 Cursor 使用的接口协议与服务商支持的字段一致。不要只依据 HTTP 状态码猜原因。 |
| 401 Unauthorized | Key 无效、撤销、复制错误或发往错误地址 | 独立请求验证 Key，检查是否有多余空格，并确认 Key 属于当前 Base URL 对应的服务。 |
| 403 Forbidden | 权限、组织、项目或地域策略 | 检查 API 项目权限、组织设置和服务商访问策略。更换模型名称通常不能解决权限拒绝。 |
| 404 或 Model Not Found | Base URL 拼接错误或模型 ID 不存在 | 删除重复的 /v1，移除 /chat/completions，再用模型列表返回的准确 id 测试。 |
| 429 | 限速、额度、余额或 spend limit | 先读取错误体和 error.code。临时限速时遵循 Retry-After；余额、账单、项目或组织额度错误不能靠重复重试解决。可查看OpenAI 错误码文档和OpenAI 限速文档。 |
| 连接超时或请求长时间无响应 | 网络、代理、TLS、防火墙或服务端处理时间 | 先用最短提示词测试，检查本机网络和代理，再查看服务商状态；不要在同一时间反复修改 Key、Base URL 和模型。 |
| 流式输出中断 | 连接被代理、客户端或服务端提前关闭 | 先关闭复杂工具调用，测试短回复；记录是否有 HTTP 错误体或连接异常，再分别检查代理、超时和接口是否完整支持流式响应。 |
OpenAI 官方错误说明要求结合 HTTP 状态、返回的 error 对象以及具体错误代码处理；限速文档也说明，Retry-After 是临时限速时的最短等待时间，账单、额度和配额错误不应无限重试。
配置完成后的安全清单
- 不要把 API Key 提交到 Git、写进前端代码、公开 issue、截图或终端录屏。
- 不同项目尽量使用不同 Key，便于轮换、撤销和核对用量。
- 如果 Key 已经公开，立即在对应服务商控制台撤销并重新生成，不要只删除本地配置。
- 不要把真实 Key 放入本文示例、脚本参数或共享笔记；优先使用环境变量或系统密钥存储。
- 使用第三方兼容接口时，确认请求会经过哪些系统。Cursor 官方说明，自定义 Key 请求会经过 Cursor 服务器进行最终提示词构建，数据处理还应同时查看所选提供商的隐私政策。
如果配置后仍无法判断请求是否到达目标接口，优先查看服务商侧请求日志或用量记录；没有服务商日志时，只能把返回结果作为有限证据，不能仅凭 Cursor 界面显示已保存就断定路由成功。
常见问题
Cursor 配置官方 OpenAI API Key 后，还需要填写 Base URL 吗？
通常不需要。官方 OpenAI API 可直接填写并启用 OpenAI API Key，使用默认地址即可。只有接第三方 OpenAI 兼容接口时，通常才需要开启 Override OpenAI Base URL，并填写该服务商提供的接口根地址。
Cursor 的 Base URL 应该填写到 /v1 还是 /chat/completions？
通常填写到 /v1 这样的版本根地址，不要填完整的 /chat/completions，也不要重复添加 /v1。若服务商文档定义了不同路径，应以该服务商文档和独立请求结果为准。
为什么 Cursor 显示 Model Not Found？
先检查模型 ID 是否与接口实际接受的值完全一致，再检查 Base URL 是否多了 /v1、少了版本路径，最后确认 Use OpenAI API Key 和 Override OpenAI Base URL 已按接口类型开启。
自己的 OpenAI API Key 能用于 Cursor Tab 自动补全吗？
不能据此保证。Cursor 官方说明，自定义 API Key 只适用于聊天模型，Tab 补全继续使用 Cursor 内置模型。
为什么开启自定义 Base URL 后 Cursor 自有模型也报错？
先关闭 Override OpenAI Base URL 和相关 Key 覆盖，再重新打开新的 Chat 会话测试 Cursor 自有模型。自定义地址如果不支持 Cursor 发出的请求，可能导致相关模型调用失败。
Cursor 团队版看不到 API Keys 设置怎么办？
联系团队管理员检查 Restrict Personal API Keys 以及 OpenAI 个人 API Key 权限。Cursor 社区支持人员说明，限制开启时可能隐藏 Settings → Models 下的 API Keys 区域。
Cursor 3.15.6 输入框无法粘贴 API Key 怎么办？
Cursor 社区曾记录该版本在部分 Windows x64 环境中出现输入框无法键入或粘贴的问题。可先开启对应开关，再用 Tab 键移动到输入框；同时检查是否有更新版本，必要时按官方支持记录回退到已知可用版本后复测。
相关阅读
参考资料
- Cursor 官方：Bring your own API key（cursor.com）
- OpenAI 帮助中心：Using OpenAI models in Cursor
- OpenAI API Reference：List models
- OpenAI API：Error codes
- OpenAI API：Rate limits
- Cursor 社区：How to adjust settings for custom added models?（forum.cursor.com）
- Cursor 社区：3.15.6 API Key 与 Base URL 输入框回归问题（forum.cursor.com）
- Cursor 支持：No verify button when setting custom OpenAI API key（forum.cursor.com）