Cursor 自定义模型为什么不生效？Override 路由机制与常见错误排查

在 Cursor 里填好 API Key 和 Override OpenAI Base URL、Add Model 之后，模型加不进去、报 404，或者请求根本没到 API 服务商。这类问题常被当成"配置填错了"，但其中一部分来自 Cursor 按模型名选择请求路径的方式。本文整理 Cursor 官方文档和论坛里 Cursor 员工的公开回复，说明 Override 的路由规则，并给出配置步骤和"请求有没有到服务商"的验证方法。文中的 API 示例以灵眸 AI 的 OpenAI 兼容接口为例，其他兼容服务同理。

核验日期 2026-11-03，论坛回复越早越可能过时。

一、为什么 Cursor 添加了模型却无法调用？

典型现象：

1. Add Model 提示 The model "xxx" is already available as "Xxx"，加不进去。
2. 配置了 API Key 和 Base URL，服务商后台却没有任何请求记录。
3. 开启 Override 后，Cursor 自带的模型也报错或被送往自己的地址。
4. 自定义模型报 Provider Error、404，或 Model name is not valid。

共同点：Cursor 自定义模型涉及的不只是 API Key 和 Base URL，还有模型名匹配、提供商 Key 槽位和一个全局开关。 请求最终走哪条路，取决于模型名和开关状态，而不是你在下拉里点了哪一项。

背景：Cursor 官方 BYOK 文档只列了 OpenAI、Anthropic、Google、Azure OpenAI、AWS Bedrock 五家提供商，没有记载 Override OpenAI Base URL【A】。另一位论坛用户的帖子也指出，文档没有覆盖 Override OpenAI Base URL（帖 176811，2026-10-30）【B】，该回复的发布者身份未确认。Cursor 员工在论坛称它是"officially supported setup"【B，帖 147219，2026-09-02】，规则散落在论坛回复里。

二、Cursor 自定义模型的请求路由机制

三个设置项各管什么

• Use OpenAI API Key：打开后，走 OpenAI 这条路的请求使用你保存的 Key。员工提到关掉它会影响所有自定义模型【B，帖 175557】。
• Override OpenAI Base URL：把走 OpenAI 这条路的请求发往你填的地址，与 OpenAI Key 一起"适用于每一个不是 Claude 或 Gemini 的模型"【B，帖 172795，2026-09-23】。
• Add Model：在 Models 页登记一个模型名，之后出现在下拉里。登记不等于请求会走你的地址【C】。

请求怎么分流

下图是根据员工回复整理的简化路由，不是 Cursor 公开的内部实现，分支顺序是推断【C】：

你在下拉里选中的模型
 │
 ├─ 名字以 claude- 开头的自定义模型 ──► Anthropic Key 槽位【B】
 │
 ├─ Cursor 托管的内置模型（如 Kimi K3） ─► Override 不生效，请求到不了你的地址【B】
 │      └ Composer、Grok：OpenAI Key 开着时被拒绝【B】
 │
 ├─ 内置的 GPT 系模型，Override 开着 ───► 也被送往你的地址【B】
 │
 └─ 其余自定义名称 ───────────────────► OpenAI Key + Override Base URL ──► 你的 API 服务商

两点需要说明：

• 不同内置模型的表现不一致。 员工确认内置 gpt-5.6-luna 在 Override 开启时被送往自定义地址（帖 169088，2026-08-21），而内置 Kimi K3 是 Cursor 托管的，Override 不适用（帖 175557，2026-10-21）。原因 Cursor 没有公开。
• Claude 和 Gemini 另有各自的 Key 槽位，不受 OpenAI Key 影响（帖 147219，2026-11-01）【B】。

三、三个最容易踩的配置陷阱

陷阱一：自定义模型 ID 与 Cursor 内置模型重名

问题现象

• Add Model 提示 The model "kimi-k3" is already available as "Kimi K3"（论坛用户贴出的提示原文，帖 168231，2026-08-13）。
• 选内置的 Kimi K3，立刻报 Provider Error，providerStatusCode: 404，Moonshot 后台没有任何请求（帖 175557，2026-10-21）。

原因分析

员工的解释：内置 Kimi K3 是 Cursor 托管的模型，Override 对它不适用，请求到不了服务商，才有 404 和空日志。ID 与内置名完全一致时（如 kimi-k3、kimi-k2.7-code），Override "无论地址指向哪里"都不会生效（帖 175557，2026-10-23）【B】。

解决办法

• 换一个不与内置名重合的 ID。员工建议加提供商前缀或在网关侧做别名；Moonshot 案例里名字不同的 kimi-k2.7-code-highspeed 能走自己的地址【B】。别名是否可用要看服务商。
• 想用内置那一份，就关掉 OpenAI Key 开关。此时走的是 Cursor 套餐额度，不是你自己的 Key【B】。

