我一开始也以为 Codex 在 Windows 上的配置就是“下载安装包、双击下一步、打开就能用”。直到自己亲手装了一遍才发现真正卡人的不是安装本身而是安装完之后那一串莫名其妙的提示什么“Windows settings setup was not completed”、什么“start the windows daemon from a non-elevated terminal”、再就是控制台里刷出一段带/responses的路由报错。如果你也正准备在 Windows 上配置 Codex或者已经卡在半路这篇文章应该能帮你省下不少折腾时间。我会把 Windows 版从下载、安装、登录到常见的报错排查、再到现在很多人关心的接入第三方模型按实际操作的顺序完整过一遍最后再聊几个日常使用里容易忽略的细节。1. 装之前先搞明白Codex 在 Windows 上到底由哪几部分组成1.1 CLI、桌面版和插件三者的关系很多人一上来就搜索“Codex 安装包”结果发现官网给的东西和自己理解的不太一样。Codex 在 Windows 上并不是只有一个“绿色软件”它至少分成三层。最底层是Codex CLI这是一个跑在终端里的命令行工具负责跟模型后端通信、管理会话、执行代码。CLI 是核心后面要讲的所有配置、报错、模型切换基本都发生在这层。第二层是Codex 桌面版也就是带图形界面的 App它把 CLI 的能力包了一层 UI适合不想碰终端的人。第三层是IDE 插件比如 VS Code 里的扩展它本质上还是调用 CLI 的能力只是把对话界面嵌进了编辑器。这三者的关系用一个生活化的类比CLI 是发动机桌面版是轿车外壳IDE 插件是方向盘和仪表盘。你当然可以只开发动机纯终端使用但大多数人是从外壳开始接触的。Windows 上最容易出问题的点就在这里桌面版和 IDE 插件的登录状态、配置路径、后台进程全都跟 CLI 共享同一套配置。所以不管你是用桌面版还是插件最终都得先把 CLI 这一层弄清楚。1.2 Windows 环境的三个坑终端、权限、PATHWindows 配置 Codex 比 macOS 和 Linux 麻烦主要不是 Codex 本身的问题而是 Windows 的环境差异。第一个坑是终端。Codex 在交互模式下会用到 ANSI 转义序列、光标控制、历史命令回显Windows 自带的旧版cmd.exe对这些支持得并不好。建议直接用 Windows Terminal 或者 PowerShell 7不要用老掉牙的 Windows PowerShell 5.1更不要用 cmd。后面所有命令我都默认你在 Windows Terminal 的 PowerShell 标签页里执行。第二个坑是权限。Windows 喜欢“以管理员身份运行”但这个习惯在 Codex 这里恰恰是反的。Codex 会启动一个后台 daemon 进程来管理会话如果你在提权管理员终端里启动它随后再用普通权限的客户端去连接两边权限不一致就会看到那一句“start the windows daemon from a non-elevated terminal; shared clients”。这个我后面专门拆开讲但你现在先记住一条配置和运行 Codex全程不要用管理员权限。第三个坑是 PATH。无论你是用 npm 装 CLI还是用安装包装桌面版安装完成后已经打开的终端不会自动刷新 PATH。很多人的“装完打不开”“提示不是内部或外部命令”其实只是忘了重开终端。Windows 下刷新 PATH 最靠谱的办法就是关掉所有旧终端新开一个而不是在旧窗口里反复折腾。1.3 账号与网络的前提条件检查在动手之前先把前提条件过一遍避免后面排查半天发现是一开始就缺东西。一个可用的 OpenAI 账号并且能在官方页面正常登录。如果你是团队账号确认当前账号能访问对应的组织。系统方面Windows 10 版本号 1903 以上或 Windows 11 都行没有硬性版本要求但太老的 Windows 10 可能缺一些 TLS 组件。终端方面建议装 Windows TerminalPowerShell 7 属于加分项不装也能跑只是某些输出排版会丑一点。关于“Codex 国内能不能用”这个问题我直接说结论Codex 官方的登录和模型请求依赖 OpenAI 账号体系与官方 API 服务是否可用取决于你的账号类型和当前网络对官方域名的连通性这属于账号侧和网络侧的问题配置本身再对也没用。判断方法很简单PowerShell 里执行curl.exe -I https://api.openai.com如果这个请求超时或者连不上那不是 Codex 配置的问题问题在网络侧或账号侧。别去修改 Codex 配置硬刚先把连通性解决到能用官方域名的程度再回来继续。顺带一提如果你后续改用第三方兼容 API后面第四章会讲本质上是把请求从官方域名转到第三方域名这也是很多人绕开官方账号体系来本地使用 Codex 能力的原因。但需要注意这种方式只适用于通过 API Key 调用模型的场景Codex 桌面版的部分账户功能仍依赖官方登录。2. 从下载到登录Windows 版 Codex 的完整配置链路2.1 安装方式选择与安装验证Codex CLI 在 Windows 上安装主要有两条路npm 全局安装和官方编译好的二进制包。npm 方式最简单前提是你装了 Node.js 18 或更高版本。打开 PowerShell 执行npm install -g openai/codex装完验证codex --version如果你不想为 CLI 额外装 Node 环境也可以直接下载官方发布的 Windows 二进制包解压后把codex.exe所在目录加进 PATH。相比 npm二进制包对系统依赖更少升级时需要手动替换文件。提示安装完无论走哪条路都先重开一个终端再验证版本。如果你在旧终端里执行codex --version提示找不到命令先不要怀疑装坏了先考虑 PATH 有没有刷新。桌面版则是从官网下载 Windows 安装包双击运行按向导装完。桌面版安装过程本身没什么好说的真正值得注意的是它首次启动时的登录环节经常卡在“设置未完成”上这个放到第三章讲。2.2 CLI 初始化codex login 的全过程与常见卡点CLI 装好且版本号能正常输出之后第一步是登录。在 PowerShell 里直接执行codex login正常情况下CLI 会弹出一个浏览器窗口跳转到 OpenAI 账号授权页。你在网页上确认授权后CLI 终端会显示登录成功并把凭据写入用户目录下的配置文件里。有几个卡点我需要单独提一下。浏览器没有自动弹出。这种情况多出现在默认浏览器被系统策略锁定、或者终端的 URL 唤起逻辑异常时。CLI 通常会在终端里打印一个http://127.0.0.1...或者https://...的授权链接你手动复制这个链接贴到任何浏览器的地址栏打开即可不一定非要用默认浏览器。授权页面提示“设备确认”。某些登录模式下网页会显示一个验证码让你回终端确认注意看终端和浏览器两边的提示不要只盯着网页。登录耗时很长或者最终超时。授权回调是走本机回环地址的如果你的电脑上有安全软件拦截了本机回环端口授权流程会一直转圈。排查思路是临时退出安全软件、或者看看 Windows 防火墙是否拦截了 Node/Codex 进程的入站回环连接。登录成功后配置文件会生成在%USERPROFILE%\.codex\目录下。核心文件是config.toml里面存了模型配置还有auth.json存了登录凭据。这两个文件后续会频繁用到。2.3 桌面版与 CLI 的登录打通如果你下载的是桌面版首次启动会看到一个登录引导页。你可能会觉得“我已经在浏览器里登录过 OpenAI 了怎么这里还要登录”。没错桌面版的登录态是独立的它需要走一次跟 CLI 类似的授权流程。桌面版登录完成后有个细节建议检查一下打开桌面版的设置页看它是否能识别到 CLI 的登录状态。很多新版桌面版会直接复用%USERPROFILE%\.codex\auth.json里的凭据也就是说你先用 CLI 登录过桌面版启动后会自动读取。如果桌面版始终显示未登录可以先确认 CLI 登录是否成功再重启桌面版。反过来也一样桌面版登录成功后CLI 通常也能直接用了因为底层共享配置文件。注意如果你同时安装了 CLI 和桌面版尽量让两者版本保持一致。桌面版会自带一个 CLI 运行时如果版本不一致可能出现桌面版能跑、CLI 却提示配置不兼容的怪问题。2.4 初步可用性自检用一条简单命令验证登录之后不要着急上手复杂任务先跑一个最小请求验证整条链路通不通。codex exec 请用一句话介绍你自己或者英文也行codex exec Say hello in one sentence如果这条命令能正常返回内容说明 CLI 登录状态有效、模型接口连通、配置没有大问题。如果它报错优先看报错信息里有没有401凭据问题、403账号权限问题、429限流之类的状态码。我自己在实际操作中还有个习惯第一次跑通之后会再跑一条带文件读写的小任务比如codex exec 创建一个 hello.py 文件里面打印 hello world确认它能真正读写磁盘因为后面让它操作仓库时文件系统权限问题很常见。Windows 下如果你是从普通 PowerShell 启动的一般权限够用但如果你让它去写C:\Program Files这类受保护目录就会遇到拒绝访问。3. Windows 专属报错逐个拆解别再被“设置未完成”卡住3.1 桌面版提示“Windows settings setup was not completed”应该先查什么这个提示是 Windows 版用户反馈最多的问题之一。它字面意思是“Windows 设置流程没有完成”听起来像是安装包没装好实际上大部分情况根本和安装无关。我遇到的情况是安装完成后第一次启动桌面版弹出登录窗口我在里面输完账号密码界面卡了一下然后桌面版就显示设置未完成。后来排查发现问题出在桌面版首次启动时需要写%USERPROFILE%\.codex\下的配置文件而当时电脑上的某个安全软件把该目录的写入操作拦截了。所以遇到这个提示按顺序查三件事看%USERPROFILE%\.codex\目录是否存在且可写。可以直接在 PowerShell 里执行Test-Path $env:USERPROFILE\.codex如果不存在手动创建这个目录再重启桌面版。检查后台是否已经有残留的 codex 进程。安装新版本时旧进程会占用配置文件句柄导致新进程写入失败。打开任务管理器把所有含codex的进程结束掉再启动桌面版。检查终端相关设置是否完成。如果你之前打开过命令行工具并做过一些首选项设置而桌面版在初始化时会调用一个检测逻辑恰好这个逻辑在旧版本 cmd 的环境下无法正常完成。解决办法是先把默认终端模拟器改成 Windows Terminal再去启动桌面版。3.2 daemon 权限报错为什么要求“非提升终端”再看那个经典报错“error: start the windows daemon from a non-elevated terminal; shared clients”。很多 Windows 用户第一反应是“没有权限那我用管理员身份运行不就行了”这是完全搞反了。Codex 的 daemon 机制是这样的CLI 启动后会有一个后台守护进程负责读写会话状态、维护沙箱环境。这个 daemon 实例会绑定一个共享句柄供同一用户的其他 Codex 客户端连接。Windows 的权限模型里普通用户进程无法直接访问管理员进程创建的共享对象反过来管理员进程创建的共享对象普通用户客户端也连接不上。一旦你用“以管理员身份运行”启动了终端再在里面跑 Codexdaemon 就成了一个提权进程。然后你回到普通终端里再跑 Codex新的客户端去连这个 daemon 时就会收到上面那句“shared clients”的提示。解决方式很简单全部使用普通权限的终端启动 Codex不要在任何管理员终端里运行。如果已经出现了权限不匹配先把后台所有 codex 相关进程清掉再重新从普通终端启动。桌面版如果是以管理员身份安装的运行时也要确保“以管理员身份运行”这个选项没被勾选。右键桌面图标 → 属性 → 兼容性检查“以管理员身份运行此程序”是否是勾选状态如果是取消它。提示Windows 终端本身有个“以管理员身份运行”的快捷方式平时我建议普通编辑用普通标签确实需要管理员权限的操作另开一个提权窗口两个标签页各干各的避免混用。3.3 无法加载组织设置账号侧和本机侧怎么查“无法加载组织设置”这个提示我见过很多次一般在打开桌面版的设置页或者切换组织时出现。它本质上是一个客户端到官方组织接口的拉取失败不一定是配置错误。先分清楚是账号侧问题还是本机侧问题。账号侧登录 OpenAI 网页版确认你的账号在某个组织下并且该组织处于正常状态。个人账号也会有组织只是组织名叫“Personal”或类似的名字。如果你的账号本身没有组织归属Codex 桌面版当然加载不出来。本机侧Codex 客户端在加载组织设置时需要请求官方接口。如果当前网络访问官方域名不通或者安全软件拦截就会出现这个提示。可以先用curl.exe测目标域名的连通性思路和前面 1.3 一样。注意测试用的是curl.exe不是 PowerShell 里的curl别名。如果账号和网络都正常那大概率是配置缓存的锅。Windows 上 Codex 会在%USERPROFILE%\.codex\下缓存一些会话数据删掉缓存目录里除了auth.json和config.toml之外的可再生文件比如sessions、history这类子目录再重启 Codex 让它重新拉取。这个操作不会影响登录状态可以放心试。3.4 自定义接口路由报错/responses 端点是关键配置了第三方模型或者自定义接口后有些用户会在控制台里看到一段类似“switch ... failed while handling codex endpoint /responses. provider...”的报错。第一次看到时我也以为是自己电脑网络的问题后来才意识到它跟本地网络没关系。这段报错的本质是Codex 在切换或调用某个模型服务商时请求被路由到了该服务商的/responses端点但对方并没有正确支持这个端点。Codex 新版走的是 Responses API接口路径里带/responses而很多第三方兼容层只实现了传统的 chat completions 接口也就是说它们的 endpoint 不支持/responses。排查思路按下面几步走检查config.toml里配置的base_url是否写对了协议头和路径。第三方服务商的 OpenAI 兼容地址通常是https://api.xxx.com/v1不带结尾斜杠。确认该服务商是否声明支持 Codex 使用的 Responses 协议。如果对方只支持 chat completions就需要降级配置或者换一个明确兼容 Codex 的服务商。查看环境变量是否生效。config.toml里如果写了env_key DEEPSEEK_API_KEY那么对应的环境变量必须在启动 Codex 的终端里已经设置好。PowerShell 下设置临时环境变量用$env:DEEPSEEK_API_KEY sk-...保存到用户级别的用setx DEEPSEEK_API_KEY sk-...。最后把配置简化到只剩一个 provider排除多个 provider 同时存在时的切换冲突。如果简化后能跑通说明是多个 provider 定义之间互相干扰需要重新组织配置文件结构。4. 不依赖官方模型也能跑把 Codex 接到第三方兼容 API以 DeepSeek 为例4.1 为什么有人切换模型成本与可用性把 Codex 接第三方模型是最近中文社区里问得特别多的话题。原因无非两个一是官方模型的额度消耗快二是部分网络环境下官方接口的通路不稳定。于是很多人选择保留 Codex 的本地工作流但把模型请求转发到 DeepSeek 这类 OpenAI 兼容接口上。先说清楚一点Codex 这个工具的价值分成两层一层是对话模型本身一层是模型调用代码执行、读写文件、跑测试这些自动化能力。切换模型相当于只换发动机不换车身。你依然可以在本地让 Codex 创建文件、执行命令、迭代代码只是思考过程变成了第三方模型。这个方案适合谁适合已经有第三方 API Key、且接受功能差异的人。如果你是新用户还没搞明白 Codex 基础配置我建议先用官方模型跑通全流程再折腾切换否则出了问题你很难判断是配置问题还是模型能力差异。4.2 配置文件的核心逻辑model_providers 到底在配置什么Codex 的模型路由通过config.toml里的model_providers表控制。你要理解的不只是“填个 base_url”而是这整套映射逻辑。顶层有个model字段表示默认使用的模型名model_provider字段表示该模型归属哪个 provider。然后在[model_providers.xxx]表里定义这个 provider 的细节name是显示名称base_url是接口地址env_key是存放 API Key 的环境变量名。用生活化的类比model是你要点的菜名model_provider是选哪个餐厅base_url是餐厅地址env_key是进门用的会员卡放在了哪个抽屉里。Codex 每次请求会先看菜名再按餐厅地址找过去然后从指定抽屉里拿会员卡。所以切换模型的本质就是告诉 Codex以后别去原来的餐厅了去另一家同样卖兼容菜的餐厅。4.3 具体配置与验证以 DeepSeek 为例。DeepSeek 提供 OpenAI 兼容接口base_url 是https://api.deepseek.com/v1模型名是deepseek-chat或deepseek-reasoner。在 PowerShell 里设置 API Keysetx DEEPSEEK_API_KEY 你的key重开终端让环境变量生效。然后编辑%USERPROFILE%\.codex\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保存后新开终端执行codex exec 11等于几请直接输出结果如果能正常返回说明配置生效。如果报 401检查DEEPSEEK_API_KEY是否真的传进了环境变量PowerShell 里可以用$env:DEEPSEEK_API_KEY查看。如果报连接错误先单独测一下接口通不通curl.exe -I https://api.deepseek.com/v1提示有些第三方服务商还要求设置wire_api chat之类的字段原因就是之前 3.4 里说的 Responses 协议兼容问题。Codex 新版默认走 Responses API如果你的服务商不支持需要在 provider 里显式声明用 chat completions 协议。具体字段名以你所用的 Codex 版本文档为准配置文件里加错了会直接提示无法解析。4.4 切回官方模型与多模型共存配置成第三方模型后想切回官方模型很简单把model和model_provider改回默认值或者删掉这两行Codex 会使用内置的官方默认配置。如果你想在多个模型之间来回切换而不是每次都改配置文件可以给不同模型分别命名 provider然后通过命令行临时指定。Codex 支持在启动命令中用参数指定模型比如codex exec --model deepseek-chat 写一个冒泡排序或者codex exec --model gpt-5-codex 对这段代码做 review前提是配置里对应的 provider 都存在。需要提醒的是如果你在配置文件里写了一个 Codex 当前版本支持的模型列表之外的模型名CLI 会直接提示“the xxx model is not supported when using codex with a...”这种情况下先别怀疑配置语法去看看你用的版本到底支持哪些模型或者直接升级 Codex 版本。多模型共存的坑主要在限流上。第三方接口和官方接口的限流策略完全不同同一个任务在 A 模型下能跑换到 B 模型下可能因为限流直接中断。我自己会为不同模型设置不同的超时预期复杂任务优先用稳定模型简单任务用快模型。5. 日常使用里的细节终端选择、多客户端共享与安全建议5.1 终端选择PowerShell 和 Windows Terminal 的取舍前面提过终端重要性这里展开讲。Windows 下跑 Codex最稳妥的组合是 Windows Terminal PowerShell 7。如果系统里只有 Windows PowerShell 5.1建议升级因为 5.1 在某些 Unicode 输出、ANSI 颜色支持上确实有老态。具体到 Codex 的命令行操作我还有一个实际体会在 PowerShell 里运行codex时如果终端显示乱码第一反应不应该是设置chcp 65001而是检查终端字体。Windows Terminal 默认字体对代码块和特殊符号支持得不错旧版 conhost 的字体在渲染 Codex 的交互界面时经常错位。5.2 daemon 共享机制shared clients 是什么报错里的 “shared clients” 其实点明了 Codex 的一个关键设计多个 Codex 客户端共享同一个本地 daemon。这意味着你可以在终端 A 里跑一个 Codex 会话在 VS Code 插件里再开一个会话两个客户端连的是同一个 daemon会话状态、文件沙箱都是互通的。这个设计本意是好的但 Windows 权限模型把它变成了坑只要有一个客户端以提权身份启动共享链就断了。除了不要用管理员终端之外还有一点容易被忽略如果在多个终端标签页里同时跑 Codex尽量保持所有标签页的用户身份一致。不要一个标签是管理员账号、另一个标签是普通用户账号。Windows 的多用户会话之间不共享 daemon你切换 Windows 用户账户后需要重新登录 Codex 授权。5.3 密钥与配置文件的安全习惯Codex 在 Windows 上会把auth.json和config.toml明文存在用户目录下。如果你在config.toml里直接写了第三方 API Key 的明文那这个文件的保护就要上点心。我的建议是能用环境变量引用的就不要硬编码。env_key机制就是为此设计的。如果你非要在配置文件里放明文至少确保%USERPROFILE%\.codex目录的访问权限只对当前用户开放。右键目录 → 属性 → 安全检查继承的权限列表把不需要的账户删掉。另外不要把auth.json或者config.toml提交到 Git 仓库尤其是公开仓库。很多人用 Codex 管理代码项目顺手把整个用户目录同步到云盘这就有点危险了。密钥这层一旦失守配置本身再完美也没意义。5.4 升级与回滚别在旧版本上死磕Codex 版本更新很快Windows 上最容易出现的怪问题往往是“CLI 是新的、桌面版是旧的”这种版本割裂导致的。定期检查更新是个好习惯但我建议遵循一条原则先备份%USERPROFILE%\.codex\config.toml再升级。升级后如果发现某些模型名称不生效、或者配置文件解析报错大概率是新版本改动了配置格式。这时候不是你的操作问题而是版本兼容问题。回滚方式很简单npm 装的就用npm install -g openai/codex上一个版本号二进制包就直接替换 exe。回滚后把备份的 config 文件放回去一切恢复原样。我自己在实践中总结了一条经验不要每次更新都立刻升先在 macOS 或者 Linux 环境观察两天如果你有别的电脑确认新版本没有大坑再升 Windows。Windows 这端的折腾成本总比别的平台高一点。说到最后Codex 在 Windows 上的配置其实没有什么神秘的地方核心就是三件事终端权限用对、配置文件路径找对、接口协议选对。只要这三点理顺不管是官方模型还是第三方模型跑起来都只是时间问题。我第一次配完整整花了一个下午其中大半时间耗在“管理员终端导致 daemon 权限不匹配”上后来想明白原理重装加配置只用了十分钟。希望这篇能帮你把那十分钟提前到今天。