Cursor 如何接入自定义模型：Override Base URL 完整配置与四类踩坑速查

发布日期：2026-08-25 | 话题：Cursor / 自定义模型 / BYOK / OpenAI Base URL

Cursor 的自定义模型接入（BYOK，Bring Your Own Key）允许用户将 Chat/Composer/Agent 对话请求路由至任意 OpenAI 兼容端点------DeepSeek 官方 API、Ollama 本地模型、Groq、多模型聚合平台均支持，配置核心是 Settings → Models 下的 OpenAI API Key 字段加 Override OpenAI Base URL 两步联动；该机制仅覆盖 Chat 类请求，Tab 代码补全始终走 Cursor 自有模型且不受此配置影响。常见踩坑集中在四处：URL 末尾多余斜杠导致验证失败、Anthropic 模型错走 Override 通道引发 422 错误、Agent 子任务静默降级走 Cursor 后端、以及 2026 年 5 月已知 Bug 致 model 字段丢失。本文覆盖 5 分钟完成配置的操作路径、主流服务商参数速查表、Ollama 本地模型接入全流程、Agent 模式兼容性说明，以及订阅用户与 BYOK 的选型决策。

先搞清楚：BYOK 覆盖了什么，覆盖不了什么

这是最先需要明确的边界，也是很多用户配完之后发现"不对劲"的根本原因。

功能	是否走你的自定义 API
Chat（普通对话）	✅ 是
Composer（多文件编辑）	✅ 是
Agent 模式（主对话）	✅ 是
Agent 子任务（内部工具调用）	⚠️ 部分仍走 Cursor 后端
Tab 代码补全（Autocomplete）	❌ 始终走 Cursor 自有模型
Apply from Chat（应用代码变更）	❌ 始终走 Cursor 自有模型

Tab 补全是 Cursor 的核心差异化能力，官方明确不开放给 BYOK 配置。如果你主要依赖 Tab 补全，换自己的 API 对这块体验没有影响。

配置路径：两步联动

所有自定义模型配置都在同一个入口：Cursor Settings → Models （快捷键 Cmd/Ctrl + , 打开设置后选 Models 标签）。

第一步：填入 API Key

在 OpenAI API Key 字段填入你的服务商密钥。

注意：即使你接入的不是 OpenAI 的服务（比如 DeepSeek、本地 Ollama），也要填在 OpenAI API Key 这一栏------因为 Override Base URL 机制挂在 OpenAI 通道上。Anthropic Key 有专属字段，不走这条路。

第二步：设置 Override OpenAI Base URL

打开 Override OpenAI Base URL 开关，填入服务商端点地址。

URL 格式规则：

复制代码

✅ https://api.deepseek.com/v1
✅ http://localhost:11434/v1
✅ https://api.qnaigc.com/v1

❌ https://api.deepseek.com/v1/chat/completions  ← Cursor 会自动追加路径，不要写到终点
❌ https://api.deepseek.com/v1/                  ← 末尾多余斜杠，会导致验证失败

填好后点击 Verify 验证连通性，通过后 Save。

第三步：添加模型 ID

验证成功后，Cursor 不会自动拉取 该端点支持的模型列表，需要手动添加：点击 + Add Model，填入端点实际支持的模型 ID（必须与服务商完全一致，不能缩写）。

主流服务商配置速查

服务商	Override URL	示例模型 ID	说明
DeepSeek 官方	`https://api.deepseek.com/v1`	`deepseek-chat`, `deepseek-reasoner`	直接填官方 Key
Ollama 本地	`http://localhost:11434/v1`	`qwen2.5-coder:14b`, `llama3.1`	详见下方
Groq	`https://api.groq.com/openai/v1`	`llama-3.1-70b-versatile`	Groq 提供推理加速
七牛云 AI	`https://api.qnaigc.com/v1`	`deepseek-v4-flash`, `kimi-k3`	OpenAI 兼容格式，支持多款主流大模型
Azure OpenAI	需要 Endpoint URL	你的 Deployment Name	单独有 Azure 字段，不走 Override

