Cursor 自定义 OpenAI Base URL：配置、验证与错误排查

更新于 2026-10-24 · pateway.cyou

简答：在 Cursor 中接入 OpenAI 兼容接口，通常要进入 Settings → Models，启用 OpenAI API Key 和 Override OpenAI Base URL，填写服务商文档提供的根地址，再添加与接口返回值完全一致的模型 ID。先用 /models 和最小 Chat Completions 请求验证地址、Key、模型三项，再在本地 Chat 或 Agent 中测试；Tab、Auto、Cloud/Background Agents、Automations、CLI、API 和 SDK 不应作为自定义 Key 的验证入口。

定义：Cursor 自定义 OpenAI Base URL，是把 Cursor 支持的 OpenAI 请求发送到指定的 OpenAI 兼容接口根地址，而不是把完整的聊天接口路径填入设置项。

先看填写规则：Base URL 不要机械地只写 /v1

本站为第三方指南，非 Cursor 或相关接口服务官方，以其官网和当前版本界面为准。以下内容截至 2026 年 10 月 24 日整理，Cursor 的设置名称和支持范围可能随版本变化。

Cursor 官方文档确认，自定义 API Key 主要用于聊天模型，Tab 补全继续使用 Cursor 自带模型。OpenAI 帮助中心关于 Cursor 的说明还列出 Auto、Cloud 或 Background Agents、Automations、Cursor CLI、Cursor API 和 SDK 不使用这类自定义 Key。

配置 Cursor 自定义 OpenAI Base URL：按这个顺序操作

1. 准备三项信息。从接口服务商文档确认 API Key、OpenAI 兼容根地址和模型 ID。不要因为其他服务使用 /v1，就自行修改当前服务商给出的地址。
2. 打开设置。进入 Cursor Settings → Models，找到 OpenAI API Key 或 API Keys 区域。Cursor 官方文档给出的基本路径是 Settings → Models。
3. 填写 API Key。将服务商签发的 Key 填入 OpenAI API Key 输入框，开启使用该 Key 的开关并保存。不要把真实 Key 放进公开脚本、Git 仓库、截图或工单。
4. 启用地址覆盖。打开 Override OpenAI Base URL，填写服务商指定的根地址。除非服务商文档明确要求，否则不要追加 /chat/completions、/responses 或其他具体接口路径。
5. 添加自定义模型。通过 /models 获取准确的模型 ID，再在 Cursor 中添加 Custom Model。模型名应与接口返回的 ID 完全一致。
6. 先外部验证，再在 Cursor 测试。先完成下一节的 /models 和最小聊天请求，然后在本地 Chat 中选择该模型发送短提示词，成功后再测试 Agent。
7. 切换官方模型时检查覆盖开关。Override OpenAI Base URL 是全局设置时，可能影响其他 OpenAI 系列请求。需要使用 Cursor 自带模型时，先关闭 OpenAI API Key 或 Base URL 覆盖，再新建会话。

需要特别注意网络位置：Cursor 官方说明称，API Key 会发送到 Cursor 后端，由其完成最终提示词组装；因此 localhost、内网地址、仅允许本机 IP 的网关或没有公网 HTTPS 入口的服务，通常不能直接作为 Cursor 的自定义端点。自查时应从外部云主机测试 HTTPS，并检查防火墙、端口转发、IP 白名单和证书配置。

如果你的团队界面完全看不到 API Keys 区域，还要检查团队管理员是否启用了限制个人 API Key 的设置；这类界面差异应以当前 Cursor 团队设置为准。

用 Bash 和 PowerShell 做最小接口验证

建议按“列模型 → 测试 Chat Completions → 再测试 Cursor”顺序操作。命令中的域名、Key 和模型名都是占位符，请替换为接口服务商文档提供的值。

Bash：安全读取 Key 并列出模型

