Cursor / Codex 接入国产模型 + 中转全流程避坑指南

EA同学
989 阅读7分钟

我上周在 Cursor 里配好了 DeepSeek，Agent 跑起来挺顺。切回 Claude 想改个 bug，Chat 框直接红字：

Provider Error: Invalid API key or base URL override conflict
All models unavailable except custom OpenAI endpoint

Cursor Pro 月付 140 元，我花了一下午排查，才发现 Override OpenAI Base URL 是全局开关——一开，Claude、Gemini、Composer 全被路由到 DeepSeek 端点，自然全挂。

Codex 那边更坑：我把 https://api.deepseek.com/v1 直接写进 config.toml，终端报 404，因为 Codex 0.128+ 走的是 Responses API，DeepSeek 官方暴露的是 Chat Completions，协议压根对不上。

这篇文章把 Cursor 和 Codex 两条线的完整接入流程，以及我踩过的 7 个坑，一次性讲清楚。

先搞懂：为什么用 DeepSeek 接 Cursor / Codex

国内用 AI 编程工具，通常卡在四件事：

痛点具体表现
接入难海外模型 API 需外币支付、企业资质，个人开发者门槛高
不稳定直连延迟 800ms–3s，流式传输经常断
贵GPT-4o 输入 $2.5/M tokens，重度使用月账单轻松破千元
风控部分海外账号因 IP 段、支付方式触发限制

DeepSeek 等国产模型在代码能力上已接近第一梯队，且 API 定价低一个数量级。DeepSeek 开放平台提供 OpenAI 兼容接口（https://api.deepseek.com/v1），Cursor 可以直接 Override 接入；Codex 则需要本地协议桥接，下文细讲。

我过去 3 个月实测的数据（同一套 5000 行 React 项目，每天 Agent 对话约 80 轮）：

  • 直连 OpenAI GPT-4o：月 API 约 ¥2,800
  • DeepSeek 官方 API + 本地桥接：月 API 约 ¥180

省下来的不是小数目。关键是配置要对，否则省的钱全花在排查上。

路线一：Cursor 接入 DeepSeek（OpenAI 兼容 Override）

Cursor 的自定义模型入口在 Settings → Models，核心就两个开关：

  1. OpenAI API Key — 填 DeepSeek 开放平台申请的 Key
  2. Override OpenAI Base URL — 填 DeepSeek 兼容端点

配置步骤

第一步：获取 DeepSeek API 凭证

登录 DeepSeek 开放平台，在 API Keys 页面创建 Key，记下两样东西：

  • API Key：sk-your-deepseek-key（示例占位，请替换为你自己的 Key）
  • Base URL：https://api.deepseek.com/v1（注意末尾 必须有 /v1）

第二步：写入 Cursor

打开 Cursor → Cmd + , → 左侧 Models：

OpenAI API Key:          [开启] sk-your-deepseek-key
Override OpenAI Base URL: [开启] https://api.deepseek.com/v1

第三步：添加自定义模型名

在 Models 页面底部 Add model，填入 DeepSeek 文档中的模型 ID，必须和 API 一致：

deepseek-chat
deepseek-reasoner

勾选启用后，在 Chat 模型选择器里就能看到了。

第四步：验证

在 Chat 里选 deepseek-chat，发一条：

用 Python 写个快速排序，带注释

正常的话 2–5 秒内开始流式输出。如果报错，看下文踩坑章节。

Cursor 接入的 3 个关键认知

认知 1：Override 是全局的，不是 per-model 的

这是 Cursor 社区里被吐槽最多的设计。开启 Override 后，所有走 OpenAI 协议的请求（包括你以为是 Cursor Pro 内置的模型）都会打到你的自定义端点。目前官方没有 per-model Base URL，只能手动开关切换。

我的 workaround：把 Base URL 记在备忘录里，需要切回 Cursor Pro 时，只关 OpenAI API Key 开关，不要关 Override（关 Override 会重置 URL 为默认 https://api.openai.com/v1，下次得重新粘贴）。

认知 2：模型名必须精确匹配

填 DeepSeek-Chat 或 deepseek-v3 而 API 只认 deepseek-chat，会返回 model_not_found。去 DeepSeek 官方文档核对可用模型列表，一个字符都不能差。

认知 3：Agent 模式比 Chat 更吃稳定性

Chat 单轮请求失败了重发就行。Agent 模式一次任务可能连续 20–40 轮 tool call，中间任何一轮超时或 502 都会导致整个任务废掉。跑 Agent 前先用 curl 测一下端点连通性，确认流式响应正常。

路线二：Codex CLI 接入 DeepSeek（需要协议桥接）

Codex 是 OpenAI 推出的终端 AI 编程工具（类似 Claude Code）。从 0.128.0 起，自定义 Provider 强制使用 Responses API（wire_api = "responses"），而 DeepSeek 暴露的是 Chat Completions API（/v1/chat/completions）。

直接把 DeepSeek 官方 URL 写进 Codex 配置，100% 踩坑：

# ❌ 这样写必挂
[model_providers.deepseek]
name = "DeepSeek"
base_url = "https://api.deepseek.com/v1"
wire_api = "responses"

Codex 发 /v1/responses，DeepSeek 没有这个端点 → 404 Not Found。

正确方案：本地协议桥 + Codex 指向 localhost

架构如下：

Codex CLI  ──→  本地桥接代理 (127.0.0.1:8787)  ──→  DeepSeek API
  Responses API          Chat → Responses 转换           Chat Completions

第一步：启动本地桥接

推荐 @codeproxy/cli（npm 一键启动）：

