Codex VSCode插件安装配置与DeepSeek、GPT双模型实战指南

最近 Codex 这个开源编程智能体在开发者圈子里热度很高，OpenAI 把它从命令行一路做到了 VSCode 插件，装好之后，AI 可以直接在你编辑器里读代码、改代码、跑测试、提 PR，体验和以前那种网页聊天完全不一样。更关键的是，Codex 支持自定义模型供应商，你可以把 DeepSeek、GPT 都配进去，普通改动用便宜的模型，复杂重构再切回 GPT，成本和使用体验能兼得。这篇文章就从零开始，带你装好 Codex 插件，把 DeepSeek 和 GPT 都配置好，顺手把几个高频报错也一起讲透。适合刚接触 Codex、想在 VSCode 里用上 AI 编程助手的朋友，也适合已经装上插件但被配置文件折腾过的人。

1. Codex 是什么，为什么值得进 VSCode

1.1 从终端命令到编辑器插件

Codex 是 OpenAI 开源的 AI 编程智能体，核心能力是“把一个自然语言需求变成真实的代码改动”。它不是简单的代码补全工具，而是一个能自己浏览仓库、搜索符号、编辑文件、执行命令、运行测试的智能体。最初它是以命令行工具的形式发布的，后来官方在 VSCode 扩展市场发布了插件版，把同样的能力塞进了 IDE。

插件版最有价值的一点是“上下文”。它能实时看到你当前打开的文件、选中的代码、整个工作区的目录结构，甚至 Git 变更状态都能感知。这意味着它给出的修改建议高度贴合你正在做的事，而不是像网页聊天那样只能靠你手动把代码复制过去。简单说，CLI 版适合处理“批量任务”，插件版适合“边写边改”，两者互补，建议都装。

1.2 命令行和插件怎么选

我的习惯是：日常开发一直开着 VSCode 插件，遇到“给整个目录改注释”“批量重命名”这类活儿，再单独开一个终端跑codex命令。两条路都走一遍之后，你对这个工具的边界会更有感觉。

1.3 为什么要把 DeepSeek 和 GPT 都接进来

先说结论：不是“选一个用”，而是“两个都配好，按任务切换”。

• GPT（OpenAI 官方模型）：和 Codex 原生配合最好，支持 OpenAI 最新的 Responses API，能力上限最高。复杂重构、老项目迁移、看不懂的加密逻辑，这些重活让 GPT 来，成功率明显更高。
• DeepSeek：接口格式兼容 OpenAI，价格便宜很多，上下文窗口对于日常任务完全够用（具体数值以官方文档为准）。补注释、写单测、改样式、处理重复代码，这类任务用 DeepSeek 非常省钱。

双配置的本质是“丰俭由人”。我算过一笔账：一天下来，如果所有请求都走 GPT，API 账单会涨得很快；但 80% 的小改动本来就不需要那么强的模型，切到 DeepSeek 后，账单能降一个量级，而且体验几乎没有差别。这也是我强烈建议配置双模型的原因。

2. 安装前准备与 Codex 插件安装

2.1 需要准备的东西

动手之前，先把环境列个清单：

• VSCode：版本建议越新越好，老版本对插件的新特性支持不好
• Node.js：18 以上，装 Codex CLI 要用
• Git：Codex 会读取仓库状态和变更记录，建议提前配好
• API Key：OpenAI 的 key，或者 DeepSeek 的 key，两者都配就都申请

这里多说一句，API Key 一定要在官方平台后台创建，并且创建之后马上复制保存好。很多平台只在创建时显示一次完整 key，关掉页面就再也看不到了，只能重新创建。

2.2 安装 VSCode 插件

打开 VSCode，左侧扩展面板，搜索关键字Codex，认准发布者是 OpenAI 的那个扩展，点击安装。

装完强烈建议重载一次窗口：按Ctrl+Shift+P（macOS 是Cmd+Shift+P），输入Reload Window回车。这一步能避免很多“插件装了但面板打不开”的诡异问题。

如果扩展市场搜不到，或者你是内网环境，可以去 OpenAI 的 Codex 开源仓库 Releases 页面下载.vsix文件，然后在 VSCode 扩展面板右上角的“更多操作”里选择“从 VSIX 安装”，手动指定文件即可。

2.3 安装 Codex CLI（强烈建议）

