Cursor 怎么配置自定义 OpenAI 接口？

更新于 2026-10-23 · openox.cyou

简答：在 Cursor 中打开 Settings > Models，启用 OpenAI API Key，填写兼容接口的 Key，再开启 Override OpenAI Base URL。Base URL 通常填写到接口根路径，例如以 /v1 结尾，不要直接填 localhost 或 127.0.0.1；由于请求会经过 Cursor 后端，本机地址无法被 Cursor 后端访问。Verify 前只保留接口实际支持的模型，否则可能因默认模型不存在而验证失败。

定义：Cursor 自定义 OpenAI 接口，是通过 OpenAI API Key、Override OpenAI Base URL 和自定义模型 ID，把 Cursor 的聊天或部分 Agent 请求连接到 OpenAI 兼容格式的接口。

先照做：Cursor 自定义接口字段速查

本站为第三方指南，非 Cursor 官方，以其官网为准。以下内容按截至 2026 年 10 月 23 日可核验的 Cursor 帮助文档、OpenAI API 文档和 Cursor 社区反馈整理；不同版本的设置名称可能略有变化。

Cursor 官方文档给出的基本路径是 Settings > Models，选择提供商并粘贴 API Key。官方同时说明，自定义 API Key 只适用于聊天模型，Tab 补全继续使用 Cursor 自带模型。详见 Cursor 官方 API Key 说明。

OpenAI 官方创建 Chat Completions 的完整端点是 https://api.openai.com/v1/chat/completions。因此，兼容该格式的 Cursor Base URL 通常填写到 /v1，而不是把完整的 /chat/completions 路径一并填入。详见 OpenAI Chat Completions 创建接口。

完整配置步骤：Key、Base URL 和模型 ID

1. 打开模型设置。进入 Cursor Settings，选择 Models，找到 API Keys 区域。
2. 启用 OpenAI API Key。粘贴 OpenAI 或第三方兼容接口的 API Key，并确认 Use OpenAI API Key 已打开。Key 必须与 Base URL 对应，不能把一个服务商的 Key 填到另一个服务商的地址中。
3. 填写 Override OpenAI Base URL。如果接口文档给出的完整请求地址是 https://api.example.com/v1/chat/completions，通常把 https://api.example.com/v1 填入 Base URL。不要重复添加 /chat/completions。
4. 添加模型。点击 + Add Model，填写接口实际接受的模型 ID。优先以接口的模型列表返回值中的 id 为准，不要自行修改大小写、连字符或版本后缀。
5. 关闭无关模型。点击 Verify 前，只保留当前接口确实提供的模型。假如接口只有 deepseek-chat，但默认的其他模型仍处于选中状态，Cursor 可能用不存在的模型发起验证，导致你误以为 Key 或 Base URL 错误。
6. 用新会话测试。验证成功后，新建 Chat 或 Agent 会话，选择刚添加的模型，用一条短消息测试。先不要同时测试长上下文、工具调用和流式输出。

如果修改了 Key、Base URL 或模型 ID，建议关闭旧会话后重新打开新的 Chat。独立请求能够成功而 Cursor 仍失败时，再检查模型名称、全局覆盖和 Cursor 当前版本。

三个关键边界：localhost、模型路由和功能范围

不要直接填写 localhost 或 127.0.0.1

Cursor 官方说明，使用自有 API Key 时，Key 会随请求发送到 Cursor 后端，所有请求会经过 Cursor 服务器进行最终提示词构建。因此，直接填写 http://localhost:... 或 http://127.0.0.1:... 必然无法让 Cursor 后端访问你电脑上的 Ollama、vLLM 或其他本地服务。Cursor 后端看到的 localhost 是它自己的运行环境，不是你的电脑。

如果必须连接自建服务，需要提供 Cursor 后端可以访问的公网 HTTPS 接口，例如部署在公网服务器，或使用你自行配置并确认安全性的 HTTPS 反向代理。接口必须设置鉴权和访问控制，不能把 API Key 写进公开代码、前端页面或日志。

模型 ID 可能触发路由或名称冲突

Cursor 社区反馈显示，自定义模型名如果与内置模型名称或特殊前缀冲突，可能被错误路由，或者被发送到不支持该模型的接口。尤其是使用第三方接口承载 Claude 等模型时，不要只把 Cursor 中的显示名称改掉，却不修改网关实际接受的模型 ID。

更稳妥的方式是在网关侧设置不冲突的外部 ID。例如上游真实模型是 claude-sonnet-4-5，可以让 Cursor 使用 custom-claude-sonnet-4-5，再由网关把这个 ID 映射回上游真实模型。这样 Cursor 发送的是自定义 ID，网关负责完成转换。相关行为可参考 Cursor 社区关于模型前缀路由的反馈 和 Cursor 社区关于自定义模型重命名的反馈。

Key 和 Base URL 是全局覆盖

据 Cursor 社区支持回复，Override OpenAI Base URL 目前是全局设置，并非每个自定义模型独立绑定。开启后，部分 OpenAI 系列请求可能都会经过自定义地址；切换回 Cursor 自带模型时，可能需要关闭 OpenAI Key 或 Base URL 覆盖，再重新使用内置模型。相关现象见 Cursor 社区关于全局覆盖与内置模型冲突的反馈。