npx @codeproxy/cli \
  --base-url https://api.deepseek.com/v1 \
  --model deepseek-chat \
  --apikey sk-your-deepseek-key \
  --port 8787

看到 listening on http://127.0.0.1:8787/v1 就 OK 了。

第二步：配置 Codex

编辑 ~/.codex/config.toml：

[model_providers.deepseek]
name = "DeepSeek"
base_url = "http://127.0.0.1:8787/v1"
wire_api = "responses"

[profiles.deepseek-pro]
model = "deepseek-chat"
model_provider = "deepseek"

第三步：验证

codex /status

确认输出里 Base URL 指向 127.0.0.1:8787，Connection 显示 Connected。再跑一条实际任务：

codex "分析 src 目录结构，找出最大的 3 个文件"

Codex 终端验证

我实测 DeepSeek + 本地桥接，单次 Agent 任务（约 2000 input tokens + 800 output tokens）花费约 ¥0.003，延迟稳定在 150–250ms。

Codex 接入的两种思路

方式适用场景复杂度
本地桥接 + DeepSeek 官方 API只用 DeepSeek 等 Chat 模型中（需常驻一个进程）
上游已提供 Responses 兼容端点网关已做协议转换低（改 base_url 即可）
OpenRouter BYOK一个 Key 混用多家模型低（但国内延迟偏高）

多数情况下，本地桥接 + DeepSeek 官方 API 是最稳的组合；只有当你的上游网关明确支持 Responses API 时，才可以跳过桥接。

7 个高频踩坑（附排查命令）

坑 1：Override 开启后 Cursor 内置模型全挂

现象：配好 DeepSeek 后，Claude Sonnet、Gemini 全部报 API Error。

原因：Override OpenAI Base URL 是全局路由，不区分模型来源。

解决：用 Cursor Pro 模型时，关闭 OpenAI API Key 开关（保留 Override URL 不被重置）。用 DeepSeek 时再打开。

坑 2：Base URL 末尾多了或少了 /v1

现象：404 Not Found 或 Connection refused。

排查：

curl -s https://api.deepseek.com/v1/models \
  -H "Authorization: Bearer sk-your-deepseek-key" | head -c 200

正常应返回 JSON 模型列表。如果 404，试去掉或加上 /v1。

坑 3：Codex 直连 DeepSeek 报 404

现象：config.toml 指向 https://api.deepseek.com/v1，Codex 报 404。

原因：协议不匹配（Responses vs Chat Completions）。

解决：必须加本地桥接层。参考上文路线二。

坑 4：模型名大小写/版本号写错

现象：{"error":{"message":"model not found"}}

解决：去 DeepSeek 官方文档复制模型 ID，不要凭记忆写。常见正确写法：

  • deepseek-chat（不是 DeepSeek-Chat）
  • deepseek-reasoner（不是 deepseek-r1）

坑 5：Agent 模式中途 502，任务全废

现象：Agent 跑了 15 轮 tool call，第 16 轮突然 502 Bad Gateway，前面成果全丢。

原因：网络抖动或上游超时。

解决：

  • 先用 curl 确认端点稳定
  • Agent 任务拆小：一次只让 AI 改 1–2 个文件
  • 关键步骤手动 commit

坑 6：API Key 泄露在 Git 里

现象：Push 代码后 Key 被扫，余额一夜清零。

解决：

# Cursor：Key 只写在 Settings 里，不要写进 .env 提交
# Codex：用环境变量
export DEEPSEEK_API_KEY="sk-xxx"

# config.toml 里用 env_key 引用
env_key = "DEEPSEEK_API_KEY"

绝对不要把 Key 写进 settings.json 并 commit。

坑 7：以为 Override 后 Tab 补全也会走 DeepSeek

现象：Chat/Agent 正常，但 Tab 自动补全还是走 Cursor 内置模型。

原因：Tab 补全目前不走 Override 路径，仍依赖 Cursor 订阅或内置路由。

解决：Tab 补全和 Chat/Agent 是两条链路。DeepSeek Override 主要解决 Chat 和 Agent，Tab 补全暂时无解（除非 Cursor 后续开放）。

成本速算：DeepSeek vs 内置模型

以我日常开发强度（Agent 80 轮/天，平均 3K tokens/轮）估算：

方案月成本稳定性模型选择
Cursor Pro + 内置 Claude¥140 订阅高仅 Cursor 提供的模型
直连 OpenAI GPT-4o API¥2,500–3,500中（国内）OpenAI 全系
DeepSeek 官方 API + 本地桥¥150–250高DeepSeek 系列

我的选择：Cursor Pro 留着用 Tab 补全和 Claude Agent，Chat/Agent 重活用 DeepSeek 官方 API。两者开关切换 10 秒，月总成本控制在 ¥350 以内。

总结

Cursor 和 Codex 接入 DeepSeek，核心就两件事：

Cursor 线：

  1. Settings → Models → 开启 OpenAI API Key + Override Base URL
  2. Base URL 填 https://api.deepseek.com/v1，添加精确匹配的模型名，注意 Override 是全局开关

Codex 线：

  1. 本地起协议桥接（Chat Completions → Responses）
  2. config.toml 指向 127.0.0.1:8787，wire_api = "responses"

配对了，DeepSeek 的代码能力完全够用，成本只有 GPT-4o 的 1/10。配错了，就像我上周那样，一下午耗在排查路由冲突上。

如果你也在折腾 Cursor / Codex 的接入，欢迎在评论区说说你卡在哪一步。

本文基于 Cursor 0.50+、Codex CLI 0.128+ 实测。配置界面和报错信息可能随版本更新变化，以官方文档为准。

avatar
文章
阅读
粉丝