Cursor 使用 OpenAI 兼容 API 怎么配置
简答：在 Cursor 中打开 Settings > Models，启用 OpenAI API Key，填写服务商提供的 Key、兼容接口 Base URL 和准确模型 ID，再保存并 Verify。Base URL 是否包含 /v1 不能一概而论，应以接口文档和实际请求路径为准；验证成功后优先在 Chat 或 Agent 中发送短消息测试。
定义：Cursor 使用 OpenAI 兼容 API，是指在 Cursor 的模型设置中接入能够按兼容格式接收认证信息、模型名和聊天请求的接口服务。
先看配置对照表：四个字段分别填什么
本文是 apikey.sbs 的第三方使用指南，不是 Cursor、OpenAI 或任何接口服务商的官方网站。本次检索没有找到可核验的 apikey.sbs 公开文档，因此不把它的 Key 创建入口、Base URL 或模型列表写死；如果你使用 apikey.sbs 或其他网关，请以对应服务商实际提供的接口文档为准。
| 配置项 | 应该填写 | 常见错误 | 核对方法 |
|---|---|---|---|
| OpenAI API Key | 服务商签发的 API Key，仅粘贴密钥本身 | 带了多余空格、引号或把网页登录密码当成 Key | 重新复制，并在服务商控制台确认 Key 未撤销 |
| Override OpenAI Base URL | 服务商给出的 OpenAI 兼容 API 基础地址 | 把完整的 /chat/completions 地址填入 Base URL，或盲目添加 /v1 | 用最小请求确认最终地址能正确拼出聊天接口路径 |
| 模型名 | 接口文档或 /models 返回的真实模型 ID | 填写展示名称、别名、大小写不同的名称 | 检查请求体中的 model 是否与服务商要求完全一致 |
| 模型开关 | 启用对应模型，并在 Chat 或 Agent 的模型选择器中选中 | 只保存 Key，没有启用或选中模型 | 新建会话后发送一条简短文本 |
Cursor 官方说明显示，配置入口是 Settings > Models；自有 Key 主要用于聊天模型，Tab 自动补全继续使用 Cursor 内置模型。OpenAI 的说明也指出，兼容网关的具体配置取决于服务商，端点必须支持 Cursor 需要的 API 格式。
Cursor 的实际配置步骤
- 准备三项信息。从接口服务商获得 API Key、Base URL 和模型 ID。三项信息缺一时，不要先猜值；尤其不要把网页登录地址、完整请求地址或模型展示名直接当作 Base URL 或模型名。
- 打开设置。在 Cursor 中进入 Settings，选择 Models，找到 OpenAI 相关的 API Key 配置区域。Cursor 官方文档给出的路径就是 Settings > Models。
- 填写 API Key。粘贴服务商签发的 Key，保存或点击 Verify。Key 不要放进 URL 查询参数，也不要提交到代码仓库。
- 开启自定义地址。如果使用兼容网关而不是默认 OpenAI 接口，打开 Override OpenAI Base URL，再填服务商提供的基础地址。是否以
/v1结尾，必须按照该服务商的文档和实际路由判断，公开官方说明没有给出对所有网关都适用的统一写法。 - 配置模型。启用接口支持的模型，并在 Chat 或 Agent 的模型选择器中选择它。模型字段应使用服务端识别的真实 ID，不要根据网页显示名称自行改写。
- 先做短消息测试。新建一个 Chat 或 Agent 会话，只发送“请回复 OK”。如果成功，再测试代码补全、长上下文或工具调用等更复杂场景。
OpenAI 官方 Chat Completions 示例使用 Authorization: Bearer 认证，并在 JSON 请求体中传递 model 和 messages；因此，兼容服务至少需要按照其文档支持相应的认证和请求格式，具体能力仍以服务商说明为准。
最小验证请求：先确认接口、Key 和模型
如果 Cursor 的 Verify 没有明确提示，可以先在终端用同一组参数发送最小聊天请求。下面示例不会把 Key 放入 URL；其中地址和模型只是占位符，不能直接当作 apikey.sbs 的真实配置。
Bash：需要 curl 7.76 或更高版本才能使用 --fail-with-body。
#!/usr/bin/env bash
set -euo pipefail
command -v curl >/dev/null || { echo "缺少 curl"; exit 1; }
command -v jq >/dev/null || { echo "缺少 jq"; exit 1; }
read -r -s -p "API Key: " API_KEY
echo
BASE_URL="https://your-provider.example/v1"
MODEL="your-model-id"
BODY=$(jq -n --arg model "$MODEL" '{model:$model,messages:[{role:"user",content:"请只回复 OK"}]}')
curl --fail-with-body --max-time 30 "$BASE_URL/chat/completions" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d "$BODY"如果接口文档要求的基础地址本身不含 /v1，应按文档修改 BASE_URL，但仍要保证最终请求路径是服务商实际支持的聊天端点。返回内容至少应能看到模型响应或明确的服务端错误；这一步可以把 Cursor 界面问题与接口本身的问题分开。
Base URL、模型名和 /v1 怎么判断
不要只凭经验判断。OpenAI 官方示例的完整聊天地址是 https://api.openai.com/v1/chat/completions，但兼容网关可能采用不同的基础路径、版本前缀或路由方式。Cursor 官方说明强调，自定义端点必须支持 Cursor 所需的 API 格式，且部分模型控制项可能无法通过自定义 Base URL 转发。
- 先看服务商文档。确认它要求填写的是根地址、版本地址，还是已经包含资源路径的地址。
- 再看最终拼接结果。若 Cursor 或测试命令在 Base URL 后继续拼接
/chat/completions，就不能把完整的/chat/completions再填一次。 - 最后用真实模型 ID。模型名通常区分大小写或命名空间，不能仅凭 UI 中的显示名称推断。
- 遇到 404 时优先检查路径。404 更常见地说明路由、版本前缀或资源路径不匹配；不要只重复粘贴 API Key。
本次没有检索到可核验的 apikey.sbs 官方接口文档，所以无法确认其 Base URL 是否必须以 /v1 结尾，也无法确认具体模型 ID。此处应以你实际获得的接口文档、控制台模型列表或服务端响应为准。
Cursor 中哪些功能会使用这组配置
| 功能 | 是否可直接按这组配置判断 | 说明 |
|---|---|---|
| Chat | 可以优先测试 | OpenAI 和 Cursor 文档都把自有 Key 或兼容网关的主要使用范围放在本地 Chat。 |
| Agent | 可以优先测试 | 官方说明支持在本地 Agent 场景使用自有 Key，但端点兼容性和模型能力仍取决于服务商。 |
| Tab 自动补全 | 不要默认认为会使用 | Cursor 文档明确说明，自定义 API Key 只适用于聊天模型，Tab completion 继续使用 Cursor 内置模型。 |
| Auto 或自动路由 | 不要默认认为会使用 | OpenAI 官方说明将 Auto model selection and routing 列为自有 OpenAI Key 不适用的范围。 |
| Cloud、Background Agents、Automations | 不要默认认为会使用 | 官方说明列出这些功能不使用用户在本地配置的 OpenAI Key 或网关凭据。 |
| Cursor CLI、API、SDK | 属于另一套认证与端点配置 | Cursor CLI 文档单独说明了 CLI 登录、API Key 和自定义 endpoint 参数，不能把桌面端模型设置直接套用到 CLI。 |
因此，配置成功的判断标准应限定在本地 Chat 或 Agent：模型被选中、请求发出、服务端返回有效文本。不要因为 Tab 或 Cloud Agent 仍使用其他模型，就认定桌面端的兼容接口配置失败。
Verify 失败、401、404、429、超时和空回复排查
| 现象 | 优先检查 | 处理动作 |
|---|---|---|
| Verify 失败或 401 | Key 是否有效、是否多了引号或空格、Bearer 认证是否正确 | 重新生成或复制 Key；确认该 Key 对应的服务商和接口地址；用最小请求单独验证。 |
| 403 | 账号权限、项目权限、区域限制或模型权限 | 查看服务商返回的错误正文和控制台权限，不要只更换 Base URL。 |
| 404 | Base URL 拼接路径、版本前缀、模型或部署名 | 把最终请求地址与服务商文档逐段对照，避免重复填写 /chat/completions。 |
| 429 | 余额、限速、并发或服务商队列 | 先降低请求频率和并发，检查服务商用量与限速说明；不要用不断重试代替排查。 |
| 超时 | 网络连通性、服务端排队、模型响应时间和 Cursor 请求范围 | 先用短消息和较短超时测试，再检查服务商状态与响应时间；复杂上下文可能需要更长时间。 |
| 模型无效或 model not found | 模型 ID、模型开关、Key 是否真正附加到请求 | 复制服务端真实模型 ID，重新启用 Key 和模型，并新建会话后重试。 |
| 空回复或格式错误 | 兼容接口是否支持 Cursor 使用的聊天字段、流式响应或工具参数 | 先发送纯文本请求；若最小请求成功，再逐项增加流式、工具或复杂上下文能力。 |
| Chat 成功但 Tab 不变 | 功能范围而不是 Key 配置 | Cursor 官方文档说明 Tab 使用内置模型，不应把该现象当作 Chat 配置失败。 |
排错时建议保留服务端返回的状态码、错误正文、请求时间和模型名，但不要记录完整 API Key。若要检查是否请求到了自定义端点，可在服务商控制台或网关日志中查看请求记录；公开官方资料未保证所有网关都提供相同日志字段。
配置前后的安全检查
- API Key 只粘贴到 Cursor 的密钥字段或安全的环境变量中，不要写进项目源码、提交记录、截图和 URL。
- 如果团队使用 Cursor，请确认管理员是否限制个人 API Key；Cursor 官方企业文档说明，企业团队可以控制成员是否使用个人 Key。
- Cursor 官方文档说明，使用自有 API Key 时，Zero Data Retention 政策不适用于该请求，数据处理规则要看所选服务商的隐私政策。
- 完成测试后，检查服务商用量、限速和访问日志；如果怀疑泄露，应立即撤销旧 Key 并创建新 Key。
- 兼容接口能返回文本，不代表它支持 Cursor 的全部能力。工具调用、流式输出、视觉输入、上下文长度和推理参数都应分别验证。
常见问题
Cursor 使用 OpenAI 兼容 API 时，Base URL 一定要加 /v1 吗？
不一定。本次检索到的官方资料只说明自定义端点必须符合 Cursor 需要的 API 格式，没有规定所有网关统一使用 /v1。应查看服务商文档，并确认 Base URL 最终能正确拼出聊天请求路径。
模型名称应该填完整 ID 还是自定义短名称？
优先填写服务端实际识别的模型 ID。公开官方文档没有给出适用于所有兼容网关的统一短名称映射规则；如果模型无效，应从服务商模型列表或错误响应中核对精确拼写和大小写。
Cursor 配置成功后，为什么 Tab 自动补全没有切换到这个接口？
这是功能范围限制，不一定是配置错误。Cursor 官方文档说明，自定义 API Key 主要适用于聊天模型，Tab completion 继续使用 Cursor 的内置模型，因此应在 Chat 或 Agent 中验证。
Verify 通过了，但 Chat 仍然提示模型无效怎么办？
先确认模型已启用并在模型选择器中选中，再核对模型 ID是否与服务端完全一致。随后新建会话重试；如果仍失败，用相同 Key、Base URL 和模型 ID发送最小聊天请求，区分 Cursor 设置问题与接口响应问题。
可以把 OpenAI 兼容 API 配置直接用于 Cursor CLI 吗？
不要直接套用。Cursor CLI 有独立的认证方式和 endpoint 参数，官方 CLI 文档将浏览器登录、CLI API Key 和自定义 endpoint 分开说明，应按 CLI 文档单独配置。
相关阅读
参考资料
- Using OpenAI models in Cursor
- Bring your own API key | Cursor Docs（cursor.com）
- Available models | Cursor Docs（prod.cursor.com）
- Cursor CLI Authentication（docs.cursor.com）
- Chat Completions | OpenAI API Reference
- Model and Integration Management | Cursor Docs（prod.cursor.com）