1. 为什么我最终把 AI 编程的战场从网页搬回了终端用了大半年网页版 ChatGPT 写代码我最大的感受是上下文割裂。浏览器里问一段、IDE 里粘一段、终端里跑一段思路和代码在三个窗口之间来回跳很容易断片。后来试着用了几款 AI 编程助手插件虽然补全做得不错但稍微复杂一点的重构、跨文件修改、让 AI 自己跑命令验证结果这些活儿它们干得并不利索。Codex CLI 出现在我视野里是因为它在技术社区的口碑很特别——不是又一个 AI 插件而是一个住在终端里的 AI 同事。你给它一个任务它不光能改代码还能自己执行命令、运行测试、查看结果、迭代修改一套流程走完。它不抢你 IDE 的位置也不需要你改变已经在用的编辑器只用你早就熟悉的命令行。这篇攻略不打算写成官方文档的翻译稿我按自己的实操路径来先讲清楚 Codex CLI 的核心设计思路再带你完成三大平台的安装配置接着从日常交互说起一直深入到沙箱机制、无人值守执行和多会话并行这些高级玩法最后把我踩过、也见过别人踩的坑集中整理一遍。不管你是刚接触终端的新手还是在找替代 Copilot CLI 的老手照着这份流程走完应该能比较顺畅地把它跑起来。先说结论Codex CLI 不是什么魔法它就是一个命令行前端把 OpenAI 的代码模型和本地终端环境连接了起来。你不需要学新语言不需要装重型依赖唯一需要习惯的是把写代码这件事的一部分决策权交给 AI然后学会审核它做的事。2. 安装前的准备版本要求与账号认证2.1 环境最低要求和一份安装清单Codex CLI 的安装门槛很低但有几个前置条件必须满足否则后面会卡在各种奇怪的报错上这我深有体会。首先它本质上是 Node.js 的 npm 包所以系统里必须要有Node.js 和 npm官方建议 Node.js 18 或更高版本实测 20 系列和 22 系列都跑得很稳。检查方法是在终端里执行node -v npm -v如果输出是v18.x.x以上和9.x.x以上那就没问题。版本太旧的话建议先去官网把 Node.js 升级到当前 LTS 版本不要用太老的发行版硬撑Codex CLI 的一些依赖对较新的 API 有要求。除了 Node.js平台相关的准备项不太一样平台必需组件推荐终端环境可选增强macOSNode.js 18、Xcode Command Line Tools系统自带 Terminal / iTerm2HomebrewLinux (Ubuntu/Debian)Node.js 18、build-essential、gitGNOME Terminal / Tabbyfish/zshWindowsNode.js 18、Git for WindowsWindows Terminal Git BashWSL2Windows 上的情况比较特殊后面我会单独讲。这里想额外提一句终端工具的选择我本人长期用 Tabby 和 Windows Terminal 这类现代终端它们对 ANSI 颜色、Unicode 图标、快捷键绑定的支持更好Codex CLI 的交互界面在这些终端里显示得最舒服。如果你还在用老旧的 cmd建议先换掉。另外记得检查git是否能正常执行。Codex CLI 会自动把工作目录识别成 Git 仓库来追踪文件改动如果 git 不可用部分功能会受限。Linux 上如果还没装先执行sudo apt install git。2.2 OpenAI 账号与 API Key 获取安装之前还需要一个 OpenAI 账号和对应的 API Key。这一步很多人会忽略权限问题我多说几句在 platform.openai.com 注册并登录后进入 API Keys 页面创建一个新的 Secret Key。创建时注意两点API Key 只在创建时完整显示一次关闭页面后就再也看不到了务必保存到本地密码管理器里。Codex CLI 的调用走的是 API 计费通道和 ChatGPT Plus 的订阅费是两套体系需要预先充值或者账号本身绑定了付款方式否则调用时会返回 401 或 429 错误。认证这一块Codex CLI 提供了浏览器登录的方式在终端执行codex login会弹出一个 URL授权后自动写入本地凭据。也有 OCR 方式输入 API Key适合无法弹出浏览器的服务器环境codex login --api-key sk-xxxx我个人建议尽量用浏览器登录方式让它自动管理刷新令牌省得 API Key 过期后还要手动换。还有一种情况是登录时跳转卡住多半是网络代理干扰把代理关了重试或换一个网络环境就能解决。3. 三平台安装实录从一行命令到验证成功3.1 macOS 与 Linux 的安装流程macOS 和主流 Linux 发行版的安装方式几乎一样核心就一条命令加一步验证。先全局安装 npm 包npm install -g openai/codex如果系统提示权限不足比如EACCES错误说明 npm 的全局路径没有对当前用户开放写权限。有两个解决方案一是前面先用sudo npm install -g openai/codex快速装完但这会让全局包由 root 管理之后升级比较麻烦二是把 npm 全局路径改到用户目录这是更干净的姿势mkdir -p ~/.npm-global npm config set prefix ~/.npm-global echo export PATH~/.npm-global/bin:$PATH ~/.bashrc source ~/.bashrc改完之后重新执行 npm 安装就不需要 sudo 了。安装完成后验证codex --version正常情况下会打印类似codex-cli/0.x.x的版本号。如果提示command not found多数是 PATH 没包含 npm 全局 bin 目录上面已经处理了。macOS 用户如果偏好 Homebrew也可以执行brew install codex效果类似只是后续升级方式变成brew upgrade codex。两条路选一条就行不用重复安装。3.2 Windows 安装WSL 与 Git Bash 的取舍Windows 是安装 Codex CLI 出问题最多的平台我几乎每周都能在社区里看到 Windows 用户的报错截图。最大的坑是winpty和conpty这类的终端兼容层问题——Codex CLI 是一个交互式终端应用对伪终端能力要求比较高Windows 自带的 cmd 和 PowerShell 在某些配置下无法正常承载它。所以在 Windows 上我的建议是二选一方案 AWSL2 Ubuntu 子系统推荐在管理员 PowerShell 里执行wsl --install重启后进入 Ubuntu然后在 Ubuntu 的终端里按照 Linux 方式安装 Node.js 和 Codex CLI。WSL2 的优势在于完整的 POSIX 环境CI/CD、脚本、权限模型全都贴近 Linux后续用起来最省心。缺点是有轻微的文件 I/O 性能损耗不过做 AI 编程日常任务完全感觉不出来。方案 BWindows Terminal Git Bash如果你不想装 WSL那就安装 Windows Terminal 和 Git for Windows。Git Bash 提供了一个最小化的 Unix 环境能跑npm和codex但它有个老毛病交互式程序对 winpty 的依赖。以前很多工具需要winpty codex这种方式才能跑起来新版 Codex CLI 支持得还行但偶尔还是会遇到界面刷新异常。遇到这种情况可以试试在 Git Bash 的启动脚本里加一行export NO_COLOR1把着色关闭某些渲染问题能缓解不过这只是权宜之计。长远来看建议 Windows 用户直接上 WSL2。安装完先跑codex --version验证看到版本号就说明 Bin 目录已经在 PATH 中了。3.3 登录认证与第一个会话安装好 Codex CLI 后输入codex启动。首次启动会自动检测登录状态未登录的话会显示一个 One Time Passcode 和一个 URL。重要提示先把 URL 完整复制到浏览器打开再输入 OTP 授权。不要试图自己拼接 URL容易漏掉参数导致授权失败。授权成功之后终端里会提示 Welcome to Codex。从这一刻起你就可以直接输入自然语言任务了。比如让它列出当前目录的 Python 文件Codex CLI 会调用工具来执行ls *.py并返回结果。第一印象是它的响应速度比网页版快因为它只做上下文相关的轻量交互不用带着整个聊天历史跑来跑去。如果登录后报authentication failed多半是代理干扰或系统时间不同步。检查一下date输出的时间是否正确再把代理临时关闭试一次大概率能解决。4. 日常使用掌握 Codex CLI 的交互模式4.1 会话、斜杠命令与多行输入技巧Codex CLI 启动后进入的是一个交互式 REPL 环境。你输入的自然语言指令会变成对终端的操作AI 会展示它打算执行的命令然后等你确认。默认情况下执行命令前需要手动确认这样能防止 AI 自作主张做出危险操作。最基本的几个斜杠命令建议先记住/model # 切换模型 /quit # 退出会话 /status # 查看当前会话状态 /clear # 清空上下文 /help # 查看全部命令这里需要解释一个很多人都问过的问题在 Codex CLI 的多行输入场景里怎么换到上一行熟悉传统终端的用户会习惯用上下方向键来翻历史但 Codex CLI 的交互模式里上下方向键也有自己的逻辑。如果你已经输入了几行内容想回到上一行修改按CtrlP前一行和CtrlN下一行是更可靠的方式这是 Emacs 风格的快捷键绑定。方向键在历史命令和当前输入之间切换容易让人困惑。如果你需要输入多行任务描述比如粘贴一段需求文档建议先打开文本编辑器组织好内容再整体粘贴进来比在 REPL 里逐行输入可控得多。粘贴时如果出现格式错乱注意终端是否处于括号粘贴模式现代终端基本都自动支持但老旧终端需要手动开启。4.2 让 Codex CLI 看懂你的项目结构Codex CLI 不是凭空写代码的它需要理解当前目录的文件结构和上下文。所以日常使用有一个铁律在项目根目录下启动 Codex CLI这样它才能正确解析整个项目的文件树、依赖配置和 Git 状态。比如你有一个 Python Django 项目启动前先确认当前路径cd ~/projects/my-django-app codex然后对它说修复 user 模型缺少 updated_at 字段的问题它会先查看models.py、相关迁移文件再给出修改方案并执行测试。这个过程中它是在真实的工作目录里操作文件每一次改动都会以 Git diff 的形式展示出来你可以看到它改了哪些行、新增了哪些行。如果项目特别大默认上下文窗口可能会被文件树撑爆。我有个项目有一千多个文件Codex CLI 有时候会漏看一些模块。解决办法是先在任务描述里明确指定范围比如只关注app/apis/目录下的代码这样它能更精准地定位相关文件。4.3 多文件编辑与 Git 变更审核Codex CLI 最爽的功能之一是多文件编辑。你给它一个跨文件的重构任务比如把整个项目里所有requests.get调用换成httpx.get它会自己找出所有相关文件、逐一修改然后汇总展示一份改动清单。关键流程是这样的Codex CLI 在修改文件之前通常会先扫描项目结构判断哪些文件涉及改动。修改时它会在终端里展示 diff 片段你可以选择接受、拒绝或者让它重新调整。实测下来对于几十个文件的大规模改动它的处理速度比人肉搜索替换快几个数量级但审核的主动权必须在你手里。我习惯在每个改动确认前问自己三个问题这个改动是不是最小化的有没有顺手改了不该改的东西。改动后测试能过吗有没有引入新的边界问题。如果这是我自己写的我会用这种方式实现吗Codex CLI 支持全部接受Accept all或逐个确认我强烈建议逐个确认哪怕麻烦一点也值得。见过不少开发者图省事一股脑接受结果带入了一个隐形的行为变化排查了好几天才发现是 AI 改的。AI 只是工具不是你放弃代码解释权的理由。4.4 沙箱机制白名单、黑名单与命令审批逻辑Codex CLI 执行终端命令时默认包了一层沙箱这是它跟普通代码生成器最本质的区别。沙箱的职责是控制命令执行权限防止 AI 跑出危险操作。默认规则可以总结为白名单命令直接执行不需要确认。比如ls、cat、git status、pwd这类只读命令。黑名单命令直接拒绝。比如rm -rf /这类毁灭性命令无论如何都会被拦下来。其他命令需要你手动确认。比如pip install、npm run migrate、git push。你可以通过配置文件自定义规则。Codex CLI 的配置文件路径在~/.codex/config.toml首次启动后会自动创建。想运行敏感命令时加上--sandbox danger-full-access参数可以放开全部限制但千万不要在重要项目上这么做。我见过有开发者在生产环境的目录里用 full access 模式跑AI 一键执行了git push --force直接把远端历史推没了只能全员回滚。这个沙箱设计在我看来是 Codex CLI 最可靠的机制之一。它把 AI 的能力限制在你允许的范围内不是单纯相信 AI 不会做坏事而是从机制上让它做不了坏事。5. 深度玩法从交互模式到无人值守 Agent5.1 Agent 模式非交互式任务执行除了交互式 REPLCodex CLI 还提供了exec模式也就是一次性执行模式。这个模式非常契合 CI/CD、批量任务、自动化脚本场景。语法很简单codex exec 修复 src/utils/date.ts 里的时区计算 bug并运行测试确认这条命令会启动一个会话执行任务结束后自动退出全程不需要人工介入。输出结果可以直接重定向到日志文件codex exec 给 README.md 补充 Windows 安装步骤 result.log 21实测在无人值守场景下exec模式用处非常大。比如我在 CI 流水线里加了一步每次打包前让 Codex CLI 检查代码风格并自动修复小问题遇到无法自动修复的再报警。这比让代码风格检查只输出报错要高效得多因为修复工作被 AI 自动消化掉了。不过要注意CI 环境里跑exec模式需要预先配置好 API Key 环境变量通常设置一个OPENAI_API_KEY即可。exec模式还有几个参数值得了解一下codex exec 任务描述 --model gpt-5-codex # 指定模型 codex exec 任务描述 --sandbox read-only # 沙箱只读AI 不能改文件 codex exec 任务描述 --skip-git-repo-check # 跳过 git 仓库检测谨慎5.2 多会话并行同时开多个 Codex CLI 实例很多开发者会问Codex CLI 能不能同时跑多个任务 答案是可以的但需要注意资源消耗和上下文隔离。Codex CLI 本身就是按独立进程设计的。你可以同时打开多个终端标签页每个标签页里各自启一个codex分别处理不同的任务。比如一个会话在重构接口层另一个会话在补测试用例两者互不干扰。不过有几个实测下来的注意点API 速率限制多个会话同时跑API 请求量会成倍增加。如果账号是低额度档位容易在高峰时段触发 429 限流。偶尔一两个会话并行没问题批量并行任务最好走企业账号或需求限制速率。文件冲突两个会话同时修改同一个文件后保存的会覆盖先保存的改动。这就像两个人同时编辑同一份文档最后保存的赢。解决方法是把不同会话放在不同的子目录或分支里最后用 Git merge 合并。上下文独立每个会话的记忆是独立的会话 A 讨论过的上下文会话 B 完全不知道。如果需要跨会话共享信息把需求写成文档放进项目里需要时让 AI 读文档。5.3 通过 MCP 扩展 Codex 的能力边界MCP 可能很多人还不熟悉简单说它是一套标准协议让 AI 应用能够调用外部工具和数据源。Codex CLI 支持通过 MCP 接入各种服务从而突破只能操作本地文件的限制。比如我可以让 Codex CLI 通过 MCP 连接数据库它就能直接查询线上数据库的 schema 和采样数据来辅助代码修改。也可以连接内部 Wiki写代码时自动参考团队最新的接口文档。这一块的能力扩展空间很大具体配置方式依赖于你要接入的服务核心流程是在config.toml里声明 MCP server 地址和认证信息[mcp_servers.my-db] command npx args [-y, my-mcp-server, --token, xxx]配置完成后重启 Codex CLI它就能自动发现这个 MCP server 提供的工具。注意接入外部数据源会带来额外的安全风险尤其是数据库查询能力建议严格限制在只读权限。5.4 终端复用工具配合方案前面提到热词里有终端复用和tabby终端工具这个搭配确实值得介绍。我自己日常的姿势是用 Tabby 或 tmux 作为终端复用层在同一个窗口里分屏跑多个 Codex CLI 会话左边一个审核 diff右边一个跑测试中间一个写代码。这样不用来回切换标签页效率高很多。如果你用 tmux可以设置快捷键快速分屏# 水平分屏 Ctrlb # 垂直分屏 Ctrlb %配合 tmux 的会话持久化功能即使关掉终端窗口Codex CLI 会话依然在后台存活重新 attach 回来就能继续工作。这对跑长时间任务特别友好比如让 Codex CLI 做一次覆盖全项目的大规模重构中途有事要离开直接断开会话回来后任务还在跑。6. 常见报错与排查技巧实录6.1 unable to locate the codex cli binary 全解析这个报错是搜索热词里的高频问题凡是尝试把 Codex CLI 接入 IDE 或第三方工具的人几乎都会踩一次。它的完整提示通常是unable to locate the codex cli binary. set codex_cli_path or ensure the electron resources include bin/codex.这个报错虽然长但核心信息只有一句系统找不到 codex 这个可执行文件的路径。出现这个错误的原因有几个层次最简单的情况Codex CLI 根本没有正确安装。先用codex --version确认命令是否存在。如果不存在重新执行 npm 全局安装。PATH 环境变量不完整npm 全局 bin 目录不在当前环境的 PATH 里。比如你通过交互式 shell 安装但 IDE 里的子进程没有继承完整环境变量。解决方法是找到 codex 的实际路径which codex在 Linux/macOS 下会输出类似/usr/local/bin/codex或~/.npm-global/bin/codex的路径。然后把这个路径配置给第三方工具。比如某些 IDE 设置里有codex_cli_path的项手动填上完整路径即可。Electron 环境的特殊问题如果报错信息里带electron resources说明涉及 Electron 应用内置 CLI 的寻址问题。这类场景通常不是 PATH 问题而是插件或应用本身内置的 CLI 分发不完整。排查思路是检查应用版本是否最新、插件是否需要单独安装配套的 CLI 组件。总结成排查表格症状可能原因解决方案codex: command not foundnpm 全局 bin 不在 PATH将 npm 全局 bin 目录加入 PATHIDE 报 unable to locateIDE 进程环境变量不完整手动配置 codex_cli_path 为绝对路径Electron 应用内报错内置 CLI 组件缺失或版本不匹配更新应用到最新版重装 CLI 组件路径里能执行但工具找不到符号链接或别名干扰用 which codex 定位真实路径后写死6.2 Windows 平台conpty、winpty 与终端启动失败Windows 用户报错的关键词还有这一组终端进程启动失败: 启动期间发生本机异常(无法启动 conpty)。已移除 winpty。这个问题看起来像是 Codex CLI 的锅但根子其实在终端环境上。conpty是 Windows 的新版伪终端 APIwinpty是第三方提供的兼容层。某些旧版终端工具或 IDE 内置终端无法正确创建 conpty 会话时会退回到 winpty 模式但 Codex CLI 的交互式渲染需要较完整的 ANSI 终端能力两者衔接不好就会启动失败。排查顺序换用Windows Terminal而不是 cmd 或旧版 PowerShell。如果能用 WSL2直接在 WSL2 的终端里跑 Codex CLI绕开 Windows 原生终端的所有兼容性问题。检查终端版本是否过旧Windows Terminal 的更新中不断修复 conpty 相关问题。6.3 登录、API Key 与限流错误登录过程中的常见问题不多但 API 相关的错误却五花八门401 invalid_api_key说明 API Key 无效或已过期。方案重新登录或重新设置环境变量OPENAI_API_KEY。429 rate_limit_exceeded超出速率限制或余额不足。方案去控制台查看用量和余额提高限额或降低请求频率。403 forbidden账号权限不足可能代码模型对该账号不可用。方案确认账号是否有 Codex API 访问权限。这些错误在 Codex CLI 交互界面里会以红色报错信息展现在 exec 模式下会以非零退出码结束进程。建议在脚本里加上退出码判断方便 CI 流程感知失败状态codex exec ... 21 if [ $? -ne 0 ]; then echo Codex 任务执行失败 exit 1 fi6.4 沙箱误拒与命令执行不了的问题沙箱机制虽然保证了安全但有时候也会误伤合法操作。比如你想让 Codex CLI 执行docker build如果 docker 命令不在白名单里它会停下来问你确认。正常场景下确认一下就放行了。但有一种情况让人头疼配置了自定义规则却仍然弹出确认框。检查一下config.toml的规则写法[permissions] allow [docker run, docker build] ask [git push] deny [rm -rf /]注意规则匹配是前缀匹配还是精确匹配不同版本的 Codex CLI 行为略有差异。如果规则太宽泛所有命令都被匹配到ask或deny里交互体验会变得很糟糕。建议规则尽量写具体一些比如docker run就只匹配这一个动作不要写成docker这样可以减少很多无谓的确认。6.5 上下文超限或响应变慢的排查Codex CLI 在使用一段时间后可能会感觉响应变慢。这通常不是因为网络而是因为会话上下文积累得太长。AI 每次生成前都需要处理完整的历史会话记录历史越长耗时越高费用也越高。排查方法用/status查看当前会话的 token 使用情况。用/clear清空历史开启新话题。大任务拆成小任务一个会话只干一件事。还有一个技巧在任务描述里提醒 AI 忽略历史上下文比如先忽略之前的讨论现在只关注这个具体问题。虽然不是每个模型都严格遵循但实测对响应速度和输出准确性有帮助。7. 从工具到工作流Codex CLI 怎么融入团队协作聊完功能细节我想把视角拉高一点。Codex CLI 最有价值的地方不是单机环境里的效率提升而是它可以被整合进团队协作的整个流程中。举个例子我们团队现在把 Codex CLI 的exec模式接入了代码评审辅助流程。提交 PR 之后流水线会自动跑一个步骤用 Codex CLI 对改动做一次AI 评审重点检查明显的边界错误、意外删除、安全隐患。它不是替代人工 reviewer而是当一个最初的检查器把低级问题提前筛掉人工评审就能集中精力看设计逻辑。实际跑了两个月效果相当明显PR 的平均往返轮次降了不少。再比如Codex CLI 可以配合 Git flow 做自动化补丁生成。你只需要写清楚需求背景和期望行为让它直接基于 main 分支新建一个开发分支、完成实现、提交代码然后推送到远端。配合公司的代码规范模板AI 生成代码的风格完全可以被约束。但这里必须提醒AI Agent 在团队协作中能走多远取决于代码审查机制有多严格。Codex CLI 再聪明它也不了解你们项目的隐式约定、历史原因、客户偏好。把这些信息写进上下文往往比写进提示词更有效。我们会在项目根目录放一个AGENTS.md文件里面记录项目的架构决策、编码规范、常用命令。Codex CLI 会自动读取这类文件来确定上下文效果比每次都手动描述详细信息要好得多。加上APP_README类似的指引文件让 AI 每次开工前先读一遍能显著降低AI 我行我素的概率。这是我在使用过程中收获最大的一条经验比任何参数调优都管用。8. 我的使用节奏与最后几条建议从第一次跑通codex --version到现在Codex CLI 已经深度融入了我每天的工作流程。我个人的使用节奏是大块的需求拆解和探索性实验用交互模式慢慢对话明确且可复现的任务直接交给exec模式批量跑需要并行处理多个独立改动时开多会话配合终端复用分屏管理。有几个平时不太会写进文档、但我踩过坑后留下的习惯这里一并分享每天开工第一件事先git pull再启动 Codex CLI。因为 Codex CLI 的 Git 逻辑高度依赖当前分支状态如果本地有冲突或未提交的改动AI 生成的方案可能建立在一个过时的文件视图上改完全部错位。复杂任务先让它写计划再让它动手我会先输入先列出完成这个需求需要的步骤不要执行等它输出规划后再确认按这个计划执行。这个操作看起来多了一步但对降低返工率非常有效。修改完代码后一定让它跑一次测试如果项目有测试用例直接在任务描述里加一句完成后运行 npm run test 验证Codex CLI 会主动执行测试并修正失败。实测下来这比在测试失败后再追加指令省太多时间。不要让 AI 同时处理安全和业务两件大事比如数据库迁移脚本涉及生产数据的操作再忙也要人工复核每一行。AI 编写这类脚本的出错率虽然不高但一旦出错代价极大不值得赌。Codex CLI 不是银弹它改变不了糟糕的架构设计也替代不了代码评审。但它确实把编程这件事里比较机械的部分——搜索、替换、重构、调参、修错——加速了一大截。把 AI 当同事而不是当神这才是正确的姿势。