Codex 出来之后身边不少同事都在折腾这个终端编程代理。简单说它就是 OpenAI 开源的一个 coding agent你可以在命令行里用自然语言交代任务——把这个模块的测试补一下帮我查一下这个报错为什么出现顺手修掉——它会自己读代码、改代码、跑命令、出 diff比 IDE 里那种只会补全的 AI 要主动得多。但国内开发者很快就撞上一个现实问题Codex 默认对接的是 OpenAI 官方接口账号和支付方式对很多人来说都是门槛。于是大家普遍的做法是把它指向国内那些提供 OpenAI 兼容接口的 API 服务商比如 DeepSeek、智谱这类既能直连访问又可以用国内常见的支付方式开通。这篇文章就是我在 Windows 上从零到一配通这件事的完整记录包括环境准备、Codex 安装、config.toml 编写、跑通第一个任务以及我踩过的各种报错和排查方法。适合所有想在 Windows 上用 Codex 干活的开发者不管你是第一次装还是已经配到一半卡住都能在里面找到对应思路。1. 先别急着装三分钟理清 Codex 到底在配什么1.1 市面上其实有三个Codex很多人一搜就懵因为Codex这个名字同时指了好几样东西。第一是 ChatGPT 桌面版和网页版里的 Codex那是 OpenAI 官方托管的云端编程 agent你登录账号就能用但它不开放任何自定义 API 配置你也改不了它背后用的模型。第二是我们这篇文章的主角 Codex CLI这是一个开源本地工具通过 npm 安装后跑在终端里它的特点就是可以自定义模型后端只要对方提供 OpenAI 兼容接口就能把请求转过去。第三是 OpenAI 模型接口层面上的 Codex API 命名一般开发者日常接触不到。所以当你搜到codex 接入 deepseekcodex 使用教程codex 官网下载这些关键词的时候要找的基本都是 Codex CLI。后面我所有的配置、报错也都是围绕 Codex CLI 讲的。1.2 所谓接入国内 API本质是给 Codex 换后端Codex 不是一个和 OpenAI 绑死的客户端。它的底层逻辑非常简单启动时读一个配置文件拿到服务商地址、模型名、API Key然后按照 OpenAI 兼容协议发请求。你只要找到一个实现了/chat/completions接口的国内服务商把它的地址填进去Codex 就以为自己在和 OpenAI 说话实际流量全进了国内服务商。这里有个很重要的概念接口协议。OpenAI 自己的官方接口现在更推荐responses协议而国内绝大多数服务商实现的是更传统、也更通用的chat/completions协议。Codex 通过配置里的wire_api字段来决定用哪套协议说话。这个理解到位了后面很多报错你一眼就能看出来是怎么回事。1.3 整条配置链长什么样Codex CLIWindows 终端→C:\Users\用户名\.codex\config.toml告诉它连谁、用什么模型、Key 从哪个环境变量读→ 国内服务商 APIDeepSeek / 智谱 / 其他兼容服务商。这三个环节缺一不可环境变量里要有 Keyconfig.toml 格式要对模型名要和服务商文档一致。后面你遇到的所有报错几乎都逃不出这三点。2. 环境准备先把 Git 和 Node.js 装明白2.1 GitCodex 干活的基本盘Codex 在工作区里干活时会大量依赖 Git 来做文件变更追踪比如生成 diff、应用 patch、克隆仓库、甚至帮你产生 commit message。你可以不理解为啥一个 AI 工具要装 Git但你只要知道没有 GitCodex 很容易在半路报一些奇奇怪怪的错误。安装很简单去 git-scm.com 下载 Windows 版一路默认安装就行。需要注意两点一是安装时尽量保持英文路径别往中文目录里塞二是 Git for Windows 默认会带上 Git Credential Manager这个组件一定别去掉后面访问私有仓库能不能免密登录就靠它。装完验证一下git --version能输出版本号就说明没问题。如果提示找不到命令大概率是安装时 PATH 没加进去重开一个终端再试还不行就重新安装在安装向导里把把 Git 加入 PATH的选项勾上。2.2 Node.js装 LTS 就好别追最新版Codex CLI 是通过 npm 分发的所以本机必须有 Node.js。官方要求 Node.js 版本在 20.5 以上我的建议是直接装 22 LTS稳一点。下载地址是 nodejs.org选 LTS 版本Windows 安装包双击装完会自动配好 PATH。国内 npm 下载经常慢装完 Node 顺手把 npm 镜像源换成国内源后面装 Codex 会快很多npm config set registry https://registry.npmmirror.com验证一下node -v npm -v两个都能输出版本号就成。这里有个容易踩的坑如果电脑上装了多个 Node 版本或者用过 nvm-windowsPATH 里可能同时存在多个 node 路径导致版本混乱。建议只保留一个版本尤其是别在一个终端里来回切换Codex 依赖的 npm 全局包很容易因此找不到。2.3 装完先验证别着急跳过很多人的 Codex 装到一半出问题根子都在环境没验证好。我建议在装 Codex 之前先执行这两个命令where git where nodeTerminal 会返回这两个命令的实际路径。如果输出的路径不对或者不在你预期的安装目录先解决 PATH 问题再进行下一步否则后面排错会非常痛苦。另外提醒一句装完 Node 或 Git 后之前已经打开的终端窗口是不会自动刷新 PATH 的必须新开一个窗口再验证。这一点 Windows 用户最容易忽略。3. 安装 Codex CLI一行命令的事但坑也不少3.1 用 npm 全局安装最通用环境准备就绪后安装 Codex 其实就一条命令npm install -g openai/codex装完验证codex --version能输出版本号就说明装好了。如果你之前搜到过codex 官网下载或者codex windows 桌面版那是官方提供的安装器也可以装但我个人更推荐 npm 方式因为后面升级只需要一条npm update -g openai/codex比重新下载安装包省事。3.2 安装卡住、下载慢、报错怎么办如果你在安装的时候卡住半天不动或者报各种网络错误十有八九是 npm 默认源的问题。前面我们已经把 registry 换成了 npmmirror如果还是慢可以再检查一下是不是当时换源没生效npm config get registry输出了https://registry.npmmirror.com就没问题。另外Windows Defender 或者其他杀毒软件有时会把新装的命令行工具误报导致安装看起来完成了但实际文件被删了。如果你遇到codex windows 安装未完成这类情况先把安装目录加入杀毒白名单再重新安装一次。还有一种情况是之前安装中断留下了残留此时先执行npm uninstall -g openai/codex清理干净后再重装。3.3 安装成功却提示codex 不是内部或外部命令这是 PATH 的问题。npm 全局安装的目录没有加入系统 PATH导致终端找不到 codex。可以先看看全局目录在哪npm prefix -g比如输出是C:\Users\你的用户名\AppData\Roaming\npm那就把这个目录加到系统 PATH 里然后新开终端再试。顺便说一句升级 Codex 很简单npm update -g openai/codexCodex 更新频率挺高的功能和行为都会变建议隔一段时间升一次级升级后重新跑个简单任务验证配置仍然有效。4. 核心环节写 config.toml把 Codex 指向国内 API4.1 配置文件到底放在哪Codex 的配置文件位置是C:\Users\你的用户名\.codex\config.toml。注意是点开头的一个.codex文件夹不是别的名字。第一次运行 codex 时一般会自动创建这个目录如果没创建手动建一个同名目录和一个空的 config.toml 文件也行。在 PowerShell 里可以用这个命令确认路径存在Test-Path ~\.codex\config.toml返回 True 就是配置文件已经在返回 False 就自己新建。4.2 Codex 接入 DeepSeek一个直接抄的模板下面这段是把 Codex 指向 DeepSeek 的完整配置新建或覆盖写入 config.toml 即可model deepseek-chat model_provider deepseek [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY wire_api chat我逐个字段解释一下因为后面所有服务商都是同一个套路model顶层要用的模型名必须和服务商平台上的名字一致。DeepSeek 目前代表性的模型名是deepseek-chat推理模型是deepseek-reasoner具体以 platform.deepseek.com 控制台看到的为准。model_provider指定下面配的哪个服务商块生效。[model_providers.deepseek]定义一个名为 deepseek 的服务商块方括号里这个名字你可以随便起只要和顶层匹配即可。name展示名没有实际功能。base_url服务商的 OpenAI 兼容接口根地址。注意这里只写到 API 根路径比如https://api.deepseek.com/v1不要再往上拼/chat/completions否则 Codex 会拼出双份路径导致 404。env_key告诉 Codex 去哪个环境变量里读 API Key这里是DEEPSEEK_API_KEY。wire_api接口协议类型填chat表示走/chat/completions。这是接入国内服务商最关键的一个字段漏掉它 Codex 可能默认走 OpenAI 的responses协议而国内服务商大多不支持直接报错。4.3 多服务商并存智谱 GLM 和硅基流动的写法DeepSeek 之外智谱GLM 和硅基流动也是国内开发者常用的选择。它们可以一起写在同一个 config.toml 里通过改顶层的model和model_provider来切换。智谱的配置model glm-4.6 model_provider zhipu [model_providers.zhipu] name Zhipu GLM base_url https://open.bigmodel.cn/api/paas/v4 env_key ZHIPU_API_KEY wire_api chat智谱的国内站是 open.bigmodel.cn模型名以控制台展示为准不同时期的版本号会变比如 glm-4.5、glm-4.6 这种配置前先去官网核对一次。硅基流动的配置model deepseek-ai/DeepSeek-V3 model_provider siliconflow [model_providers.siliconflow] name SiliconFlow base_url https://api.siliconflow.cn/v1 env_key SILICONFLOW_API_KEY wire_api chat硅基流动是个聚合平台上面托管了很多开源模型好处是一个平台能试多种模型。但要注意Codex 调用服务商会用到工具调用function calling如果选的模型不支持这个能力Codex 会表现得听不太懂话所以优先选官方标注支持工具调用的模型。4.4 API Key 的正确保存方式环境变量别写进配置文件每个服务商都需要注册账号、创建 API Key。以 DeepSeek 为例去 platform.deepseek.com 注册后在控制台创建一个 API Key复制出来。其他服务商流程类似。拿到 Key 之后不要直接写进 config.toml。正确做法是存成环境变量。在 Windows 上用setx命令设置用户级环境变量setx DEEPSEEK_API_KEY sk-你的key注意setx只对之后新开的终端窗口生效。如果当前终端想立即生效就先临时设置$env:DEEPSEEK_API_KEY sk-你的key更稳妥的图形化方式是Windows 设置 → 系统 → 关于 → 高级系统设置 → 环境变量 → 用户变量 → 新建变量名填DEEPSEEK_API_KEY变量值填 Key。为什么不建议把 Key 写进 config.toml因为配置文件很容易被同步到网盘、打进 dotfiles 仓库稍不注意就把 Key 泄露了。环境变量的好处是 Key 独立于配置换 Key 时也不用改文件。4.5 配置完怎么验证先测 API再测 Codex配置是否生效先别急着开 Codex先用 PowerShell 直接调一次服务商接口这样可以快速隔离问题。$env:DEEPSEEK_API_KEY sk-你的key $headers { Authorization Bearer $env:DEEPSEEK_API_KEY } $body { model deepseek-chat messages ({ role user; content 说你好 }) } | ConvertTo-Json -Depth 5 $resp Invoke-RestMethod -Uri https://api.deepseek.com/v1/chat/completions -Method Post -Headers $headers -ContentType application/json; charsetutf-8 -Body ([System.Text.Encoding]::UTF8.GetBytes($body)) $resp.choices[0].message.content如果这段命令能返回一段文字说明网络、Key、模型名都没问题剩下的问题只可能出在 Codex 配置层。如果这步就报错那就先根据报错解决服务商侧的问题比如 Key 无效、模型名写错、余额不足等。API 测试通过后在任意目录执行codex 用一句话解释什么是递归能正常回复说明整个链路已经通了。5. 跑通第一个任务交互模式、exec 模式和权限策略5.1 交互模式codex 直接开聊进入一个测试项目目录直接运行codex会进入交互式对话界面。你可以像跟人聊天一样提任务比如请给这个项目写一个 READMECodex 会先读取目录结构再给出计划然后动手改文件。每一步改动它会征求你的确认即使是删一个多余文件也会先问。退出交互模式输入/exit或者按 CtrlC。第一次进入时如果它弹出登录界面、要求你登录 ChatGPT 账号先别急。用自定义服务商时其实不需要登录 OpenAI出现登录提示多半是环境变量没读到或者 config.toml 没生效。检查一下 4.5 的验证步骤把配置理通再跑。5.2 一次性任务与全自动模式codex exec不想进交互界面可以直接用一次性执行codex exec 用 Python 写一个脚本统计当前目录下所有 .py 文件的行数并运行它看看结果这是相对新版本的用法如果你用的版本不支持codex exec就先用codex --help看看命令说明。还有全自动模式可以让 Codex 不经过确认直接执行命令、修改文件codex exec --full-auto 把当前目录下所有 TODO 注释整理到 TODO.md全自动模式风险较高我建议第一次体验时在一个临时副本目录里跑别一上来就在正式仓库里开全自动。不同版本参数可能略有差异执行前先跑codex exec --help确认。5.3 approval_policy 和 sandbox_modeWindows 上要留个心眼Codex 的行为可以在 config.toml 里通过两个顶层字段控制approval_policy suggest sandbox_mode workspace-writeapproval_policy控制审批策略on-request是每次操作都询问suggest是给建议但仍会等待你确认full-auto是自动批准。我日常用suggest既不会太啰嗦又留了确认的机会。sandbox_mode控制沙箱workspace-write允许修改当前工作区文件read-only只读danger-full-access是彻底放开限制。这里有个 Windows 用户要特别注意的现实Codex 的沙箱在 Windows 上的隔离能力是不完整的官方文档也明确说过这一点。所以别以为开了沙箱就万事大吉重要项目操作前最好先备份或者在一个单独的目录里让 Codex 干活。我自己是把 Codex 的默认工作区放在一个专用的临时目录验证完再手动迁移代码。6. 常见报错与排查我踩过的坑都在这里6.1 400 模型名错误API 其实已经把答案告诉你了遇到下面这类报错不要慌报错本身就是在帮你API error: 400 the supported api model names are ...意思是你填的模型名不在这个服务商的白名单里。注意看报错后面列出的模型名列表照着填就行。有些聚合平台会把模型名改得和官方不一致比如把 DeepSeek 的模型写成deepseek-flash、deepseek-v4这种风格和官方文档对不上遇到时以服务商 API 返回的supported api model names为准不用怀疑自己。顺便说一句DeepSeek 官方平台的常用模型名是deepseek-chat和deepseek-reasoner模型名是区分大小写的别写错。6.2 401/403 认证失败八成是环境变量没生效这类报错典型表现是Authentication failed首先确认环境变量有没有真的设置成功echo $env:DEEPSEEK_API_KEY如果输出为空说明环境变量没设置或者是在setx之前打开的终端里运行的。setx只对之后新开的终端生效所以我每次配置完都会强制自己新开一个终端再测。还有一种情况是复制 Key 时多复制了看不见的空格粘贴时注意别带多余字符。如果是多服务商并存还要检查 config.toml 里的env_key是不是对上了你设置环境变量时用的名字比如智谱写了ZHIPU_API_KEY环境变量却设成了ZHIPU_KEY那肯定 401。6.3 codex endpoint /responses 相关报错接口协议和网络层一起查如果你看到类似这样的报错片段cc switch ... failed while handling codex endpoint /responses ...这个报错有两个常见来源。第一个是wire_api没配或者配错导致 Codex 用 OpenAI 专属的responses协议去请求国内服务商而服务商只提供/chat/completions。排查方法很简单确认 config.toml 每个服务商块里都有wire_api chat。第二个来源就麻烦一点。如果你的 Windows 上开着系统级流量转发或加速类的软件它可能会把 Codex 发往国内 API 的 HTTPS 请求也拦截或改写一遍导致 Codex 在处理 endpoint 时出现cc switch ... failed这类报错。遇到这种情况先把这类软件退出恢复系统默认网络设置再试。配置国内可直连的服务商本来就是希望请求走直连不需要任何多余的网络中转层。如果一定要保留这类软件那就把服务商 API 域名加入它的直连规则。6.4 上下文超长报错省着点喂给模型还有一种常见报错This models maximum context length is 1048576 tokens. However, you requested ...意思是输入的内容超过了模型上下文上限。Codex 作为 agent会把项目里的相关文件内容作为上下文发给模型。如果你的目录里有超大日志文件、构建产物、node_modules 这类东西很容易一下子把上下文撑爆。解决办法是给 Codex 一个干净的工作区配合.gitignore把大文件排除掉另外对话太长时直接新开一个会话不要在一个上下文里无限追加任务。上下文超长不只是报错问题还直接关系到费用消耗因为发给模型的内容是按 token 计费的。6.5 Git 认证和 GitLab 相关报错这锅不是 Codex 的有人遇到login failed. check api token or gitlab version. log in via git if the versi...这类报错大多发生在 Codex 执行 git 操作时比如克隆私有仓库、拉取代码。它的本质是本机 Git 的凭据没配好Codex 只是代替你执行了 git 命令认证失败自然就抛出来了。解决办法是先把 Git 凭据问题解决确保 Git for Windows 安装了 Git Credential Manager然后自己先在终端里手动 clone 一次仓库让它记住凭据。对于 GitLab也可以在 GitLab 后台生成 Personal Access Token把它配置到 Git 凭据里。Git 层面能正常拉取推送了Codex 层的报错自然消失。6.6 Windows 特有坑中文路径、执行策略、编码Windows 上还有几个很琐碎但很烦人的坑。第一是中文用户名或中文路径某些工具链在处理非 ASCII 路径时会异常建议项目目录用纯英文路径。第二是 PowerShell 执行策略运行某些安装脚本时会提示在此系统上禁止运行脚本可以执行Set-ExecutionPolicy -Scope CurrentUser RemoteSigned然后选 Y。第三是输出乱码Codex 输出的中文在旧版终端里可能显示成乱码切一下 UTF-8 编码chcp 65001另外如果你之前遇到过 codex windows 安装未完成记得把杀毒软件加白名单这属于 Defender 误删文件导致的半成品安装重新装之前先彻底卸载。6.7 Docker API 报错跟服务商无关还有一种报错和 API 服务商一点关系都没有failed to connect to the docker api at npipe:////./pipe/dockerdesktoplinuxen...如果你在 Codex 里配置了 Docker 相关的 MCP 工具启动时它会尝试连接 Docker Desktop 的 Windows 管道连不上就是这个报错。解决办法是先启动 Docker Desktop等它右下角状态变绿再跑 Codex。如果你不做容器相关开发暂时不需要这项能力直接把这个 MCP 配置注释掉就行不影响正常使用。6.8 排错顺序速查表出了报错别乱试按这个顺序排查效率最高报错特征最常见原因优先检查方向400 ... supported api model names模型名填错按报错列出的名字重新填401 / 403 认证失败Key 没读到或 Key 错误echo $env:变量名、新开终端fetch failed / ECONNREFUSED / timeoutbase_url 错、网络层被干扰先用 PowerShell 直连测试 APIcodex endpoint /responses 相关错误wire_api 缺失、网络层拦截确认wire_api chat、清理转发类软件maximum context length ...上下文超长新开会话、清理大文件目录login failed / gitlab versionGit 凭据问题配 Git Credential Manager、手动 clone 一次failed to connect to docker apiDocker Desktop 未启动启动 Docker Desktop 或注释 MCP 配置codex 不是内部或外部命令npm 全局目录不在 PATH把npm prefix -g的路径加入 PATH7. 完整配置模板与我的几个实际教训7.1 一个三服务商并存、可直接抄的模板最后把我目前在用的完整配置贴出来你可以直接覆盖到 config.toml按需调整模型和 Keymodel deepseek-chat model_provider deepseek approval_policy suggest sandbox_mode workspace-write [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY wire_api chat [model_providers.zhipu] name Zhipu GLM base_url https://open.bigmodel.cn/api/paas/v4 env_key ZHIPU_API_KEY wire_api chat [model_providers.siliconflow] name SiliconFlow base_url https://api.siliconflow.cn/v1 env_key SILICONFLOW_API_KEY wire_api chat想切换服务商只需要改顶层的model和model_provider比如切到智谱就把顶层改成model glm-4.6、model_provider zhipu改完保存后新开终端生效。7.2 长期使用要留意的几件事费用是第一个要留意的Codex 作为 agent 消耗 token 的速度比普通对话快得多它每读一个文件、每运行一次命令都要消耗额度。我建议在服务商后台开启余额提醒或者定期看一眼消费记录别让它不知不觉烧掉太多。第二个是数据隐私所有发出去的问题和代码都会经过服务商敏感项目不要直接丢给 Codex或者提前做脱敏处理。第三个是版本更新Codex 的更新非常频繁每次升级后行为可能变化建议升级后先跑一个简单任务验证一下原配置还正常。7.3 我的两个真实翻车记录第一个翻车是 base_url 写错。我一开始想当然把 base_url 写成了https://api.deepseek.com/v1/chat/completions结果 Codex 拼接请求时变成了双份路径直接 400。折腾了好一会儿才意识到 base_url 只要写到 API 根路径剩下的路径 Codex 会自己拼。第二个翻车更蠢用setx设置好环境变量后没开新终端就急着跑 codex连续报 401。我一度以为是 Key 出了问题反复重新创建了好几次 Key最后才发现是终端里根本读不到刚设的环境变量。后来我学乖了每次用setx之后强制新开一个终端或者干脆先用$env:DEEPSEEK_API_KEY sk-xxx在当前终端里临时设一遍先跑通再说。最后分享一个小技巧给 Codex 安排一个专门的临时工作目录所有冒险操作都让它在那个目录里进行。这个做法帮我避免了很多一觉醒来仓库被改得乱七八糟的惨剧。Codex 是个很好用的工具但再好的工具也得用对方式熟悉了这套配置流程之后你在 Windows 上应该能比较顺手地把它用起来了。