npm install -g @openai/codex

装完运行codex --version确认版本号能正常打印。

为什么插件之外还要装 CLI？两个原因。第一，官方插件的部分版本会调用本地的 codex 引擎，提前装好 CLI 能避免“插件装上了却用不了”的尴尬；第二，CLI 本身就是最直接的调试工具，后面遇到配置问题，可以用命令行先测一遍，快速区分是“配置错了”还是“插件坏了”。

装完 CLI 之后，先解决身份认证，两种方式：

• codex login：用 ChatGPT 账号登录，适合已经订阅 ChatGPT Plus/Pro 的人
• 设置环境变量：把 API Key 写进系统环境变量，适合走 API 计费的人

如果你想用 DeepSeek 这类第三方模型，建议直接用环境变量方式，不走 ChatGPT 登录。因为账号登录模式基本绑定官方模型，用第三方模型时需要的是 API Key 模式。

3. 配置 DeepSeek 与 GPT 模型供应商

3.1 认识 Codex 的配置文件

Codex 的全局配置文件位于用户目录下的~/.codex/config.toml。这个文件是理解整个配置体系的钥匙。

文件里可以定义多个模型供应商，每个供应商对应一个“OpenAI 兼容的 API 地址”。Codex 干活的时候，核心就靠三个字段和一个模型名：

• base_url：API 服务地址
• env_key：从哪个环境变量读取 API Key
• wire_api：用哪种协议通信，responses对应 OpenAI 新版 Responses API，chat对应传统的 Chat Completions API
• model：默认使用的模型 ID

这个设计很像路由器里配置多个 DNS 服务器：平时默认走一个，需要时随时手动切换。理解了这个结构，配置任何新模型都只是“套模板”的事。

3.2 配置 OpenAI GPT

打开（或新建）~/.codex/config.toml，写入：

model = "gpt-5-mini" model_provider = "openai" [model_providers.openai] name = "OpenAI" base_url = "https://api.openai.com/v1" env_key = "OPENAI_API_KEY" wire_api = "responses"

然后设置环境变量。macOS 或 Linux 下临时设置：

export OPENAI_API_KEY=sk-你的key

想永久生效，就把这行写进~/.bashrc或~/.zshrc，然后执行source ~/.bashrc让它立即生效。

Windows 用户用 PowerShell 临时设置：

$env:OPENAI_API_KEY="sk-你的key"

永久设置用setx OPENAI_API_KEY "sk-你的key"，注意setx设置完当前终端不生效，要新开一个终端。这里有个特别容易忽略的点：改完环境变量后，VSCode 必须完全退出再重新打开，仅仅重载窗口是不够的，因为环境变量是进程启动时读取的。

关于模型 ID，gpt-5-mini只是我常用的一个例子，具体以 OpenAI 官方模型列表为准，换成你有权限访问的 ID 即可。

3.3 配置 DeepSeek

还是在~/.codex/config.toml里，加一段：

model_provider = "deepseek" model = "deepseek-chat" [model_providers.deepseek] name = "DeepSeek" base_url = "https://api.deepseek.com/v1" env_key = "DEEPSEEK_API_KEY" wire_api = "chat"

然后设置环境变量：

export DEEPSEEK_API_KEY=sk-你的deepseekkey

DeepSeek 官方提供的是 OpenAI 兼容接口，但兼容的是 Chat Completions 这一套，并没有实现 OpenAI 最新的 Responses API。所以wire_api必须写成chat。如果照抄 OpenAI 的配置写成responses，请求会直接报 404 或者协议错误，这是接入 DeepSeek 时最常踩的坑。

另外 DeepSeek 平台一般有两个模型可用：deepseek-chat是通用对话模型，速度快成本低；deepseek-reasoner是推理增强模型，适合复杂逻辑任务。想用哪个，就把model字段换成哪个。

3.4 怎么在模型之间切换

配置好之后，切换方式有两种。

第一，直接改config.toml里的默认model和model_provider，然后重载 VSCode 窗口。适合“这段时间主要用哪个模型”这种长期切换。

第二，命令行用参数临时指定，适合单次任务切换：

codex --model deepseek-chat --model-provider deepseek codex --model gpt-5-mini --model-provider openai