验证方法

加好模型后发一条消息，看服务商后台有没有记录。没有，说明被内置路径接走了。

陷阱二：claude- 前缀导致的提供商路由问题

问题现象

自定义模型叫 claude- 开头的名字，只保存了 OpenAI Key 时，调用报 AI Model Not Found、Model name is not valid。

原因分析

员工回复（帖 173253，2026-09-28）【B】：Cursor 根据模型名开头决定发送哪个已保存的 Key，名字以 claude- 开头时使用 Anthropic Key 槽位，只有 OpenAI Key 时请求就不带 Key。

适用边界

回复只说明了 claude- 前缀，针对"自定义地址加自定义模型名"的场景；gemini- 开头的名字是否同理，员工没有说明【C】。

解决办法

• 用不以 claude- 开头的别名（员工的建议），前提是服务商支持别名。
• 或者直接使用 Anthropic 官方 Key 的槽位。注意 Claude 目前没有 Override Anthropic Base URL：员工在 帖 175557 中表示会把"为 Anthropic 增加 Override"这一需求转给团队（2026-10-23）【B】，没有发布说明，因此经自定义地址接 Claude 的方式未在官方文档中确认。
• 或者在 Cursor 里装 Claude Code 等插件，配置独立于 Models 页【C】。

验证方法

改名后报错应消失，服务商后台应出现记录。

陷阱三：Override 是全局开关，不是单模型分流

问题现象

开启 Override 后，选 Cursor 内置的 GPT 模型，请求被发往自己的地址；选 Composer 或 Grok，报 This model does not support custom API keys。

"This isn't something wrong with your setup. This is expected behavior in the current implementation." — Cursor 员工 deanrie，Cursor 论坛，2026-08-21（帖 169088）

原因分析

员工明确：OpenAI Key 和 Override 适用于所有非 Claude、非 Gemini 的模型，包括 Composer 和 Grok；这两个跑在 Cursor 自己的基础设施上，带着你的 Key 会被拒。"自定义模型走自己的地址、内置模型留在 Cursor"同时生效，目前做不到（帖 172795，2026-09-23）【B】。也不能按模型或提供商分别配置 Base URL 和 Key（帖 147219，2026-11-01）【B】。

解决办法

• 用 Cursor 托管的模型时，关闭 OpenAI Key 开关。
• 来回切换用命令面板里的 Toggle OpenAI key，员工给的快捷键是 Ctrl + Shift + 0（macOS Cmd + Shift + 0），它同时开关 OpenAI Key 和 Override 并保留已存的设置，切换后新开对话【B】。

验证方法

切换后各发一条消息：开关打开时后台应有记录；关闭后选内置模型应正常回复，后台无记录。

四、配置步骤：以 OpenAI 兼容 API 为例

示例使用灵眸 AI 国内站的 OpenAI 协议地址 https://api.lmuai.com/v1 和国产模型 deepseek-v4-pro，灵眸文档列出了这个站点、协议和模型。国际站的 Cursor 接入没有在官方文档里查到，所以没有套用国际站地址；换其他服务商时，用其文档给出的地址和模型 ID。

第 1 步：检查前提、模型 ID 和 API Key

• 套餐需是 Premium 及以上，Plus 不含自带 Key【A】。团队账号还要确认管理员放开了个人 Key 和 OpenAI 一项（帖 173253，2026-09-28）【B】。Enterprise 管理员可在团队后台 Team Settings > Models 限制成员使用个人 API Key【A】（Model and integration management）；员工说明，开启后成员的 API Keys 区域会被隐藏（帖 173253）【B】。
• 在服务商后台创建密钥，确认模型在可用范围内。
• 对照 Cursor 模型与价格页，确认 ID 不与内置名重合，如该页的 DeepSeek V4.1 Flash【A】。

第 2 步：先用 curl 测通服务商

# 列出当前密钥可用的模型（端点存在，带密钥的返回内容未实测）
curl https://api.lmuai.com/v1/models \
  -H "Authorization: Bearer sk-你的密钥"

# 发一条最小对话
curl https://api.lmuai.com/v1/chat/completions \
  -H "Authorization: Bearer sk-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-v4-pro","messages":[{"role":"user","content":"ping"}]}'

能返回内容，说明密钥、地址、模型都正常，后面的故障在 Cursor 侧。

第 3 步：配置 OpenAI API Key

打开 Cursor Settings > Models【A】，在 OpenAI API Key 区域粘贴密钥，并打开 Use OpenAI API Key 开关。

第 4 步：设置 Override OpenAI Base URL

打开 Override OpenAI Base URL，填 https://api.lmuai.com/v1，必须带 /v1，Cursor 自动拼接 /chat/completions，漏掉会 404（服务商文档）。