Azure 注意：Azure OpenAI 有专属配置字段（需要填 API Key + Endpoint + Deployment Name），不使用 Override Base URL 机制。

Ollama 本地模型接入全流程

Ollama 是接入本地开源模型最常用的方案，它会在本机起一个 OpenAI 兼容的 HTTP 服务。

前提：Ollama 已启动且有模型

bash 复制代码

# 安装后拉取模型
ollama pull qwen2.5-coder:14b

# 确认服务已在运行
curl http://localhost:11434/v1/models

Cursor 侧配置

OpenAI API Key：填任意非空字符串（Ollama 不校验 Key，但字段不能留空）
Override OpenAI Base URL ：填 http://localhost:11434/v1
Add Model ：填你拉取的模型名，如 qwen2.5-coder:14b

常见本地模型问题

连接失败但 curl 测试正常 ：Cursor 有时需要用 127.0.0.1 代替 localhost，改试一下。

模型响应格式不完全兼容：部分本地模型的流式输出格式与 OpenAI 规范有细微差异，会导致 Cursor 渲染异常。换用社区推荐的 Ollama 版本或模型量化格式（Q4_K_M）通常可解决。

防火墙或 CORS 问题：若 Cursor 和 Ollama 在不同网络环境（如 WSL2 + Windows），需明确指定实际 IP 而非 localhost。

四类高频踩坑

坑 1：URL 末尾多余斜杠

这是最常见的失败来源。https://api.example.com/v1/ 和 https://api.example.com/v1 的验证结果完全不同------带斜杠的版本 Cursor 会拼出错误路径。填写时对齐示例格式，去掉末尾斜杠。

坑 2：Anthropic 模型走了 Override 通道（422 错误）

Anthropic 使用的是 /v1/messages 接口格式，与 OpenAI 的 /v1/chat/completions 完全不同。如果你同时设置了 Override Base URL 又在用 Claude 模型，Cursor 会把 Anthropic 请求也路由到 Override 端点，导致 422 格式错误。

解决方式 ：Claude 系列模型使用 Anthropic API Key 专属字段，不开 Override；或者通过支持协议转换的聚合代理（如 LiteLLM）统一接入，避免 Cursor 直连两套格式。

坑 3：Agent 模式子任务静默失败（已知 Bug）

Cursor 论坛 2026 年 4-5 月的讨论记录了两个相关 Bug：

子 Agent 静默忽略 Override 配置：主对话走自定义模型正常，但 Agent 内部工具调用被静默路由回 Cursor 后端（Forum thread #159369）
model 字段丢失（Forum thread #160070）：Agent 模式下 BYOK 请求发出时 model 字段被丢弃，服务商收到的请求缺少模型标识，返回"model is required"错误------官方已确认为 Bug

当前应对：Agent 模式下遇到上述情况，确认 Cursor 是最新版本；子任务静默降级目前无完整解法，需等待官方修复。

坑 4：Cursor 订阅模型被路由到 Override 端点

2026 年 8 月（约 4 天前）的论坛帖显示，有用户报告 Cursor 托管的订阅模型（非 BYOK）也开始走 Override Base URL，导致订阅模型不可用。临时解法：在使用订阅模型时手动关闭 Override Base URL，切换回 BYOK 模型时再开启------官方正在排查。

Anthropic / Google / Azure 的独立配置

Override OpenAI Base URL 只影响 OpenAI 通道。其他提供商有各自专属字段：

Anthropic（Claude 系列）

字段：Settings → Models → Anthropic API Key
直接粘贴 Anthropic Console 生成的 Key，不需要 URL

Google（Gemini 系列）

字段：Settings → Models → Google API Key
Key 从 Google AI Studio（aistudio.google.com）获取

Azure OpenAI

