如果你最近在 Windows 上折腾 Codex大概率见过一类以 cc switch local 开头的英文报错后面还跟着 handling codex endpoint /responses 这种描述。我头一次在 PowerShell 里撞见这段提示时第一反应是把 config.toml 翻来覆去改了好几遍折腾到半夜才发现问题根本不在 Codex 的配置而是这台 Windows 机器本地的端口和服务状态。这次我把整个配置流程完整重走了一遍顺手把过程里踩过的坑全部记下来就有了这篇 Windows 版配置教程。这篇内容不对着安装包截图做步骤教学因为 Codex 的核心是一条 CLI 工具链。我会先讲清楚它到底有哪几种形态、Windows 上该走哪条安装路径然后逐步处理三个闭环环境准备、安装与登录、配置文件与模型接入最后把 Windows 上高频报错的定位思路交代完。适合的人是想在 Windows 上用 Codex 写代码的开发者、被各种搜索关键词绕晕的新手以及那些已经把软件装了一堆却依然跑不起来的人。很多人搜 Codex 教程时会同时看到 mysql 安装配置教程、git 安装及配置教程、tomcat 安装及配置教程、zotero 安装与配置教程这类关键词不是说它们完全无关而是搜索引擎很容易把配置教程当成一个宽泛主题。这篇文章的意义就是把乱线头理成一条主线你真正需要的只有 Node.js、Git、一个终端以及 Codex 本身的几条命令。1. 为什么网上那么多 Codex 教程Windows 用户还是会卡在前面1.1 Codex 到底有几种形态先分清你在讲哪一个Codex 这个名字在不同产品语境里出现过好几轮。这里先对齐我讲的 Codex指的是 OpenAI 的 AI 编程助手产品系列它至少有三个形态——ChatGPT 网页和桌面端里的 Codex 面板、以命令行形式存在的 Codex CLI、以及以 API 形式暴露给开发者接口的编程能力。Windows 上大家说配置 Codex绝大多数情况是在把 Codex CLI 跑起来。CLI 与网页端的使用体验差异很大网页端点两下鼠标就能对话CLI 则要求你在终端里完成登录、管理配置文件、理解环境变量。这个差异导致了一部分人的困惑他们以为 CLI 也像网页一样有个设置中心找不到之后就去乱改配置。所以在动手之前先把目标明确如果你只想在网页里体验那安装章节可以跳过登录方式倒是可以参考如果你希望有一个在终端里随叫随到的编程助手下面每条命令都值得认真看。1.2 被全家桶教程带偏的安装路径我在整理 Windows 机器时也搜过相关教程结果首页上经常混着一大串不相干的软件安装教程mysql 安装配置教程、git 安装及配置教程、tomcat 安装及配置教程、zotero 安装与配置教程……不能说它们完全没价值但对于只想装 Codex 的人来说这种搜索结果特别容易让人跑偏。有人一路装到晚上电脑里多了好几个服务Codex 依然跑不起来问题就出在把别人教程里的步骤全都照做了一遍。真实情况是Windows 上装 Codex CLI硬性前置条件只有两个——一个可用且较新的 Node.js以及一个能正常跑命令的现代终端。Git 不是严格必需但强烈建议装原因后面会说。其他软件绝大多数跟 Codex 没有关系装多了反而容易埋下端口、环境变量、服务冲突的隐患。1.3 我建议的路径原生 Windows 安装先不动 WSL社区里不少教程推荐 Windows 用户先装一个 WSL 子系统理由是 Codex 早期设计更偏 Linux 环境。这套路径对本来就用 Ubuntu 工作流的人没问题但如果你只是普通开发、不想折腾子系统的文件路径、磁盘挂载和权限问题那完全可以直接走原生 Windows 路线PowerShell npm 全局安装。网上那些ubuntu 24.04 lts 配置教程windows 子系统关键词其实就是另一条路线不是 Windows 上配置 Codex 的必要动作。我在这篇里写的是原生路径命令全部在 PowerShell 里执行目录结构直观排查起来也简单。你未来想迁移到 WSL同样可以照葫芦画瓢只是换了个终端入口。2. 一条命令装好 Codex 之前先把 Node.js 和 Git 收拾干净2.1 Node.js 版本选择别装太老也别追 betaCodex CLI 是构建在 Node.js 生态上的工具。Windows 上最常见的安装失败原因不是网络问题、不是权限问题而是 Node 版本太旧。我有一次帮人排查Codex 启动直接抛了一堆模块语法错误最后发现系统里 Node 还停在 12.x距离当前主流版本隔了好几个大版本。建议下载 Node.js LTS 版本当前直接选 20 或 22 这条线。安装时一路默认即可唯一要注意的是安装向导里 Add to PATH 这个勾选默认是选中的别手滑关掉。装完之后开一个新的 PowerShell 窗口验证node -v npm -v两个命令都有版本号输出了Node 环境才算真正就绪。如果提示node 不是内部或外部命令说明 PATH 没生效要么重开终端要么手动把 Node 安装目录加进系统环境变量常见路径是 C:\Program Files\nodejs。npm 是随 Node 一起装好的包管理器Codex CLI 就是通过它来安装。如果 npm 下载速度慢可以在 ~/.npmrc 或命令行里临时切换国内 npm 镜像源。需要说明的是npm 镜像源只影响安装 Codex 这个动作本身不影响 Codex 运行时访问模型接口两件事不要混为一谈。2.2 Git for Windows看起来没用到实际上悄悄在帮忙装 Git 不是为了安装 Codex而是为了让 Codex 在项目里的体验完整。Codex 处理编程任务时会频繁读取当前代码仓库的信息检查当前分支、看一下 git diff、帮你生成 commit message、甚至在多文件改动时基于整个仓库上下文做决策。如果系统里没有 git这些能力会退化成我读不到仓库状态的半残状态。Git for Windows 安装时会问一个 PATH 选项一定选择从 Windows 命令提示符和 PowerShell 使用 Git这一项。我遇到过不少人装完 Git 后在 PowerShell 里跑 git --version 提示找不到命令原因就是当时选了仅从 Git Bash 使用 Git。装完后记得验证一下git --version这一步做完后面 Codex 处理真实项目时就不会再抱怨缺仓库信息了。另外也有个附加好处如果你哪天想手动备份 Codex 配置Git 也能帮上忙。2.3 终端选择PowerShell 够用Windows Terminal 更舒服Codex CLI 本身不挑终端但它的交互界面是一个全屏 TUI对终端渲染要求不低。Windows 自带的经典 cmd 窗口跑起来很粗糙特殊字符可能显示错位颜色也不对劲。我建议从 Microsoft Store 安装 Windows Terminal然后把默认终端配置成它能识别的 PowerShell这会直接影响后续使用体验。这一步纯粹是体验优化不装也不影响 Codex 能跑但你要跟这个 TUI 天天打交道窗口丑真的会影响心情。Windows Terminal 支持多标签、分屏、主题配置我习惯左边开一个项目终端右边开 Codex 会话写代码和查代码并行效率比来回切换高不少。3. 从装到登录Codex CLI 的安装全流程与两种认证方式3.1 安装命令、版本验证与首次运行前置干净之后安装 Codex 本身只有一条命令。打开 PowerShell执行npm install -g openai/codex全局安装的好处是任何目录下都能直接调用 codex 命令不需要进到特定工程目录。安装过程通常在一两分钟内完成如果网络波动导致下载失败可以把 npm 镜像源切换成国内镜像再重新执行一次。注意这只影响 npm 包的下载速度不影响 Codex 运行时的模型接口访问。装完先验证codex --version能显示版本号说明 CLI 已经进了系统 PATH。如果这里提示codex 不是内部或外部命令先重开终端再试还不行就检查 npm 全局包的安装路径是否在 PATH 中。Windows 下 npm 全局目录通常是 %APPDATA%\npm也就是 C:\Users\你的用户名\AppData\Roaming\npm。第一次运行 codex 时它会先检查配置和登录状态。还没登录的话会引导进入登录流程。这里有个小建议正式登录前先把终端窗口最大化因为 Codex 的 TUI 是全屏界面窗口太窄时排版会非常难受。运行 codex 后如果看到英文交互界面不要慌这正是它正常的首次启动姿态。3.2 两种认证方式别搞混Codex CLI 的认证有两条线很多教程把它们混在一起讲新手就容易乱。第一条是 ChatGPT 账号授权。在终端里运行codex loginCLI 会生成一个授权链接你需要在浏览器中打开、用 ChatGPT 账号确认授权。授权成功后凭证会写入本地 %USERPROFILE%.codex\auth.json 文件。这种方式能使用的额度主要跟在 ChatGPT 订阅里是否包含 Codex 访问权限有关适合已经订阅了相应套餐的用户。第二条是 API Key 方式。如果你不用 ChatGPT 网页订阅而是作为开发者走按量计费的 API 渠道那就去 OpenAI 开发者后台生成一个 API Key然后设置环境变量setx OPENAI_API_KEY sk-你的keyCLI 检测到这个环境变量后会自动切换到 API 计费模式。两种方式的差异简单讲就是一个类似包月套餐一个是按使用量付费。社区里那句Codex 是付费 ai 编程软件的说法其实指的就是这两种付费形态先想清楚自己走哪条线后面看日志时才不会一头雾水。3.3 登录不上与无法加载组织设置的排查Windows 上codex 登录不上是很典型的求助关键词。我实际排过的案例里大多数问题不在 Codex 本身而是下面三件事。第一系统时间偏差。Windows 开了快速启动后时间同步偶尔会滞后。登录时用的是 JWT 令牌对时间差非常敏感偏差超过几分钟服务端就会直接拒绝。解决办法是去设置里手动同步时间或者顺手关掉快速启动。第二登录缓存损坏。codex login 过程中断、auth.json 被其他工具改坏会导致后续请求 401。最直接的办法是退出登录或删除凭证文件codex logout如果不行就手动到 %USERPROFILE%.codex\ 目录把 auth.json 删掉重新执行 codex login。第三组织权限问题。我频繁看到的无法加载组织设置报错多发生在公司账号场景你的账号从属于某个组织但组织没有给成员开放 Codex 权限或者组织的 API 计费方式没有绑定就会反复出现这个提示。正确的处理方向是去开发者后台检查组织设置确认组织开通了对应访问权限如果只是个人做实验选个人组织就行不要挂在一个权限不完整的组织下面。4. config.toml 逐项解读配置文件里藏着哪些可用选项4.1 配置文件的位置与格式陷阱Codex CLI 的配置集中在用户主目录下的隐藏文件夹C:\Users\你的用户名.codex\。里面有两个关键文件config.toml 和 auth.json。前者是配置项后者是登录凭证直白说就是一个管怎么设置一个管我是谁。千万别把凭证文件当成配置文件去编辑。首次安装后config.toml 可能不存在也可能只有非常简单的几行。没有关系你可以用记事本新建一个。这里有一个 Windows 特有的坑记事本默认保存会带 BOM某些版本的 CLI 在读取配置时可能解析出错。如果你改了配置但它像没生效一样优先检查文件的编码是不是 UTF-8 无 BOM。用 Visual Studio Code 或 Notepad 重存一次通常就能解决。4.2 最常用的几个字段配置文件的逻辑其实很直白告诉 CLI 默认用哪个模型、模型走哪个提供方的接口、密钥从哪个环境变量取。下面是一个可用的基础示例model gpt-5-codex model_provider openai theme dark [model_providers.openai] name OpenAI base_url https://api.openai.com/v1 env_key OPENAI_API_KEYmodel 是默认模型名这个值会随官方版本迭代调整不需要死记。运行 codex --help 或者进入对话后使用斜杠命令都可以看到当前可用的候选模型。model_provider 指定走哪条接口通道默认是 openai。theme 控制 TUI 明暗主题纯体验选项。env_key 告诉 CLI 去读取哪个环境变量作为密钥它把密钥和代码配置分开管理避免把 Key 直接写死在文件里。对入门用户来说不理解这些字段也不影响最基础的登录和对话。但一旦你想接入第三方模型问题就会绕回到这几行配置上所以早点理解是值得的。4.3 让 Codex 说中文的正确做法codex 怎么设置成中文是个高频搜索词。我直接说结论Codex CLI 目前没有一个独立的界面语言开关你不需要去配置里找 locale 之类的字段乱加不存在的字段反而会导致配置解析报错。真正决定你看到中文还是英文的是模型在对话中的输出语言。所以最直接的办法是会话开始后第一句话明确说请用中文回复我所有内容保持简体中文。如果你希望每次打开 Codex 都自动用中文可以把这句话固定成你的开场方式。模型对用户语言偏好的记忆在同一个会话内是很稳定的日常使用完全够。4.4 用 DEBUG 模式快速判断配置是否被正确读取改完配置不确定是否生效时我会直接跑codex --debug加了 --debug 之后CLI 会在启动时把读取到的配置、选择的模型、登录态、当前请求的端点等信息打印出来。你在 Windows 上改完 config.toml想验证 model 和 model_provider 是不是已被正确读取这是最靠谱的方式。比看网上那些改完重启就行的帖子有效得多日志里写的才是事实。5. Windows 上接入 DeepSeek 等兼容模型到底改什么5.1 为什么可以换模型Codex CLI 值得在 Windows 上配置其中一个重要原因是它的模型提供方机制设计得很开放。它并不会把模型请求写死到唯一的官方端点而是通过 [model_providers.xxx] 区块定义一系列接口通道。只要某个服务提供了与 OpenAI 兼容的接口你就能在配置里声明一个新的 provider并把 CLI 的请求转发过去。这意味着你留住了 Codex CLI 的交互体验——全屏 TUI、会话管理、文件读写、工具调用——同时可以根据场景切换不同的模型后端。对 Windows 用户来说这尤其实用因为不是每个场景下都方便直连官方接口。很多人问codex 国内能用吗我的回答是如果你的网络能正常访问目标服务官方端点当然可以用如果访问不方便那就走兼容端点方案接 DeepSeek 这类国内服务不仅合规还是社区里非常成熟的做法。5.2 一个可以直接抄的 DeepSeek 接入配置以 DeepSeek 为例完整配置分两步先在 config.toml 里声明 provider再在环境变量里放入密钥。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然后设置对应的环境变量setx DEEPSEEK_API_KEY sk-你的key保存配置、设置完环境变量后务必新开一个终端窗口再启动 codex。如果当前终端是 setx 之前打开的环境变量不会自动加载启动后就会一直报缺 Key 的错误。这是 Windows 上被问最多的问题之一改了变量但没生效。这里有个容易踩的小细节DeepSeek 兼容接口的 base_url官方文档有时写 https://api.deepseek.com有时写带 /v1 的形式。差一个 /v1某些 SD K 的路径拼接就会完全不一样导致 404 或者路由异常。我习惯统一写成带 /v1 的形式并在改动后用 codex --debug 启动一次看请求端点是否确实指向了预期地址。如果还是连不通就去查服务商最新的兼容接入文档不要死磕旧帖子里的地址。5.3 在对话里临时切换模型提供方如果不想把全局默认模型改成 DeepSeek也可以只在特定会话里用。启动 Codex 时带参数覆盖就行codex --model-provider deepseek --model deepseek-chat这种方式适合平常默认用官方模型需要切换场景时临时用兼容端点的工作流。我的 Windows 配置就是这么组织的config.toml 里保留官方 openai 作为默认值但在 [model_providers] 区块里同时注册好 DeepSeek 的入口需要时用参数临时覆盖不需要纠结全局默认。5.4 接入其他 OpenAI 兼容服务的通用判断标准除了 DeepSeek国内还有其他提供 OpenAI 兼容接口的模型服务。判断一个服务能不能接到 Codex看三点第一是否提供 OpenAI 兼容的 chat completions 风格接口第二是否允许自定义 base_url第三是否支持环境变量传入密钥。三点都满足基本就能按上面的模板改一个 provider。具体到每个服务模型名、base_url 路径、密钥名都可能不同配置时以服务商最新的官方文档为准。我在这个环节上唯一的建议是先在 codex --debug 里确认 provider 被正确加载再谈下一步的报错否则容易把服务商接口变更误判成自己配置错误。6. 高频报错的定位方法从登录失败到对话接口无响应6.1 cc switch local 这类报错先检查本地环境而不是 Codex如果你在搜索时见过一条以 cc switch local 开头的报错后半段是 handling codex endpoint /responses 之类的描述我先给结论这大概率不是 Codex 配置文件的问题而是请求在到达目标接口之前被本机的某个环节拦了一下。我在这台 Windows 机器上复现过接近的现象最后定位到的原因是本机同时跑了好几个网络相关工具它们都试图监听或管理本地接口流量结果 Codex 发出的请求找不到一个稳定的出口。排查顺序是这样的先退出所有开机自启的、跟网络接管相关的后台工具再重开终端跑 codex 随便问一句如果恢复了就一个个把刚才退出的工具打开找到那个和 CLI 起冲突的元凶。Windows 上这类问题的共性在于本地网络状态的多主而不在于 Codex 本身别一上来就把 config.toml 删了重写。6.2 环境变量没生效和密钥读取失败Windows 配置环境变量后经常出现一种让人抓狂的情况setx 明明写进去了Codex 却一直报缺密钥。原因很简单setx 写入的是持久化环境变量但已经打开的终端不会读取新值。你需要新开一个终端窗口甚至注销重登一次新值才会进入进程环境。新开终端后如果还是不行可以用下面这条命令验证当前进程里到底有没有这个变量echo $env:DEEPSEEK_API_KEY没有输出就说明变量没有进入当前进程。此时再检查一下你是否在 PowerShell profile$PROFILE里覆盖过同名变量这种局部覆盖会把系统值顶掉。我遇到过一个人系统变量和 profile 变量分别指向两个不同的 Key结果 CLI 读到的始终是 profile 里那个失效的 Key排查到这一步才真相大白。6.3 我这台机器的完整排错顺序把 Windows 上 Codex 从装不上到跑不稳的全过程复盘之后我给自己定了一个固定的排错顺序现在也分享给同样踩坑的人。第一步验证基础环境node -v git --version npm -v三个命令都有正常输出才有资格把问题归结到 Codex 头上。第二步检查登录状态auth.json 是否存在、系统时间是否正确同步。第三步检查配置解析config.toml 是否存在、格式是否正确、编码是否为 UTF-8 无 BOM。第四步才轮到网络层本地是否有端口占用、是否有需要退出的后台工具。这个顺序恰好是大多数人踩坑路径的反面。很多人一看到报错就改配置、换模型、重装 CLI结果前面几步的小问题压根没解决。Codex 在 Windows 上的配置真没有想象中复杂按顺序排查绝大多数问题能在十分钟内定位。6.4 我的个人使用习惯最后聊点使用层面的东西。命令行工具折腾顺之后剩下的就是每天的磨合了。我在 Windows 上跑 Codex 一段时间后的习惯是在 Windows Terminal 里把它放到右侧分屏左侧留着写代码的终端。Codex 支持在单个会话里连续追问所以我通常把一天的需求都沉淀在同一个会话里让模型保持上下文连续而不是频繁新建会话导致每次都从零开始。配置层面我保持极简主义config.toml 里只有默认模型、一个 provider 区块和主题设置其他一切从简。因为配置越多排查面越广而 Codex 的核心价值在于编程任务本身不在于把配置文件玩出花。这篇教程能帮你把 Windows 上的坑填平剩下的就是多跑几个真实项目慢慢摸清它的脾气。