先说结论如果你在 Windows 上折腾过 Codex CLI大概率被config.toml的格式和缩进坑过如果你还试过接入 DeepSeek那更是在“主模型、provider、API Key”这一串概念里绕了不少弯路。这篇博文就把我的完整方案分享出来一个用 PowerShell 写的免费安装助手把 Windows 上装 Codex、改 TOML、接 DeepSeek 的过程压缩到 3 步全程不用手碰配置文件适合刚接触 Codex 想直接跑起来的人也适合已经手动配过、被各种报错折磨过的老手——你至少能从这里找到几条排查思路。1. 为什么我放弃了手改 TOMLCodex 在 Windows 上的配置痛点1.1 Codex 是什么Windows 用户为什么要装Codex 是 OpenAI 推出的命令行编程助手简单说就是在终端里跑一个 AI 结对编程工具。它不依赖 IDE输入codex 帮我写个批量重命名脚本就能在当前目录下直接生成和修改文件还能执行命令、解析报错整个体验非常接近在终端里多了一个懂代码的同事。以前它只支持 macOS 和 Linux现在官方已经支持 Windows但安装和配置过程没有图形界面那么友好所有设置都集中在一个 TOML 文件里。Windows 用户想要用上 Codex通常的路径是装 Node.js、用 npm 装 Codex CLI、然后手动创建或修改~/.codex/config.toml。对于熟悉命令行的人不难但如果你只想快速跑通这一步就开始劝退了。1.2 手改 TOML 的三个真实痛点第一个痛点是格式敏感。TOML 看起来简单但它对缩进、键值顺序、数组和嵌套表的写法有严格要求。多打一个空格、少写一个引号解析器直接报错。更麻烦的是Codex 的报错信息往往只告诉你“解析失败”不会精确提示是哪一行出的问题排查全靠肉眼。第二个痛点是字段含义不直观。要接入 DeepSeek你需要理解model、model_provider、model_providers、base_url、env_key这一串概念之间的关系。model_providers是一个包含多个 provider 的映射表每个 provider 又有自己的base_url和env_key。model字段决定了主模型名model_provider决定了用哪个 provider。这几个字段只要有一个对不上Codex 就会在启动时立刻报错或者等实际调用 API 时才爆出 404、401。第三个痛点是环境变量。Codex 默认会从环境变量读取 API Key而不是写死在配置文件里。这意味着你改完 TOML 还不够还得去 Windows 的“系统属性 - 环境变量”里新建一个变量然后关掉当前终端重新打开变量才能生效。这一步对非开发背景的用户特别不友好。1.3 安装助手的出现一次点击代替反复试错我一开始是老老实实手动改的前后试了三次每次都因为不同的小问题失败。后来我意识到这类“配置型工具”最大的门槛不是功能本身而是前置配置的琐碎。干脆写一个 PowerShell 脚本把环境检测、Codex 安装、配置写入、API Key 提示全部自动化。运行一次脚本就相当于替你完成了几十个手工步骤。这也是这篇文章标题里“安装助手”的由来。它不是某个大厂出的 GUI 软件就是一段你可以打开看、可以修改的脚本逻辑透明、没有后门适合放在本地跑。折腾了几次之后我把这套脚本稳定下来整个过程只需要 3 步也就是说下载脚本、运行、填 API Key。下面我把脚本原理和实操过程完整拆开讲。2. 安装助手的设计思路与配置原理2.1 TOML 配置结构拆解model、model_provider和model_providers在动手写脚本之前必须先搞清楚 Codex 的 TOML 配置到底在描述什么。一份最简配置长这样model deepseek-chat model_provider deepseek [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY拆开看model是实际使用的模型名Codex 会把这里的字符串原样当作模型 ID 传给 API。model_provider是当前要激活的 provider 名称它必须和[model_providers.xxx]这个表名一致。model_providers是一个嵌套表定义了供应商的连接信息name只是展示名base_url是 API 的地址env_key是读取 API Key 的环境变量名。理解这个结构后手动配置的难点就清晰了如果你把model_provider deepseek写成deep-seek但下面的表名还是[model_providers.deepseek]Codex 就会报找不到对应的 provider。更隐蔽的是如果你同时配置了 OpenAI 官方和其他厂商的 providermodel还指向官方模型名Codex 就可能去默认的 API 地址请求结果返回的模型不存在报错信息让你误以为是配置格式错了。2.2 为什么用 PowerShell 脚本而不是写一个 GUI 工具我确实考虑过要不要做成图形界面工具但最终放弃了。命令行工具的配置过程往往带有“连续性”检测 Node.js、执行 npm 安装、检查 .codex 目录、备份文件、写配置、设置环境变量、提示验证。这些动作用脚本做是线性的每一步都可以通过退出码判断是否成功失败就中断用户能立刻看到哪一步出了问题。而 GUI 工具要把这么多状态同步到界面上反而复杂而且分发一段 PowerShell 脚本比分发一个 exe 更轻量用户还能直接查看源码避免安全顾虑。PowerShell 在 Windows 10/11 上默认存在不需要额外安装运行时。它调用npm、git、node的方式与 Bash 脚本调用命令没有本质区别但处理 Windows 路径、环境变量、注册表等系统级操作时更顺手。对于用户来说运行方式是“右键脚本 - 使用 PowerShell 运行”没有门槛。2.3 脚本的核心逻辑检测、安装、备份、写入、提示安装助手的工作流程可以拆成五个环节。第一是检测检查node、npm、git是否存在于 PATH 中并检查版本是否满足要求。第二是安装如果 Codex 尚未安装就执行npm install -g openai/codex。第三是备份如果config.toml已存在先复制一份带时间戳的.bak文件防止改坏后无法回滚。第四是写入把 DeepSeek provider 的配置写入新配置。第五是提示把输入框中的 API Key 写入用户级环境变量并提醒用户重启终端。这样一个流程覆盖了绝大多数失败场景。检测步骤能在早期拦截“没装 Node.js”这类基础问题备份步骤让用户可以放心反复尝试写入步骤把 TOML 格式完全隐藏掉用户只需要提供一个 Key。3. 3 步接入 DeepSeek 的完整实操3.1 前置环境检查Windows 版本、Git、Node.js 和 API Key正式开始之前先确认几件事。系统最好是 Windows 10 或 Windows 11PowerShell 5.1 或更高版本都能跑脚本老版本 PowerShell 部分语法可能不兼容。需要提前装好 Node.js 18 或更高版本因为 Codex CLI 是 npm 包没有 Node.js 环境装不了Git 建议也装上Codex 的部分功能会调用 Git 做文件差异和版本操作实际上很多 Windows 开发机都会装这里就不赘述。还要准备一个 DeepSeek 的 API Key。去哪里申请我就不展开了但提醒一句API Key 是可以创建多个的建议单独创建一个给 Codex 用不要在多个地方共用一把 Key这样万一某个场景下泄露你可以在控制台单独撤销而不影响其他服务。创建之后复制下来脚本运行时直接粘贴即可。3.2 第一步运行安装助手自动检测环境并安装 Codex把下面这段脚本保存为codex-deepseek-setup.ps1然后右键选择“使用 PowerShell 运行”。脚本会先检测环境缺什么就在终端里明确提示。$ErrorActionPreference Stop Write-Host Codex DeepSeek 安装助手 # 1. 检查 Node.js $node Get-Command node -ErrorAction SilentlyContinue if (-not $node) { Write-Host [错误] 未检测到 Node.js请先安装 Node.js 18 以上版本。 -ForegroundColor Red exit 1 } Write-Host [通过] Node.js 版本: $(node -v) # 2. 检查 npm $npm Get-Command npm -ErrorAction SilentlyContinue if (-not $npm) { Write-Host [错误] 未检测到 npm请确认 Node.js 安装完整。 -ForegroundColor Red exit 1 } # 3. 安装 Codex CLI $codex Get-Command codex -ErrorAction SilentlyContinue if (-not $codex) { Write-Host [步骤] 正在全局安装 openai/codex ... npm install -g openai/codex } else { Write-Host [通过] 已检测到 Codex CLI: $($codex.Source) } Write-Host 环境准备完成。这段脚本的作用是把“环境检测”和“安装 Codex”合并成一个动作。$ErrorActionPreference Stop是核心细节它让脚本在任意一行报错时立即停止而不是带着错误继续往下跑这样问题更容易定位。3.3 第二步输入 DeepSeek API Key自动写入配置环境准备完成后脚本接着执行配置写入。为了直观我按照一个更完整的版本来展示这一阶段的核心逻辑# 4. 备份已有配置 $configDir $env:USERPROFILE\.codex $configPath $configDir\config.toml if (Test-Path $configPath) { $backupPath $configPath.bak_$(Get-Date -Format yyyyMMdd_HHmmss) Copy-Item $configPath $backupPath Write-Host [备份] 原配置已备份到 $backupPath } # 5. 写入 DeepSeek Provider 配置 $apiKey Read-Host 请输入 DeepSeek API Key if ([string]::IsNullOrWhiteSpace($apiKey)) { Write-Host [错误] API Key 不能为空。 -ForegroundColor Red exit 1 } # 写入用户级环境变量 [Environment]::SetEnvironmentVariable(DEEPSEEK_API_KEY, $apiKey, User) # 生成 config.toml $configContent model deepseek-chat model_provider deepseek [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY if (-not (Test-Path $configDir)) { New-Item -ItemType Directory -Path $configDir -Force | Out-Null } Set-Content -Path $configPath -Value $configContent -Encoding UTF8 Write-Host [完成] 配置写入成功。请关闭当前终端重新打开后即可使用 codex 命令。这一步解决了我之前手动配置时遇到的 80% 的问题。base_url的值建议以 DeepSeek 官方文档为准不同时期官方给出的地址可能有细微差别以前是https://api.deepseek.com后面也出现过带/v1的形式如果你调用时碰到 404优先去官方文档确认一次这个地址。env_key决定了 Codex 从哪个环境变量读取密钥我在这里统一用DEEPSEEK_API_KEY这样和官方文档的示例保持一致。3.4 第三步重启终端启动 Codex 验证连通性配置写入后最关键的一步是重新打开终端。如果你在当前终端直接运行codex大概率会提示找不到 API Key因为当前会话的环境变量还是旧的。关掉终端再开一个然后输入codex 你好请用一句话介绍你自己正常情况下Codex 会通过 DeepSeek 的 API 返回结果。如果出现 401说明 API Key 有问题回到控制台检查 Key 是否复制完整或者是否多了空格如果出现 404优先检查base_url是否和你申请 API 的平台一致如果出现超时多半是网络连接问题后面我会细说。这里顺带提一个体验细节第一次跑codex时它会要求你选择登录方式。如果你只是想用 DeepSeek API选择 API Key 方式而不是 ChatGPT 账号方式否则后续会走 ChatGPT 账号的鉴权流程和你配置的 DeepSeek provider 完全不在一条链路上。选错的话启动时会一直卡在登录引导阶段。4. 常见问题与排查技巧实录4.1 网络类报错cc switch local proxy failed while handling codex endpoint我见过不少人在接入 DeepSeek 时终端里弹出类似cc switch local proxy failed while handling codex endpoint /responses的报错或者出现Client network socket disconnected之类的提示。这类问题的本质是 Codex 在尝试连接 API 时网络层没有走通但它把底层细节也抛到了终端里看起来非常复杂。排查顺序我建议是先确认base_url能否直接访问。可以在终端里执行curl https://api.deepseek.com如果返回一段 JSON 或非空的响应说明地址本身可达。接着检查系统代理设置Codex 会读取系统的 HTTP_PROXY、HTTPS_PROXY 等环境变量如果你之前设置过代理但代理服务没启动或者地址失效就会导致 Codex 连接失败。这种场景下要么暂时清掉代理环境变量要么确保代理服务是运行状态再重新运行命令。这里有个常见误区很多人以为是config.toml问题反复改配置但其实配置一点问题没有纯粹是网络层没通。我的经验是先跑一个curl验证把网络问题和配置问题分开能省很多时间。4.2 上下文超限codex ran out of room in the models context这个报错和 TOML 配置无关是模型上下文达到上限的表现。Codex 会把当前会话的文件内容、对话历史和工具调用结果都塞进上下文里当总 token 数量超过模型的上下文窗口时它就报这个错。DeepSeek 的 chat 模型上下文窗口相对有限长时间不清理对话历史、每个会话里塞入大量文件代码都容易触发这个报错。处理方式有三个一是启动新会话遇到上下文超限时先开一个新会话把未完成的修改带过去二是在输入指令时主动缩小范围比如让 Codex “只读这几个文件”而不是“扫描整个项目目录”三是检查 Codex 有关上下文的参数配置看看是否有--max-budget之类的限制选项把这个值调低一点Codex 会更早提醒你而不是等爆了才报错。4.3 模型请求报错request extension preparation failed与模型名校验接入 DeepSeek 后有时候启动 Codex 本身是正常的但一旦发出具体请求就会看到类似request extension preparation failed的报错。我遇到过几种情况其中最典型的是模型名写错。DeepSeek 的模型 ID 并不是gpt-4o或gpt-5这种Codex 默认配置里的模型名都是 OpenAI 的如果你没有把model字段改成 DeepSeek 的模型名Codex 就会用默认值去请求 DeepSeek 的接口DeepSeek 返回“模型不存在”但 Codex 把这个错误包装成了比较抽象的报错看起来像脚本崩溃。解决方案很简单确认config.toml里的model deepseek-chatmodel_provider deepseek。如果两个字段不匹配宁可不配 provider 直接用默认也不要让模型名和 provider 指向不同阵营。另一个细节是DeepSeek 目前提供的基础对话模型叫什么名字要按官方文档为准不同时期有不同叫法而且可能在更新后老模型名被下架遇到这种问题直接登录平台看“模型列表”即可。4.4 登录态与账号类型的限制the gpt-5.6-sol model is not supported when using codex with a chatgpt account还有一类报错和 provider 配置完全无关比如你看到the xxx model is not supported when using codex with a chatgpt account。这个报错出现在你用 ChatGPT 账号方式登录 Codex 时但配置里的模型名又不是该账号可用的模型。如果你是想接 DeepSeek强烈建议不要用 ChatGPT 账号登录改用 API Key 方式。Codex 的登录流程里通常有Sign in with ChatGPT和Use API Key两个选项。接 DeepSeek 必须走 API Key因为 DeepSeek 的 API 只认自己的 Key和 ChatGPT 账号体系完全不互通。选错账号类型即使配置全对最终模型名校验那一步还是会卡住。这里我整理了一个速查表方便你快速定位问题报错关键信息主要原因解决优先级local proxy failed/socket disconnected网络层问题通常和代理设置有关先 curl 验证连通性再查代理ran out of room上下文 token 超限开新会话减少文件读取范围request extension preparation failed模型名或 provider 配置不匹配检查 model 和 model_provider 字段model is not supported when using codex with a chatgpt account登录方式选错改用 API Key 方式登录401 UnauthorizedAPI Key 错误或为空检查环境变量和 Key 是否正确404 Not Foundbase_url 或模型名错误去官方文档核对 base_url 和模型列表4.5 我自己踩过的一个隐藏坑环境变量没生效最后说一个我认为最隐蔽的坑。我的配置完全正确Codex 还是提示找不到 API Key查了很久才发现是因为我设置完环境变量之后忘了关闭终端窗口。PowerShell 的当前会话继承的是启动时的环境变量快照你后来用setx或者其他方式改了用户级环境变量当前窗口不会自动刷新必须重开终端。更隐蔽的是有时候你重开的终端是从旧终端里“嵌套”启动的比如在 VS Code 里点了终端窗口右上角的新建终端但这个进程的父进程还是之前那个旧会话环境变量依然是旧的。最佳做法是完全关闭 VS Code 或 Windows Terminal重新打开一个新窗口再尝试运行codex。如果还是不行在终端里手动执行echo $env:DEEPSEEK_API_KEY看看输出是否是你粘贴的那个 Key这一步能立刻判断环境变量有没有真正生效。安装助手的价值不在于代码本身多复杂而在于它把上述这些需要反复试错的步骤收敛到了“运行一次脚本”里。按照我个人的实际体验不管你是第一次用 Codex还是已经手动配置过但被各种奇怪的网络和模型报错折磨过都建议从备份配置开始然后让脚本接管写入逻辑。脚本帮你生成的 TOML 结构是固定模板降低了你手误的可能如果你后续想再换回 OpenAI 官方模型也不用慌备份文件里的.bak就是你的后悔药一条Copy-Item命令就能恢复原状。以后再看到类似“为什么我明明配对了还是报错”的问题我会建议大家的第一反应不要是怀疑配置内容而是先检查环境变量、网络连通性和登录方式。把这个排查顺序固化下来Windows 上接 Codex DeepSeek 这件事真的可以稳定跑起来。