Cursor 自定义 OpenAI API 失败？先查 Base URL、Key 和模型名

更新于 2026-10-21 · onomeo.cyou

简答：填了 Key 和 Base URL 后，Cursor 仍报错或 Tab 没变化时，先不要反复改配置：先用 <code>/models</code> 验证 Key 与 Base URL，再用同一个模型 ID 发送最小 Chat 请求。本文讲 Cursor 调用外部 OpenAI 兼容接口，不讲把 Cursor 订阅包装成 API；Agent 是否使用自定义接口需按当前版本实测，Tab 补全不会使用自定义 API Key。

定义：OpenAI 兼容 API 是采用相近认证方式、请求路径和请求体格式提供模型调用的接口，Cursor 可在支持的配置入口中尝试将部分模型请求指向自定义 Base URL。

先看结论：三项配置、一个验证顺序

本文由第三方 AI API 接入指南站整理，不是 Cursor 官方页面。检查日期为 2026 年 10 月 21 日，Cursor 的设置名称和可用功能可能随版本变化。

如果你要让 Cursor 调用外部 OpenAI 兼容接口，先核对 API Key、Base URL、模型 ID 三项。最稳妥的顺序是：先请求 Base URL 加 /models，确认认证和路径；再使用同一个模型 ID 发送最小聊天请求；最后回到 Cursor 检查实际请求地址和响应。

功能范围先说清楚：Cursor 官方 API Key 文档明确写明，自定义 API Key 只适用于 Chat 模型，Tab 补全继续使用 Cursor 内置模型。Agent 是否经过自定义接口，本文不作统一承诺，应通过当前版本的 Network 日志实测，不能仅凭 Chat 成功推断。

以上功能边界可参阅 Cursor 官方 Bring your own API key 文档。其中还说明，使用自有 API Key 时，请求会经过 Cursor 服务端进行最终提示词构建，因此本地接口是否能被 Cursor 访问，需要单独验证。

在 Cursor 中填写 Key、Base URL 和模型 ID

1. 打开 Cursor 设置，进入 Models 页面。官方文档给出的入口是 Settings → Models，然后选择对应提供方并粘贴 API Key。
2. 填写外部接口的 API Key。不要把登录密码、Cursor 账号凭据或其他服务的 Key 混用。Key 不要放入公开仓库、截图、Issue 或共享日志。
3. 如果当前版本显示 Override OpenAI Base URL，填写接口要求的根地址。不要把完整的 /chat/completions 或 /responses 路径直接当成 Base URL，除非接口文档明确要求如此。
4. 在模型选择处填写接口实际接受的模型 ID。本文不硬编码具体模型 ID，请从接口官方模型列表或 /models 响应中复制，并在页面中写入 <MODEL_ID> 所代表的真实值。
5. 先测试 Chat，再决定是否继续排查 Agent。不要用 Tab 补全作为自定义接口的验收标准，因为 Cursor 官方文档明确说明 Tab 继续使用内置模型。

Base URL 是否能按模型分别配置，不能凭界面猜测。Cursor 社区问题记录显示，某些情况下 Override OpenAI Base URL 是全局设置，可能影响标准模型；可参考 Cursor 社区关于自定义模型独立 Key 与 Base URL 的记录。这属于社区问题记录，不是永久产品承诺，具体行为以当前客户端为准。

如果找不到 API Key 或 Base URL 输入框，先检查当前版本的 Models 页面、是否启用了限制自定义模型的设置，以及页面是否已经保存了其他提供方配置。不要根据旧截图断言当前界面一定存在某个按钮。

先在命令行验证：/models，再发一次 Chat 请求

命令行验证的作用是把问题拆成两层：接口是否接受认证，以及模型请求是否符合接口格式。下面的 Bash 示例依赖 curl 和 jq；其中 jq 用于生成 JSON，请先确认它已安装。示例放在子 Shell 中运行，不会因为 set -eu 改变当前交互终端的退出行为。

Bash：列出模型并发送最小请求

(
  set -eu
  tmp_models="$(mktemp)"
  tmp_chat="$(mktemp)"
  trap 'rm -f "$tmp_models" "$tmp_chat"' EXIT

  read -rs -p "API Key: " API_KEY
  printf '\n'
  read -r -p "Base URL（例如 https://example.com/v1）: " BASE_URL
  BASE_URL="${BASE_URL%/}"
  read -r -p "模型 ID（从 /models 响应复制）: " modelId

  status_models="$(curl -sS -o "$tmp_models" -w '%{http_code}' \
    -H "Authorization: Bearer $API_KEY" \
    "$BASE_URL/models")"
  printf 'models HTTP %s\n' "$status_models"
  cat "$tmp_models"

  status_chat="$(jq -n --arg model "$modelId" \
    '{model:$model,messages:[{role:"user",content:"Reply with OK"}],temperature:0}' \
    | curl -sS -o "$tmp_chat" -w '%{http_code}' \
      -H "Authorization: Bearer $API_KEY" \
      -H 'Content-Type: application/json' \
      "$BASE_URL/chat/completions" \
      --data-binary @- )"
  printf '\nchat HTTP %s\n' "$status_chat"
  cat "$tmp_chat"

  unset API_KEY
)

