Cursor OpenAI 兼容 API 配置：先验接口，再排查 401、404 与模型不存在

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

简答：Cursor 填了 OpenAI 兼容 Base URL 仍报 401、404 或模型不存在，通常是 API Key、Base URL、模型 ID 三项没有对齐，或接口无法被 Cursor 后端访问。最稳妥的顺序是：先请求 /models，再请求 /chat/completions，最后在 Cursor Settings → Models 中打开 OpenAI API Key 和 Override OpenAI Base URL。还要注意，Cursor 的 Override 可能影响其他内置模型，Tab 补全也不会改用你的自定义 API。

定义：OpenAI 兼容 API 是采用相近认证头、模型标识和聊天请求结构的接口，Cursor 只有在 API Key、Base URL、模型 ID、请求路径及网络可达性都满足服务端要求时，才能正常调用。

30 秒自查：先验证接口，再打开 Cursor

如果你已经填写了 Base URL 但 Cursor 一直报错，不要先反复切换模型。先用同一组 API Key 和 Base URL 验证两个接口：GET /models 用来检查认证和地址，POST /chat/completions 用来检查模型 ID 和聊天格式。OpenAI 官方分别提供了模型列表接口说明和聊天完成接口说明，兼容接口是否支持这些路径，仍应以对应服务端文档为准。

速查结论：/models 返回 200，继续测聊天接口；聊天接口返回 200，再回到 Cursor；任何一步失败，都先修复该层，不要把问题归因于编辑器。

BASE_URL="https://api.example.com/v1"
MODEL_ID="<MODEL_ID>"
BODY_FILE="$(mktemp)"
trap 'rm -f "$BODY_FILE"' EXIT

read -r -s -p "API key: " API_KEY
printf '\n'

curl -sS -o "$BODY_FILE" -w 'HTTP %{http_code}\n' "$BASE_URL/models" \
  -H "Authorization: Bearer $API_KEY"
printf '\n模型列表响应：\n'
cat "$BODY_FILE"

curl -sS -o "$BODY_FILE" -w 'HTTP %{http_code}\n' "$BASE_URL/chat/completions" \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d "{\"model\":\"$MODEL_ID\",\"messages\":[{\"role\":\"user\",\"content\":\"Reply with OK.\"}]}"
printf '\n聊天接口响应：\n'
cat "$BODY_FILE"
unset API_KEY

MODEL_ID 只是占位符，请从官方模型列表复制实际值。示例使用 curl -o 将响应体写入临时文件，再单独输出状态码和响应体，避免把状态码混入 JSON。

在 Cursor 中配置三项参数

根据Cursor 官方 Bring your own API key 说明，自定义 Key 的入口在 Settings → Models。页面名称和开关可能随客户端界面变化；官方当前说明的基本流程是选择提供方、粘贴 API Key 并保存。若需要自定义 OpenAI 兼容接口，再填写 Override OpenAI Base URL。

1. 打开 Models 页面。进入 Cursor Settings → Models，找到 OpenAI API Key 配置区域。
2. 开启并保存 Key。粘贴服务端 API Key，并打开使用该 Key 的开关。不要把 Key 写进项目文件或命令历史。
3. 填写 Override OpenAI Base URL。填服务端要求的根地址，不要直接填 /chat/completions 或 /responses。是否需要 /v1，必须以接口文档和实际请求路径为准。
4. 添加或选择模型。模型名使用服务端实际识别的 ID。本文统一使用 <MODEL_ID>，请从官方模型列表复制，不能直接照抄占位符。
5. 新建聊天测试。选择自定义模型发送短消息。若接口测试成功但 Cursor 提示模型不存在，重新核对模型 ID、Key 权限和模型是否已在设置中启用。

当前官方帮助页的基本流程是保存 Key，并没有要求一定存在 Verify 按钮。较早的 Cursor 社区问题记录显示，部分版本曾出现 Verify 入口或相关验证行为，后续版本可能移除该按钮，因此不要把“看不到 Verify”单独判断为配置失败。

Cursor 的四个机制限制：配置前必须知道