需要三个值：API Key + Endpoint URL + Deployment Name
在 Settings → Models 的 Azure 区域分别填写

BYOK vs Cursor 订阅：怎么选

场景	建议方案
主要用 Tab 补全，偶尔 Chat	Cursor 订阅，BYOK 无法影响 Tab 补全
大量 Composer/Agent 任务，用量超出订阅额度	BYOK，自控成本
需要使用 Cursor 默认模型列表以外的模型	BYOK，自行接入目标模型
隐私敏感场景（企业数据、代码不出内网）	结合本地 Ollama 或私有化部署端点
Azure/AWS Bedrock 企业合规	分别使用对应专属字段

重要说明：使用 BYOK 后，数据处理遵循所选服务商的隐私政策，而非 Cursor 的零数据保留（ZDR）政策。对于高合规要求场景，需要额外评估。

常见问题

Q：我用的不是 OpenAI 的服务，为什么还要填 OpenAI API Key 字段？

因为 Override Base URL 机制本质上是"把 OpenAI 格式请求重定向到其他端点"。Cursor 的请求仍然采用 OpenAI 格式（/v1/chat/completions），只是目标地址换成了你的服务------Key 字段也因此跟着 OpenAI 通道走。Anthropic、Google 等有自己格式的提供商，要用专属字段。

Q：验证通过但模型列表里没有我填的模型？

验证只测通道连通性，不会自动发现端点支持的模型。需手动点击 + Add Model 添加模型 ID。如果端点不支持 GET /v1/models 接口，Cursor 无法自动拉取列表，只能手动填。

Q：Agent 模式下自定义模型和订阅模型有什么差异？

主对话行为基本一致。差异在于 Agent 内部子任务：Cursor 自有订阅模型的子任务走完整 Agent 通道，BYOK 自定义模型的子任务存在静默降级或 model 字段丢失的已知 Bug（见上文踩坑 3），生产环境使用前建议先验证。

Q：本地 Ollama 模型用 Cursor 有什么限制？

主要是两点：① Tab 补全不受影响，仍走 Cursor 服务器；② Cursor 的 Chat/Composer 请求会经过 Cursor 后端转发（带加密），本地模型数据并非完全绕过 Cursor，若需要完全隔离可考虑自部署 LiteLLM 网关在本地做路由。

Q：能同时用 Override Base URL 和 Anthropic API Key 吗？

不能同时稳定使用。Override 设置生效时，Cursor 可能将 Anthropic 格式的请求也路由到 Override 端点，导致格式不兼容报错。解决方案是使用支持多格式转换的聚合代理，统一用 OpenAI 格式接入所有模型，只配置一个 Override URL。

总结

Cursor 接入自定义模型的核心是两步：OpenAI API Key 字段填服务商密钥 + Override OpenAI Base URL 填服务端点------两者必须同时启用，且 URL 不能带末尾斜杠。Anthropic/Google 各有专属字段，不走这条路。Tab 补全永远走 Cursor 自有模型，不受 BYOK 配置影响。Agent 模式下存在已知 Bug，子任务可能静默降级或丢失 model 字段，生产环境需留意。

本地 Ollama 接入成本最低，Key 随便填，URL 填 http://localhost:11434/v1，但需要注意 Cursor 请求仍经过 Cursor 后端转发，不是完全的本地化链路。

本文基于 Cursor 2026 年 8 月版本，BYOK 相关 Bug 仍在修复中，建议结合官方论坛确认最新状态。

延伸资源

Cursor 官方 API Keys 文档：cursor.com/docs/settings/api-keys
Cursor 论坛 BYOK 讨论（Agent Bug）：forum.cursor.com/t/gent-mode-with-openai-base-url-override-sends-request-without-model-model-is-required/160070
AI 编程工具 API 统一配置（多工具覆盖）：https://developer.qiniu.com/aitokenapi/13417/tools-AI-Coding-api
Ollama 官方文档（本地模型）：ollama.com/docs