🚀 Cursor 接入 CodingPlanX 自定义模型

> 导语：Cursor 是一款深受开发者喜爱的 AI 编程工具，内置了强大的大模型能力。但有时出于网络限制、成本控制（使用第三方中转 API 或更便宜的模型如 DeepSeek）或企业内网部署的需求，我们需要配置自定义的 API URL 和 API Key。 > > 本教程将手把手教你如何轻松完成配置。

📋 准备工作

在开始配置之前，请确保你已经准备好了以下信息：

已安装 Cursor：确保你的 Cursor 是最新版本。
API Key（密钥）：如 sk-xxxxxxxxxxxxxxxxxxxxxxxx。
Base URL（接口地址）：你的自定义 API 代理地址。
- 注意：通常需要以 /v1 结尾，例如 https://api.codingplanx.ai/v1。
模型名称（Model Name）：你打算使用的模型标准名称（如 gpt-4o, claude-3-5-sonnet, deepseek-chat 等）。

⚙️ 详细配置步骤

第一步：打开 Cursor 设置

启动 Cursor 编辑器。
点击右上角的 齿轮图标 ⚙️，或者使用快捷键打开设置：
- Windows / Linux: Ctrl + ,
- macOS: Cmd + ,

第二步：进入 Models（模型）配置页

在弹出的设置面板左侧导航栏中，找到并点击 Models（模型）选项卡。

第三步：配置 API Key

在 Models 页面向下滚动，找到 OpenAI API Key 区域。
将你的自定义 API Key 粘贴到输入框中。
点击右侧的 Verify（验证）按钮。（如果此时验证失败没关系，因为我们还没配置 URL）。
⚠️ 重要提示：请确保上方 Cursor 官方的 Cursor Tab 和其他需要付费订阅的开关处于合适的状态（如果是纯白嫖第三方API，建议关闭官方的模型开关）。

第四步：配置 Base URL（覆盖默认接口）

这是最关键的一步，决定了你的请求发往哪里：

在 OpenAI API Key 输入框下方，找到 Override OpenAI Base URL（覆盖 OpenAI 基础 URL）选项。
展开该选项，将你的自定义接口地址填入框中。 > 💡 示例填写格式： > - CodingplanX AI：``https://api.codingplanx.ai/v1`
填写完毕后，务必**按下回车键（Enter）**保存设置。

第五步：添加自定义模型名称（可选但推荐）

如果你使用的模型不在 Cursor 的默认列表中（例如 deepseek-coder），你需要手动添加：

滚动到 Models 页面的最上方，找到 Model Names 区域。
点击 + Add Model（添加模型）。
准确输入你的模型名称（如 deepseek-chat），然后按回车确认。
将刚刚添加的模型前面的开关打开，并建议关闭你不使用的其他模型，以防选错。

✅ 测试与验证

配置完成后，我们需要测试一下是否生效：

返回代码编辑界面。
按下 Ctrl + L (Windows) 或 Cmd + L (macOS) 唤出右侧的 Chat 聊天窗口。
在聊天窗口的底部，点击当前显示的模型名称，切换为你刚刚配置好的模型（如 gpt-4o 或 deepseek-chat）。
发送一句简单的问候，例如："你是谁？请告诉我你的模型版本。"
如果 AI 能够正常且快速地回复，恭喜你，配置成功！🎉

❓ 常见问题排查 (FAQ)

故障现象	可能的原因	解决办法
连接超时 / 404 Not Found	Base URL 格式错误。	检查 URL 是否缺少了 `/v1` 后缀，或者多加了 `/chat/completions`。正确格式应为 `https://xxx.com/v1`。
Model not found (找不到模型)	请求的模型名称在你的 API 渠道中不支持。	检查你在 Cursor 中选中的模型名称，是否与你的 API 提供商支持的名字完全一致（区分大小写）。
Authentication failed (鉴权失败)	API Key 填写错误或余额不足。	检查 Key 是否复制完整（不要有多余的空格），并前往 API 提供商后台检查账户余额。
无法使用 Cursor Tab (代码补全)	Cursor 的内联代码补全(Copilot)使用的是独立模型。	第三方 API 仅能接管 Chat 和 Cmd+K 功能。Cursor Tab 补全功能通常仍依赖 Cursor 官方服务或需特殊配置支持 FIM 的模型。

> 📝 结语： > 掌握自定义 API 的配置，不仅能大幅降低使用 AI 辅助编程的成本，还能让你自由切换各种前沿大模型。如果你觉得这篇教程有帮助，欢迎分享给你的开发者朋友！