最近不少同事都在问同一件事：Codex 在 Windows 上到底怎么配置才能顺利跑起来。我最初也是从命令行一路踩坑，装完 Node.js、配好 npm、处理完登录认证，才把这套 AI 编程工具真正在 Windows 下用顺。这篇教程基于我自己的实操经验，从环境准备、安装登录，到配置文件解析和常见报错排查，把 Windows 上配置 Codex 的完整链路讲清楚，适合所有想在 Windows 终端里用 Codex 辅助写代码的开发者参考。
1. Codex 在 Windows 下到底依赖什么：先把配置思路理清楚
1.1 Codex 是什么，适合谁用
Codex 是 OpenAI 推出的编程智能体工具，核心形态是一个跑在终端里的 CLI 程序。它和普通的 AI 聊天工具不太一样，Codex 能直接读取你的项目代码、分析目录结构、执行命令、修改文件，甚至可以自己跑测试来验证改动。简单说，你在终端里给它一个任务，它不只是“给建议”，而是会动手改代码。
这种工具最适合三类人：一是日常用终端开发、愿意把重复性编码工作交给 AI 的开发者；二是想快速验证某个技术方案、需要 AI 帮忙写脚手架代码的人；三是团队里需要统一 AI 辅助编程工作流、希望把配置固化下来的技术负责人。如果你只是想要一个网页聊天窗口，那 Codex 不是你的目标；但如果你想要一个真正能和你并肩写代码的命令行助手，它值得你花半小时把环境配好。
1.2 Windows 配置的整体链路与关键决策
在 Windows 上配置 Codex，核心其实不是 Codex 本身，而是它周边的运行环境。整条链路大概是：Node.js 环境 -> npm 包管理器 -> Codex CLI 安装 -> ChatGPT 账号登录认证 -> config.toml 配置文件 -> 日常使用与排错。
之所以要先装 Node.js，是因为 Codex CLI 本身就是基于 Node.js 生态分发的，官方推荐通过 npm 全局安装，后续更新也靠 npm。装 Git 则是实际开发中绕不开的依赖，Codex 在分析代码库、生成补丁、执行 git diff 这类操作时，底层会调用 git 命令，没有它很多功能会报错。
macOS 和 Linux 用户往往只需要一条命令就能装完，但 Windows 用户需要额外注意三件事：PowerShell 的脚本执行策略、PATH 环境变量是否包含了全局包目录、终端编码是否支持 Codex 交互界面。这三个地方只要有一个没处理好，后续就会有各种奇奇怪怪的报错。所以这篇教程的顺序很重要：先把地基打好，再装 Codex，最后再碰配置。
2. Windows 环境准备：Node.js 与 Git 安装的避坑指南
2.1 Node.js 版本选择与安装细节
安装 Node.js 时，最省心的选择是官方 LTS 版本，建议 18 或 20。不要贪图新奇装最新的奇数版本，Codex 这类 CLI 工具对 Node 版本有兼容要求，LTS 版本经过大量测试，稳定性高得多。更不要装特别老的版本，我见过有人机器上还是 Node 12，结果 Codex 安装后直接启动失败，报错内容五花八门，最后查下来就是 Node 版本太低。
下载时去 Node.js 官网拿 Windows Installer (.msi) 安装包，安装过程中有一个关键步骤：在“Custom Setup”页面确认勾选“Add to PATH”。这一步默认是勾上的，但有些精简安装教程会让人取消，千万别取消。装完之后打开一个新的 PowerShell 窗口，运行下面两条命令验证：
node -v npm -v能看到版本号就说明 Node.js 装好了。如果终端提示“node 不是内部或外部命令”，多半是 PATH 没配上，要么重装并勾选 Add to PATH，要么手动把 Node.js 的安装目录加到系统环境变量里。
2.2 npm 镜像与全局包路径设置
Windows 下直接用 npm 安装大型工具包，速度通常不太理想。这不是 Codex 的问题，而是 npm 默认源在海外，国内网络环境拉取速度不稳定。我一般会先把 npm 源切换到国内镜像，这一步能省下大量等待时间。
npm config set registry https://registry.npmmirror.com设置完成后可以用npm config get registry确认是否生效。这个镜像源是合规的公开 npm 镜像，日常开发非常常用，放心用。
接下来还要确认一件事：npm 全局安装目录是否在 PATH 中。运行下面的命令查看全局包的安装位置：
npm config get prefix默认情况下，Windows 的全局包目录会在%APPDATA%\npm，npm 安装时通常会自动把这个目录加进 PATH。但如果你用了一些第三方 Node 版本管理工具，或者手动调整过环境变量，这个路径可能就丢了。后续如果出现“codex 命令找不到”的情况，优先查这里。
2.3 Git 安装与终端选择
Git for Windows 的安装没什么技巧，一路默认即可，但安装过程中有一个容易忽略的选项：在“Adjusting your PATH”这一步，务必选择“Git from the command line and also from 3rd-party software”。这个选项会把 git 命令注入到全局 PATH，否则你在 PowerShell 里敲git会提示找不到命令。
终端方面，强烈建议使用 Windows Terminal 或 PowerShell 7，不要用传统 cmd 窗口。原因很简单：Codex 的交互界面有大量彩色输出和动态刷新，老 cmd 窗口对 ANSI 转义序列支持不完整，显示出来会是一堆乱码或者排版错乱。Windows Terminal 默认支持这些现代终端特性，而且字体渲染更好，长时间盯屏幕也舒服一些。
装完 Git 后，在新的终端里验证一下：
git --version能输出版本号，环境准备就算完成了。到这一步，你的 Windows 已经具备了运行 Codex 的基础条件，接下来才是真正的 Codex 安装。
3. 安装 Codex 与登录认证：最常见的两个卡点
3.1 通过 npm 安装 Codex CLI
环境准备好之后，安装 Codex 本身其实是很简单的一条命令：
npm install -g @openai/codex如果你之前配置了 npm 镜像源，这一步会非常快。等它跑完，先验证一下是否安装成功：
codex --version如果提示codex不是可识别的命令，不用慌，八成是全局 npm 目录没在 PATH 里。我用一个临时方案快速验证：先找到全局目录，再手动把目录加进用户级 PATH 环境变量。具体做法是在 PowerShell 里运行：
npm config get prefix把输出的路径复制下来，然后在系统设置里打开“编辑账户的环境变量”，在 Path 变量中新增这个路径，保存后重新打开终端。这个方法同样适用于其他 npm 全局工具找不到命令的情况。
还有一个 PowerShell 特有的坑：脚本执行策略。Codex 安装后会在全局目录生成一些 .cmd 和 .ps1 包装脚本，如果 PowerShell 的执行策略是 Restricted（Windows 默认值），运行codex时可能被拦截，提示“无法加载文件 ... 因为在此系统上禁止运行脚本”。解决办法是用管理员身份打开 PowerShell，执行：
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser这个策略允许运行本地创建的脚本和带有有效签名的远程脚本，既能跑 Codex，又不至于完全放开安全限制，是开发机上的合理选择。
3.2 ChatGPT 账号登录与设备码认证
安装成功后，第一次运行codex会进入登录流程。Codex 的登录方式是在终端里发起认证，屏幕上会显示一个链接地址和一组一次性设备码。你需要做的是：在浏览器里打开那个链接，登录你的 ChatGPT 账号，然后输入终端显示的设备码完成授权。
这一步有几个细节需要提醒。第一，终端不要关闭，整个认证过程要保持终端处于运行状态。第二，浏览器打不开链接的情况也正常，手动复制链接到任意浏览器地址栏打开即可。第三，授权完成的瞬间，终端会自动检测到状态变化并进入交互界面，不需要手动刷新。
认证成功之后，Codex 会把登录状态保存在本机配置目录下，通常是在%USERPROFILE%\.codex\auth.json这类位置。这意味着你不需要每次打开终端都重新登录，只有 token 过期或主动退出时才需要重新走一遍流程。如果你换了电脑或者换了账号，直接把这个文件删掉再运行codex，就会重新触发登录流程，这个清理方法比找退出命令更直接。
3.3 组织设置加载失败的处理思路
登录之后，有些用户会看到类似“无法加载组织设置”的提示。出现这个提示，绝大多数情况不是 Codex 坏了，而是下面几类原因：账号登录状态过期、当前网络环境无法正常访问服务端、账号本身没有可用的组织空间。
处理顺序我建议这样排查。先看账号状态，回浏览器确认 ChatGPT 账号是否正常登录，是不是 Plus、Pro、Team 这类有 Codex 使用权限的账号；再看登录缓存，删掉%USERPROFILE%\.codex下的认证文件，重新跑一遍登录流程；最后看网络连通性，确认本机网络环境可以正常访问 Codex 服务端。如果这三步都走完了还是不行，大概率是账号权限问题，换一个满足条件的账号即可。
这里特别想强调一个原则：网络可达性是登录成功的前提，这属于环境问题而不是配置问题。如果你所在的网络环境无法正常访问相关服务，那不管怎么配 Codex 都会卡在登录或请求环节，请先确认这一点，再去排查其他配置。
4. 配置文件深度解析：模型切换、中文回复与第三方服务接入
4.1 配置文件位置与基本结构
Codex 的配置文件在 Windows 下的默认位置是%USERPROFILE%\.codex\config.toml。如果登录成功但目录下没有这个文件，可以手动创建，Codex 会正常读取。
config.toml 用的是 TOML 格式，结构不复杂，最核心的就是几个顶层配置项。我第一次打开这个文件时也有点懵，但拆开看其实就三块内容：模型选择、模型服务商定义、系统提示词设置。
# 默认使用的模型 model = "gpt-5-codex" # 模型服务商列表 model_providers = [ { name = "openai", base_url = "https://api.openai.com/v1", env_key = "OPENAI_API_KEY" } ]看懂这个结构之后，你会发现 Codex 的配置思路非常灵活：它并不绑定单一服务商，而是允许你通过model_providers定义多个服务入口，再通过model字段指定用哪个模型。这个设计为接入第三方模型服务提供了很大的自由度，后面会详细展开。
4.2 让 Codex 用中文回复：别把“界面中文”和“回复中文”搞混
“Codex 怎么设置成中文”这个问题，我经常看到，但需要先澄清一个概念：Codex CLI 的界面文字目前主要以英文为主，基本没有官方中文语言包选项，所以“把整个工具界面变成中文”目前没有简单开关。
但绝大多数人问这个问题，真实需求其实是“让 AI 回复的内容用中文”。这个完全能实现，而且有稳定可靠的办法。最简单的就是在对话里直接说“请用中文回答”，Codex 会遵循这个指令。但如果每次都要说一次，体验就差了，更好的做法是把中文要求写进配置文件里。
在 config.toml 中，可以通过系统提示词来固化行为：
model = "gpt-5-codex" system_prompt = "你是一名严谨的软件工程师。请始终使用简体中文回复，技术术语可以保留英文原文。"设置完成后，每次启动 Codex 对话，它都会自动以中文回复你。如果你希望它在不同项目里表现不同，还可以针对不同目录维护不同的配置文件，这个后面再说。建议新手一上来就把这条配置加上，能极大降低使用门槛。
4.3 接入 DeepSeek 等第三方模型服务的完整配置
Codex 默认使用 OpenAI 自己的模型，但对很多开发者来说，第三方模型服务也是刚需。以 DeepSeek 为例，接入方式非常清晰：在model_providers里增加一个新的服务商定义，指定它的接口地址和对应的环境变量名，然后把model切换到该服务商的模型名称。
model = "deepseek-chat" model_providers = [ { name = "deepseek", base_url = "https://api.deepseek.com/v1", env_key = "DEEPSEEK_API_KEY" } ]其中name是这个服务商在 Codex 里的标识名，base_url是 API 接口地址，env_key告诉 Codex 从哪个环境变量里读取 API Key。配置好之后，再设置环境变量：
[System.Environment]::SetEnvironmentVariable("DEEPSEEK_API_KEY", "你的密钥", "User")设置完环境变量记得重新打开终端，让变量生效。这一步做完，Codex 就会用 DeepSeek 的模型来分析和修改代码了。同样的思路可以扩展到任何提供 OpenAI 兼容接口的服务，只要格式对得上，都能这样接。
接入第三方服务有一个特别值得注意的点：不同模型的代码理解和指令遵循能力有差异，DeepSeek 这类模型的性价比确实高，但在 Codex 这种“直接改代码”的场景里，模型的稳定性会直接决定你的使用体验。如果遇到改错文件、理解偏差等问题，不要怪 Codex 本身，先试试切回默认模型对比一下，往往能定位到模型能力差异上。
4.4 常用配置项与工作流增强技巧
除了模型和服务商，config.toml 里还有几个配置项值得关注。系统提示词system_prompt不只是用来设置语言，它还可以定义整个团队的编码规范。比如你的团队要求所有生成的代码必须包含单元测试、必须使用 TypeScript、禁止使用 any 类型，这些都能写进系统提示词里，相当于把 Codex 训练成了你的团队协作者。
system_prompt = """ 你是一名严谨的软件工程师。请始终使用简体中文回复。 所有生成的代码必须附带完整的单元测试。 代码必须通过 eslint 检查，不允许出现 any 类型。 """这样配置之后，Codex 每次回答都会主动遵守这些规则，省去了反复交代的麻烦。另外，如果你手头有多个项目、每个项目要求不同，Codex 支持在工作目录下放独立的配置文件，用项目级配置覆盖全局配置。这个设计非常实用，比如一个项目要求全英文注释，另一个项目要求中文注释，每个项目单独维护一份配置即可。
5. Windows 常见报错与排查实录
5.1 登录不上、无法加载组织设置的完整排查流程
登录问题是 Windows 用户遇到频率最高的坑。我整理了一套固定的排查顺序，按这个流程走，基本能覆盖九成问题。
第一步，检查系统时间。Windows 系统时间如果出现偏差，TLS 证书校验会失败，表现就是 Codex 请求服务端时反复超时或报错。右键任务栏时间，选择“调整日期和时间”，打开“自动设置时间”。这一步很多人会忽略，但它真的是最常见的原因之一。
第二步，清理本地认证缓存。删除%USERPROFILE%\.codex目录下的 auth.json（如果目录里有其他配置想保留，就只删认证文件），然后重新运行codex触发登录。
第三步，确认账号权限。Codex 登录对账号类型有要求，普通免费账号不一定能正常使用。回浏览器确认账号是否有对应功能权限，以及是否处于正常登录状态。
第四步，检查网络连通性。用浏览器或其他工具访问 Codex 服务端域名，确认当前网络环境可以正常连接。如果这一步就不通，说明问题不在配置层面，先把网络环境搞定再继续。
5.2 “local proxy failed”与请求失败类错误的排查要点
Windows 环境下，Codex 使用过程中可能出现类似cc switch local proxy failed while handling codex endpoint /responses的错误，这类报错信息本身就很有指向性：Codex 在处理请求时，本地某个环节的转发或握手失败了。
我遇到这类问题时的排查思路是：先确认本机能否直接访问 Codex 服务端域名。能访问，说明问题出在本地程序干扰或端口占用上，查看一下是否有其他程序占用了 Codex 默认使用的本地端口，有的话重启 Codex 或关闭冲突程序；不能访问，说明网络环境有问题，这是前提条件，配置层面无法解决。
还有一个 Windows 特有的干扰源：防火墙拦截。Windows Defender 防火墙有时会拦截新安装程序的出站请求，弹窗时如果误点了“取消”，后续请求就会一直失败。解决办法是打开“Windows 安全中心”，在“防火墙和网络保护”里找到“允许应用通过防火墙”，确认 Codex 对应的 Node.js 进程被允许在专用和公用网络上通信。
5.3 管理员终端启动报错：必须从非提权终端运行
Windows 上有个很反直觉的坑：用管理员身份打开 PowerShell 后运行 Codex，反而可能启动失败，报错提示和 “start the windows daemon from a non-elevated terminal” 类似。意思是 Codex 的守护进程模式要求从非管理员终端启动，提权终端反而会引发权限冲突。
这个问题的本质是 Windows 的 UAC（用户账户控制）机制：管理员终端和普通用户终端的令牌权限不同，Codex 在启动共享客户端时如果检测到提权环境，会直接拒绝启动。解决办法很简单：关掉管理员终端，打开普通用户身份的 PowerShell 或 Windows Terminal，再运行codex。
这个小知识点其实也提醒了一个 Windows 使用习惯：日常开发不要动不动就用管理员终端运行命令行工具，很多工具在提权环境下行为会变得不可预期。普通用户终端跑 Codex，不仅报错少，权限控制也更合理。
5.4 其他高频问题速查表
我把 Windows 下常见的其他问题整理成了一张表，方便对号入座。
| 报错或现象 | 常见原因 | 解决方法 |
|---|---|---|
| codex 命令找不到 | 全局 npm 目录不在 PATH | 用npm config get prefix查路径，手动加入用户 PATH |
| npm 安装速度极慢 | npm 默认源网络延迟高 | npm config set registry https://registry.npmmirror.com |
| 运行 codex 提示禁止脚本 | PowerShell 执行策略为 Restricted | Set-ExecutionPolicy RemoteSigned -Scope CurrentUser |
| 代码输出中文乱码 | 终端编码不支持 UTF-8 | 使用 Windows Terminal，或设置chcp 65001 |
| 模型切换后提示 404 | base_url 或模型名不匹配 | 检查 model_providers 的 base_url 和 model 名称是否与服务商文档一致 |
| 端口被占用导致请求失败 | 其他程序占用了 Codex 本地端口 | 用 `netstat -ano |
这张表里的问题都有一个共同特点：它们都不是 Codex 自身的问题，而是 Windows 环境细节没对齐。很多人卡住之后第一反应是重装 Codex，其实先按这张表排查一遍，大概率能省下大把时间。
我在实际配置 Codex 的过程中，最大的体会是“先理清依赖链再动手”。Windows 上配置开源工具，本质就是一条依赖链的打通：Node.js 通了，npm 就通；npm 通了，Codex 就能装上；登录通了，配置文件才有意义。每一步踩的坑，几乎都是上一步环境没到位的结果。
给新手一个实用建议：第一次配置，先老老实实用默认模型跑通一个完整任务，再折腾第三方模型和自定义系统提示词。给老手的建议是：把 config.toml 当作团队资产来维护，系统提示词里写清楚代码规范，配合项目级独立配置，Codex 才能真正变成符合团队风格的高效协作者。配置这个东西，不怕花时间研究，就怕每次重装系统后重新踩一遍同样的坑。把这篇教程收藏起来，下次再遇到问题，直接照着排查表处理就行。