这也是为什么“自定义模型验证成功”不等于所有 Cursor 功能都使用了你的 Key。Cursor 官方明确说明，Tab 补全继续使用 Cursor 自带模型；自定义接口应优先在 Chat 或支持的 Agent 会话中验证。

常见报错排查表：区分本地、网关与上游错误

排错时先记录模型 ID、Base URL 是否包含 /v1、响应状态码以及请求是否到达你的网关。错误文案会因网关和上游模型不同而变化，下面按常见位置给出优先检查顺序。

独立验证时可先对照 OpenAI Chat Completions 创建接口 的请求结构，确认网关是否接受 model、messages 和 stream 等字段。

Verify 失败时的最小验证方法

先把问题拆成“接口能否响应”和“Cursor 是否正确路由”两层。下面的 Bash 示例只检查变量是否存在，不打印 Key：

test -n "$OPENAI_API_KEY" && echo "OPENAI_API_KEY is set" || echo "OPENAI_API_KEY is missing"

然后用完整聊天地址发送最小请求。请将示例域名、模型 ID 和 Key 换成自己的值：

curl -i https://api.example.com/v1/chat/completions -H "Content-Type: application/json" -H "Authorization: Bearer $OPENAI_API_KEY" -d '{"model":"your-model-id","messages":[{"role":"user","content":"hello"}],"stream":false}'

Windows PowerShell 可使用 Invoke-RestMethod。$env: 变量只对当前 PowerShell 会话生效：

$env:OPENAI_API_KEY = Read-Host "API key"; $headers = @{ Authorization = "Bearer $env:OPENAI_API_KEY" }; $body = @{ model = "your-model-id"; messages = @(@{ role = "user"; content = "hello" }); stream = $false } | ConvertTo-Json -Depth 5; Invoke-RestMethod -Method Post -Uri "https://api.example.com/v1/chat/completions" -Headers $headers -ContentType "application/json" -Body $body

如果独立请求失败，优先修复 Key、路径、模型或上游权限；如果独立请求成功而 Cursor 失败，再检查 Use OpenAI API Key、模型名称、全局 Base URL 覆盖和会话状态。不要把真实 Key 写入聊天记录、脚本或公开日志。

常见问题 FAQ

Cursor 可以直接连接我电脑上的 Ollama 或 vLLM 吗？

不能直接把 localhost 或 127.0.0.1 填入 Cursor Base URL。请求会经过 Cursor 后端，本机地址对 Cursor 后端不可见。需要使用 Cursor 后端能够访问的公网 HTTPS 接口，并做好鉴权和访问控制。

Base URL 到底要不要加 /v1？

以接口文档给出的完整路径为准。如果完整聊天请求是 https://api.example.com/v1/chat/completions，通常 Base URL 填到 https://api.example.com/v1。不要把 /chat/completions 再重复写入。

为什么 Verify 一直失败，但我的 Key 明明有效？

常见原因是 Verify 同时测试了接口没有提供的默认模型。先关闭其他无关模型，只保留刚添加且确认存在的模型，再检查模型 ID、Use OpenAI API Key 开关和 Base URL 路径。

为什么自定义 Claude 模型被路由到错误接口？

模型名可能触发 Cursor 的特殊路由或与内置名称冲突。可以在网关侧使用不冲突的别名，例如 custom-claude-sonnet-4-5，再映射回真实模型 ID；不要只修改 Cursor 中的显示名称。

配置成功后，为什么 Tab 补全没有使用我的 Key？

这通常是功能边界，不一定是配置失败。Cursor 官方说明自定义 API Key 主要用于聊天模型，Tab 补全继续使用 Cursor 自带模型。因此应分别测试 Chat、Agent 和 Tab。

能不能给每个自定义模型配置不同的 Key 和 Base URL？

据 Cursor 社区支持回复，当前 Key 和 Override OpenAI Base URL 属于全局设置，不能按每个自定义模型独立绑定。切换不同接口时，需要修改全局配置并重新验证，或在自己的网关中统一做模型路由。

常见问题

Cursor 可以直接连接 localhost 或 127.0.0.1 吗？

不能直接连接。Cursor 请求会经过其后端，直接填写本机地址时，Cursor 后端无法访问你的电脑；应使用可访问的公网 HTTPS 地址，并做好鉴权。

Base URL 要不要加 /v1？

如果完整请求路径是 /v1/chat/completions，通常 Base URL 填到 /v1，不要把 /chat/completions 一并填入。最终以接口文档为准。

为什么 Verify 失败但 Key 有效？

先关闭其他无关模型，只保留接口确实提供的模型，再检查模型 ID、Use OpenAI API Key 开关和 Base URL 路径。

为什么自定义 Claude 模型被路由到错误接口？

模型名可能触发特殊路由或与内置名称冲突。可使用不冲突的自定义别名，并在网关侧映射回真实模型 ID。

自定义 Key 能用于 Tab 补全吗？

通常不能。Cursor 官方说明自定义 Key 主要用于聊天模型，Tab 补全继续使用 Cursor 自带模型。

参考资料

1. Cursor 官方：Bring your own API key（cursor.com）
2. Cursor 社区：自定义 OpenAI 覆盖与内置模型不能同时正常使用（forum.cursor.com）
3. Cursor 社区：自定义模型前缀与 Key 路由反馈（forum.cursor.com）
4. Cursor 社区：自定义模型自动重命名反馈（forum.cursor.com）
5. Cursor 社区：自定义 OpenAI Base URL 覆盖排查（forum.cursor.com）