Cursor 国内接入 Claude / GPT API 完整教程:自定义 Base URL 配置、model not found 排查与 Agent 能不能用(2026)
Cursor 允许覆盖 OpenAI 的 Base URL,指向任何 OpenAI 兼容端点,就能用自己的 key 调 Claude / GPT / Gemini。逐步配置、先在 Cursor 外面用 curl 自检、model not found / 401 / 连不上的排查表,以及 Chat、Tab、Agent 各模式对自定义 key 的不同表现。
1. 原理:Cursor 留了一个标准入口
Cursor 和模型之间说的是 OpenAI 的 chat completions 协议。任何实现了这套协议的端点都是合法目标,所以 Base URL 被做成了设置项,而不是藏起来的参数。这不是绕过什么限制,而是产品本来就留好的扩展口 —— 同样的方法对 Cline、Continue、Cherry Studio 这类支持 OpenAI 兼容端点的工具都适用。对国内开发者来说,意义很直接:模型额度可以用一个能用支付宝 / 微信支付(人民币)充值的中转 key 来付,模型也可以按活自己挑。
2. 两分钟配置
① 注册 cocodot,充值后在控制台新建一个 API Key;② 打开 Cursor 的 Settings → Models;③ 在 OpenAI API Key 栏粘贴 key;④ 打开覆盖 OpenAI Base URL 的开关,填 https://cocodot.co/api/ai/v1(带 /v1,末尾不要再加斜杠或 /chat/completions);⑤ 添加你要用的模型名,至少加两个:一个强模型干难活、一个便宜模型干杂活;⑥ 在 Chat 里选中刚加的模型发一句话,能回复才算通。Cursor 各版本的菜单名和开关文字会变,如果界面和这里对不上,以 Cursor 当前文档的字段名为准。
3. 先在 Cursor 外面验通:两条 curl
很多人一上来就在 Cursor 里反复改设置,其实问题可能出在 key 或模型名本身。先用终端把这两件事单独验掉,Cursor 里剩下的问题就只可能是配置问题。第一条:拉模型列表(这个接口公开,不需要 key),确认你要用的名字确实在里面。第二条:用你的 key 和这个名字发一条最小请求,能返回内容,就证明 key 有效、余额够、名字对。两条都通、Cursor 里还报错,就只剩栏位、开关、Base URL 这三处要查。
# 1) 看端点支持哪些模型名(公开接口,无需 key)
curl https://cocodot.co/api/ai/v1/models
# 2) 用你的 key 和模型名发一条最小请求
curl https://cocodot.co/api/ai/v1/chat/completions \
-H "Authorization: Bearer 你的-key" \
-H "Content-Type: application/json" \
-d '{"model":"claude-sonnet-5","messages":[{"role":"user","content":"ping"}]}'4. 模型名:报错的第一来源
「model not found」的意思是端点不认识这个名字,不是 key 有问题。在 cocodot 上两种写法都可以:官方型号名(如 claude-sonnet-5、claude-opus-5)和中转代号(如 mcs-6、mco-7)。完整列表在 cocodot.co/pricing#models,机器可读的版本就是上一节第一条 curl 的返回。从列表里复制粘贴,别凭记忆手打 —— 版本号里的点和横线容易写错。还有一种情况:同一个名字在 curl 里能通、在 Cursor 里却报错。这时说明 key 和名字本身没问题,先逐项核对栏位、覆盖开关和 Base URL;再用中转代号添加一次做对照,能帮你判断问题出在这个名字上还是出在配置上。
5. Cursor 有两个 key 栏位,别填混
Cursor 把 OpenAI API Key(带可覆盖的 Base URL)和 Anthropic API Key 分成了两个栏位。想通过 OpenAI 兼容中转用 Claude 模型时,key 要填进 OpenAI 栏,配上中转的 Base URL,再按中转支持的名字选模型。把中转 key 填进 Anthropic 栏,请求会被发到 Anthropic 官方地址,结果是一个看起来像「key 无效」的 401 —— 其实 key 没问题,是目的地错了。想切回 Cursor 内置模型时,先把覆盖开关关掉再测,排查时少一个变量。
6. 各模式表现不同:先把预期摆对
这是最容易误以为「是不是坏了」的地方。Chat:完整走你的自定义端点。Tab 补全:不管你怎么设置,都走 Cursor 自家的补全模型,所以配了中转之后 Tab 没变化是正常现象。Agent / Composer / Edit:依赖工具调用,对模型能力要求更高;而且哪些功能能计到自定义 key 上、哪些必须由 Cursor 自己的服务承担,和你的 Cursor 版本与套餐有关,不同时期还变过。最诚实的检验办法是实测:每种你依赖的模式各跑一次请求,再去 cocodot 控制台的调用明细里看有没有对应记录 —— 没有记录的模式,就是 Cursor 自己处理的。花五分钟做一次,能省掉几周「以为在用自己的 key,其实没有」的误会。
7. 请求是从哪里发出去的
使用自定义 key 时,请求不一定是从你的电脑直接发到端点的 —— 它可能先经过 Cursor 自己的服务器再转发,具体以 Cursor 当前文档为准。如果是这样,会带来两个后果:只跑在你本机(localhost)上的端点,Cursor 访问不到,必须是公网可达的 HTTPS 地址;服务商看到的是 Cursor 服务器的地址而不是你的,所以给 key 设了 IP 白名单的话,请求会被挡掉。自查方法很简单:如果 Cursor 里发了消息、cocodot 控制台的调用明细里却一条记录都没有,先查 Base URL,再查这两点。
8. 跑通之后:对账和成本怎么控
配通之后照这个清单过一遍:① 每个添加的模型在 Chat 里各发一句话,确认都能回;② 去 cocodot 控制台看调用明细,确认请求确实走到了你的端点,扣费和调用对得上;③ 在 Agent 里跑一个小任务,看它是否也出现在明细里。成本上,最有效的办法是强弱搭配:读代码、写注释、小范围修改用中档模型,跨文件重构和真正卡住的难题才切到旗舰模型;同一个 key、同一个余额,在对话框上方切换模型即可。价格方面:Claude / GPT / Gemini 各线挂牌价不超官网,逐型号以价格页实时标价为准。key 别提交进代码仓库,同一个 key 在 Cline、Claude Code、Cherry Studio 里都能用,不用分别开户。
Cursor 自定义端点报错排查表
| 报错 / 现象 | 最可能的原因 | 怎么办 |
|---|---|---|
| model not found / 400 | 模型名和端点支持的名字对不上 | 从 https://cocodot.co/api/ai/v1/models 复制准确的名字,别凭记忆手打 |
| 401 / invalid API key | key 复制不完整、已删除,或填进了错误的栏位 | 中转的 key 要填在 OpenAI API Key 栏,不是 Anthropic 栏 |
| 402 / 余额不足 | key 有效但没有余额 | 充值后再试,反复重试没有用 |
| 连不上 / 404 | Base URL 少了 /v1,或多拼了路径 | 只填 https://cocodot.co/api/ai/v1,不要带 /chat/completions |
| curl 能通,Cursor 里报错 | key 和名字都没问题,问题在 Cursor 里的配置 | 逐项核对栏位、覆盖开关、Base URL;再用中转代号(如 mcs-6)添加一次做对照 |
| Chat 正常,Agent 异常 | Agent 依赖工具调用,和版本、套餐、模型都有关 | Chat 通了就说明连接没问题,Agent 换强模型单独测 |