Cursor 怎么配置 OpenAI API？官方 Key、兼容接口与 401/404 排查

更新于 2026-10-24 · gpt.boats

简答：在 Cursor 中配置 OpenAI API，先进入 Settings > Models，再根据接口类型填写 API Key、Base URL 和模型 ID。官方 OpenAI API 主要用于本地 Chat 与 Agent；兼容接口还要核对服务商规定的基础地址和模型 ID。配置后用低成本请求测试，遇到 401、404 或 429 时，优先检查 Key、路径、模型和账户额度。

定义：Cursor 配置 OpenAI API，是在 Cursor 的模型设置中接入官方 OpenAI API 或兼容 OpenAI 格式的接口，并选择模型供本地 Chat 或 Agent 调用。

先试这一步：三字段速填卡

打开 Cursor，进入 Settings > Models。官方 OpenAI API 与 OpenAI 兼容接口的填写方式不同，先按下面的对照表确认自己应该填什么。

字段	官方 OpenAI API	OpenAI 兼容接口	常见错误
API Key	填写 OpenAI API Key	填写接口服务商提供的 Key	复制了 ChatGPT 登录信息，或 Key 已撤销
Base URL	通常使用 Cursor 默认配置	填写服务商规定的 OpenAI 兼容基础地址	误填完整的 /chat/completions 地址
模型 ID	从 Cursor 模型列表选择可用模型	填写接口实际接受的 model 字段值	把产品展示名、部署名和模型 ID 混用
测试位置	Cursor Chat 或 Agent	Cursor Chat 或 Agent	误以为自定义 Key 会覆盖 Tab 或全部功能

Cursor 官方文档说明，配置入口是 Settings > Models，选择提供商、粘贴 API Key 并保存；自定义 API Key 只适用于聊天模型，Tab 补全继续使用 Cursor 内置模型。可查看 Cursor 的 API Key 文档。

本文是独立的 AI API 接入指南，不代表 Cursor 或 OpenAI 官方。Cursor 的菜单名称和可用功能可能随版本调整，找不到 Models 时应优先使用设置搜索功能，并以当前界面为准。

官方 OpenAI API：按 5 步完成配置

准备 API 账户和计费。需要可用的 OpenAI API 账户、API Key，以及已经配置的 API 计费。ChatGPT 订阅和 API 平台是独立计费系统，ChatGPT 订阅不自动包含 API 用量。OpenAI 对 Cursor 的说明也明确区分了自带 API Key、Codex IDE 扩展和 AI 网关三种方式，详情见 OpenAI 关于在 Cursor 中使用 OpenAI 模型的说明。
打开模型设置。启动 Cursor，进入 Settings > Models。Windows 和 macOS 的具体菜单布局可能不同，但核心路径是模型设置页面。
填写 OpenAI API Key。找到 OpenAI API Key 输入框，粘贴 Key 并保存或验证。OpenAI API 使用 Bearer 认证，Key 属于秘密信息，不应写入前端代码、公开仓库、日志或截图。认证格式可参考 OpenAI API Authentication 文档。
启用模型。保存后，在模型列表中启用当前账户和 Cursor 界面显示的可用模型。不要直接照抄旧教程中的模型 ID，实际可用模型应以 Cursor 模型选择器和 OpenAI 账户权限为准。
进行低成本测试。打开 Chat 或 Agent，选择刚启用的模型，先发送“解释当前文件中的一个函数，不要修改代码”这类小请求。确认能返回结果后，再进行较大的代码任务。

如果 API Key 输入框保存后不再显示完整内容，不要仅凭输入框外观判断失败。更可靠的检查方式是看模型能否启用，并发送一次低成本测试请求；如果返回 401，再重新复制 Key 并检查是否已撤销。

OpenAI 兼容接口：Base URL 正确与错误示例

接入兼容接口时，通常需要在 Cursor 的 OpenAI 设置中启用 API Key、填写 Override OpenAI Base URL，并添加或启用服务商实际支持的模型。字段名称和开关位置可能随 Cursor 版本变化，最终以当前 Settings > Models 页面和接口服务商文档为准。

