Cursor 自定义 API 的完整配置与四类常见报错

配置前先明确一件事

Cursor 的「自定义 API」能力只覆盖部分功能。它的补全（Tab completion）、部分索引功能依赖官方服务，自定义 API 通常只作用于 Chat 与 Agent 面板。

这个前提很重要：如果你配好了自定义 API，却发现 Tab 补全没走你的 Key，那是设计如此，不是配置失败。

配置步骤

第一步：关闭可能干扰的官方开关

在设置里，把内置的官方模型开关关掉或忽略 —— 部分版本在两者同时存在时优先走官方通道。

第二步：填入 Base URL

关键判断：要不要带 /v1。

• 如果中转站文档写的是 https://<域名>/v1，就填 https://<域名>/v1；
• Cursor 会自己在后面拼 /chat/completions；
• 填成 https://<域名>/v1/chat/completions 会变成双份路径 → 404。

验证方法：拼完之后的完整地址应该是 https://<域名>/v1/chat/completions。如果不确定，先用 curl 打这个地址确认能通。

第三步：填入 API Key

注意前缀。有些中转站的 Key 需要带 Bearer 前缀，有些 Cursor 版本会自己加 —— 重复加会变成 Bearer Bearer xxx → 401。

判断方法：先用 curl 验证，-H "Authorization: Bearer $KEY" 能通就说明 Key 本身没问题，剩下的就是在 Cursor 里试哪种填法。

第四步：手动添加模型名 ★最易漏

这是最高频的「配置全对但模型列表是空的」原因：Cursor 不会从中转站的 /v1/models 自动拉取模型列表。你必须手动输入模型名。

填写的名字必须是中转站接口能识别的名字。判断方法：

curl -s https://<域名>/v1/models -H "Authorization: Bearer $KEY" \
  | python -c "import sys,json;print([m['id'] for m in json.load(sys.stdin)['data']][:40])"

用这个清单里的名字，不要用官方文档里的名字（两者常常不一致）。

第五步：处理 verify 开关

部分版本有一个「verify」或「验证」开关，开启时会向官方端点发一次校验请求 —— 在中转站场景下会失败。

症状：配置看起来正确，但一直提示验证失败或请求被拒。关掉它。

四类常见报错逐条解释

报错一：401 Unauthorized

三种可能，按概率排序：

1. Key 前缀重复（Bearer Bearer）—— 见第三步；
2. Key 被中转站禁用或余额耗尽 —— 用 curl 单独验证；
3. 中转站要求的是 x-api-key 而不是 Authorization —— 少数只做 Anthropic 协议的站会这样。Cursor 走的是 OpenAI 格式，这类站接不上。

报错二：404 Not Found

两种可能：

1. Base URL 路径重复（/v1/chat/completions 被拼了两次）；
2. 模型名中转站不认 —— 有些站对未收录的模型返回 404 而不是 400，容易误判成路径问题。

区分方法：看错误响应体。如果是路径问题，通常是 nginx 层的 HTML 404 页面；如果是模型问题，通常是 JSON 格式的错误对象。

报错三：400 Bad Request

最常见的三条：

1. 请求里带了中转站不支持的参数。Cursor 会发送一些官方扩展字段（如 top_k、特定的 tool_choice 形态）。多数站会忽略未知字段，但严格校验的实现会直接 400。行业里针对 Claude 系客户端有一句经验：建议用站方提供的「Cursor 专用」端点或参数兼容模式（有些中转站会提供）。
2. 消息结构不符合预期：Cursor 会发送它自己的 system prompt，内容较长。如果站方有 prompt 长度或内容过滤，会被拒。
3. 工具定义过多：Cursor Agent 模式会带上一大批工具定义，超过某些实现的解析上限。

报错四：一直转圈不返回

成因：流式响应不完整或首字延迟过高。

1. 中转站做了请求缓冲（先收完再转发）→ TTFT 非常长；
2. 流式结束标记缺失 → Cursor 一直等；
3. 站方的超时设置短于 Cursor 的等待时间 → 连接被中断但不报错。

排查：用 curl 的 -N 抓流，看首字时间与结束标记。参考本站《流式输出（SSE）在中转站上的六种异常》一篇，六类异常里有三类会表现为「转圈」。

配置完成后的验证清单

1. Chat 面板发一句简单问候 → 有回复；
2. 让它读一个文件 → 工具调用正常（这一步最关键，见工具调用专文）；
3. 让它改一个文件 → 改动正确落地；
4. 长对话续几轮 → 不失忆；
5. 输出一段中文 → 不乱码。

五条全过，才算真的配通。第 2、3 条是 Agent 场景的核心，很多人只测了第 1 条就以为成功了。

一个务实的替代方案

如果你在中转站上始终调不通 Cursor 的 Agent 功能，有两步可退：

1. 换一家在详情页标注「支持 Cursor」的中转站（本站列表中会标注客户端兼容信息）；
2. 在本地跑一个协议转换代理（把 OpenAI 转成它需要的形态），让 Cursor 指向 localhost。

第 2 步会引入额外维护成本，但如果你的上游只在 OpenAI 格式上可用，这是唯一的路。