最近不止一个朋友跑来问我“Codex 装好了但在终端里敲codex告诉我不是内部或外部命令是怎么回事”还有同事装了 VS Code 扩展一启动就弹unable to locate the codex cli binary or required runtime。我先说一个结论Codex 不是一个“下载个 App 装完就完事”的工具它拆开了至少有 CLI、IDE 扩展、桌面应用三层很多人装一半就卡住不是因为不会敲命令而是没搞明白自己到底该装哪一层。这篇我打算把两条主线讲透一条是 Mac 和 Windows 两个平台分别怎么装一条是 CLI 和 IDE 两种使用方式怎么选、怎么配、怎么排错。文章中所有步骤都是我这段时间反反复复装出来的实测结果中间还掺了不少摔过的跟头。不管你是想把它接进自己最顺手的编辑器还是打算在自动化脚本里直接用命令行调用这篇都适合花十分钟看完然后照着一步步操作。1. 先搞清楚 Codex 的三层结构和两条路线1.1 Codex 不是单一软件而是“CLI IDE 桌面端”的组合Codex 本质是一个代理式编程工具你给我一句自然语言它自己去读你仓库里的文件、改代码、跑测试、甚至提交改动。它在安装层面拆成了三块这三块互相有关联但不等价Codex CLI一个命令行工具npm 包名是openai/codex装完之后你在终端里敲codex就能用。适合脚本化、自动化、CI 集成这些场景。IDE 扩展VS Code 插件安装后在编辑器侧边栏里出现 Codex 面板。它更适合你一边写代码一边让它帮忙改能直接看 diff。桌面应用ChatGPT 桌面端内置了 Codex可以在图形界面里新建 Codex 任务适合不想碰终端的人。很多人容易踩的坑就是以为装了桌面端就等于有了命令行工具结果在终端里输codex当然找不到。反过来也有人只装了 CLI跑到 VS Code 里找 Codex 面板当然也没有。还有一个关键关联很多 IDE 扩展和桌面应用在运行 Codex 子进程时会去找系统的codex二进制。这也是为什么热搜里那句chatgpt failed to start. unable to locate the codex cli binary or required runtime会出现得这么频繁——CLI 没装或者装了但 PATH 里找不到图形界面就跟着罢工。1.2 动手安装前这四件事先确认ChatGPT 账号Codex 登录用的是它。免费账号能体验但速率和可用功能有限Plus 或 Pro 账号体验完整得多。Node.js 18 或更高版本CLI 的安装依赖 npm所以 Node 是硬前提。如果只走桌面端应用Node 可以暂时不装但走命令行这一步绕不开。网络环境要能正常访问 OpenAI 的服务登录授权、向模型发请求都需要网络通。如果你本机开了代理工具建议先把代理去掉再装免得装一半卡住后面第 6 章会专门讲 proxy 报错。磁盘空间不用太担心Codex 本身只有几十 MB真正的模型运算都在云端本地不占太多东西。我的建议是无论你最终目的是 CLI 还是 IDE都先把 CLI 装好。因为 IDE 扩展和桌面端在底层都会去找它你先把地基建好后面所有入口都通畅了。2. Mac 环境把 Homebrew、Node、PATH 一次理顺2.1 最快路径npm 全局安装Mac 上装 Codex CLI 最直接的方式就是 npmnpm install -g openai/codex装完之后验证版本codex --version能看到版本号比如0.x.x就说明 CLI 装好了。以后要更新也很方便npm update -g openai/codex为什么我推荐走 npm 而不是 Homebrew因为 Codex 的发布节奏很快npm 是官方同步最快的渠道而且版本回退也简单npm install -g openai/codex具体版本号就能锁定旧版。如果你之前用老办法装过早期版本直接用 npm 覆盖装一遍也可行。2.2 Mac 上装 Node 的 Homebrew 报错排查很多 Mac 用户会先通过 Homebrew 装 Nodebrew install node但“mac安装homebrew报错”这个热搜词不是没原因的。我遇到过的典型问题有两类第一类是执行 Homebrew 官方安装脚本时提示curl: (7) Failed to connect to raw.githubusercontent.com port 443这类连接错误。遇上这种问题先看看终端里有没有残留的代理环境变量env | grep -i proxy如果有输出先unset http_proxy、unset https_proxy确认网络恢复正常后再跑安装脚本。如果没有任何代理输出但依然连不上那大概率是当前网络本身的问题。不要钻牛角尖直接换个路子去 Node.js 官网下载 macOS 安装包.pkg安装完自带node和npm完全不依赖 Homebrew。第二类是权限报错。老款 Intel Mac 的/usr/local目录常见权限问题报Permission denied时用下面这条修复ls -ld /usr/local sudo chown -R $(whoami) /usr/localApple SiliconM 系列芯片的 Homebrew 装在/opt/homebrew同样方式处理。注意chown要慎重只针对 Homebrew 涉及的目录别对整个系统目录来一遍。2.3 dmg 安装的桌面应用和 CLI 是什么关系也有人在官网下载了 ChatGPT 桌面端装完发现终端还是不能用codex命令。这是预期中的结果桌面端安装包自带运行环境它内置了 Codex 功能但不往系统 PATH 里放命令行工具。一句话总结分工你只想在图形界面里和 Codex 对话比如“帮我看一下这个项目的结构”那就用桌面应用。你想在脚本里写codex -c ...或者在终端里持续交互那就必须单独装 CLI。两边不冲突装完 CLI 再打开桌面应用体验反而更顺因为桌面端能找到底层命令了。2.4 zsh 提示 command not found: codex 的处理装完 npm 包一敲codex却报zsh: command not found: codex这是典型的全局 bin 目录没在 PATH 里。排查分两步npm prefix -g这条命令会输出 npm 全局根目录比如/usr/local或/Users/你的用户名/.nvm/versions/node/v20.x.x。然后把 bin 目录加进 shell 配置echo export PATH$PATH:$(npm prefix -g)/bin ~/.zshrc source ~/.zshrc之后codex --version就应该生效了。还有一个容易忽略的情况如果你用 nvm 管理 Node 版本切到另一个版本后全局包会“消失”这很正常——切回原来版本或者在新版本里重新npm install -g openai/codex即可。3. Windows 环境没有包管理器也能装明白3.1 推荐路径先装 Node再 npm 全局安装Windows 上没有类似 Homebrew 的统一命令行包管理器最省心的路线是打开 PowerShell强烈建议用 Windows Terminal它对 ANSI 颜色和交互式界面的支持好很多。安装 Node.js二选一winget install OpenJS.NodeJS.LTS或者去 Node.js 官网下载 Windows 安装包.msi安装时务必勾选“Add to PATH”选项。安装 Codexnpm install -g openai/codex验证codex --version看到版本号就成功了。3.2 PowerShell 权限和 PATH 的坑Windows 上最容易踩的三个坑我一个个说。第一个是安装时报EPERM: operation not permitted全局安装目录写不进去。原因是 Node 默认装在C:\Program Files\nodejs\普通用户对这个目录没有写权限。解决办法很直接用管理员身份打开 PowerShell再执行安装命令。第二个是装完提示codex 不是内部或外部命令。原因是 npm 全局目录不在系统 PATH 中。先查一下npm config get prefix输出一般是C:\Users\你的用户名\AppData\Roaming\npm把这个路径加到系统环境变量的 Path 里然后重新打开终端。注意环境变量改了之后已经打开的终端窗口不会自动刷新这点和 Mac 不一样。第三个是 PowerShell 执行策略拦截Set-ExecutionPolicy RemoteSigned -Scope CurrentUser有些 npm 全局包会生成.ps1脚本默认策略下 PowerShell 会拒绝运行执行上面这句授权当前用户即可。3.3 Git Bash 和 WSL 用户的备选方案Windows 上不少人装了 Git Bash。在 Git Bash 里执行npm install -g openai/codex和运行codex命令通常都没问题因为它模拟了 Unix 环境。但要注意Git Bash 的 PATH 格式和 Windows 原生的不一样某些环境变量可能需要重新设置。如果你电脑上有 WSLWindows Subsystem for Linux也可以在 WSL 里安装流程和 Linux 完全一致先在 WSL 里用 nvm 或 apt 装好 Node然后npm install -g openai/codex。使用习惯上更贴近 Mac 和 Linux。一个提醒把项目放在 WSL 自己的文件系统里读写性能更好放在/mnt/c/这类 Windows 挂载目录下性能会明显变差。3.4 Windows 安装器“安装未完成”的处理“codex windows安装未完成”这个热搜词我在帮助朋友排查时遇到过几次。多数情况是官网下载的桌面应用安装器在安装过程中中断或者安装到一半卡住残留目录导致二次安装失败。处理方式很直接先打开%LOCALAPPDATA%\Programs把里面残留的 Codex 或 ChatGPT 相关目录删掉再重新运行安装器。如果还是失败检查一下杀毒软件是否拦截了安装进程临时关掉防护再跑一次。4. 初始化与登录让 Codex CLI 真正跑起来4.1 登录 Codex浏览器授权和 token 两种方式CLI 装好之后终端里直接运行codex首次运行会提示登录自动打开浏览器跳到 ChatGPT 授权页。点确认后切回终端登录就完成了。整个过程和“用 GitHub CLI 登录”很像。如果你在服务器上或者环境没有浏览器可以用codex login它会给你一个链接和一段待输入的 code在能上网的机器上打开链接、登录、粘贴 code授权也能完成。token 或 API key 相关的能力范围会受账号类型限制免费号能跑但功能上限明显。登录之后再次运行codex就不会再问授权了。如果哪天提示登录过期重新执行codex login就行。4.2 两种任务姿势交互式和一次性执行登录之后就可以干活了。交互式 REPL直接输入codex回车进入一个对话界面你可以像聊天一样发任务帮我看看当前目录里的项目是干什么的列出核心文件和它们的作用Codex 会读目录、给出计划按y批准后动手执行。一次性执行不进入交互界面直接在命令里带上任务描述codex 修复 tests 目录下失败的单元测试非交互执行适合脚本codex -c 给 README.md 补一段安装说明如果你的版本比较老非交互模式的命令可能是codex exec 任务新版统一成了-c。在执行时加上--json还可以让输出变成结构化 JSON方便其他程序消费。首次跑任务建议拿一个小 demo 仓库练手别一上来就扔一个几十万行代码的大仓库既费 token也容易超时。4.3 沙盒、审批和自动执行安装之后的安全第一课Codex 默认启用沙盒机制文件系统大部分只读网络也受限。它动文件之前会先征求你的确认这相当于一个安全缓冲防止“看懂需求”变成“乱改代码”。默认情况只读沙盒改文件前询问。--sandbox danger-full-access放开全部权限。--full-auto自动批准所有操作几乎不需要你介入。我的建议非常明确不要一上来就--full-auto。先默认模式跑几轮观察它改文件的方式和命令执行逻辑确认它不会乱碰仓库之外的东西再考虑放开。毕竟 Codex 执行的是自然语言转换来的命令理解偏差是不可避免的多一层确认就少一次事故。5. IDE 接入VS Code、桌面应用、其他编辑器5.1 VS Code 扩展安装在 VS Code 扩展市场搜索 “Codex” 或 “OpenAI Codex”安装官方扩展。装完之后侧边栏会出现 Codex 面板首次使用需要登录 ChatGPT 账号过程跟 CLI 登录一致。扩展和 CLI 的使用体验差异很明显。IDE 里选中一段代码可以直接让它解释、重构或补测试最舒服的是改动的 diff 直接显示在编辑器里你可以逐行确认它改了哪里决定接不接受。这是命令行里做不到的直观感。5.2 “unable to locate the codex cli binary” 的排查链路这个报错该好好讲讲因为它的出现逻辑非常典型。完整信息一般是chatgpt failed to start. unable to locate the codex cli binary or required runtime一句话解释桌面应用或者 IDE 扩展启动 Codex 子进程时去系统 PATH 里找不到codex命令于是罢工。排查顺序如下在终端里试codex --version如果报 “不是内部或外部命令 / command not found”说明 CLI 根本没装上回头补装。如果 CLI 装了但桌面端还是报错确认 npm 全局 bin 目录在 PATH 里。重启桌面应用和 VS Code让新的环境变量生效。Windows 上改完环境变量最稳妥的做法是重启一次系统保险系数最高。这个报错是一个绝佳的例子你以为图形界面是独立的其实底层还是依赖 CLI。5.3 在 Cursor 等编辑器里调用 Codex 的轻量思路如果你不用 VS Code而是用 Cursor、Zed、Neovim 之类最简单的方式不是装插件而是把 Codex 当一个外部命令工具集成进来。把下面这条绑定到编辑器快捷键或者放进编辑器任务codex -c 帮我重构 src/utils.ts 里的 xxx 函数Codex 改完文件编辑器会自动刷新配合终端输出体验也不差。本质就是“编辑器里开一个终端干活”不用依赖任何插件生态。6. 折腾进阶把 Codex 接到 DeepSeek 等模型并排查本地代理报错6.1 config.tomlCodex 的核心配置位置Codex CLI 的配置文件路径Mac/Linux~/.codex/config.tomlWindows%USERPROFILE%\.codex\config.toml文件不存在就手动创建。它是 TOML 格式最常用是model_providers和model两块。6.2 把 Codex 接入 DeepSeek 的一份完整配置很多人在问“codex 接入 deepseek”官方其实支持自定义 model provider。我在本地实测可跑的一份配置如下# ~/.codex/config.toml model deepseek-chat model_provider deepseek [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com env_key DEEPSEEK_API_KEY然后去 DeepSeek 开放平台申请一个 API key加到系统环境变量里名为DEEPSEEK_API_KEY。Mac 上写入~/.zshrcexport DEEPSEEK_API_KEY你的keyWindows 上通过“系统属性 - 环境变量”添加同名变量。启动codex后用/model命令查看当前模型。如果远端模型不支持 Codex 的某些工具调用可能会降级成普通问答模式这是正常现象换更强一点的模型就行。其它兼容 OpenAI 协议的模型服务套路完全一样改name、base_url、env_key三处。6.3 “local proxy failed while handling codex endpoint /responses” 排查链路热搜词里那句cc switch local proxy failed while handling codex endpoint /responses. providing response with error message我第一次遇到时也头大但拆下来其实就几个原因。第一步查环境变量里的代理残留。env | grep -i proxy # Mac/Linux echo %HTTP_PROXY% # Windows如果HTTP_PROXY或HTTPS_PROXY指向了一个没启动的本地代理端口比如http://127.0.0.1:7890Codex 会把 API 请求转发给这个地址代理没响应就直接报local proxy failed。处理方式是移除或清空这些变量unset http_proxy https_proxyWindows 在系统环境变量编辑框里删掉对应项然后重启终端。正常的默认配置是不需要这些代理变量的。第二步检查 config.toml 里的 base_url。如果你在model_providers里把某个 provider 的base_url改成了localhost或127.0.0.1那也相当于把请求指向了本地代理。排查方式就是打开配置文件逐项确认 base_url 是否符合预期。不需要自定义 provider 时直接把相关段落删掉恢复默认指向 OpenAI 官方地址。第三步切换模型验证。用/model临时切回一个已知可用的模型排除“当前模型本身不可用”的可能。这套链路能覆盖九成以上的 local proxy 报错。核心思路就一句话Codex 说“本地代理失败”通常不是 Codex 坏了而是你把它的请求转发到了一个不通的中转地址。7. 高频报错排查清单照着这个顺序来报错或现象可能原因处理方式codex: command not foundnpm 全局 bin 目录不在 PATH按第 2.4 或 3.2 节添加 PATH重开终端EPERM: operation not permitted全局安装目录没有写权限管理员身份打开终端再执行 npm installchatgpt failed to start... locate the codex cli binary桌面端找不到 CLI 二进制先装好 CLI确认 PATH再重启桌面端local proxy failed while handling codex endpoint /responses环境变量或 base_url 指向无效代理按第 6.3 节三步排查codex login后浏览器一直转圈网络不通或代理残留移除代理变量确认网络正常重新登录npm install 超时或下载慢网络波动或镜像源问题可临时切换国内 npm 镜像源安装完改回默认源7.1 安装顺序为什么不能乱说了这么多我把最稳定的安装顺序列出来这也是我现在每次装新机器的固定流程装 Node.jsMac 用官网 pkg 最省心Windows 用 winget 或官网 msi。npm install -g openai/codex装 CLI。终端验证codex --version。codex login完成授权。跑一个小任务确认端到端流程通。再决定要不要装 VS Code 扩展或桌面端。这个顺序最大好处是每一步都能立刻验证不会出现 IDE 装好了结果 CLI 没装的连锁报错。7.2 这些都是我自己踩过的坑总结给你Homebrew 装不上时别死磕官网 pkg 包快得多。Windows 上codex命令失效时别急着重装先看 PATH。把 Codex 接第三方模型时base_url一定写对少一个斜杠都会导致请求失败。最关键的不要从--full-auto开始用那等于把写代码的刹车踩掉一半再上高速。我自己每次折腾完一个新环境都会顺手把终端里跑通的命令记在笔记里下次直接复制粘贴。像 Codex 这种更新频率快的工具保不准下个月命令又变了一点留一份自己的“安装手记”比什么都管用。
Codex安装实战：CLI/IDE/桌面端配置与排错指南
最近不止一个朋友跑来问我“Codex 装好了但在终端里敲codex告诉我不是内部或外部命令是怎么回事”还有同事装了 VS Code 扩展一启动就弹unable to locate the codex cli binary or required runtime。我先说一个结论Codex 不是一个“下载个 App 装完就完事”的工具它拆开了至少有 CLI、IDE 扩展、桌面应用三层很多人装一半就卡住不是因为不会敲命令而是没搞明白自己到底该装哪一层。这篇我打算把两条主线讲透一条是 Mac 和 Windows 两个平台分别怎么装一条是 CLI 和 IDE 两种使用方式怎么选、怎么配、怎么排错。文章中所有步骤都是我这段时间反反复复装出来的实测结果中间还掺了不少摔过的跟头。不管你是想把它接进自己最顺手的编辑器还是打算在自动化脚本里直接用命令行调用这篇都适合花十分钟看完然后照着一步步操作。1. 先搞清楚 Codex 的三层结构和两条路线1.1 Codex 不是单一软件而是“CLI IDE 桌面端”的组合Codex 本质是一个代理式编程工具你给我一句自然语言它自己去读你仓库里的文件、改代码、跑测试、甚至提交改动。它在安装层面拆成了三块这三块互相有关联但不等价Codex CLI一个命令行工具npm 包名是openai/codex装完之后你在终端里敲codex就能用。适合脚本化、自动化、CI 集成这些场景。IDE 扩展VS Code 插件安装后在编辑器侧边栏里出现 Codex 面板。它更适合你一边写代码一边让它帮忙改能直接看 diff。桌面应用ChatGPT 桌面端内置了 Codex可以在图形界面里新建 Codex 任务适合不想碰终端的人。很多人容易踩的坑就是以为装了桌面端就等于有了命令行工具结果在终端里输codex当然找不到。反过来也有人只装了 CLI跑到 VS Code 里找 Codex 面板当然也没有。还有一个关键关联很多 IDE 扩展和桌面应用在运行 Codex 子进程时会去找系统的codex二进制。这也是为什么热搜里那句chatgpt failed to start. unable to locate the codex cli binary or required runtime会出现得这么频繁——CLI 没装或者装了但 PATH 里找不到图形界面就跟着罢工。1.2 动手安装前这四件事先确认ChatGPT 账号Codex 登录用的是它。免费账号能体验但速率和可用功能有限Plus 或 Pro 账号体验完整得多。Node.js 18 或更高版本CLI 的安装依赖 npm所以 Node 是硬前提。如果只走桌面端应用Node 可以暂时不装但走命令行这一步绕不开。网络环境要能正常访问 OpenAI 的服务登录授权、向模型发请求都需要网络通。如果你本机开了代理工具建议先把代理去掉再装免得装一半卡住后面第 6 章会专门讲 proxy 报错。磁盘空间不用太担心Codex 本身只有几十 MB真正的模型运算都在云端本地不占太多东西。我的建议是无论你最终目的是 CLI 还是 IDE都先把 CLI 装好。因为 IDE 扩展和桌面端在底层都会去找它你先把地基建好后面所有入口都通畅了。2. Mac 环境把 Homebrew、Node、PATH 一次理顺2.1 最快路径npm 全局安装Mac 上装 Codex CLI 最直接的方式就是 npmnpm install -g openai/codex装完之后验证版本codex --version能看到版本号比如0.x.x就说明 CLI 装好了。以后要更新也很方便npm update -g openai/codex为什么我推荐走 npm 而不是 Homebrew因为 Codex 的发布节奏很快npm 是官方同步最快的渠道而且版本回退也简单npm install -g openai/codex具体版本号就能锁定旧版。如果你之前用老办法装过早期版本直接用 npm 覆盖装一遍也可行。2.2 Mac 上装 Node 的 Homebrew 报错排查很多 Mac 用户会先通过 Homebrew 装 Nodebrew install node但“mac安装homebrew报错”这个热搜词不是没原因的。我遇到过的典型问题有两类第一类是执行 Homebrew 官方安装脚本时提示curl: (7) Failed to connect to raw.githubusercontent.com port 443这类连接错误。遇上这种问题先看看终端里有没有残留的代理环境变量env | grep -i proxy如果有输出先unset http_proxy、unset https_proxy确认网络恢复正常后再跑安装脚本。如果没有任何代理输出但依然连不上那大概率是当前网络本身的问题。不要钻牛角尖直接换个路子去 Node.js 官网下载 macOS 安装包.pkg安装完自带node和npm完全不依赖 Homebrew。第二类是权限报错。老款 Intel Mac 的/usr/local目录常见权限问题报Permission denied时用下面这条修复ls -ld /usr/local sudo chown -R $(whoami) /usr/localApple SiliconM 系列芯片的 Homebrew 装在/opt/homebrew同样方式处理。注意chown要慎重只针对 Homebrew 涉及的目录别对整个系统目录来一遍。2.3 dmg 安装的桌面应用和 CLI 是什么关系也有人在官网下载了 ChatGPT 桌面端装完发现终端还是不能用codex命令。这是预期中的结果桌面端安装包自带运行环境它内置了 Codex 功能但不往系统 PATH 里放命令行工具。一句话总结分工你只想在图形界面里和 Codex 对话比如“帮我看一下这个项目的结构”那就用桌面应用。你想在脚本里写codex -c ...或者在终端里持续交互那就必须单独装 CLI。两边不冲突装完 CLI 再打开桌面应用体验反而更顺因为桌面端能找到底层命令了。2.4 zsh 提示 command not found: codex 的处理装完 npm 包一敲codex却报zsh: command not found: codex这是典型的全局 bin 目录没在 PATH 里。排查分两步npm prefix -g这条命令会输出 npm 全局根目录比如/usr/local或/Users/你的用户名/.nvm/versions/node/v20.x.x。然后把 bin 目录加进 shell 配置echo export PATH$PATH:$(npm prefix -g)/bin ~/.zshrc source ~/.zshrc之后codex --version就应该生效了。还有一个容易忽略的情况如果你用 nvm 管理 Node 版本切到另一个版本后全局包会“消失”这很正常——切回原来版本或者在新版本里重新npm install -g openai/codex即可。3. Windows 环境没有包管理器也能装明白3.1 推荐路径先装 Node再 npm 全局安装Windows 上没有类似 Homebrew 的统一命令行包管理器最省心的路线是打开 PowerShell强烈建议用 Windows Terminal它对 ANSI 颜色和交互式界面的支持好很多。安装 Node.js二选一winget install OpenJS.NodeJS.LTS或者去 Node.js 官网下载 Windows 安装包.msi安装时务必勾选“Add to PATH”选项。安装 Codexnpm install -g openai/codex验证codex --version看到版本号就成功了。3.2 PowerShell 权限和 PATH 的坑Windows 上最容易踩的三个坑我一个个说。第一个是安装时报EPERM: operation not permitted全局安装目录写不进去。原因是 Node 默认装在C:\Program Files\nodejs\普通用户对这个目录没有写权限。解决办法很直接用管理员身份打开 PowerShell再执行安装命令。第二个是装完提示codex 不是内部或外部命令。原因是 npm 全局目录不在系统 PATH 中。先查一下npm config get prefix输出一般是C:\Users\你的用户名\AppData\Roaming\npm把这个路径加到系统环境变量的 Path 里然后重新打开终端。注意环境变量改了之后已经打开的终端窗口不会自动刷新这点和 Mac 不一样。第三个是 PowerShell 执行策略拦截Set-ExecutionPolicy RemoteSigned -Scope CurrentUser有些 npm 全局包会生成.ps1脚本默认策略下 PowerShell 会拒绝运行执行上面这句授权当前用户即可。3.3 Git Bash 和 WSL 用户的备选方案Windows 上不少人装了 Git Bash。在 Git Bash 里执行npm install -g openai/codex和运行codex命令通常都没问题因为它模拟了 Unix 环境。但要注意Git Bash 的 PATH 格式和 Windows 原生的不一样某些环境变量可能需要重新设置。如果你电脑上有 WSLWindows Subsystem for Linux也可以在 WSL 里安装流程和 Linux 完全一致先在 WSL 里用 nvm 或 apt 装好 Node然后npm install -g openai/codex。使用习惯上更贴近 Mac 和 Linux。一个提醒把项目放在 WSL 自己的文件系统里读写性能更好放在/mnt/c/这类 Windows 挂载目录下性能会明显变差。3.4 Windows 安装器“安装未完成”的处理“codex windows安装未完成”这个热搜词我在帮助朋友排查时遇到过几次。多数情况是官网下载的桌面应用安装器在安装过程中中断或者安装到一半卡住残留目录导致二次安装失败。处理方式很直接先打开%LOCALAPPDATA%\Programs把里面残留的 Codex 或 ChatGPT 相关目录删掉再重新运行安装器。如果还是失败检查一下杀毒软件是否拦截了安装进程临时关掉防护再跑一次。4. 初始化与登录让 Codex CLI 真正跑起来4.1 登录 Codex浏览器授权和 token 两种方式CLI 装好之后终端里直接运行codex首次运行会提示登录自动打开浏览器跳到 ChatGPT 授权页。点确认后切回终端登录就完成了。整个过程和“用 GitHub CLI 登录”很像。如果你在服务器上或者环境没有浏览器可以用codex login它会给你一个链接和一段待输入的 code在能上网的机器上打开链接、登录、粘贴 code授权也能完成。token 或 API key 相关的能力范围会受账号类型限制免费号能跑但功能上限明显。登录之后再次运行codex就不会再问授权了。如果哪天提示登录过期重新执行codex login就行。4.2 两种任务姿势交互式和一次性执行登录之后就可以干活了。交互式 REPL直接输入codex回车进入一个对话界面你可以像聊天一样发任务帮我看看当前目录里的项目是干什么的列出核心文件和它们的作用Codex 会读目录、给出计划按y批准后动手执行。一次性执行不进入交互界面直接在命令里带上任务描述codex 修复 tests 目录下失败的单元测试非交互执行适合脚本codex -c 给 README.md 补一段安装说明如果你的版本比较老非交互模式的命令可能是codex exec 任务新版统一成了-c。在执行时加上--json还可以让输出变成结构化 JSON方便其他程序消费。首次跑任务建议拿一个小 demo 仓库练手别一上来就扔一个几十万行代码的大仓库既费 token也容易超时。4.3 沙盒、审批和自动执行安装之后的安全第一课Codex 默认启用沙盒机制文件系统大部分只读网络也受限。它动文件之前会先征求你的确认这相当于一个安全缓冲防止“看懂需求”变成“乱改代码”。默认情况只读沙盒改文件前询问。--sandbox danger-full-access放开全部权限。--full-auto自动批准所有操作几乎不需要你介入。我的建议非常明确不要一上来就--full-auto。先默认模式跑几轮观察它改文件的方式和命令执行逻辑确认它不会乱碰仓库之外的东西再考虑放开。毕竟 Codex 执行的是自然语言转换来的命令理解偏差是不可避免的多一层确认就少一次事故。5. IDE 接入VS Code、桌面应用、其他编辑器5.1 VS Code 扩展安装在 VS Code 扩展市场搜索 “Codex” 或 “OpenAI Codex”安装官方扩展。装完之后侧边栏会出现 Codex 面板首次使用需要登录 ChatGPT 账号过程跟 CLI 登录一致。扩展和 CLI 的使用体验差异很明显。IDE 里选中一段代码可以直接让它解释、重构或补测试最舒服的是改动的 diff 直接显示在编辑器里你可以逐行确认它改了哪里决定接不接受。这是命令行里做不到的直观感。5.2 “unable to locate the codex cli binary” 的排查链路这个报错该好好讲讲因为它的出现逻辑非常典型。完整信息一般是chatgpt failed to start. unable to locate the codex cli binary or required runtime一句话解释桌面应用或者 IDE 扩展启动 Codex 子进程时去系统 PATH 里找不到codex命令于是罢工。排查顺序如下在终端里试codex --version如果报 “不是内部或外部命令 / command not found”说明 CLI 根本没装上回头补装。如果 CLI 装了但桌面端还是报错确认 npm 全局 bin 目录在 PATH 里。重启桌面应用和 VS Code让新的环境变量生效。Windows 上改完环境变量最稳妥的做法是重启一次系统保险系数最高。这个报错是一个绝佳的例子你以为图形界面是独立的其实底层还是依赖 CLI。5.3 在 Cursor 等编辑器里调用 Codex 的轻量思路如果你不用 VS Code而是用 Cursor、Zed、Neovim 之类最简单的方式不是装插件而是把 Codex 当一个外部命令工具集成进来。把下面这条绑定到编辑器快捷键或者放进编辑器任务codex -c 帮我重构 src/utils.ts 里的 xxx 函数Codex 改完文件编辑器会自动刷新配合终端输出体验也不差。本质就是“编辑器里开一个终端干活”不用依赖任何插件生态。6. 折腾进阶把 Codex 接到 DeepSeek 等模型并排查本地代理报错6.1 config.tomlCodex 的核心配置位置Codex CLI 的配置文件路径Mac/Linux~/.codex/config.tomlWindows%USERPROFILE%\.codex\config.toml文件不存在就手动创建。它是 TOML 格式最常用是model_providers和model两块。6.2 把 Codex 接入 DeepSeek 的一份完整配置很多人在问“codex 接入 deepseek”官方其实支持自定义 model provider。我在本地实测可跑的一份配置如下# ~/.codex/config.toml model deepseek-chat model_provider deepseek [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com env_key DEEPSEEK_API_KEY然后去 DeepSeek 开放平台申请一个 API key加到系统环境变量里名为DEEPSEEK_API_KEY。Mac 上写入~/.zshrcexport DEEPSEEK_API_KEY你的keyWindows 上通过“系统属性 - 环境变量”添加同名变量。启动codex后用/model命令查看当前模型。如果远端模型不支持 Codex 的某些工具调用可能会降级成普通问答模式这是正常现象换更强一点的模型就行。其它兼容 OpenAI 协议的模型服务套路完全一样改name、base_url、env_key三处。6.3 “local proxy failed while handling codex endpoint /responses” 排查链路热搜词里那句cc switch local proxy failed while handling codex endpoint /responses. providing response with error message我第一次遇到时也头大但拆下来其实就几个原因。第一步查环境变量里的代理残留。env | grep -i proxy # Mac/Linux echo %HTTP_PROXY% # Windows如果HTTP_PROXY或HTTPS_PROXY指向了一个没启动的本地代理端口比如http://127.0.0.1:7890Codex 会把 API 请求转发给这个地址代理没响应就直接报local proxy failed。处理方式是移除或清空这些变量unset http_proxy https_proxyWindows 在系统环境变量编辑框里删掉对应项然后重启终端。正常的默认配置是不需要这些代理变量的。第二步检查 config.toml 里的 base_url。如果你在model_providers里把某个 provider 的base_url改成了localhost或127.0.0.1那也相当于把请求指向了本地代理。排查方式就是打开配置文件逐项确认 base_url 是否符合预期。不需要自定义 provider 时直接把相关段落删掉恢复默认指向 OpenAI 官方地址。第三步切换模型验证。用/model临时切回一个已知可用的模型排除“当前模型本身不可用”的可能。这套链路能覆盖九成以上的 local proxy 报错。核心思路就一句话Codex 说“本地代理失败”通常不是 Codex 坏了而是你把它的请求转发到了一个不通的中转地址。7. 高频报错排查清单照着这个顺序来报错或现象可能原因处理方式codex: command not foundnpm 全局 bin 目录不在 PATH按第 2.4 或 3.2 节添加 PATH重开终端EPERM: operation not permitted全局安装目录没有写权限管理员身份打开终端再执行 npm installchatgpt failed to start... locate the codex cli binary桌面端找不到 CLI 二进制先装好 CLI确认 PATH再重启桌面端local proxy failed while handling codex endpoint /responses环境变量或 base_url 指向无效代理按第 6.3 节三步排查codex login后浏览器一直转圈网络不通或代理残留移除代理变量确认网络正常重新登录npm install 超时或下载慢网络波动或镜像源问题可临时切换国内 npm 镜像源安装完改回默认源7.1 安装顺序为什么不能乱说了这么多我把最稳定的安装顺序列出来这也是我现在每次装新机器的固定流程装 Node.jsMac 用官网 pkg 最省心Windows 用 winget 或官网 msi。npm install -g openai/codex装 CLI。终端验证codex --version。codex login完成授权。跑一个小任务确认端到端流程通。再决定要不要装 VS Code 扩展或桌面端。这个顺序最大好处是每一步都能立刻验证不会出现 IDE 装好了结果 CLI 没装的连锁报错。7.2 这些都是我自己踩过的坑总结给你Homebrew 装不上时别死磕官网 pkg 包快得多。Windows 上codex命令失效时别急着重装先看 PATH。把 Codex 接第三方模型时base_url一定写对少一个斜杠都会导致请求失败。最关键的不要从--full-auto开始用那等于把写代码的刹车踩掉一半再上高速。我自己每次折腾完一个新环境都会顺手把终端里跑通的命令记在笔记里下次直接复制粘贴。像 Codex 这种更新频率快的工具保不准下个月命令又变了一点留一份自己的“安装手记”比什么都管用。