这里使用 BASE_URL="${BASE_URL%/}" 去掉末尾斜杠，避免拼出 //models。HTTP 状态码通过 -o 将响应体写入临时文件后单独输出，没有把状态码和 JSON 混在一起交给 jq。

如果接口官方文档要求 Responses 风格，而不是 Chat Completions 风格，请按该接口文档替换请求路径和 JSON 结构。Cursor 社区排错记录提到，开发者工具中可能看到 /v1/responses 或 /v1/chat/completions，因此不要仅凭一个路径假设所有兼容接口都相同。

PowerShell 7.x：使用 SecureString 输入 Key

$apiKeySecure = Read-Host "API Key" -AsSecureString
$ptr = [Runtime.InteropServices.Marshal]::SecureStringToBSTR($apiKeySecure)
try {
  $apiKey = [Runtime.InteropServices.Marshal]::PtrToStringBSTR($ptr)
} finally {
  [Runtime.InteropServices.Marshal]::ZeroFreeBSTR($ptr)
  $apiKeySecure.Dispose()
}

$baseUrl = (Read-Host "Base URL（例如 https://example.com/v1）").TrimEnd('/')
$modelId = Read-Host "模型 ID（从 /models 响应复制）"
$headers = @{ Authorization = "Bearer $apiKey" }

try {
  $models = Invoke-WebRequest -Uri "$baseUrl/models" -Headers $headers -Method Get
  "models HTTP $($models.StatusCode)"
  $models.Content

  $body = @{
    model = $modelId
    messages = @(@{ role = "user"; content = "Reply with OK" })
    temperature = 0
  } | ConvertTo-Json -Depth 5

  $chat = Invoke-WebRequest -Uri "$baseUrl/chat/completions" -Headers $headers -ContentType "application/json" -Method Post -Body $body
  "chat HTTP $($chat.StatusCode)"
  $chat.Content
} catch {
  "HTTP request failed"
  if ($_.ErrorDetails -and $_.ErrorDetails.Message) {
    $_.ErrorDetails.Message
  } else {
    $_.Exception.Message
  }
  return
} finally {
  $apiKey = $null
}

这段 PowerShell 按 7.x 写法组织，未声称已验证 Windows PowerShell 5.1。错误分支读取 $_.ErrorDetails.Message，避免对 HttpResponseMessage 调用不适用的响应流方法；$modelId 会实际进入请求体，不会被另一个硬编码模型名覆盖。

401、403、404、429 和超时：按状态码处理

HTTP 状态码只能说明请求在协议层面的结果，不能单独证明问题一定来自 Key 或模型。RFC 9110 的 HTTP 语义说明将 4xx 归为客户端错误，并分别定义了认证、权限和资源路径含义；排查时应同时保存请求 URL、状态码和响应体。

404 的关键不是猜测 Cursor 一定会自动追加哪一段路径，而是记录真实请求。把 Base URL 分别设为根地址和带 /v1 的地址，分别请求 /models，再查看 Cursor Network 中最终访问的路径。这样能区分“接口没有该资源”和“客户端拼接路径不符合接口要求”。

429 不应通过连续刷新 Cursor 来解决。先保存响应体和 Retry-After，确认是否是单 Key、单模型、单项目或整个接口入口限速，再调整并发和重试策略。

curl 成功但 Cursor 失败：重点查 Network、localhost 和全局覆盖

1. 打开 Developer Tools。进入 Help → Toggle Developer Tools，切换到 Network，发送一次 Chat 请求，查看失败请求的完整 URL、状态码和响应体。Cursor 社区问题记录给出的排查步骤也是先从 Network 中确认真实请求。
2. 确认实际路径。社区记录列举了 /v1/responses 和 /v1/chat/completions 两种可能路径。记录结果后，按接口文档核对 Base URL 是否应包含 /v1，不要只看设置框中的文字。
3. 检查 localhost 或内网地址。假如本机 curl 成功而 Cursor 失败，两者可能处于不同的网络视角。Cursor 社区问题记录提到，沙箱或网络限制可能导致 Cursor 无法按预期访问 localhost，并建议检查 HTTP/1.1 兼容模式。可参考 Cursor 社区关于自定义 OpenAI 兼容接口的排错记录。这不是对所有系统的统一结论，应以你的系统、客户端版本和 Network 日志为准。
4. 检查 HTTP Compatibility Mode。如果接口是本地服务，或 Network 显示连接层异常，可在 Cursor 的 Network 设置中尝试 HTTP/1.1 兼容模式，然后重新发送一次请求并记录差异。
5. 检查全局 Base URL 覆盖。如果外部接口成功后，内置模型出现模型不存在或路径错误，先关闭 Override OpenAI Base URL，再选择内置模型。社区记录显示该覆盖可能影响标准模型，但具体行为随版本变化。
6. 重新复制模型 ID。不要使用聊天界面的简称。用 /models 响应或接口官方模型列表中的完整 ID，确保大小写、斜杠、前缀和后缀完全一致。