read -s API_KEY; echo; export API_KEY; export BASE_URL='https://api.example.com/v1'; curl -i "$BASE_URL/models" -H "Authorization: Bearer $API_KEY"

Bash：测试最小 Chat Completions 请求

read -r MODEL; curl -i "$BASE_URL/chat/completions" -H "Authorization: Bearer $API_KEY" -H 'Content-Type: application/json' -d "{\"model\":\"$MODEL\",\"messages\":[{\"role\":\"user\",\"content\":\"Reply OK\"}],\"max_completion_tokens\":16}"

PowerShell：当前会话设置变量并列出模型

$env:API_KEY = Read-Host 'API key'; $env:BASE_URL = 'https://api.example.com/v1'; Invoke-RestMethod -Method Get -Uri "$env:BASE_URL/models" -Headers @{ Authorization = "Bearer $env:API_KEY" }

PowerShell：测试最小 Chat Completions 请求

$env:MODEL = Read-Host 'Model ID'; $body = @{ model = $env:MODEL; messages = @(@{ role = 'user'; content = 'Reply OK' }); max_completion_tokens = 16 } | ConvertTo-Json -Depth 5; Invoke-RestMethod -Method Post -Uri "$env:BASE_URL/chat/completions" -Headers @{ Authorization = "Bearer $env:API_KEY" } -ContentType 'application/json; charset=utf-8' -Body $body

上述 PowerShell 的 $env: 变量只对当前会话生效。Bash 使用 read -s 避免直接把 Key 写进命令；如果 Key 已经出现在历史记录、日志或截图中，应立即撤销并重新生成。

OpenAI Chat Completions 官方参考显示，创建聊天请求使用 POST /v1/chat/completions。如果服务商明确支持 Responses API，再按其文档测试对应路径；不要因为“兼容 OpenAI”就默认 Chat Completions 和 Responses 两套格式都支持。

功能范围速查：Chat、Agent、Ask、Composer 和 Tab 怎么判断

Ask 和 Composer 的单独行为没有在公开官方资料中被完整保证，因此这里不把它们绝对归为支持或不支持。更稳妥的验证顺序是：本地 Chat → 本地 Agent → Ask 或 Composer。另一个需要注意的现象是，社区反馈显示 Override OpenAI Base URL 可能对所有 OpenAI 系列请求生效，切换 Cursor 自带模型时可能需要关闭覆盖；这属于社区反馈，行为可能随版本变化，可查看 Cursor 社区相关讨论。

按错误现象排查 400、401、403、404、422、429 和网络问题

如果请求一直转圈或流式响应中断，可查看 Cursor 网络排查文档，在 Settings → Network 中运行诊断；文档说明部分代理会阻断 HTTP/2，此时可尝试切换 HTTP Compatibility Mode 为 HTTP/1.1 并重启 Cursor。HTTP/1.1 只能解决协议或代理兼容问题，不能修复错误的 Base URL、Key 或模型 ID。

最容易误判的是“本机 curl 成功但 Cursor 失败”。由于 Cursor 请求会经过其后端，localhost、内网 IP、只对白名单本机开放的网关和本地端口，都可能在 Cursor 中不可达。应从外部网络再次请求，并查看 Cursor 开发者工具或网关日志中的实际状态码和路径。

安全与兼容性检查清单

• 确认数据路径。使用自定义 Key 时，请分别阅读 Cursor 和接口服务商的隐私、日志、保留及训练政策。Cursor 官方说明，自有 API Key 不适用其 Zero Data Retention 政策，数据处理遵循所选服务商的政策。
• 限制密钥权限。如果服务商支持，创建仅用于测试的 Key，并配置额度、并发或来源限制。
• 不要泄露真实 Key。Key 若出现在 Git、终端历史、截图、CI 日志或公开工单中，应立即撤销并重新生成。
• 先测最小请求。兼容 OpenAI 不等于支持全部参数、工具调用、流式响应和 Responses API。遇到 400 或 unsupported_parameter 时，先回到最小 Chat 请求。
• 留意全局覆盖。启用 OpenAI API Key 和 Override OpenAI Base URL 后，如果 Cursor 自带模型也报错，先关闭相关开关并新建会话。
• 记录实际模型 ID。不要只看网页展示名；以 /models 返回的 id 为准。