填写方式	判断	说明
`https://example.com/v1`	✓ 可能正确	适合作为兼容接口基础地址，但仍需以服务商文档规定的路径为准。
`https://example.com/v1/chat/completions`	✗ 通常不应填写	这是具体请求地址，不是供客户端拼接请求的 Base URL。
`https://example.com`	需核对	有些服务商要求客户端自行补充 /v1，有些服务商则要求 Base URL 已包含 API 前缀。
`https://example.com/v1/`	需核对	末尾斜杠是否会导致重复路径，取决于 Cursor 和服务商的路径拼接方式。

OpenAI API 的参考路径包含 /v1/models 和 /v1/chat/completions，但兼容接口是否包含 /v1 不能一概而论。不要根据域名或其他教程猜测，直接复制服务商文档中的基础地址。若漏填 API 前缀，常见结果是请求落到错误路径并返回 404；若把完整聊天路径填入 Base URL，也可能导致客户端再次拼接路径。

# 仅用于检查兼容接口是否能返回模型列表；真实 Key 不要写进截图或公开脚本
curl "$BASE_URL/models" \
  -H "Authorization: Bearer $OPENAI_API_KEY"

如果服务商要求不同的认证头、模型列表路径或请求格式，应以其官方 API 文档为准。Cursor 官方也提示，自定义网关必须支持 Cursor 需要的 API 格式，部分模型控制参数可能无法通过自定义 Base URL 传递。

官方 API、兼容网关与 Cursor 订阅：费用怎么分

配置成功不代表所有费用都由同一方收取。下面按费用来源拆开看，避免把 Cursor 订阅、OpenAI API 和兼容网关当成一笔账。

项目	费用归属	需要核对什么
Cursor 订阅	支付给 Cursor	当前套餐包含的功能、消息或用量规则。
官方 OpenAI API	支付给 OpenAI API 账户	API 余额、项目支出限制、组织额度和模型用量。
第三方兼容网关	支付给对应接口服务商	该服务商的模型计费、限速、余额、日志和数据处理规则。
团队或企业计划中的自定义 Key	可能同时涉及提供商费用与 Cursor 规则	Cursor 当前页面是否适用 Cursor Token Rate、团队预付余额或按量规则。

Cursor 官方说明，个人计划使用自有 API Key 时，模型成本由提供商收取；Teams 和 Enterprise 计划可能适用 Cursor Token Rate，具体规则以 Cursor 官方 API Key 页面当前说明为准。不要只查看 OpenAI 或网关账单，也要检查 Cursor 团队账户的用量和支出设置。

OpenAI 的预付余额、组织使用限额、项目硬支出限制和请求速率限制不是同一个概念。遇到额度错误时，应先读取响应中的 error.code，再分别检查余额、组织限制、项目限制和速率限制。可参考 OpenAI API 使用限额排查说明和 OpenAI 预付 API 计费说明。

配置成功但不能用：401、404、429 逐项排查

现象	优先检查	处理方法
401 或 invalid API key	Key 是否完整、是否复制了错误提供商的 Key、是否已撤销	重新复制对应服务商的 Key，去掉多余空格，并确认当前 Cursor 设置使用的是正确的提供商。
404 或 model not found	模型 ID、Base URL 路径、部署名称	使用接口文档中的实际模型 ID；如果是部署型服务，不要把部署名和模型名混用。
404 或 endpoint not found	Base URL 是否漏填或重复拼接 /v1	对照服务商文档检查基础地址，不要填写完整的 /chat/completions 地址。
429 rate limit	请求速率、Token 速率、账户余额或支出限制	先查看错误码和响应内容；临时速率限制可降低请求突发，余额或支出限制则需要处理账户设置，单纯重试不能解决额度问题。
billing、quota 或 insufficient_quota	预付余额、组织使用限额、项目硬支出限制	到对应 API 账户的 Billing、Limits 或项目设置中核对，不要把 ChatGPT 订阅当作 API 余额。
Chat 能用但 Tab 或自动补全不走自定义 Key	是否误解了自定义 Key 的适用范围	这通常不是配置失败。Cursor 官方说明，自定义 Key 主要用于本地 Chat 和 Agent，不适用于 Tab、Auto、Cloud 或 Background Agents、Automations、Cursor CLI、Cursor API 和 SDK。