Cursor 官方说明明确写到，自定义 Key 请求会经过 Cursor 后端进行最终提示词构建，且自定义 API Key 只适用于聊天模型，Tab 补全继续使用 Cursor 内置模型。关于 localhost 和内网地址，Cursor 社区的问题记录及回复说明目前需要公网 HTTPS 端点；这属于社区问题记录中的产品限制说明，不应理解为本地接口已经得到官方长期支持。

另一个容易误判的情况是：开启 Override OpenAI Base URL 后，Cursor 内置模型可能也受到影响。Cursor 社区问题记录显示，Override 可能对多个非 Claude 或 Gemini 模型统一生效，导致内置模型返回自定义 Key 无效、模型不支持自定义 Key 或模型不存在等错误。遇到这种情况，先关闭 Override 验证内置模型，再打开 Override 验证自定义模型，不要同时用两个结果判断同一条配置。

关于请求格式，还要确认接口支持 Cursor 实际发出的路径。Cursor 社区排查记录提到，部分请求可能使用 /v1/responses，而一些兼容服务只实现 /v1/chat/completions；因此，若认证成功却在聊天阶段返回 404 或格式错误，应在开发者工具的 Network 面板中确认实际请求路径，并按服务端支持范围选择接口。

Windows PowerShell 5.1 与 PowerShell 7.x 验证脚本

下面脚本按 Windows PowerShell 5.1 与 PowerShell 7.x 的常见语法编写。API Key 使用 SecureString 输入；模型列表和聊天请求分别执行；错误处理会尝试读取 HTTP 状态码和响应体。不同 PowerShell 版本或服务端响应类型可能导致错误体读取方式略有差异，因此脚本会同时保留异常消息作为兜底。

$BaseUrl = "https://api.example.com/v1"
$ModelId = "<MODEL_ID>"
$secureKey = Read-Host "API key" -AsSecureString
$bstr = [IntPtr]::Zero
$key = $null

try {
  $bstr = [Runtime.InteropServices.Marshal]::SecureStringToBSTR($secureKey)
  $key = [Runtime.InteropServices.Marshal]::PtrToStringBSTR($bstr)
  $headers = @{ Authorization = "Bearer $key" }

  try {
    $models = Invoke-RestMethod -Method Get -Uri "$BaseUrl/models" -Headers $headers
    $models.data | ForEach-Object { $_.id }
  } catch {
    $response = $_.Exception.Response
    if ($response) {
      $status = [int]$response.StatusCode
      $reader = New-Object System.IO.StreamReader($response.GetResponseStream())
      $errorBody = $reader.ReadToEnd()
      $reader.Dispose()
      Write-Error "模型列表请求失败，HTTP $status：$errorBody"
    } else {
      Write-Error "模型列表请求失败：$($_.Exception.Message)"
    }
  }

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

  try {
    $result = Invoke-RestMethod -Method Post -Uri "$BaseUrl/chat/completions" -Headers $headers -ContentType "application/json" -Body $body
    $result.choices[0].message.content
  } catch {
    $response = $_.Exception.Response
    if ($response) {
      $status = [int]$response.StatusCode
      $reader = New-Object System.IO.StreamReader($response.GetResponseStream())
      $errorBody = $reader.ReadToEnd()
      $reader.Dispose()
      Write-Error "聊天请求失败，HTTP $status：$errorBody"
    } else {
      Write-Error "聊天请求失败：$($_.Exception.Message)"
    }
  }
} finally {
  if ($bstr -ne [IntPtr]::Zero) {
    [Runtime.InteropServices.Marshal]::ZeroFreeBSTR($bstr)
  }
  if ($secureKey) {
    $secureKey.Dispose()
  }
  $key = $null
}

如果 PowerShell 5.1 对错误响应流的读取方式与 PowerShell 7.x 表现不同，先保留状态码和异常消息，再使用 Cursor 的开发者工具查看实际响应。脚本不会把 Key 写入命令行参数，但进程内存和服务端日志仍应按你的安全策略管理。

401、404、模型不存在与请求中断排查

