先说一个我身边的真实案例。有个同事在群里说 Codex 装了三遍还是用不了我远程一看他桌面上同时开着四个窗口浏览器里停着 codex 网页版终端里跑着 codex 命令行VS Code 里装着插件还下了一个桌面版。他其实不是没装上而是根本不知道自己用的是哪条入口更别提登录之后拿什么标准确认真的装好了。后来我把四条入口的区别讲清楚他自己五分钟就搞定了。这篇就围绕Codex 安装和登录这件事把四条入口怎么选、每种怎么装、登录会遇到什么卡点、装完该验证什么写明白。你不用把所有入口都装一遍选一条主用的再知道另外几条是什么就够了。1. 四条入口分别解决什么场景为什么不是越多越好1.1 先用一张表把四条入口说清楚Codex 现在的使用入口不只有命令行官方推了不少形态但核心逻辑都是同一个你在界面里描述需求Codex 调用模型、操作代码、给你结果。区别在于你在哪个环境里工作。入口形态适合谁登录方式需要额外安装什么Web 版浏览器访问想快速尝鲜、临时用一下ChatGPT 账号什么都不用装CLI 命令行终端里的交互式工具写脚本、批量任务、把 Codex 接进自动化流程ChatGPT 账号或 API KeyNode.js、npm 全局包VS Code 插件编辑器侧边栏面板日常在 IDE 里写代码、边写边改账号登录VS Code、插件本体桌面版独立客户端应用重度用户需要沙盒隔离和图形界面账号登录对应系统的安装包这四个入口本质上是同一套能力的不同前端。Web 版最轻适合判断这东西到底适不适合我的工作流CLI 最适合脚本化和自动化我日常用得最多VS Code 插件适合一边改代码一边让它补全或改 bug桌面版则是把文件工作区、沙盒、会话管理做成了独立应用适合不想碰命令行的人。1.2 我的选型逻辑按你在哪写代码来决定选入口没有标准答案我一般让朋友回答三个问题你是重度 IDE 用户吗是的话直接上 VS Code 插件CLI 和桌面版可以作为补充。你是不是经常要跑批量的、重复性的任务比如批量改文件、按固定模板生成代码、接入 CI 做自动 review。这种情况 CLI 是唯一正解插件和桌面版很难做脚本化。你只是想看看 Codex 现在到底什么水平那 Web 版就够了别折腾安装。我是 CLI 主力党。原因很实在CLI 能进 shell 管道能写进 shell 脚本能和 git 配合做提交前代码审查。这些东西在图形界面里做起来别扭得很。但我也装了 VS Code 插件因为写业务代码的时候我人就在编辑器里开个终端跑 CLI 反而多一道切换。1.3 入口选错是后面一堆怪问题的根源我帮人排查 Codex 问题的时候很大比例不是软件坏了而是入口混用了。典型现象在命令行工具里找了半天设置按钮在哪儿——那是桌面版和插件才有的东西。在 Web 版里挂着一个大任务等它跑完等到超时——这种长任务走 CLI 更可控也能断点续跑。装了 VS Code 插件却不知道插件要单独再登录一次——每个入口的登录态不一定是共享的。下载了桌面版又同时开了 Web 版结果两个窗口各自登录不同账号怎么想都不对劲。如果你发现自己卡在类似状态先停下来确认我现在说的是哪一个 Codex把它明确下来再继续往下走。2. 安装三板斧CLI、插件、桌面版每步命令和坑位安装这件事本身不难难在很多人漏掉了前置条件。下面把三条安装路径拆开讲Web 版不需要装跳过。2.1 装之前先检查三个前置条件第一确认系统满足要求。Windows 10/11、macOS、主流 Linux 发行版都能跑但 Windows 上要特别注意终端权限问题这个后面单说。第二CLI 依赖 Node.js 20 及以上版本。很多安装失败是因为 Node 版本太老。先执行node -v npm -v看到版本号再继续。看不到版本就先装 Node.js建议直接装 LTS 版本。第三确认你能正常打开官方服务页面。如果连官网下载页都打不开问题不在安装步骤而在你的网络环境能不能正常访问官方服务这块需要你自己先处理好本文只讨论安装和登录本身。2.2 CLI 安装npm 一把梭但要注意全局目录CLI 的安装命令很简单npm install -g openai/codex装完先别急着登录跑一下版本号codex --version能输出版本号说明二进制文件已经就位。如果提示codex命令找不到基本是 npm 全局目录没在 PATH 里。Windows 用户常见于用了 nvm-windows 之后切换了 Node 版本npm 全局包装到老版本目录去了。解决方式是把当前 Node 版本的全局目录加进 PATH或者干脆重新装一次 Node 再装 Codex。升级用的命令是npm update -g openai/codex我习惯两周左右升一次。Codex 这个产品迭代非常快旧版本经常会碰到模型已经切换但本地还按旧参数请求的怪问题升级往往能直接解决。2.3 VS Code 插件和桌面版的安装细节VS Code 插件直接在扩展商店搜索 Codex认准发布者是 OpenAI 官方再装。装完你会看到一个侧边栏图标点开后是对话面板。这里有个很多人忽略的点插件装完不代表就能用了它还要再走一次登录跟 CLI 登录不是一回事。桌面版去官网下载对应系统的安装包。macOS 用户下 dmg 文件拖进 Applications 就行如果系统提示无法打开通常是 Gatekeeper 拦截右键图标选打开一次即可。Windows 用户下 exe 安装包这里有个很重要的提醒Windows 安装桌面版、以及后续运行 Codex 任何入口都别用管理员权限。这不是小问题后面第 5 章有一个高频报错就跟这个直接相关。你现在记住了后面能少踩一个坑。2.4 安装卡死和装完没反应的解法安装时最常见的两种异常npm 卡住不动、桌面版进度条走不完。npm 卡住多数是网络到 registry 的链路慢。可以临时把 npm registry 切成国内常用镜像源装完再切回来。这不是什么见不得人的技巧所有 npm 用户都会用不影响软件本身正确性。桌面版进度条走不完我遇到过的原因有磁盘权限不足、杀毒软件把沙盒组件隔离了。先看杀毒软件有没有拦截记录没有的话就把安装包重新下载一遍很多进度条卡死其实是安装包下载不完整。如果桌面版无限停留在正在更新沙盒直接卸载重装别在界面里死等。卸载之前把聊天记录和项目目录备份一下省得后悔。提示网上流传的各种汉化版破解版 Codex我强烈建议你别碰。这类分发的安装包来源不可控你等于把账号凭据和本地文件暴露给第三方。官方界面再朴素也比被薅走 API Key 强。3. 登录的两条路径与四个高频卡点Codex 的登录本质上只有两条路ChatGPT 账号登录和 API Key 登录。先想清楚走哪条再动手因为你选的路直接决定了后面会遇到哪些限制。3.1 账号登录与 API Key 登录什么时候用哪个ChatGPT 账号登录适合订阅了 ChatGPT Plus/Pro/Team 等套餐的用户。流程是浏览器授权Codex 拿你的账号身份去调用服务按套餐权益计费。好处是不用管 Key坏处是账号套餐可能不支持某些实验模型。API Key 登录适合开发者。你去 platform.openai.com 手动创建一个 API KeyCodex 用这个 Key 的身份调用服务按 token 用量计费。好处是模型权限更接近开发视角坏处是你要自己管 Key而且费用直接从你的 API 账户扣。一句话概括你是普通用户账号登录你是开发者想折腾模型和自动化API Key 登录。千万别两个混着用混用产生的登录态串扰是很多登录不上问题的源头。3.2 登录流程到底发生了什么以 CLI 为例运行codex login终端会打印一个 URL同时尝试自动打开默认浏览器。你在浏览器里完成账号授权后Codex 会把身份凭据写到本地配置文件里通常在用户目录下的~/.codex/里终端会提示登录成功。这个过程里哪怕什么都不点它也能跑通前提是你的系统默认浏览器能正常打开授权页面。如果终端提示waiting for login然后一直不动大概率是自动打开浏览器那一步失败了。这时候别傻等直接把终端里打印的那个 URL 手动复制到浏览器地址栏打开授权完回到终端你会发现它已经自动继续了。VS Code 插件和桌面版的流程本质一样只是入口换成了面板上的 Sign in 按钮。桌面版登录完成之后可能还要加载组织设置、初始化沙盒第一次点进去耐心等一下别连续点好几次登录否则容易触发并发冲突。3.3 登录失败排查按现象对号入座我按遇到频率从高到低列四个卡点卡点一授权页打开后一片空白或转圈。大概率是网络环境问题换一个能正常访问官方服务的网络再说。卡点二命令行一直waiting for login浏览器也没弹出来。手动复制终端里的 URL 打开这是最稳的解法。卡点三提示auth token is unavailable。这是凭据丢了或者环境变量干扰。先退出再重新登录codex logout codex login如果还是不行检查你是不是在系统环境变量里设了OPENAI_API_KEY之类的变量。有些第三方工具会自动注入这个变量Codex 看到之后会优先用它的值导致账号登录的 token 被认为是无效的。把无关的变量临时清掉再试通常能解决。卡点四手机号验证过不去。注册或登录过程中官方要求验证手机号就按页面提示一步步来。每一步的验证短信都有可能延迟别频繁重发等一两分钟再说。反复重发反而可能被风控短暂锁定。4. 装完怎么确认三层验证从版本号到端到端最小任务很多人装完的标准是图标能打开、界面能看到。这个远远不够。我把验证拆成三层每一层都是下一层的前提。4.1 第一层身份命令确认组件与凭据就位CLI 用户执行codex --version codex whoamiwhoami能返回当前登录的账号身份说明登录链路是通的。如果whoami报错直接回第 3 章重新登录。VS Code 插件用户看侧边栏面板头部正常状态会显示你的账号信息或者模型选项而不是一片灰的Sign in。桌面版用户在设置或个人中心里看账号绑定状态。这一步是最低成本的全链路体检版本号说明安装没问题whoami 说明登录没问题。4.2 第二层跑一个 10 秒的最小任务验证端到端这一步很多人偷懒跳过结果进了正式任务才发现模型请求根本没通。CLI 用户用非交互模式跑一个最最简单的任务codex exec 用 python 写一个打印当前时间的脚本并运行它如果 CLI 能给出脚本、执行并输出当前时间恭喜你安装、登录、网络、模型、沙箱执行五条链路全部打通了。比 whoami 更进一步因为 whoami 只证明了身份有效这一步证明的是能干活。桌面版和插件用户在对话窗口里发同样一句话能拿到正常回复就算通过。提示这个最小任务一定要选端到端可执行的不要只问知识性问题。你真正要确认的是从界面到模型再到执行器全链路健康不是模型背答案的能力。4.3 第三层确认配置没被忽略CLI 用户输入codex --help看看命令里有没有debug、doctor之类的自检子命令。不同版本提供的子命令不一样以你自己的--help输出为准。有的话跑一下它会把当前生效的配置、模型、认证方式列出来和你想的是否一致一目了然。到这一层常见的我明明改了配置但没生效的问题就暴露出来了。更多时候你会发现不是没生效是配置字段写错了压根没被读取。这正是下一章要讲的高频报错里的重头戏。5. 高频报错对照表报什么错查哪一环以下问题都是我在各种讨论帖里见了一遍又一遍的按报错关键字直接对号入座比通读文档高效。5.1 model is not supported when using codex with a chatgpt account原话大概是the gpt-5.6-sol model is not supported when using codex with a chatgpt account。意思是你用 ChatGPT 账号登录的身份去请求了一个该身份不支持的模型。Codex 用账号登录时能用的模型是受你套餐权益限制的预置列表而像gpt-5.6-sol、gpt-6-astra这类名字一看就是某个新模型的内测代号或实验别名普通账号身份当然不能用。解决办法分两种情况你不关心指定模型那就把配置文件里的 model 声明删掉让它用版本默认值。你就想用某个特定模型那别用账号登录换成 API Key 登录在平台端确认你的 Key 有权限再配置。这个报错特别容易出现在升级 Codex 版本之后新版默认模型变了你旧配置里还写死着一个旧模型名一升级就炸。你把配置里的 model 字段更新成新版默认值就能解。5.2 unrecognized configuration setting报错里会把具体字段名一起列出来比如codex is ignoring 1 unrecognized configuration setting. check for typos or remove it.。这句大白话是你配置文件里有一个它不认识的字段。原因无非三种拼写错误、字段名来自旧版本、照抄网上的配置没注意版本差异。解法是打开你的配置文件路径通常在~/.codex/config.toml把报错指出的那个字段删掉或者改正。怎么改看你当前版本支持什么去官方配置文档对一遍。很多网上配置教程已经过时了字段名对不上很正常。根治习惯改完配置先跑一遍codex --help或 debug 自检确认没有 ignore 提示再开始干活。5.3 start the windows daemon from a non-elevated terminal原话是codex error: start the windows daemon from a non-elevated terminal; shared ...。一个非常典型的 Windows 权限坑。Codex 在 Windows 上会起一个本地后台服务daemon来做执行和管理。如果你是从以管理员身份运行的终端里启动 Codex这个 daemon 就会跑在提权环境里后续操作容易跟普通权限的进程冲突于是它直接拒绝启动要你换一个非管理员终端。解法一句话别用管理员权限开终端跑 Codex。把 PowerShell 或 CMD 关掉重新以普通身份打开再跑codex --version或codex login就正常了。这个坑在桌面版上也会出现如果 Windows 用户右键以管理员身份运行桌面版同样可能碰到类似权限报错。记住Codex 全家桶都不要提权运行。5.4 auth token is unavailable这个我在第 3 章提过这里单独再说一次因为它是登录问题里最高频的一个。auth token is unavailable表示 Codex 拿不到有效的认证凭据。可能原因从未登录成功过。登录成功后配置文件被清理工具删了或者权限被改了。环境变量里存在OPENAI_API_KEYCodex 尝试用它反而绕过正常 token。账号会话过期。我的排查顺序是先codex logout再codex login解决 80% 的过期问题不行就检查环境变量把当前 shell 里跟 OpenAI 相关的变量打印出来看看再不行检查~/.codex目录下凭据文件是否存在、是否有读权限。这里格外提醒用第三方模型管理工具的朋友有些工具会往系统里写OPENAI_API_KEY之类的全局变量你和 Codex 的登录态可能就被它覆盖了。这种冲突不好查但知道了方向排查起来就快了。5.5 第三方配置工具报错问题往往在 base URL不在你的操作现在不少人会用 CC Switch 这类第三方配置管理工具来快速切换 Codex 所用的模型服务商比如切到 DeepSeek、切到别的兼容服务。工具本身不坏但我看到的报错太多了关键是它把请求发到了一个不合适的服务地址上。这类工具在切换时会修改 Codex 的模型提供方配置一旦选错你会在工具里看到类似local forward failed while handling codex endpoint /responses. provided base url ...的提示。翻译成人话Codex 把请求打到一个 base URL但那个地址对应的服务不知道怎么处理/responses这个接口的请求。排查逻辑是先看清楚报错里给你的 base URL 是什么是不是你真正想连的那个服务商。如果工具里能选接口格式确认服务商支持的是responses还是chat。现在不少兼容服务只实现了chat协议Codex 默认按responses去打自然打不通。实在排查不清楚就不要依赖工具了直接用配置文件手写下一章会讲。这个报错和安装登录没有关系它是服务地址对不上的问题。看清楚 base URL问题就解决一半了。6. 给 Codex 换个模型后端比如 DeepSeek时配置到底怎么写既然热搜里大量出现codex 接入 deepseek我就把这块也讲透。很多人改完配置发现 Codex 完全无视它原因几乎都出在配置文件格式不对或者版本对不上。6.1 config.toml 的打开方式Codex 的配置文件在~/.codex/config.toml。换模型后端的基本思路是声明一个 model_provider把它的 base_url 指到目标服务再用环境变量给它配对应的 API Key。一个常见的配置示例长这样model gpt-5 model_provider deepseek [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY wire_api chat注意字段名。不同版本的 Codex配置字段存在差异我这段时间见过的就有model_provider、providers、model_providers几种写法。所以你抄配置之前先跑一下你当前版本的codex --help看它提示的配置路径和字段名。如果你写的字段版本不认识就会触发第 5.2 节的unrecognized configuration setting。配置写好后还要把环境变量配上export DEEPSEEK_API_KEY你的keymacOS/Linux 写进 shell 配置文件Windows 用setx或者系统环境变量界面。设好之后重启终端和 Codex 再验证。6.2 wire_api 选错是接入第三方时最大的坑上面配置里的wire_api字段很多教程不解释但它直接决定成败。简单说OpenAI 体系现在有两套接口协议responses和chat。Codex 原生走responses协议但很多第三方模型服务商实现的是更通用的chat协议。你在配置里把wire_api明确标成chatCodex 就会用chat协议去跟第三方服务通信不标或标错它默认按responses打过去服务商那边直接不认。判断你的目标服务商支持哪个协议就看它的 API 文档有没有/responses端点。只有一个/chat/completions那wire_api就写chat。另外有个容易忽略的点一旦你换成了第三方 model_provider你原来的 ChatGPT 账号登录凭据在模型调用这个环节就不生效了。因为模型请求是拿env_key对应的第三方 Key 去做的和你的 ChatGPT 账号是两套体系。这也是很多人明明登录成功了但 Codex 好像不认识我的原因。6.3 混用多个工具时的配置洁癖如果你装了 CC Switch 这类工具又手动改过 config.toml很可能出现两边互相覆盖。建议定一个原则要么全用工具管理要么全手写配置别两个都碰同一个文件。我自己是手写党因为配置文件就几十行看得到摸得着工具适合频繁切换不同服务商的人。但要清楚工具的本质就是帮你改这个配置文件它只是编辑器改的还是同一份文件。版本升级后工具没跟上 Codex 新配置格式就会把文件写成旧格式Codex 又是一通报错。这时候把工具暂时卸载、手写配置反而是最快的恢复路径。7. 最后再分享一点我的使用习惯Codex 装和登录这件事本身不复杂但它横跨四个入口、两套登录体系、一个配置文件任何一个环节理解错位都会让你觉得这东西怎么这么难用。我实际用下来的体会是九成的安装登录问题都是环境权限、登录态串扰和配置格式这三件事引起的没有一个是 Codex 本身没法用。我在新机器上的固定流程是这样的先装 Node.js再npm install -g openai/codex然后 VS Code 插件顺手装上接着codex login一次跑codex exec 用 python 输出当前时间验证全链路最后用默认配置干活不急着换第三方模型。等默认链路稳定跑通一周再考虑要不要接 DeepSeek 之类的后端接的话也只动 config.toml不引入多余工具。如果你现在卡在某个报错上别急着卸载重装。回到第 5 章的对照表找到你的报错关键字顺着排查链路走一遍。大部分问题五分钟内能定位。装对了、登录通了、验证过了后面用起来才会真的顺。