OpenAI 官方建议，遇到速率或额度错误时先区分请求限制、Token 限制、余额和支出上限；429 既可能是临时速率限制，也可能是余额或额度问题。可查看 OpenAI 的 429 与速率限制排查说明。

功能边界、Codex 扩展与安全检查

自定义 OpenAI API Key 与 Codex IDE 扩展不是同一条配置链路。自定义 Key 是在 Cursor Settings > Models 中供本地 Chat 或 Agent 使用；Codex IDE 扩展在自己的面板和登录流程中运行，不会自动改变 Cursor Chat、Agent、Tab、Auto 或其他 Cursor 服务使用的模型。需要使用 Codex 时，应按 OpenAI 官方 Cursor 指南中的扩展流程单独配置。

为不同项目或环境使用不同 API Key，出现泄露时可以单独撤销。
不要把 Key 写进前端代码、Git 仓库、终端命令历史、日志、录屏或工单截图。
为 OpenAI API 项目设置支出提醒和硬限制；注意硬限制的执行可能不是即时的。
定期查看 API Usage Dashboard，并按项目、模型和时间范围核对用量。OpenAI 说明，用量数据还可以从 API 响应中的 usage 字段查看。
使用兼容网关时，单独核对它的计费、限速、日志保留和数据处理规则；Cursor 中能保存配置，不等于网关与 OpenAI 具有相同规则。

如果配置后仍失败，保留错误码、响应中的请求 ID、发生时间和所选模型，但在提交工单或截图前删除 API Key。OpenAI 的认证文档说明，响应头和请求 ID可用于进一步排查，详情见 OpenAI API Authentication。

常见问题

Cursor 配置 OpenAI API 后，ChatGPT Plus 能抵扣 API 费用吗？

不能直接这样理解。OpenAI 官方说明，ChatGPT 订阅与 API 平台是独立计费系统；使用 OpenAI API Key 时，请求费用按 API 账户的计费、余额和项目设置结算。

Cursor 的 Base URL 应该填写到 /v1 还是 /chat/completions？

不要把完整的 /chat/completions 请求地址直接填入 Base URL。应填写服务商文档规定的基础地址；是否包含 /v1，要根据该接口实际路径决定。漏填或重复拼接 API 前缀，都可能导致 404。

为什么 Cursor Chat 可以使用自定义 Key，但 Tab 不能用？

这通常是产品功能边界，不一定是配置失败。Cursor 官方说明，自定义 API Key 只适用于聊天模型，Tab 补全继续使用 Cursor 内置模型；Auto、Cloud 或 Background Agents 等功能也不应默认视为使用你的 Key。

模型名称应该填写产品名还是模型 ID？

优先填写接口文档中的模型 ID，也就是请求中实际传给 model 字段的值。产品展示名、Cursor 列表名称、部署名称和 API 模型 ID 可能不同，遇到 404 时应回到接口文档核对。

API Key 保存后输入框变空，是不是没有保存？

不能只凭输入框外观判断。先查看模型是否可启用，并发送一次低成本测试请求；如果返回 401，再重新复制 Key，检查提供商、空格和 Key 是否已撤销。

Cursor 配置兼容接口后返回 429，应该继续重试吗？

先读取错误内容和 error.code。429 可能表示请求或 Token 速率过高，也可能表示预付余额、组织额度或项目支出限制；临时速率限制可降低请求突发，余额或额度问题则需要先处理账户设置。

OpenAI API 和 Codex IDE 扩展有什么区别？

OpenAI API Key 是在 Cursor 模型设置中供本地 Chat 或 Agent 使用；Codex IDE 扩展拥有独立的面板和登录流程，不会自动改变 Cursor Chat、Agent、Tab 或 Auto 使用的模型。