峰瑞资本最近在 Windows 上折腾 Codex + WeCode 这套组合，前后踩了一堆坑，从"装完打不开"到"API 报 400"，再到"本地代理切换失败"，每个问题都能让人卡上半天。这篇文章把整个配置过程、踩坑点、完整解决方案全部记录下来，尤其是接入第三方 API（以 DeepSeek 为例）的部分，网上几乎没有讲透的。如果你也准备在 Windows 下把 Codex CLI 接进 WeCode，用国产大模型 API 跑 AI 编程，这篇文章可以直接当攻略抄。
Codex 是 OpenAI 推出的命令行 AI 编程智能体，WeCode 是腾讯出的 AI 原生 IDE（VS Code 的分支版本），两个工具本身都挺好用，但"Windows + Codex + WeCode + 第三方 API"这个组合，官方文档基本只覆盖了最理想的情况，实际跑起来会遇到一堆中国开发者特有的问题。比如 Codex CLI 二进制找不到、DeepSeek 模型名不被识别、上下文窗口超限、CC Switch 切换本地代理失败等，每一个都是真实踩过的坑。下面按实际操作顺序，从原理到配置，再到排错，完整过一遍。
1. 先搞清楚这套组合到底在干什么
1.1 Codex CLI：一个跑在终端里的 AI 编程员
Codex CLI 是 OpenAI 开源的终端编程智能体，核心能力是让你用自然语言和它对话，它能在你的项目目录里读代码、改代码、执行命令、检查运行结果，像一个坐在你旁边帮你写代码的结对程序员。和 ChatGPT 网页版最大的区别在于，它直接跑在你的本地环境里，能操作真实文件，调用真实命令，甚至能自己跑测试来验证改动是否正确。
从技术实现上看，Codex CLI 本质上是 OpenAI API 的客户端，通过 responses 接口调用大模型。它本身不内置模型，需要配置模型提供商和 API Key。这就引出了两个关键点：一是官方默认配置指向 OpenAI 自己的 API，二是它通过统一的 OpenAI 兼容接口来对接不同的模型服务商。理解了这两点，后面配置第三方 API 的时候就容易多了。
1.2 WeCode：AI 原生的代码编辑器
WeCode 是腾讯推出的 AI 原生 IDE，基于 VS Code 的分支开发，界面和操作习惯和 VS Code 基本一致，内置了腾讯自家的 AI 能力，同时兼容 VS Code 生态的大量扩展。对于国内开发者来说，WeCode 有个天然优势：从官网下载、登录、更新都在国内网络环境下顺畅完成，不需要额外处理网络问题。
在 WeCode 里使用 Codex，主要是通过安装 Codex 扩展来实现。WeCode 的扩展市场兼容 VS Code 扩展，所以可以直接搜索安装 Codex 扩展。这里有一个容易踩的坑：Codex 扩展需要调用本机的 Codex CLI 二进制，如果 WeCode 找不到这个可执行文件，就会报 unable to locate the codex cli binary 错误。这个问题后面专门讲。
1.3 第三方 API：把模型换成自己选的大模型
所谓第三方 API，指的就是不直接用 OpenAI 官方接口，而是通过其他模型服务商提供的 OpenAI 兼容接口来驱动 Codex。目前国内用得最多的是 DeepSeek，原因是便宜、上下文窗口大、代码能力在同价位里表现突出，而且国内服务器直连，不需要额外的网络配置。
使用第三方 API 的核心逻辑在于：Codex 通过标准的 OpenAI 兼容接口和模型服务商通信，只要服务商提供了兼容接口，把 Codex 配置里的接口地址、模型名、API Key 换成服务商的信息，就能跑起来。这个方案的好处是灵活，你可以根据预算和需求随时切换模型，不用被某一个厂商绑定。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. Windows 下的环境准备与前置安装
2.1 前置依赖：Node.js 和 Git 一个都不能少
先说 Node.js。Codex CLI 的安装包本身是 npm 包，需要 Node.js 环境来安装和运行。我当时第一遍装的时候，机器上 Node.js 版本是 14，安装 Codex 的时候各种报错，后来把 Node.js 升级到 20 LTS 版才顺利装上。这里建议直接装最新的 LTS 版本，不要用太老的版本，也不要追最新的 non-LTS 版本，LTS 稳定最重要。
安装 Node.js 的时候注意勾选"Add to PATH"选项，这样 npm 命令才可以在命令行里直接使用。装完后在 PowerShell 里跑一下 node -v 和 npm -v 确认版本，两个命令都有输出就说明环境没问题。如果提示找不到命令，多半是 PATH 没配好或者安装时没勾选，把 Node.js 安装目录手动加到系统环境变量里就可以解决。
再说 Git。Codex 有些操作会用到 Git 命令，比如在项目初始化、查看 diff、提交代码的时候。WeCode 本身也内置了 Git 支持，但 Codex CLI 在终端环境里调用 Git 还是需要系统能识别 git 命令。从 Git 官网下载 Windows 版安装包，一路默认安装即可。安装完成后在 PowerShell 里运行 git --version 验证。
2.2 安装 Codex CLI 的两种方法
Codex CLI 的安装方式有两种，一种是 npm 全局安装，一种是直接下载编译好的二进制文件。在 Windows 上用 npm 安装最为省事，打开 PowerShell（建议用管理员权限），执行：
bash复制npm install -g @openai/codex
安装完成后运行 codex --version，如果能输出版本号，说明安装成功。如果你是用桌面版 Codex（OpenAI 官方也提供了桌面应用），注意 CLI 和桌面版的二进制在 Windows 上可能是两个不同的可执行文件，WeCode 扩展默认找的是 CLI 的 codex 命令，驱动的是命令行版 Codex，这一点要分清。
安装过程中如果遇到 npm 下载慢或者超时的问题，可以设置 npm 的国内镜像源，比如：
bash复制npm config set registry https://registry.npmmirror.com
设置完镜像源再装一次，速度会快很多。这个方法在安装任何 npm 全局工具时都适用，不仅是 Codex。
2.3 申请第三方 API Key 的完整流程
这里用 DeepSeek 举例。去 DeepSeek 开放平台注册账号，完成实名认证，创建一个 API Key，然后在账户里充值（几十块钱够用很久）。创建 API Key 的时候，注意把 Key 完整复制保存下来，因为它只在创建时显示一次，关掉页面就再也看不到了。
拿到 API Key 之后，还要确认一下 API 接口的 base URL 和模型名。DeepSeek 开放平台提供的是 OpenAI 兼容接口，base URL 一般是 https://api.deepseek.com 或者 https://api.deepseek.com/v1，模型名目前是 deepseek-chat 和 deepseek-reasoner。如果你用的是其他 API 服务商，就去对应平台的文档里找这两个信息。这里提醒一下，不同服务商的模型名不一样，有些服务商还会在 API 返回报错里列出当前支持的模型名，这个报错信息反而是最准确的参考。
3. 关键配置：config.toml 与 WeCode 设置
3.1 彻底搞懂 Codex 的 config.toml
Codex CLI 的配置文件是 config.toml，在 Windows 上位于 %USERPROFILE%\.codex\config.toml。这个文件是 Codex 配置的核心，包括模型提供商、模型名、上下文窗口等。我最后调试通过的配置文件长这样：
toml复制model = "deepseek-chat"
model_reasoning = "deepseek-reasoner"
[model_providers.deepseek]
name = "DeepSeek"
base_url = "https://api.deepseek.com"
env_key = "DEEPSEEK_API_KEY"
wire_api = "responses"
逐行解释一下这些配置的作用。model 是默认使用的模型名，需要和你选的 API 服务商提供的模型名一致。model_reasoning 是推理模型，Codex 在需要深入思考的时候会调用它，如果你用的是 DeepSeek，就填 deepseek-reasoner。
[model_providers.deepseek] 这一行定义了一个新的模型提供商，名字叫 deepseek。base_url 是 API 接口地址，必须和 DeepSeek 官方文档一致。env_key 是环境变量的名字，Codex 会从这个环境变量里读你的 API Key，而不是直接把 Key 写在配置文件里。wire_api = "responses" 指定了 API 的通信协议格式，这里要特别注意，OpenAI 的 Codex 默认用的是新的 responses 接口，而很多第三方服务商只支持旧的 chat completions 接口（也就是 /v1/chat/completions），如果你的服务商报 404 或者不支持某个参数，可以尝试把 wire_api 改成 "chat"。
配置好后，在 PowerShell 里设置环境变量：
powershell复制$env:DEEPSEEK_API_KEY = "sk-你的API Key"
为了不用每次重启终端都设置一遍，可以把环境变量永久写入系统：
powershell复制[System.Environment]::SetEnvironmentVariable("DEEPSEEK_API_KEY", "sk-你的API Key", "User")
设置完重新打开终端，环境变量才生效。这里有一个容易忽略的问题：Codex 在启动时读环境变量，如果你是在 WeCode 的终端里启动 Codex，那环境变量必须设置在系统或用户级别，只在某个已打开的终端里临时 $env: 设置是不够的，因为 WeCode 的终端进程可能不会继承之前终端的临时变量。
3.2 WeCode 里的 Codex 扩展配置
打开 WeCode，在扩展市场搜索 "Codex"，找到 OpenAI 官方的 Codex 扩展（图标是 OpenAI 的 logo），点击安装。安装完成后，左侧会出现 Codex 的图标，点击可以看到对话面板。
在扩展设置里，有一个关键项叫 "Codex CLI Path"，需要填写 codex 可执行文件的路径。如果你是用 npm 全局安装的，在 PowerShell 里运行 Get-Command codex | Select-Object Source，把输出的路径填进去，比如：
code复制C:\Users\你的用户名\AppData\Roaming\npm\codex.CMD
注意 Windows 上 npm 全局安装的命令行工具通常是一个 .CMD 文件，WeCode 扩展需要的是能直接执行的路径，把 .CMD 后缀和完整路径都填上最稳妥。填完之后重启 WeCode，扩展应该就能正常连接 CLI 了。如果还报找不到二进制，大概率是路径填错了，或者 npm 的全局目录不在 PATH 里。
WeCode 里打开 Codex 面板后，会让你选择工作目录，选一个项目文件夹就可以开始对话。此时 Codex 会读取项目里的 config.toml 和系统环境变量，自动使用你配置好的 DeepSeek API 来驱动对话。实测下来，从面板里发指令、看 diff、接受改动，体验和 VS Code 里原生的 Codex 扩展基本一致。
3.3 环境变量与 PATH 的那些坑
环境变量的问题在 Windows 上尤其多。比如，你用 npm 安装 Codex 后，codex 命令的默认路径是 %APPDATA%\npm，这个目录需要存在于系统的 PATH 环境变量里。如果你在 PowerShell 里能运行 codex，但 WeCode 里的集成终端却提示找不到命令，多半是 WeCode 是在修改 PATH 之前启动的，进程没有继承新的环境变量，重启一下 WeCode 就好。
还有一种情况，你同时安装了多个 Node.js 版本（比如通过 nvm-windows），npm 的全局目录指向了某个特定版本。这时候 Get-Command codex 显示的路径可能是临时链接，重启或切换 Node 版本后路径会变。我的建议是固定用 LTS 版本的 Node.js，不要频繁切换版本，不然 Codex 扩展里的 CLI Path 配置会反复失效。
4. 踩坑实录：五个高频问题完整复盘
4.1 unable to locate the codex cli binary：扩展找不到 CLI
这个报错出现得最频繁，完整信息是 unable to locate the codex cli binary. set codex_cli_path or ensure the electron...。报错原因很直白：Codex 扩展在启动时找不到本机的 codex 可执行文件。
排查思路分三步。第一步，确认 codex 命令真的装了，在 PowerShell 里运行 codex --version。如果命令不存在，说明没装好，回到 2.2 节重新安装。第二步，如果命令存在，运行 Get-Command codex | Select-Object Source 找到完整路径，把路径填到 WeCode 扩展设置里的 "Codex CLI Path" 里。第三步，填写路径后重启 WeCode，再次打开 Codex 面板。正常情况下这个报错就消失了。
我在这里卡了特别久，原因是最开始把路径填成了 C:\Users\xxx\AppData\Roaming\npm\node_modules\@openai\codex\codex.js，但 WeCode 需要的是能直接执行的文件路径，而不是模块的入口文件。后来改成 C:\Users\xxx\AppData\Roaming\npm\codex.CMD 才正常。这个细节官方文档里没有，纯靠试错试出来的。
4.2 API 报错：模型名不被识别
接第三方 API 后最常见的报错是 400 错误，里面会带一句类似 the supported api model names are deepseek-v4-pro, deepseek-v4-flash, and deepseek-reasoner 这样的提示。这个报错说明你的 config.toml 里 model 或 model_reasoning 填的模型名和 API 服务商实际支持的模型名对不上。
遇到这种报错，解决方案很简单：看报错信息里列出的支持列表，把 config.toml 里的模型名改成服务商支持的模型名。比如服务商告诉你支持 deepseek-v4-pro，就把 model 改成这个名字。这里要特别提醒，不同服务商的模型命名差异很大，有些叫 gpt-4o-mini 这种 OpenAI 风格的名字，有些叫 deepseek-chat 这种自家的名字，不要想当然地填，以服务商文档或报错信息里的实际列表为准。
还有一种情况是 wire_api 配置不对。如果服务商的接口是 OpenAI 兼容的 /v1/chat/completions 格式，而 Codex 默认用 responses 格式传输，服务商可能直接拒绝请求。我自己用 DeepSeek 时，wire_api = "responses" 是可以工作的，但换成某些第三方聚合平台就得改成 "chat"，这个要根据实际测试结果来定。
4.3 api error: 400 this model's maximum context length is 1048576 tokens
这个报错的场景很典型：你在对话里贴了一大段代码，或者让 Codex 处理一个大文件，然后 API 返回 400，提示模型的最大上下文长度是 1048576 token，但当前请求超出了限制。
问题在于 Codex 默认把上下文窗口设置为 1048576 token（这是 OpenAI 某些旗舰模型的窗口大小），但第三方模型的上下文窗口通常只有 64K、128K 或者 256K，远小于这个值。Codex 发送请求时带着超出模型能力的上下文长度，API 服务商就直接拒绝了。
解决办法是修改 config.toml，给模型显式指定上下文窗口大小。比如 DeepSeek 的上下文窗口是 64K，配置：
toml复制[model_providers.deepseek]
name = "DeepSeek"
base_url = "https://api.deepseek.com"
env_key = "DEEPSEEK_API_KEY"
wire_api = "responses"
[model_providers.deepseek.models.deepseek-chat]
context_window = 65536
context_window 参数就是告诉 Codex 这个模型能处理的上下文上限，Codex 在组装请求时会自动限制在指定范围内。这里我吃了大亏，一开始没配这个参数，每跑一次长对话就报一次 400，后来查文档才发现 Codex 默认用的超大上下文窗口并不是所有模型都支持的。
4.4 cc switch local proxy failed 与本地代理问题
WeCode 的 Codex 面板有时候会报 cc switch local proxy failed while handling codex endpoint /responses，这个报错出现在用 CC Switch 这类工具管理 API 端点切换的场景。CC Switch 的作用是在不同 API 配置之间快速切换，方便你测试不同模型服务商，它会在本地启动一个代理服务，把请求转发到目标 API 地址。
报错的原因是 CC Switch 的本地代理没有正常启动，或者 Codex 请求到了代理端口但代理转发失败。排查步骤：先确认 CC Switch 已经启动且选择了正确的配置项，然后检查本机端口是否被占用，最常见的是 8080 端口被其他程序占了，换一个端口就行。如果 CC Switch 本身正常运行，但 Codex 还是报错，检查一下 config.toml 里的 base_url 是否指向了 CC Switch 的本地代理地址，比如 http://127.0.0.1:8080，如果直接指向了原始 API 地址，CC Switch 就不参与转发，报错自然也没了。
我的建议是：如果你只用一个 API 服务商，就没必要引入 CC Switch，直接把 base_url 指向服务商的真实域名，少一层代理少一层问题。如果你确实需要多个服务商切换，那再考虑用 CC Switch，并且优先检查端口占用和代理状态。
4.5 login failed: 登录失败与 Token 问题
login failed. check api token or gitlab version. log in via git if the version... 这个报错虽然看着像 GitLab 的报错，但在 Codex 环境里出现，很多时候是因为 Codex 尝试用 Git 的认证信息去登录代码托管平台，结果认证失败了。
这种情况通常发生在你同时配置了 Git 的 remote 地址和 API Key 的前提下。Codex 在工作时可能会调用 Git 命令，比如读取项目信息、提交改动，如果 Git 远端地址需要认证而凭据过期了，就会报这个错。解决方案是先去 Git 托管平台重新生成访问令牌，更新本地 Git 凭据管理器里的信息，再回来跑 Codex。
另一个更常见的原因：Codex CLI 默认在启动时会尝试登录 OpenAI 账号，如果你没有配第三方 API 而是直接运行 codex，它可能会弹浏览器引导你登录 OpenAI，登录不了或者 Token 无效就会报错。如果你用的是第三方 API 并且不打算用 OpenAI 官方服务，可以不登录，只要配置文件里 model_providers 和 API Key 都正确，Codex 会直接用第三方接口，不再要求 OpenAI 账号登录。
5. 问题速查表与配置成功后的使用心得
5.1 常见报错与解决方案速查表
把这次踩坑过程中遇到的所有报错和解决办法整理成一张表，方便你直接对着排查。
| 报错信息 | 原因 | 解决方案 |
|---|---|---|
| unable to locate the codex cli binary | WeCode 扩展找不到 codex 命令 | 在扩展设置里填写 codex.CMD 的完整路径，重启 WeCode |
| api error 400 model names supported... | config.toml 模型名和服务商不一致 | 按报错信息里的模型名列表，修改 model 字段 |
| maximum context length is 1048576 | Codex 默认上下文窗口大于第三方模型能力 | 在 config.toml 里给模型配置 context_window 参数 |
| cc switch local proxy failed | CC Switch 本地代理未启动或端口被占用 | 检查 CC Switch 状态，换端口，或直接改用直连 API |
| login failed check api token | Codex 尝试登录或 Git 认证失败 | 确认第三方 API Key 正确，更新 Git 远端凭据，不登录 OpenAI 账号 |
| 400 bad request with unsupported parameter | 服务商不支持 responses 接口 | 把 wire_api 改成 chat，用 chat completions 接口 |
| 环境变量不生效 | WeCode 启动早于环境变量设置 | 重启 WeCode，或把变量写入用户级环境变量 |
5.2 配置成功后的使用体验
配置成功后的体验确实是值得折腾的。在 WeCode 里打开 Codex 面板，直接说"帮我把登录接口的错误处理加上"，它会在当前项目里定位相关文件、写出改动方案、展示 diff，我来确认后点击接受，改动就应用到文件里了。整个过程行云流水，响应速度取决于你选的 API 服务商的延迟，DeepSeek 的响应通常在一两秒内，完全可用。
日常使用中，我慢慢总结了一些个人经验。第一，Codex 适合处理明确的小任务，比如修复某个 bug、补测试用例、重构函数，不适合让它直接从头搭建整个项目，后者容易在复杂逻辑里迷失方向，代码质量不稳定。第二，对话时把上下文控制在合理范围内，不要把一整个大文件全塞进去，让 Codex 按函数或模块来理解和改动，既能减少 token 消耗，也能降低报错概率。第三，善用.gitignore 和权限控制，Codex 会修改项目文件，建议先在一个独立的 git 分支里测试，确认改动没问题再合入主分支。
5.3 写在最后的一点建议
根据我这次在 Windows 上完整走了一遍 Codex + WeCode + 第三方 API 的配置经历，最大的感受是：这类工具的核心逻辑是相通的，配置文件的层次结构、环境变量的优先级、API 接口的兼容性，这些知识搞透一次，以后换任何工具链都能快速上手。如果你也是 Windows 用户，建议严格按照顺序来：先装好 Node.js 和 Git，再装 Codex CLI，然后申请 API Key，最后配置 config.toml 和 WeCode 扩展，不要跳步。
如果你在配置过程中遇到本文没有覆盖的报错，优先去看 %USERPROFILE%\.codex 目录下的日志文件，Codex 会记录详细运行日志，报错原因基本都能在里面找到线索。日志定位问题的效率，远高于盲目搜索报错信息。最后祝你在 Windows 下也能顺利跑起这套 AI 编程组合，少踩坑，多产出。