我的习惯是：config.toml里默认放deepseek-chat，日常的绝大多数请求都走它；遇到复杂的重构需求，再临时切到 GPT。这样既有性价比，又不会在关键时刻掉链子。

4. 实操：在 VSCode 里用 Codex 干活

4.1 插件的基本操作

配置全部完成并重载窗口后，左侧边栏会出现 Codex 图标。点击打开面板，底部是输入框，顶部可以看到当前使用的模型。

插件的核心交互方式有三种：

• 直接对话：在输入框里描述需求，Codex 会分析当前项目并给出修改方案。涉及代码改动时，它会展示 diff，你确认之后改动才会真正写入文件
• 选中代码后右键：菜单里有解释代码、修改选中代码、写测试等快捷入口，不用手动描述上下文
• 终端命令授权：Codex 需要跑测试或执行命令时，会弹出一个授权请求，你确认后它才会运行

这里有个安全习惯值得养成：第一次用的前几周，每次改代码之前都仔细看一下 diff，确认它没动不该动的东西。等你对它的行为模式熟悉了，再慢慢放宽信任。

4.2 一个真实场景：修复登录报错

比如项目里有个登录功能，密码错误时没有任何提示。选中相关文件，在 Codex 面板里输入：

“这段登录代码在认证失败时没有任何用户提示，帮我补上错误提示；如果是因为密码错误，要给出具体原因，而不是笼统的失败。”

Codex 会浏览相关文件，定位认证逻辑，然后在合适的位置加上错误分支。它给出的 diff 会很清楚地标出改了哪个文件、加了哪些判断。确认后，再让它跑一下相关测试，整个流程几分钟就结束了。如果你只用网页版 AI 聊天工具，这个过程需要你手动复制代码、再把修改粘回去，体验完全不在一个量级。

4.3 另一个场景：补单测

给工具函数写单测是 Codex 的强项。选中工具函数文件，输入：

“为 src/utils/format.ts 写单元测试，覆盖空字符串、超长字符串、特殊字符、null 这些边界情况，测试框架用项目现有的。”

它会先读懂项目里的测试框架和既有风格，再生成符合规范的测试文件，而不是给你一段风格完全不一致的代码。确认 diff 后，你只需要运行一次测试命令，看结果全绿就行。

4.4 跨文件重构时怎么提需求

跨文件重构是最能体现“选对模型”价值的场景。这种任务建议把模型切到 GPT 或deepseek-reasoner。

提需求时，尽量把“现状”和“目标”说清楚。比如：

“payment 模块里所有地方还在直接用旧的费率计算函数，请统一改成从配置中心的 new_rate 结构读取，并更新调用方，最后跑一遍现有测试确保没有破坏行为。”

Codex 会列出所有涉及的文件，逐个修改，并给出改动清单。这种多文件任务，如果一次说不清楚，就拆成几步做：先让它列出所有受影响位置，确认无误后再让它动手。实践证明，任务拆得越细，成功率越高，来回返工也越少。

4.5 省钱和提速的几个小技巧

用了几个月之后，我总结了几条很实用的经验：

• 简单任务直接用deepseek-chat当默认模型，只有任务明显复杂时才切 GPT
• 一次让 Codex 只做一件事，比让它“一口气把所有功能都实现”成功率高，而且 token 消耗更少
• 重要改动前，先让它“只给方案，不要改文件”，你过一遍思路，再让它执行
• 对话太长时，主动新开一个会话，不要让 Codex 背着冗长的历史继续干活

5. 常见问题与排查实战

5.1 网络连接类报错

不少人在插件里会看到类似cc switch local ... failed while handling codex endpoint /responses的报错，后面的内容经常被截断。这类报错的本质是：插件到 API 服务之间的网络连接没有打通。

我的排查顺序一般是这样：

• 第一步，确认浏览器能正常打开对应的 API 官方平台。能打开，说明网络基本可用，问题可能出在插件或本地环境上
• 第二步，检查系统环境变量里有没有指向本机某个端口的网络配置项。Codex 发起请求时会读取这些配置，如果它指向的服务并没有运行，连接就会一直失败。把多余的配置项清掉，然后重启 VSCode
• 第三步，关闭 VSCode 里所有可能改动网络请求的扩展，重载窗口再试。有时是扩展之间相互干扰，把嫌疑对象隔离出来问题就清楚了
• 第四步，如果用了 WSL，确认 VSCode 当前连接的是 WSL 环境还是 Windows 本机，两边的环境变量和配置要分开检查

