上个月在 Windows 上折腾 Codex CLI（OpenAI 的终端编程助手），从装 Node.js 到登录账号，再到手动改 config.toml 配模型供应商，前前后后踩了不少坑。趁着热乎劲把这套完整的 Windows 配置流程整理出来，覆盖 Node.js 环境准备、npm 全局安装、两种登录方式的区别、config.toml 逐项解析、常见报错排查，以及配好之后怎么把它真正用起来。这篇教程适合两类人：一类是第一次接触 Codex、想在自己电脑上快速跑通的人；另一类是已经装过但被各种网络报错、权限问题、配置混乱搞到想放弃的。我会尽量把每一步背后的逻辑讲清楚，而不是只甩几条命令让你复制。
1. Codex 到底是什么，为什么要在 Windows 上配它
Codex CLI 是 OpenAI 推出的命令行编程代理。说白了，它是一个跑在终端里的 AI 开发助手，你用自然语言描述需求，它会自动读取项目文件、生成代码、执行命令、甚至帮你提交版本记录。跟 ChatGPT 网页版、IDE 插件最大的不同是，它活在终端里，不依赖任何特定编辑器。这意味着 Linux、macOS、Windows 都能跑，也意味着你可以把它塞进自己习惯的任何工作流，哪怕是纯命令行环境也能用。
好多人容易把 Codex 和 GitHub Copilot 当成一类东西，其实两者的侧重点完全不同。Copilot 的核心是代码补全：你写一行，它接三行，帮你把上下文里的规律延续下去。Codex 的核心是任务执行：你给它一个完整的需求描述，它自己去翻代码、定位问题、做修改、运行测试，然后给你结果。这个定位差异决定了它的配置和使用方式完全不同。它需要在本地保存会话状态、调用 shell 执行命令、管理模型供应商，所以在 Windows 上配置时会涉及环境变量、配置文件、权限策略这些环节，这也是这篇教程要重点覆盖的内容。
从实际体验来看，我觉得两类人最应该装 Codex：第一类是终端工作流比较重的开发者，习惯在命令行里搞定所有事情；第二类是经常在多台机器上开发的人，因为 Codex 的配置完全可以跟着环境走，一个 config.toml 备份过去就能复用。如果你平时只做轻量修改、不太想碰命令行，那可以等生态再成熟一点再考虑，没必要现在就折腾环境。
2. 前期准备：Windows 环境下先把三件事做对
动手装 Codex 之前，建议先把 Windows 侧的三样东西准备好：Node.js、一个能正常使用的终端、以及 OpenAI 账号与 API Key。这三样缺一样，后面都会以各种奇怪的报错形式提醒你，到时候再回头补反而更浪费时间。
2.1 Node.js 安装与环境变量检查
Codex CLI 通过 npm 分发，而 npm 又跟随 Node.js 一起安装，所以第一步是装 Node.js。直接去官网下载 LTS 版本安装包，一路点下一步就行。安装完成后需要确认 PATH 里已经包含 node 和 npm 的目录，否则在命令行里输入 npm 会提示“不是内部或外部命令”。
验证方法在 PowerShell 或 CMD 里执行：
node -v npm -v正常会输出类似 v20.x 和 10.x 的版本号，说明环境没问题。这里我建议装 LTS 而不是 Current 版本，因为很多原生模块在 Windows 下对 LTS 的兼容性更好，而且 Codex 官方文档也推荐 LTS。如果你电脑里之前装过旧版本 Node，建议先卸掉再装新版，避免版本残留导致 npm 全局路径混乱。
2.2 终端选择：Windows Terminal 优先
Windows 下跑 Codex 建议使用 Windows Terminal，而不是系统自带的旧版控制台窗口。原因很简单：Codex 的输出带颜色和交互式渲染，旧终端对 ANSI 转义序列支持不好，经常出现乱码和排版错乱。Windows Terminal 在 Microsoft Store 里就能直接安装，装好后默认 shell 切成 PowerShell 7 或系统自带的 PowerShell 5.1 都行。
有个细节比较容易忽略：终端编码。如果后面命令行里出现中文乱码，大概率是编码问题。在 Windows Terminal 的设置里，把配置文件默认编码调整为 UTF-8，同时注意不要在系统区域设置里勾选“使用 Beta 版 Unicode UTF-8 提供全球语言支持”，这个选项会带来一堆旧软件兼容问题，属于典型的“治标不治本”。另外，如果你平时用 Git Bash 比较多，也可以把 Windows Terminal 的默认 shell 指到 Git Bash，Codex 在 Git Bash 里跑得也很顺畅。
2.3 OpenAI 账号与 API Key 的区别
配置 Codex 前先明确账号和 Key 的区别，这一步很多人一开始没搞懂，后面就卡在鉴权上。Codex CLI 支持两种鉴权方式：一种是 ChatGPT 账号登录，走 OAuth 授权流程，适合订阅了 ChatGPT Plus 或 Pro 的服务用户；另一种是 API Key，按 token 量计费，适合有 API 调用需求的开发者。如果你只是想本地体验 Codex，优先用 ChatGPT 账号登录，流程更顺；如果要做自动化脚本或大批量调用，建议用 API Key。
这个区分很重要，因为后面 config.toml 里有些配置跟着鉴权方式走。比如把模型供应商切到第三方服务时，基本只能走 API Key 模式，这个在第五章展开讲。我的建议是：先想清楚自己属于哪种使用场景，再决定登录方式，不要两种都配，否则排查问题时会多一个变量。
3. 安装 Codex CLI：npm 全局安装与基础验证
准备工作做好后，安装本身其实只有一条命令，但 Windows 下有几个衍生问题值得单独说。
3.1 全局安装命令
打开 PowerShell，建议以普通用户身份打开，不要用管理员模式，然后执行：
npm install -g @openai/codex安装完成后验证一下：
codex --version如果能输出类似 0.x.y 的版本号，就说明装好了。这里有一个 Windows 下非常常见的坑：npm 的全局 bin 目录不在 PATH 里。npm 默认把全局可执行文件放在C:\Users\<你的用户名>\AppData\Roaming\npm，如果系统 PATH 没有包含这个路径，命令行就会提示找不到 codex 命令。解决办法是把该目录手动加进环境变量的 PATH，然后重新打开终端。注意加完 PATH 之后一定要重开终端，让它重新读取环境变量，在同一个窗口里等是等不出来的。
3.2 安装后的目录结构
Codex 安装成功后，第一次运行会在用户目录下生成.codex文件夹，也就是C:\Users\<你的用户名>\.codex。这个文件夹里保存运行所需的核心数据，包含 config.toml 配置文件、log 日志目录、sessions 会话历史。第一次运行命令后才会真正创建这些目录，如果你提前去找可能会扑空。理解这个目录结构对排查问题很有帮助，比如遇到配置不生效的情况，优先检查 config.toml 是否真的放在这个路径下。
3.3 npm 安装报错与源的选择
安装阶段最容易卡住的就是 npm 报错。常见问题集中在三处：权限不足、下载源连接不稳定、Node.js 版本过旧。Windows 下如果报 EPERM 或权限相关错误，先确认全局目录是否可写，必要时手动修改 npm 目录的权限。如果报网络相关错误，多半是 npm 源的问题，可以切换到国内镜像源，比如 npmmirror：
npm config set registry https://registry.npmmirror.com切换之后如果还报错，执行一次npm cache clean --force再重试。给新手提个醒：npm 安装失败时不要反复重装赌运气，先看报错关键词，再决定是清理缓存、换源、还是升级 Node.js，大部分问题三选一就能解决。
4. 登录与鉴权配置：两种方式逐项对照
Codex 的登录流程在 Windows 下有一个容易踩坑的点：它默认尝试打开浏览器做授权，如果浏览器没弹出来，整个流程就会卡住。下面分别说两种方式。
4.1 ChatGPT 账号登录方式
在终端执行：
codex login正常情况下会弹出浏览器，让你完成授权。授权成功后终端会打印登录成功的提示。如果在 Windows 下浏览器没有自动弹出，先看终端里有没有打印授权链接，有的话手动复制到浏览器访问即可。授权完成后，Codex 会在.codex目录下保存凭据，之后运行会自动检测登录状态。哪天提示需要重新登录，再执行一次 codex login 就行，不用翻文档。
这里有一个小细节：Windows 下授权回跳可能会失败，浏览器提示无法打开本地地址。遇到这种情况，检查默认浏览器是否支持自定义协议回跳。Chrome 和 Edge 都没问题，但某些严格模式的浏览器或安全软件会拦截本地回跳，这时候临时换默认浏览器再试一次往往能解决。
4.2 API Key 鉴权方式
API Key 的配置更轻量，不需要走 OAuth。可以直接在终端里临时设置环境变量：
$env:OPENAI_API_KEY = "sk-你的key"也可以写入系统环境变量，这样以后每次开终端自动生效。注意 API Key 是按量计费的，日常体验时要格外注意用量，不要让 Codex 在循环场景里跑出高额账单。写入环境变量后，同样需要重开终端才能生效。
4.3 两种方式如何选
一句话总结：有 ChatGPT 订阅，走 codex login；有 API 使用场景，走 Key。Codex 运行时会优先读取 config.toml 里配置模型的凭据来源，如果同时配了两种，配置文件里的优先级更高。我个人建议只配一种，配两种反而会在排查问题时多一个变量。登录相关的配置不要提交到版本库里，尤其 API Key 属于敏感信息，务必做好隔离。
5. config.toml 核心配置解析
这是整个教程最值得细看的部分。Codex 的很多行为都通过C:\Users\<你的用户名>\.codex\config.toml控制，不理解它，遇到问题只能瞎猜。
5.1 配置文件位置与基本结构
如果该文件不存在，先手动创建一个。基本结构是 TOML 格式，由若干个配置段组成，常见的有 model、model_provider、model_providers、permission 等。下面是一个最小可运行的示例：
model = "gpt-5-codex-mini" [model_providers.openai] name = "OpenAI" base_url = "https://api.openai.com/v1" env_key = "OPENAI_API_KEY"这段配置的意思是：默认模型用 gpt-5-codex-mini，模型供应商是 OpenAI，API 基地址是官方地址，密钥从环境变量 OPENAI_API_KEY 读取。如果你走 ChatGPT 账号登录，这段配置其实可以不写，直接 codex login 就行。写出来的好处是配置一目了然，后续要切其他模型供应商时不容易乱。
5.2 模型选择逻辑
Codex CLI 的模型参数既可以通过命令行临时指定，也可以写在 config.toml 里统一控制。命令行支持类似codex exec -m 模型名的方式临时覆盖。Windows 下把最常用的模型写进配置文件是最省事的，省得每次敲一长串。模型 ID 会随着版本迭代变化，建议在登录后的终端里执行 codex 帮助命令查看当前可用模型，别把网上的老教程内容直接复制过来用。
5.3 接入其他 OpenAI 兼容服务（以 DeepSeek 为例）
除了 OpenAI 官方模型，Codex CLI 也支持配置第三方兼容服务，只要目标服务提供 OpenAI 兼容的 API 端点。这里以 DeepSeek 为例，在 config.toml 末尾追加：
[model_providers.deepseek] name = "DeepSeek" base_url = "https://api.deepseek.com/v1" env_key = "DEEPSEEK_API_KEY"然后在文件顶部把 model 改成对应的模型标识，比如：
model = "deepseek-chat" model_provider = "deepseek"配置完成后，Codex 会把请求发往 DeepSeek 的 API，密钥从环境变量 DEEPSEEK_API_KEY 读取。注意模型标识要以服务商实际支持的为准，不同服务商的命名差异很大，直接照搬其他服务的配置必然翻车。切换供应商之前，先确认目标 API 服务能正常访问，别在 Codex 里排查半天，最后发现是网络根本连不通。DeepSeek 这类服务目前提供 deepseek-chat 和 deepseek-reasoner 两个模型标识，具体以官方文档为准。
5.4 其他常用配置项
- model_provider：指定当前使用的模型供应商名称，配合 model 使用。
- model_providers：注册一个或多个自定义供应商。
- permission：控制 Codex 自动执行命令的权限范围，建议先设置为 ask，让它在执行敏感操作前征求你的同意。
- approval_policy：命令批准策略，常见有 unedited、on_request、never。
- enable_output_parsing：控制工具调用的输出解析，一般保持默认即可。
这些配置项很多都有默认值，不建议一开始全部改掉。我的经验是从最小配置跑通，再按需增加，千万别一上来就抄一份网上很复杂的配置，出了问题根本不知道改了哪里。
5.5 配置文件备份与多机同步
Windows 下换机器重配 Codex 是一件很烦的事。好在 config.toml 是纯文本，把整个.codex目录下的 config.toml 备份下来，换机器后放到相同位置就能复用。注意不要备份 sessions 和 log 目录，那是本机运行产生的临时数据，直接丢弃即可。如果你在多个项目里使用不同的厂商配置，也可以将 config.toml 按场景拆成多份模板，配合环境变量切换使用。
6. 在 Windows 终端里跑 Codex：实测场景与操作细节
配置完，总要真正跑起来才知道有没有配对。
6.1 第一次对话实验
建议第一次用一个不涉及敏感信息的简单项目做测试，比如在某个临时目录里让 Codex 创建一个 Python 脚本。先进入临时目录，再执行：
codex进入交互界面后输入：“在当前目录创建一个 hello.py，输出当前时间”。如果模型配置正确，你会看到它先读取目录内容，然后创建文件，最后打印执行结果。第一次运行时会有权限确认流程，Codex 在创建文件或执行命令前会询问你是否允许，这是它在申请执行权限。选择允许或拒绝会直接影响后续行为，建议首次全部选择允许，跑通整个流程之后再收紧权限策略。
6.2 交互模式与自动执行模式
Codex 支持交互模式和在非交互状态下执行的自动模式。交互模式下你直接在终端连续对话，边看输出边调整需求，适合日常改项目。自动模式则适合明确知道要做什么的场景，比如：
codex exec "把当前目录下所有 .js 文件中的 console.log 替换为标准日志输出"这个命令会在非交互状态下发起请求，跑完退出。自动模式很适合集成到 CI 脚本里，也适合做批量代码处理任务。如果你是第一次用，建议先体验交互模式，等熟悉了 Codex 的行为边界后再尝试自动模式。
6.3 Windows 下的终端权限与路径问题
Windows 下运行 Codex 时，如果项目路径包含中文或空格，建议给路径加引号，否则路径解析容易出错。另外，Codex 执行命令时可能调用 PowerShell 脚本，如果遇到“无法加载脚本”类报错，检查终端执行策略。不一定需要管理员权限，把当前用户的执行策略改成 RemoteSigned 通常就能解决：
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned改完之后重开终端再试。如果你同时在使用 VS Code 做 C/C++ 开发，完全不冲突，Codex 不依赖编辑器，你现有的 VS Code 环境可以原样保留。
7. Windows 下常见问题与排查实录
最后这部分是重头戏，挑几个我在 Windows 下实际遇到或帮别人排查过的高频问题，按排查思路写出来。
7.1 登录不上、组织设置加载失败
这个问题的表现是 codex login 打开浏览器授权后一直转圈，或者提示无法加载组织设置。我排查过的案例里，最常见的原因是系统时间不同步，导致授权校验失败。Windows 下解决办法是手动同步系统时间并开启自动同步，然后重新登录。如果时间没问题，再看账号本身是否有有效的订阅或 API 权限。
组织设置加载失败还有一个原因：账号关联了多个组织，Codex CLI 在拉取组织列表时超时。这种情况可以暂时不切换组织，用默认组织跑通流程后再考虑多组织需求。如果你发现组织列表里是空的，先确认自己在 OpenAI 平台上创建过组织，并且当前登录账号对该组织有访问权限。
7.2 连接类报错与网络环境排查
有些用户会看到响应端点处理失败类的提示，或者本地通信链路报错。这类报错表面上是本地通信问题，实际上往往和终端里残留的系统级网络管理工具、端口占用、防火墙规则有关。排查思路分三步：先关闭不必要的系统级网络管理类工具，比如某些流量监控软件或安全加固工具，然后重启终端，最后检查本机防火墙是否允许 node.exe 作为客户端访问外部网络。
可以用下面的命令做基础连通性测试：
Test-NetConnection api.openai.com -Port 443如果输出显示 TcpTestSucceeded 为 True，说明网络链路可以访问该地址；如果为 False，就需要检查本机网络配置或防火墙了。还有一个容易被忽略的点：终端里缓存了旧环境变量。遇到莫名奇妙的连接报错，先把终端完全退出重开一次，再做下面的排查，别一开始就朝复杂方向想。
7.3 终端乱码与中文显示问题
Codex 生成的代码里如果包含中文注释，Windows 旧终端经常显示成乱码。解决方法依然是使用 Windows Terminal，并确保终端配置里文本编码为 UTF-8。另外，如果你希望 Codex 用中文回复问题，最直接的方式是在对话开始时明确要求“请用中文回答”，不要指望 CLI 界面语言自动切换，因为它的帮助和日志目前没有官方中文版。
7.4 端口占用与进程清理
Windows 下偶尔会遇到端口被占用导致服务连接失败。定位方式很直接：
netstat -ano | findstr "端口号" taskkill /PID 进程ID /FCodex 默认使用的本地端口被其他服务占用时，优先重启终端再试。如果还是不行，把占用进程列表拉出来，确认不是关键系统进程后再结束它。这条经验同样适用于其他本地开发工具，值得记到笔记里常备。注意 taskkill 结束进程前一定要确认进程身份，不要误杀系统服务。
7.5 证书相关报错
API 调用时如果出现证书校验失败，常见原因是系统时间错误或本机安全软件做了流量解密。时间问题按 7.1 的方法修，本机安全软件的情况需要到安全软件里查看证书信任链，确认 Codex 进程是否在被监控的名单里。不要私自关闭证书校验功能，这是安全底线，一旦关闭等于把请求裸奔在网络上，风险不值得冒。
7.6 命令行脚本闪退问题
有朋友遇到过 Codex 相关命令在执行过程中终端直接闪退。排查下来大多是终端执行策略或终端插件冲突的问题。可以在普通 PowerShell 窗口里先跑一条简单的 codex 命令做对照，如果普通窗口正常而 Windows Terminal 闪退，说明问题出在终端配置或插件上，比如安装过的命令提示符工具发生了冲突。逐个禁用排查即可。
8. 配置完还能怎么玩：把 Codex 变成你的项目常驻助手
到这里，Codex 已经可以稳定运行了，但配置只是第一步，真正提升效率的是把它接入日常开发流程。
8.1 用提示词文件统一项目规范
在项目根目录放一个 AGENTS.md 文件，写明项目的结构约定、代码风格、常用命令、启动方式。Codex 在读取目录时会自动参考这个文件，相当于给每一次会话都注入了项目背景。这个文件比你每次对话重复描述需求省太多事了。Windows 下创建时注意编码用 UTF-8，避免中文内容在 CLI 里乱码。这个文件同样建议提交进版本库，方便团队协作时共享。
8.2 与 VS Code 等编辑器协作
Codex 不依赖编辑器，但你可以同时开着 VS Code 看改动。在 Windows 下，Codex 修改文件后，VS Code 会自动刷新文件变更。如果你的工作流是 Codex 改代码、你人工 review，这个搭配非常顺手。不需要装额外插件，也不存在环境冲突，两边各自独立工作。
8.3 会话管理
Codex 的会话历史保存在.codex/sessions目录。交互模式下运行 codex resume 可以从上次会话继续，命令细节以当前版本 help 为准。这个能力对长任务非常有用，比如跨天的排查任务不用从头描述一遍。如果长时间使用，建议定期清理旧会话，避免目录无限制增长占用磁盘空间。
我实际配完整个流程后最大的感受是：Codex 在 Windows 上并不是装不上，而是需要把环境细节提前治理好。Node.js 的 PATH、终端的执行策略、config.toml 的模型供应商，这三块理顺了，后面的使用体验和 Linux 下基本没区别。如果你也是 Windows 用户，刚开始折腾 Codex，建议按顺序一步步来，不要跳过环境验证直接装工具。卡住的时候先看报错关键词，再对照上面的排查思路，大部分的坑都能自己填平。最后再分享一个小技巧：把常用模型供应商配置保存成一个模板文件，放到固定位置，以后换机器直接复制过去，再补齐环境变量就能复用，十分钟恢复到完整开发状态。