如果设置页没有 Verify 按钮，不要把“没有验证按钮”理解为 Key 无效。直接执行 /models 和最小 Chat 请求更可靠；Cursor 当前版本是否提供单独验证按钮，应以实际界面为准。

两类搜索意图要区分：调用外部接口 vs 暴露 Cursor 订阅

搜索“Cursor OpenAI compatible API”时，常见的是两种不同方向：

• 本文讨论的方向：把 Cursor 当作客户端，让它调用外部 OpenAI 兼容接口。重点是 Base URL、Key、模型 ID、请求路径和错误排查。
• 本文不展开的方向：把 Cursor 的订阅或模型能力包装成 OpenAI 兼容 API，再供其他工具调用。这属于反向代理或网关类方案，不等同于 Cursor 原生的自定义 API Key 配置，也不能据此推断获得官方支持。

如果要研究第二类方案，应单独核对项目代码、数据流、维护状态和适用条款；本文不评价其安全性、稳定性或合规性。涉及 Cursor 服务使用方式时，应以其当前服务条款和官方说明为准。

另外，本文不对任何具体接口的价格、额度、速度、可用模型或稳定性作承诺。模型 ID、计费和限速都应以实际接口的官方文档及响应为准。

配置完成后的最小自查清单

• 认证：/models 请求使用正确的 Bearer Key，并能返回接口允许展示的模型信息。
• 路径：Base URL 没有直接包含 /chat/completions，末尾斜杠已处理，实际请求路径与接口文档一致。
• 模型：模型 ID 从官方列表或 /models 响应复制，变量 modelId 实际用于请求。
• 范围：Chat 成功不代表 Agent 必然走自定义接口；Tab 不使用自定义 API Key。
• 网络：curl 与 Cursor 都能访问目标地址；localhost 或内网服务已确认 Cursor 的网络视角可以到达。
• 安全：Key 没有出现在 shell 历史、脚本仓库、截图和日志中；如果已经泄露，应在签发方控制台撤销并重新生成。

完成这份清单后仍失败，优先保存 Cursor Network 中的 URL、状态码和响应体，再与接口服务方核对请求格式。不要只凭界面报错文字判断是 Key、模型还是 Base URL 问题。

常见问题

Cursor 可以直接连接任意 OpenAI compatible API 吗？

不能把“格式兼容”理解成所有功能完全兼容。至少要分别验证认证头、请求路径、请求体、响应格式和模型 ID；某个接口能被 curl 调用，也不代表 Cursor 的 Chat、Agent 和 Tab 都会使用它。

为什么 curl 能访问 localhost，Cursor 却连接失败？

curl 和 Cursor 可能处于不同的网络或沙箱环境。先在 Cursor 的 Help → Toggle Developer Tools → Network 中确认请求是否发出、最终 URL 和状态码，再检查本地服务监听地址、防火墙、HTTP 兼容模式以及 Cursor 是否能访问该端口。

Cursor 的 Tab 为什么没有使用我的 OpenAI 兼容接口？

Cursor 官方 API Key 文档明确说明，自定义 API Key 只适用于 Chat 模型，Tab 补全继续使用 Cursor 内置模型。因此 Chat 成功而 Tab 没有走你的 Base URL，可能是产品边界而不是配置失败。

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

通常应填接口要求的根地址，而不是完整的聊天路径。由于不同接口的路径约定可能不同，先分别测试 Base URL 加 <code>/models</code>，再查看 Cursor Network 中最终请求的是哪条路径；不要凭猜测固定写法。

为什么会出现 401、403 或 404？

401 通常先查认证凭据；403 查权限、来源限制或接口策略；404 查 Base URL、<code>/v1</code> 和实际资源路径。三类错误都应同时查看响应体，不要只根据 Cursor 的简短提示判断。

429 应该怎么处理？

先读取响应中的 <code>Retry-After</code>，按服务方给出的时间等待，再降低并发并使用有限次数的退避重试。RFC 6585 将 429 定义为一段时间内请求过多，并说明响应可以包含 Retry-After。

参考资料

1. Cursor 官方：Bring your own API key（cursor.com）
2. Cursor 社区：自定义 OpenAI 兼容接口排错记录（forum.cursor.com）
3. Cursor 社区：自定义模型是否支持独立 API Key 与 Base URL（forum.cursor.com）
4. RFC 9110：HTTP Semantics
5. RFC 6585：Additional HTTP Status Codes