第 5 步：Add Model、重启并验证

点 Add Model，填 deepseek-v4-pro，每个模型要单独添加。重启 Cursor，新开对话再选模型发消息（员工多次建议）【B】。

五、如何判断请求是否真正到达 API 服务商？

不能只看 Cursor 界面。 模型出现在下拉里，只说明名字登记成功；能回复，也可能是内置路径给的。标准只有一个：服务商后台有没有这条请求。

最小验证流程：

Cursor 发起请求 ──► 服务商网关接收 ──► 后台出现调用记录 ──► 核对模型名、状态码和响应
        │                                    │
        └ 没记录：被内置路径接走，或地址、Key 槽位不对     └ 有记录但失败：按状态码查服务商侧

操作步骤：发一条很短的消息（如"ping"），记下时间；在服务商后台的用量或调用日志里按时间找记录，灵眸控制台的"用量统计"页可按日查看调用次数、Token 消耗和模型占比（如何使用 Token）；核对模型名、状态码、时间是否与操作一致。Cursor 侧失败时，可在对话右上角菜单用 Copy Request ID 取 Cursor 的请求 ID（员工的做法，帖 175557）【B】，它和服务商的请求 ID 是两套，求助时要分开说明。

六、常见错误排查表

后一类的状态码含义见服务商的错误码文档，示例服务商的见错误码速查。

七、总结

排查时按顺序问三个问题：模型名是否冲突（重名或 claude- 前缀）、Override 是否改变了路由（它是全局开关）、请求是否真正到达服务商（看后台记录，不看界面）。请在自己的 Cursor 版本上验证。

常见问题

Cursor 自定义模型为什么不生效？

多数情况是请求没走你的地址。 常见原因是模型 ID 与 Cursor 内置名重名、名字以 claude- 开头、Override 开关状态不对。先看服务商后台有没有请求记录，再对照第六节的排查表。

Cursor Override OpenAI Base URL 怎么填？

OpenAI 协议的地址要带 /v1****，如** https://api.lmuai.com/v1****。** Cursor 自动拼接 /chat/completions，漏掉 /v1 会 404。同时要打开 OpenAI API Key 开关并填入服务商密钥。

Cursor 接入 DeepSeek 怎么配置？

按第四节五步操作，换成 DeepSeek 服务商的 OpenAI 兼容地址、密钥和模型 ID。 Cursor 已有内置的 DeepSeek V4.1 Flash，自定义 ID 不要与它同名。

Cursor Add Model 提示 already available 怎么办？

说明模型 ID 与内置模型重名。 换一个不重名的 ID，或关闭 OpenAI Key 开关改用内置版，后者消耗 Cursor 套餐额度，不是你自己的 Key。

Cursor 模型报 404 怎么排查？

先看服务商后台有没有这条请求。 没有，多半被内置路径接走；有，再查 Base URL 是否带 /v1、模型 ID 是否在可用范围内。

参考来源

按证据级别分组。论坛回复为 Cursor 员工的公开说明，本文没有在 Cursor 里复现。

• Bring your own API key：支持的提供商、自带 Key 的适用范围、个人版与团队版计费、零数据留存的适用边界。
• Models & Pricing：Plus 不含自带 Key，Premium 起才有；Cursor Token Rate 每百万 token 0.25 美元；内置模型目录。
• Model and integration management：Enterprise 在团队后台限制个人 Key 的位置。
• 147219：Override 为受支持的设置；没有按模型或提供商分别配置；Toggle OpenAI key 命令（2026-09-02，11-01）。
• 168231：already available as 提示原文，由用户贴出（2026-08-13）。
• 169088：Override 开启时内置 GPT 也被送往自定义地址（2026-08-21）。
• 172795：OpenAI Key 与 Override 适用于所有非 Claude、非 Gemini 模型，Composer、Grok 被拒（2026-09-23）。
• 173253：claude- 前缀走 Anthropic Key 槽位；团队的个人 Key 设置；Cursor Token Rate 占月度上限（2026-09-28、09-29）。
• 175557：内置 Kimi K3 等为 Cursor 托管，Override 不生效；建议换不重名 ID；Copy Request ID；Anthropic Override 需求转交团队（2026-10-21、10-23）。
• 176811：回复指出文档未覆盖 Override OpenAI Base URL（2026-10-30，回复者身份未确认）。
• Cursor 接入第三方 API 配置：Base URL 必须带 /v1，每个模型单独添加。
• 接入协议：OpenAI 协议端点 POST /chat/completions 与示例。
• 模型广场：deepseek-v4-pro 等模型 ID。
• 如何使用 Token：控制台用量统计。
• 错误码速查：401、402、403、404、429、503 的含义。

本文 Cursor 侧行为均未实测。