如果 API 站点本身无法访问，那说明是网络环境的问题，需要先把网络环境处理好，再回来看插件。这不是 Codex 能解决的，配置再怎么调也没有用。

5.2 上下文超限报错

有朋友遇到过这么一条报错：error running remote compact task: codex ran out of room in the model's context。翻译过来就是：当前会话太长了，模型的上下文窗口已经装不下，Codex 想自动压缩会话释放空间，结果压缩也失败了。

产生的原因通常是：长时间用同一个会话聊天，或者一次让 Codex 看了太多文件。解决办法按优先级排列：

• 在新会话里继续，插件面板里找到 New Session 或清空对话的入口
• 把大任务拆成小步骤，每个步骤单独开一个会话
• 切换上下文更大的模型，DeepSeek 在这类场景下往往比小上下文模型更从容
• 提问时尽量用选中代码的方式，减少让 Codex 全局搜索整个仓库的次数

5.3 401、403、429 鉴权和额度报错

这里特别要提醒一个误区：OpenAI 的 ChatGPT 订阅（Plus/Pro）和 API 是两套完全独立的计费体系。订阅了 Plus 不代表你就有 API 额度，API Key 必须在平台后台单独创建，并且按量付费。很多人以为自己充了 ChatGPT 会员就能白嫖 API，结果一直 401 或 403，其实就是没搞清这两者的区别。

DeepSeek 这边，新注册用户一般会有赠送额度，但赠送额度用完以后就需要自己充值，否则也会报额度不足的错误。

5.4 插件打不开、一直转圈

装了插件但侧边栏打不开，或者面板一直转圈，按这个顺序排查：

• 先重载窗口，很多问题重启就能解决
• 把 VSCode 升级到最新版本，老版本对扩展的 API 支持不全
• 检查 Node.js 版本，太老的 Node 会导致扩展运行时崩溃
• Windows 用户如果各种奇怪问题反复出现，可以考虑配合 WSL 使用：在 WSL 里安装 Codex CLI，VSCode 用 Remote Development 插件连接 WSL，很多路径分隔符、权限、环境变量不一致的问题会少很多

5.5 配了 DeepSeek 但还是报错

如果 config.toml 里已经写了 DeepSeek，但还是各种报错，按这个顺序检查：

1. base_url是否写全：应该是https://api.deepseek.com/v1，注意结尾的/v1，少写或多写都会导致 404
2. wire_api是否写成了responses：DeepSeek 必须用chat，这是最高频的坑
3. 环境变量名是否和env_key完全一致：DEEPSEEK_API_KEY少一个字母都读不到
4. 改完配置文件有没有重载：config.toml不会自动生效，必须重载窗口或重启 VSCode

还有一个“终极排查法”：先绕开插件，直接用 CLI 测一遍配置：

codex --model deepseek-chat --model-provider deepseek "用一句话介绍你自己"

CLI 能正常回复，说明配置没问题，问题在插件侧，重载窗口或重装插件；CLI 也报错，那说明问题出在配置文件或环境变量上，而且命令行给出的错误信息通常比插件完整得多，照着信息改就行。

5.6 换新机器怎么快速迁移配置

我换新电脑之后的做法很简单：把~/.codex/config.toml备份一份，新机器装好 Node.js 和 Codex CLI 之后直接把文件拷过去，再重新设置一遍环境变量就完事了。注意 API Key 不要写进config.toml本身，也不要提交到 git 仓库，Key 一律走环境变量，这样即使配置文件泄露也不会直接丢密钥。

最后分享一点我的实际体会。第一次接触 Codex 时，我光看官方文档没太看懂model_provider和wire_api到底起什么作用，后来配 DeepSeek 一直报 404，折腾了大半个晚上才发现是协议类型写错了。这个配置本质上就一句话：OpenAI 官方模型走responses，兼容 OpenAI 接口但没有实现 Responses API 的第三方模型走chat。想清楚这一点，后面再接任何新模型都不慌。另外，刚开始用的时候建议先拿一个小型开源项目练手，让 Codex 帮你改点小功能、补几个测试，熟悉它的操作方式和授权逻辑之后，再让它碰生产代码。工具好用，也要用对地方，边界摸清楚，后面才会越用越顺。