拿到 Codex 安装包后很多人的第一反应是找教程结果一搜发现入口不止一个有命令行工具、有桌面客户端、有 IDE 插件还有网页版。我在本地装了三遍踩了不少坑才把四者的关系理顺。这篇文章不打算重复官网文档而是从选型开始把四条入口的区别、安装登录步骤、装完之后的确认方法说清楚。文章会贴出实际用到的命令和验证方式适合刚接触 Codex 的开发者也适合已经装完但登录总失败的人。1. 先说结论四条入口怎么选1.1 四条入口是什么Codex 这名字听起来像一个软件实际上更像一套工具链。它的四条入口分别是CLI 命令行入口通过 npm 或 Homebrew 安装在终端里运行。适合自动化脚本、批量任务、喜欢全键盘操作的人。桌面应用入口官方提供的图形界面客户端自带会话列表和终端面板。适合不熟悉命令行操作、希望用鼠标完成大部分操作的人。IDE 插件入口在 VS Code 或 JetBrains 系列编辑器里安装。适合写代码过程中随时选中代码、让 AI 做解释、补全、重构的人。网页版入口浏览器直接访问零安装。适合临时体验、给同事演示、或在一台不方便装软件的电脑上应急。这四条入口共享同一个 ChatGPT 账号体系登录一次之后会话和身份在入口之间是打通的但各自的工作区、历史记录、配置文件不完全同步。很多人以为“装了一个 CLI 就万事大吉”结果在用 IDE 插件时又重复登录就是这个关系没理顺。1.2 按人群和场景选型选入口不需要纠结“哪个最强”而要看“哪个最不打断你当前的工作流”。场景推荐入口理由脚本化处理、批量任务、Git 操作CLI可以直接嵌入 shell 脚本输出内容可重定向刚开始接触、不熟悉终端桌面应用图形界面直观内置教程和会话管理日常在编辑器里写业务代码IDE 插件选中代码即可触发不用来回切换窗口公共电脑、快速演示网页版不用安装浏览器打开即可本地资源紧张的老机器CLI无图形界面进程内存占用最小我自己的主力是 CLI因为大部分时候我会把 Codex 的输出管道交给其他命令处理桌面版反而觉得界面占地方。但如果你平时就是打开 VS Code 写代码那 IDE 插件才是最优解。四条入口完全可以同时存在它们互相不冲突只要别在同一台机器上混用两种方式安装同一个 CLI。2. 安装前的准备先把环境和依赖理清楚2.1 运行环境要求不管选哪条入口装之前先看一眼自己的系统版本很多“装不上”其实不是 Codex 的问题而是环境不达标。操作系统macOS 12 及以上、Windows 10 及以上、主流 Linux 发行版。Node.jsCLI 和 IDE 插件都依赖 Node.js 运行时建议 Node.js 18 以上npm 9 以上。版本过低会出现各种莫名其妙的报错。终端工具Windows 建议用 Windows Terminal 或 PowerShell 7macOS 用自带 Terminal 或 iTerm2 都行。GitCodex 生成代码修改时会把改动以 git diff 的形式展示也需要 git apply 来应用变更。没有 Git很多核心功能会静默失效。很多教程默认你已经有 Git 和 Node.js但实际工作中我遇到过好几台新机器连git --version都报错。建议先跑一下git --version node --version npm --version三个命令都能输出版本号再继续下一步。如果 Git 没装顺手把 Git 装好并完成基础配置git config --global user.name your_name git config --global user.email your_email2.2 安装渠道的统一约定这里要提前说明在安装 Codex CLI 时官方给的是 npm 包名openai/codex不管你用 npm 还是 Homebrew安装出来的都是同一个可执行文件。差别在于更新方式npm 全局安装npm install -g openai/codex可以完全控制版本更新用npm update -g openai/codex。Homebrew 安装brew install openai/codex/codex更新用brew upgrade codex好处是依赖管理更系统化适合 macOS 上已经重度使用 Homebrew 的人。不要两种方式都试。我见过有人先 npm 装了一遍后来觉得版本旧又用 brew 重装最后which codex指向了其中一个另一个残留在系统里每次升级都出现“版本没变”的错觉。选一种安装方式一条路走到黑。桌面应用、IDE 插件、网页版不需要提前装 Node.js它们各自有独立的更新机制。所以如果你的需求只是桌面 GUI可以跳过环境检查那一段直接看第 3 节的对应入口。3. 四条入口的安装与登录实操3.1 入口一CLI命令行入口CLI 是四条入口里功能最完整、也最容易出问题的一条所以我放在最前面讲。安装npm install -g openai/codexmacOS 也可以brew install openai/codex/codex装完先验证codex --version能看到类似codex 0.x.x的输出就说明二进制文件已经就位。接下来是登录。Codex 支持两种身份体系ChatGPT 账号登录和 OpenAI API Key。首次运行codex或执行codex login时CLI 会询问你使用哪个 providerWhich provider would you like to use? 0. ChatGPT (Recommended for individuals) 1. OpenAI API (Use your API key)如果你是普通用户选 0。随后终端会打印一个https://chatgpt.com/...的授权链接自动打开浏览器用 ChatGPT 账号确认授权然后页面会提示你可以回到终端。CLI 收到回调后会在本地生成~/.codex/auth.json保存会话令牌。如果你只有 API Key选 1然后设置环境变量export OPENAI_API_KEYsk-...需要提醒的是ChatGPT 登录态和 API Key 的优先级是有差异的。默认情况下如果~/.codex/auth.json存在CLI 会优先使用 ChatGPT 会话想强制走 API Key需要打开~/.codex/config.toml在配置里把 provider 指定为openai。不要一边登录了 ChatGPT一边又设置 API Key那样排查问题会绕很大的弯。3.2 入口二桌面应用图形界面入口桌面应用适合不喜欢终端的人。它的本质是把 CLI 封装成界面所以登录逻辑和 CLI 完全一致只是不需要你手动敲命令。下载安装包这一步比较直接从官网拿到对应平台的安装包Windows 是 exemacOS 是 dmg双击安装拖入 Applications 或一路 Next。安装完成后启动第一次打开会引导你登录 ChatGPT 账号。流程同样是浏览器授权授权完成后桌面应用内部会自动持有会话令牌你不需要关心 auth.json 在哪。桌面应用有几个值得说的点它会自带一个终端面板你可以在同一个窗口里既看界面又敲命令。会话历史以可视化的方式保存适合把之前跑过的任务归档。登录状态在应用右上角能看到当前账号信息比 CLI 判断登录状态方便很多。装完后如果登录失败问题通常出现在浏览器回调环节后面第 5 节我会专门说排查思路。3.3 入口三IDE 插件编辑器里的 CodexIDE 插件是“写代码过程中最顺手”的入口。以 VS Code 为例安装步骤是打开扩展面板搜索Codex。确认发布者是 OpenAI 官方点击 Install。安装完成后侧边栏会出现 Codex 图标。点击登录选择使用 ChatGPT 登录浏览器授权完成后回到编辑器。这里有一个隐藏依赖IDE 插件的后端依然调用本地的 Codex CLI。也就是说即使你只在 VS Code 里用 Codex也必须先确保codex命令能在终端里正常运行。很多人在 VS Code 里点登录没反应并不是插件坏了而是本机根本没装 CLI或者 CLI 版本的路径与插件寻找的路径不一致。有个小技巧装完插件后在 VS Code 的终端里跑一遍codex --version如果能正常输出再回到插件界面登录成功率会高很多。3.4 入口四网页版零安装入口网页版适合“什么都别让我装我就想看看它到底能干什么”的人。打开浏览器进入 Codex 的网页入口用 ChatGPT 账号登录即可。它提供聊天窗口、代码运行沙箱甚至可以把生成的代码导出。网页版的优势是省事但有几个天然限制它无法直接读取你本地文件系统只能靠你手动粘贴代码或上传文件。它不能像 CLI 那样直接操作 Git diff修改回本地项目需要手动复制。会话在云端保存和本地 CLI 的聊天记录不互通别指望两边自动同步。所以网页版更适合验证想法、快速出结果不适合作为日常工作的主入口。我一般拿它做两件事一是在新电脑上还没配环境时临时用二是给同事演示时不用开自己的终端。4. 装完怎么确认三条验证路径4.1 确认版本与可执行文件位置安装完第一件事是确认命令能跑通。终端执行codex --version如果报command not found说明安装路径没有进系统 PATH。npm 全局安装的常见路径是/usr/local/lib/node_modulesHomebrew 的路径一般在/opt/homebrew/bin或/usr/local/bin。可以用下面的命令确认实际路径which codexWindows PowerShell 下用Get-Command codex我踩过的坑是电脑上装了 nvm切换 Node 版本后全局包路径也变了导致原本能用的codex忽然消失。如果你也用 nvm记得在codex --version之前先nvm use切到安装时那个 Node 版本。4.2 确认登录会话是否生效如果登录动作已经完成但你还是不确定是否生效直接看认证文件cat ~/.codex/auth.json正常情况下文件里会包含账号相关的身份信息和令牌时间戳。如果文件不存在说明登录没有成功。这个文件相当于是 CLI 的“登录凭证”不要把它分享给别人也不要在公开地方打印完整内容。想要更安全的验证方式不直接看文件内容而是检查文件是否存在ls -la ~/.codex/auth.json能看到文件且最后修改时间是你执行登录的时间基本可以认为登录流程已经走通。如果文件存在但登录后仍提示未认证可以先执行一次登出再重新登录codex logout codex login重新生成一份全新的认证文件往往能解决“状态没刷新”的问题。4.3 跑一次真实请求版本有、登录状态有最后做一次端到端测试。最简单的方式是使用非交互模式codex exec 用一句话介绍你自己或者进入交互模式codex输入一个简单任务比如“写一个 Python 函数计算斐波那契数列前 10 项”观察 Codex 是否生成代码、是否能正常应用 diff。这一步通过说明安装、登录、模型调用全部正常。这比只跑--version更能说明问题。--version只能证明程序装上了不能证明后台服务和用户凭证可用。我见过太多人卡在--version能跑、一提问就报错的状态多做一次端到端测试能省得后面手忙脚乱。5. 登录失败排查高频问题与处理建议5.1 token exchange failed 和 login server error登录时报login server error: token exchange failed: token endpoint returned ...是一个常见套话真正含义是浏览器完成了授权但 CLI 在跟认证服务交换令牌时失败。大部分情况下跟账号密码无关而是下面几个原因系统时间不准。令牌交换依赖时间窗口误差超过几分钟就会失败。浏览器默认打开了授权页面但回调地址被其他应用拦截。本地残留了一份旧的认证文件。本机网络环境存在拦截或重定向导致请求没有到达真正的认证服务。按顺序处理先同步系统时间。删除旧的认证文件rm ~/.codex/auth.json。换一个默认浏览器再执行codex login。如果系统开了任何网络优化类工具先临时关闭让流量走系统默认配置再重试。第 4 条是很多人忽略的坑。Codex 登录时需要在本地起一个临时服务来接收回调如果你的系统网络配置把这个回调请求接管了就会看到“授权成功但终端一直没反应”或“token exchange failed”。恢复默认网络配置后通常立刻就能解决。5.2 浏览器授权成功但终端不跳转典型表现浏览器页面显示“授权成功可以关闭窗口”但终端还卡在等待状态没有出现“Login successful”字样。原因多半是回调 URL 没有正确回到 CLI。这时不要急着反复登录先看回调内容。一种可靠的处理方案是点浏览器授权页面里的“手动复制链接”或直接复制地址栏的完整 URL然后回到终端看 CLI 是否提示输入回调链接。如果 CLI 支持手动粘贴粘贴后按回车即可。如果手动粘贴也不行那就把认证文件清掉重来一遍rm ~/.codex/auth.json codex login过程中注意浏览器是否阻止了弹窗。Codex 登录依赖临时跳转某些浏览器的严格弹窗拦截会把回调请求拦在门外。把拦截列表里对应站点设为允许通常能解决。5.3 模型不支持的报错登录成功但运行时报错例如the gpt-5.6-sol model is not supported when using codex with a ...这句话看着吓人其实只是你配置里写了一个当前环境不支持的模型名。模型名称必须和你账号套餐、API 权限对应。ChatGPT 登录用户一般不用手动指定模型账号套餐会决定默认模型使用 API Key 时模型名必须属于该 Key 可调用的范围。排查的方法是打开配置文件cat ~/.codex/config.toml找到类似model ...的行确认名称是否拼写错误或者是否超出了套餐范围。把模型名改成官方支持的标准名称再重启会话即可。一个常见误区是网上很多教程会推荐修改 model 字段来“解锁”更强的模型。新手上路阶段我不建议这么干一是容易踩模型名不存在的坑二是生成质量未必有提升反而把排查问题的范围扩大。5.4 多入口登录状态冲突CLI 登录成功但 IDE 插件仍然提示未登录或者桌面应用显示的是另一个账号。这种情况就是四个入口的认证文件指向不一致。CLI、桌面应用、IDE 插件虽然共用~/.codex目录但有的版本会把认证文件拆分成不同文件或者桌面应用走独立的钥匙串存储。处理思路很简单把四个入口全部退出删除~/.codex/auth.json以及桌面应用自带的认证缓存然后从你最常用的入口重新登录。重新登录后其他入口通常会自动复用新的会话令牌。如果还是不行就把四者都重启一遍。配置文件没问题、认证文件没问题、命令能跑剩下的大概率就是缓存问题。6. 装完之后建议做的小事6.1 简单优化配置文件Codex 第一次使用会生成~/.codex/config.toml里面有很多默认行为新手可以改两个最有用的model gpt-5 model_provider openai如果你是用 ChatGPT 登录model_provider保持默认即可如果你打算用 API Key再显式指定。不要轻易改其他高级项比如某些人喜欢关掉审批、让代码自动应用这在个人项目上虽然方便但生成的是不确定代码一旦混进工作分支排查成本很高。6.2 保持版本更新Codex 迭代速度很快旧版本经常出现新版模型不兼容的情况。周期性执行一次更新npm update -g openai/codex用 Homebrew 的就brew upgrade codex桌面应用和 IDE 插件一般会有自动更新提示看到更新直接点同意。升级后如果发现功能异常先看版本号再去确认是否需要重新登录因为升级偶尔会触发现有认证文件结构不兼容。6.3 关于多台机器的经验我现在在办公电脑和个人电脑上都装了 Codex但从来不直接复制~/.codex/auth.json过去。认证令牌与设备绑定复制过去基本都会失效反而会让新机器出现一堆认证报错。正确做法是每台新机器都重新执行一次codex login耗时不到一分钟比复制文件后排查问题划算得多。个人体会是Codex 这类工具的价值不在于“安装成功”那一瞬间而在于装完之后的日常使用是否顺滑。安装文档看一百遍不如亲手跑一遍完整流程。四条入口你不需要全都装但至少把一个入口的登录流程走通再遇到其他入口时思路就完全通了。