配置完成后的最短自查流程

1. 请求 /models，确认根地址和 Key 有效。
2. 复制返回的准确模型 ID，不手动改名。
3. 用 /chat/completions 发送只含模型、消息和少量输出上限的最小请求。
4. 在 Cursor Settings → Models 中填写同一根地址和 Key。
5. 添加名称完全一致的 Custom Model。
6. 在本地 Chat 中发送短提示词，成功后再测试 Agent。
7. 若外部请求成功而 Cursor 失败，检查公网可达性、Cursor 后端访问限制、全局覆盖和 HTTP Compatibility Mode。

这套顺序可以把问题拆成四类：根地址错误、认证或权限错误、模型 ID 错误，以及 Cursor 功能或网络兼容问题。不要同时修改 Base URL、Key、模型名和请求参数，否则很难判断是哪一步解决了问题。

常见问题

Cursor 自定义 OpenAI Base URL 通常应该填到 /v1 吗？

不一定。应以接口服务商文档给出的 OpenAI 兼容根地址为准，可能是 <code>/v1</code>、<code>/api/v1</code>、<code>/openai/v1</code>，也可能是不带版本号的其他路径。不要把 <code>/chat/completions</code> 或 <code>/responses</code> 直接追加到 Base URL。

为什么本机 curl 能访问，Cursor 却超时或一直转圈？

Cursor 官方说明，使用自有 Key 的请求会发送到 Cursor 后端进行最终提示词组装。因此 localhost、内网地址、仅允许本机 IP 的白名单网关或没有公网 HTTPS 入口的端点，都可能在 Cursor 中失败。应从外部云主机测试端点，并检查防火墙、端口转发、证书和 IP 白名单。

Cursor 自定义 API Key 能用于 Tab、Auto 或 Cloud Agent 吗？

不能把这些功能当作自定义 Key 的支持范围。公开官方说明明确列出 Tab、Auto、Cloud 或 Background Agents、Automations、Cursor CLI、Cursor API 和 SDK 不使用这类 OpenAI 自定义 Key。首次验证应使用本地 Chat，再测试本地 Agent。

为什么添加模型后提示 model not found？

最常见原因是模型名称没有与接口返回的 ID 完全一致。先请求服务商的 <code>/models</code>，复制准确的 <code>id</code>，检查大小写、连字符和版本后缀，再在 Cursor 中删除旧模型并重新添加。

Chat 可以调用，Agent 却报 400 或 unsupported_parameter，怎么办？

这通常说明基础认证和地址已经可用，但 Agent 使用了服务商未实现的字段、工具或请求格式。先保留最小 Chat 请求确认接口正常，再按服务商文档逐项确认工具调用、流式响应、Responses API 或其他扩展字段是否支持。

为什么 Cursor 自带模型也被自定义 Base URL 影响？

Cursor 社区反馈显示，Override OpenAI Base URL 可能对 OpenAI 系列请求全局生效，而不是只绑定一个 Custom Model。需要切换 Cursor 自带模型时，可先关闭 OpenAI API Key 或 Base URL 覆盖，再新建会话；该行为可能随 Cursor 版本变化。

相关阅读

• 继续阅读：Cursor 配置 OpenAI API Key 的完整步骤

参考资料

1. Cursor 官方：Bring your own API key（cursor.com）
2. OpenAI 帮助中心：Using OpenAI models in Cursor
3. Cursor 官方：Network, proxy, and remote connections（prod.cursor.com）
4. Cursor 社区：Custom OpenAI override and Cursor models cannot both stay enabled（forum.cursor.com）