上个月在 Windows 上折腾 Codex CLIOpenAI 的终端编程助手从装 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 BashCodex 在 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 CLInpm 全局安装与基础验证准备工作做好后安装本身其实只有一条命令但 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 源的问题可以切换到国内镜像源比如 npmmirrornpm 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模型供应商是 OpenAIAPI 基地址是官方地址密钥从环境变量 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建议按顺序一步步来不要跳过环境验证直接装工具。卡住的时候先看报错关键词再对照上面的排查思路大部分的坑都能自己填平。最后再分享一个小技巧把常用模型供应商配置保存成一个模板文件放到固定位置以后换机器直接复制过去再补齐环境变量就能复用十分钟恢复到完整开发状态。