建议固定使用“认证层 → 模型层 → 聊天层 → 编辑器层”的顺序。只有 /models 成功，才能说明 Key 和 Base URL 的基础认证大致正常；只有聊天请求成功，才能继续判断 Cursor 的模型选择、流式响应或 Agent 兼容性。

版本、团队策略与安全自查

• 看不到 Base URL 或 API Key 开关：先打开 Settings → Models，确认当前客户端是否显示 API Keys 区域；再检查账户或团队是否限制自定义 Key。界面名称变化时，以当前 Cursor 帮助页为准。
• 看不到 Verify：不要以 Verify 按钮作为必需步骤。当前官方帮助页的流程是填写 Key 并保存，之后从模型选择器和实际聊天请求判断是否成功。
• 团队使用：由管理员统一确认是否允许自定义 Key、是否限制模型，以及 Key 是否应按成员或环境分别管理。本文不展开企业管理后台的具体字段。
• 公网端点：只开放必要路径，启用 HTTPS、认证、访问日志和额度限制；不要为了测试把无认证的本地接口直接暴露。
• Key 泄露：如果 Key 出现在 Git、终端录屏、调试日志或公开问题记录中，应立即在服务端撤销并重新生成。
• 敏感代码：Cursor 官方说明指出，使用自有 API Key 时请求仍会经过 Cursor 后端，数据处理还会遵循所选 API 提供方的隐私政策。接入前应分别阅读相关说明。

本文不核实任何具体兼容 API 服务的价格、限速、并发、可用性、模型路由或稳定性；这些信息应以对应服务商截至实际使用日期发布的官方说明为准。

常见问题

Cursor 的 OpenAI 兼容 Base URL 应该怎么填？

填写服务端要求的兼容接口根地址，不要把完整的 /chat/completions 或 /responses 路径直接填进去。是否包含 /v1 必须以接口文档和实际请求路径为准；填好后先用同一个地址请求 /models。

为什么 /models 返回 200，Cursor 仍提示模型不存在？

通常是 Cursor 中的模型名没有使用接口返回的真实 ID，或当前 API Key 没有该模型权限。把 /models 返回的 id 原样复制到 Cursor，并检查大小写、连字符、模型开关和账户权限。

为什么打开 Override OpenAI Base URL 后，Cursor 内置模型不能用了？

Cursor 社区问题记录显示，Override 可能对多个模型统一生效，导致内置模型请求也被发送到自定义端点。先关闭 Override 验证内置模型；使用自定义模型时再打开，当前设置可能无法为每个模型单独配置 Base URL。

Cursor 能直接连接 localhost 或局域网里的 OpenAI 兼容接口吗？

当前 Cursor 的自定义 Key 请求会经过 Cursor 后端，社区问题记录说明本机 localhost 和内网地址通常不能直接被其后端访问，需要使用 Cursor 可访问的公网 HTTPS 端点。不要把未认证的本地服务直接暴露到公网。

配置了自定义 API 后，Cursor Tab 为什么没有使用这个接口？

Cursor 官方帮助页说明，自定义 API Key 只用于聊天模型，Tab 补全继续使用 Cursor 内置模型。因此聊天请求成功而 Tab 行为不变，不一定代表 Base URL 配置失败。

没有 Verify 按钮是不是说明配置失败？

不一定。当前 Cursor 官方帮助页描述的是在 Settings → Models 中填写 API Key 并保存，部分旧版或社区记录中出现过 Verify 按钮。应以 /models、聊天请求和 Cursor 实际响应判断配置是否成功。

相关阅读

• 返回 AI API 接入首页

参考资料

1. Cursor 官方：Bring your own API key（cursor.com）
2. OpenAI 官方 API Reference：Models List
3. OpenAI 官方 API Reference：Chat Completions
4. Cursor 社区问题记录：本地模型与公网 HTTPS 端点（forum.cursor.com）
5. Cursor 社区问题记录：Override 与内置模型同时使用的限制（forum.cursor.com）
6. Cursor 社区问题记录：Override 全局生效与请求格式兼容性（forum.cursor.com）