1. 为什么我最终把主力编程工具换成了 Codex CLI第一次接触 Codex CLI 是在一个需要批量重构老项目的周末。当时手头有个五年前写的 Python 服务依赖库版本混乱、类型注解缺失、测试覆盖率不到 20%靠人工一行行改至少得搭进去三天。朋友甩给我一句“你试试 Codex CLI命令行里直接让它改”我抱着怀疑的态度装了一下结果一个下午把重构、补测试、写文档三件事全干完了。从那以后Codex CLI 就成了我终端里的常驻工具。Codex 是 OpenAI 推出的 AI 编程智能体它和你在网页里用的对话式 AI 最大的区别在于它能直接读写你本地的代码文件、执行命令、跑测试、看报错、再自己改形成一个完整的闭环。你不需要把代码复制粘贴到网页对话框里也不需要手动把 AI 给的代码再贴回编辑器。它就在你的项目目录里工作像一个坐在你旁边的结对程序员。这篇内容适合几类人看一是刚听说 Codex 但不知道从哪下手的新手我会把安装、登录、配置、第一个任务完整走一遍二是已经在用但总踩坑的中级用户我会重点讲配置文件的写法、模型选择、权限控制、常见报错排查三是想把 Codex 接入自己工作流的老手我会分享一些自动化脚本和团队协作的实践。整篇内容基于我自己的实际操作经验不是官方文档的翻译踩过的坑和绕过的弯路都会写出来。2. 安装前的环境准备与版本选择2.1 系统要求与依赖检查Codex CLI 本质上是一个 Node.js 命令行工具所以第一件事是确认你的机器上有合适的 Node 环境。我实测下来Node 18 和 Node 20 都能跑但 Node 22 在某些老版本的 npm 下会有依赖解析的警告建议直接用 Node 20 LTS这是目前最稳的选择。检查命令很简单node -v npm -v如果 node 版本低于 18先去 Node 官网下载 LTS 版本装上。Windows 用户注意安装 Node 的时候勾选“Add to PATH”否则后面 npm 全局安装的命令会找不到。macOS 用户如果用 Homebrew直接brew install node20就行比官网下载省事。还有一个容易被忽略的依赖是 git。Codex 在做代码修改时会用 git 来追踪变更如果你的项目不是 git 仓库它有些功能会受限。建议在项目根目录先git init一下哪怕不提交也能让 Codex 更好地理解文件结构。2.2 安装方式对比npm 全局装还是 npx 临时用Codex CLI 有两种使用方式我两种都用过各有适用场景。第一种是全局安装npm install -g openai/codex装完之后在任何目录下敲codex就能启动。优点是方便缺点是版本更新需要手动npm update -g openai/codex。我建议固定用这种方式因为 Codex 更新比较频繁新版本经常修一些奇怪的 bug。第二种是 npx 临时调用npx openai/codex这种方式每次都会检查最新版本适合偶尔用一次的场景。但缺点是每次启动都要下载网络不好的时候会卡很久。如果你打算长期用别省这一步直接全局装。提示如果你在国内网络环境下 npm 安装很慢可以临时切换 npm 镜像源装完再切回来。具体命令是npm config set registry https://registry.npmmirror.com用完记得npm config set registry https://registry.npmjs.org恢复。2.3 安装失败的三种典型情况和处理我帮朋友装过不下十次 Codex遇到最多的报错是权限问题。macOS 和 Linux 下全局安装需要写/usr/local/lib目录普通用户没权限报错信息里会出现EACCES。解决办法有两个一是命令前加sudo但不推荐因为会把文件属主改成 root后面更新容易出问题二是把 npm 的全局目录改到用户目录下mkdir -p ~/.npm-global npm config set prefix ~/.npm-global export PATH~/.npm-global/bin:$PATH把最后一行加到~/.bashrc或~/.zshrc里以后就不会再有权限问题了。第二种常见报错是 Windows 上的“codex 不是内部或外部命令”。这通常是 npm 全局 bin 目录没加到 PATH 里。用npm config get prefix看一下路径然后手动把这个路径加到系统环境变量里。第三种是安装过程中卡在某个包上不动。这种情况八成是网络问题先npm cache clean --force清一下缓存再重装。如果还是卡检查一下是不是公司网络有代理限制。3. 登录与认证把 Codex 接上你的账号3.1 两种登录方式的选择Codex CLI 支持两种认证方式一种是浏览器登录一种是 API Key。我两种都试过说下区别。浏览器登录最省事敲codex启动后它会自动打开浏览器你登录账号授权一下就完事。这种方式适合个人用户凭证存在本地不用手动管理 Key。缺点是如果换机器或者重装系统得重新授权一次。API Key 方式适合自动化和团队场景。你需要在 OpenAI 平台上生成一个 Key然后设置环境变量export OPENAI_API_KEYsk-xxxxxxxxxxxx或者在 Codex 的配置文件里写死。这种方式的好处是可以在 CI/CD 流水线里用也可以给不同的项目配不同的 Key方便做用量隔离。注意API Key 是敏感信息千万别提交到 git 仓库里。我见过有人把 Key 写在.env文件里然后不小心 push 上去结果被人扫到疯狂调用账单直接爆了。建议用.gitignore把.env排除掉或者用系统的密钥管理工具。3.2 登录状态检查和切换账号登录完之后可以用codex auth status看一下当前登录的是哪个账号。如果你有多个账号比如一个个人号一个工作号切换的时候用codex auth logout先登出再重新codex登录。我自己的习惯是给不同的项目配不同的 API Key通过项目根目录的.codex/config.json来指定。这样打开哪个项目就用哪个 Key不会串。3.3 关于账号风控和额度的一些经验用了一段时间之后我发现几个规律。第一新注册的账号如果短时间内大量调用容易触发风控表现为请求返回 429 或者直接拒绝。建议新号先小规模用几天让系统有个正常的用量曲线。第二免费额度和付费额度的模型访问权限不一样有些新模型只对付费用户开放。第三如果账号被停用可以通过官方渠道申诉但退款流程比较慢别指望当天到账。这些不是 Codex 本身的问题是账号层面的但新手很容易在这里卡住所以提前说一下。4. 配置文件详解让 Codex 按你的习惯工作4.1 配置文件的位置和优先级Codex 的配置分三层优先级从高到低是项目级配置、用户级配置、默认配置。项目级配置放在项目根目录的.codex/config.json只对当前项目生效。用户级配置放在~/.codex/config.json对所有项目生效。我一般把通用的设置放用户级项目特有的放项目级。配置文件是 JSON 格式结构不复杂但有几个字段容易写错。下面是一个我常用的配置模板{ model: gpt-5-codex, approvalMode: suggest, fullAutoErrorMode: ask-user, notify: true, providers: { default: { name: openai, baseURL: https://api.openai.com/v1, envKey: OPENAI_API_KEY } } }4.2 模型选择不同任务用不同模型Codex 支持多个模型我实测下来不同任务用不同模型效果差别很大。模型适用场景速度代码质量gpt-5-codex复杂重构、架构设计中等最高gpt-5通用编程任务较快高gpt-5-mini简单修改、格式化最快中等日常改个小 bug、加个注释用 mini 就够了省钱又快。遇到需要理解整个项目结构的大任务切到 codex 模型虽然慢一点但一次做对的概率高很多。我一般默认用 gpt-5遇到难题再手动切。4.3 审批模式控制 Codex 的自主程度approvalMode这个字段很关键它决定了 Codex 在执行操作前要不要问你。suggest所有修改都先给你看你确认了才执行。最安全适合新手。auto-edit文件修改自动执行但执行命令前会问你。适合有一定信任基础之后用。full-auto全部自动执行包括跑命令。效率最高但风险也最大。我自己的用法是新项目或者不熟悉的代码库用suggest用熟了之后切auto-edit。full-auto我只在隔离的容器环境里用因为万一它执行了个rm -rf之类的命令哭都来不及。提示不管用哪种模式Codex 执行危险命令前都会做一次检查但这个检查不是 100% 可靠的。我的经验是在full-auto模式下一定要确保项目有完整的 git 提交出问题可以git reset回滚。4.4 接入自定义 API 端点有些朋友因为网络或者成本原因想把 Codex 接到自己的 API 端点上。Codex 支持通过baseURL字段指定自定义端点。配置大概长这样{ providers: { default: { name: custom, baseURL: https://your-endpoint.com/v1, envKey: CUSTOM_API_KEY } } }这里要注意自定义端点必须兼容 OpenAI 的 API 格式否则 Codex 会报解析错误。我试过接几个不同的端点兼容性最好的是那些明确声明支持 OpenAI 格式的。如果报错信息里出现failed while handling codex endpoint /responses八成是端点不支持/responses这个接口需要换一个或者联系端点提供方。5. 第一个任务从零跑通一个完整流程5.1 启动和界面认识在项目根目录敲codex你会看到一个交互式界面。界面分三块上面是对话历史中间是输入框下面是状态栏显示当前模型和审批模式。第一次启动它会让你选审批模式我建议选suggest先感受一下它的工作方式。然后它会扫描当前目录把项目结构加载进来。项目大的话这一步会花几秒到几十秒耐心等。5.2 用自然语言描述任务Codex 的输入就是自然语言你不需要学什么特殊语法。但描述任务的方式直接影响结果质量。我总结了几条经验第一说清楚“做什么”和“为什么”。比如“给 utils.py 里的 parse_date 函数加上时区支持因为现在处理跨时区数据会出错”比单纯说“改一下 parse_date”效果好得多。第二一次只做一件事。别在一个请求里塞五个不相关的任务Codex 会顾此失彼。拆成多次对话每次聚焦一个点。第三给参考。如果你希望它按照某个文件的风格来写直接说“参考 models/user.py 的写法”。我实际用的时候第一个任务通常是让它读一遍项目然后写个 README。这个任务简单、风险低还能顺便测试它理解项目的能力。命令就是读一遍这个项目的结构然后写一个 README.md说明项目是做什么的、怎么安装、怎么运行。5.3 审查和确认修改在suggest模式下Codex 每做一个修改都会把 diff 展示给你然后问你要不要应用。这时候别偷懒直接按 y认真看一下改了什么。我踩过的坑就是有一次没仔细看它把一个函数的返回值类型改了导致下游调用全挂。如果 diff 有问题你可以直接回复它“这个改法不对应该……”它会重新生成。这个来回的过程其实是在教它理解你的意图几轮之后它给出的方案会越来越准。5.4 执行命令和查看结果Codex 不仅能改文件还能执行命令。比如你说“跑一下测试看看有没有问题”它会自动执行pytest或npm test然后把结果读进来分析。如果测试失败它会尝试修复再跑一遍直到通过或者它认为需要你介入。这个闭环是 Codex 最值钱的地方。传统方式是你改代码、跑测试、看报错、再改来回切换。Codex 把这些步骤串起来了你只需要在关键节点做决策。6. 进阶用法把 Codex 用出花来6.1 多文件重构的实操技巧重构是 Codex 最擅长的场景之一但多文件重构有个坑它可能改了这个文件忘了那个导致引用不一致。我的做法是分三步走。第一步先让它做影响分析。输入“我要把 User 类的 name 字段改成 full_name先分析一下哪些文件会受影响列出来”。它会扫描整个项目给你一个清单。第二步让它按清单逐个改。你可以说“按照刚才的清单从 models 目录开始改”。这样它一次只处理一个目录不容易乱。第三步改完之后让它跑一遍全量测试确认没有遗漏。这套流程我用下来比一次性让它“把整个项目里所有 name 改成 full_name”靠谱得多。后者经常漏掉一些动态引用或者字符串里的字段名。6.2 结合 git worktree 做并行开发git worktree 是个好东西可以让你在同一个仓库里同时检出多个分支到不同目录。我把它和 Codex 结合起来的用法是开两个 worktree一个跑 Codex 做重构一个自己手动改 bug互不干扰。具体操作git worktree add ../project-refactor refactor-branch cd ../project-refactor codex这样 Codex 在 refactor 分支上折腾你在主目录继续干活。等它改完了review 一下合并就行。这个用法特别适合那种“重构和修 bug 同时进行”的场景。6.3 写自动化脚本调用 CodexCodex CLI 支持非交互模式可以用在脚本里。比如你想每天定时让它检查代码质量可以写个 shell 脚本#!/bin/bash cd /path/to/project codex --approval-mode suggest --message 检查最近的代码变更找出潜在的问题并生成报告 report.txt这个模式下它不会等你确认直接输出结果。适合做 CI 检查或者定时任务。但注意非交互模式下别用full-auto因为没人盯着万一它执行了危险操作就麻烦了。6.4 团队协作中的配置共享团队里用 Codex配置统一很重要。我们的做法是在项目根目录放一个.codex/config.json把模型、审批模式、自定义指令都写进去提交到仓库。每个人 clone 下来就是统一的配置不用各自折腾。自定义指令这个功能特别有用可以写在配置里让 Codex 遵守团队的编码规范。比如{ instructions: 本项目使用 4 空格缩进所有函数必须有类型注解提交信息用中文。 }这样每次 Codex 生成代码都会自动遵守这些规则省得你每次都要提醒它。7. 常见报错和排查手册7.1 安装和启动阶段的报错报错信息原因解决办法command not found: codexPATH 没配好检查 npm 全局 bin 目录是否在 PATH 里EACCES permission denied权限不足改 npm prefix 到用户目录别用 sudounable to locate the codex cli binary安装不完整卸载重装先清 npm 缓存codex windows 安装未完成Windows 特有用管理员权限重开终端再装7.2 运行阶段的报错cc switch local proxy failed while handling codex endpoint /responses这个报错我遇到过几次通常是你配了自定义端点但端点不支持/responses接口。解决办法是换一个兼容的端点或者在配置里把 provider 切回默认的 OpenAI。chatgpt failed to start. unable to locate the codex cli binary or required这个报错一般是 Codex 和某个 IDE 插件联动时出现的说明插件找不到 Codex 的可执行文件。检查一下 Codex 是不是装在全局以及插件的配置里路径写对没有。429 报错是请求太频繁等几分钟再试或者换个 Key。如果是持续 429可能是账号额度用完了去平台看一下用量。7.3 我踩过的三个印象最深的坑第一个坑是配置文件格式错误。JSON 对逗号和引号很敏感我少写了一个逗号Codex 启动时直接报解析错误但报错信息很模糊只说“配置无效”没说是哪一行。后来我养成了改完配置先跑python -m json.tool config.json验证一下的习惯。第二个坑是审批模式设成了full-auto然后去泡咖啡。回来发现它把我一个测试文件删了因为那个文件里的测试一直失败它“自作主张”认为这个测试没用了。幸好有 gitgit checkout恢复了。从那以后我再也不用full-auto处理有测试失败的项目。第三个坑是 API Key 权限给太大。我一开始图省事用了一个全权限的 Key结果 Codex 在某个任务里调用了文件删除接口把临时目录清空了。后来我给 Codex 单独建了一个受限的 Key只开必要的权限。8. 一些提高效率的实战心得用 Codex 这几个月我攒了一些小技巧都是文档里不会写的。关于提示词我发现用英文描述任务比中文准确率高一些尤其是涉及技术术语的时候。但如果你不习惯英文中文也能用只是偶尔它会把一些术语理解偏。我的做法是技术名词用英文其他用中文混着来。关于上下文管理Codex 的对话历史是有长度限制的。长对话到后面它会忘记前面说过的内容。我的做法是每完成一个独立任务就开新对话别在一个对话里聊太久。如果任务确实需要长上下文把关键信息写在项目根目录的一个CONTEXT.md文件里让它每次读这个文件。关于代码审查别完全信任 Codex 生成的代码。它有时候会写出看起来对但边界条件处理有问题的代码。我的习惯是它改完关键逻辑后让它自己写测试然后我人工 review 测试用例是否覆盖了边界情况。关于成本控制gpt-5-codex 模型比 gpt-5 贵不少日常小任务用 gpt-5 就行。我一个月下来大部分任务用 gpt-5只有复杂重构才切 codex 模型费用能省一半以上。关于备份用 Codex 之前一定确保代码提交了。我现在的习惯是启动 Codex 前先git status看一眼有未提交的变更先 commit 或者 stash。这样万一它改乱了一条git reset --hard就能回到干净状态。最后分享一个我最近发现的用法让 Codex 帮我写 Codex 的提示词。就是我跟它说“我要让另一个 AI 帮我做 XXX 任务你帮我写一段清晰的提示词”它写出来的提示词质量比我手写的高不少。这个套娃用法挺有意思的你们可以试试。