Codex 是 OpenAI 推出的 AI 编程智能体它的定位和普通代码补全工具不太一样你给一个任务它会在命令行里读取项目结构、修改多个文件、运行命令验证然后把改动结果交给你确认。这篇教程写给两类人一类是刚听说 Codex、想装又怕踩坑的新手另一类是已经装上 CLI、但还停留在一问一答阶段的人。我把新手最该知道的事、安装登录流程、第一个任务、多文件重构、模型配置和报错排查整理成一条完整路径。最想先说的经验是Codex 的使用门槛不在安装而在于你有没有版本控制、有没有给它清晰边界、能不能从日志里定位问题。下面按我实际测试的顺序拆解。1. 先搞清楚 Codex 是什么再决定要不要装1.1 它和“代码补全”不是同一个东西很多第一次接触 Codex 的人会把它理解成“一个更聪明的自动补全插件”。这个预期错得很远。代码补全工具的核心是猜你下一个字要写什么它围绕光标附近的小范围上下文工作。Codex 不是这种形态。它可以理解一个完整的任务然后自己去翻项目目录、发现相关文件、决定改哪些地方、写代码、执行命令、看结果、再修正。换句话说它更像一个坐在你终端里工作的初级工程师而不是输入法。我实际用下来Codex 适合处理的任务有几类跨文件重构比如把多个文件里重复的工具函数抽到一个公共模块根据异常堆栈定位问题并在多个疑似位置做修改为已有函数补测试然后跑测试验证按你给的模板批量生成配置文件或接口文档在仓库里搜索相关代码汇总成调查结论。它也经常翻车尤其当任务描述过于宽泛、项目结构太乱、或者模型没理解业务约束的时候。所以不要把它理解成“交给它就可以不管”。它更像一个需要你把需求说清楚、事后还要 review 的协作者。1.2 适合哪些人不适合哪些人先看适合的场景。如果你手里有一个已经能跑的工程你自己也有读代码和改代码的基础能力那 Codex 能帮你省掉大量重复劳动。最典型的用法是你想重构某个模块但懒得逐个文件改于是告诉 Codex 目标让它先给出改动方案再执行最后你用 git diff 检查。这个流程对效率提升非常明显。如果你是一个完全没接触过命令行、连终端都不愿意开的人那 Codex 的 CLI 版本并不友好。虽然它有桌面版和 IDE 扩展但核心运行逻辑还是围绕“终端的输入输出”展开。先学命令行基础再上手 Codex 更现实。还有一种情况不要急着用项目没有版本控制。Codex 一改就是好几个文件如果改坏了又不能回滚你会瞬间陷入绝望。第一次跑 Codex 之前至少学会git init、git add、git commit这三条命令。我的判断标准很简单如果你愿意在修改代码前先提交一个版本愿意耐心看终端输出那 Codex 适合你。如果你只想复制粘贴一个“能直接用的完整项目”建议还是先老老实实补齐基础。2. 安装与登录新手最容易踩坑的 5 个环节2.1 安装之前的三个前提安装 Codex 之前先确认三件事。第一你的机器上有没有可用的命令行环境。macOS 用自带的 TerminalWindows 建议用 Windows Terminal 或 PowerShellLinux 用任意终端都可以。不要在这件事上纠结。第二当前 Codex 的发行方式要以官网页面为准。CLI 版本通常可以通过 npm 安装安装前确认 Node.js 环境可用。你可以在终端里执行node -v npm -v如果你发现命令不存在需要先安装 Node.js。版本要求不需要死记安装 Codex 时如果提示版本太低再升级就行。第三准备好一个空的练习目录。不要一上来就在重要项目里跑自动执行。创建一个很干净的目录专门用来做第一次测试。mkdir codex-demo cd codex-demo2.2 安装命令和成功判定标准CLI 的安装命令通常长这样npm install -g openai/codex具体包名和安装方式以 Codex 官网当前版本为准。如果之前装过旧版本建议先卸载干净再装新的避免两个版本互相覆盖。安装完成后很多人不知道怎样算“装好了”。最简单的判断方式是执行codex --version如果能正确输出版本号说明命令行入口已经可用。如果提示“command not found”或“无法识别”不要急着怪 Codex先检查几个地方全局安装路径是否在系统 PATH 中当前终端窗口是否在安装后重新打开过npm 全局目录是否因为权限问题没写入成功Windows 上是否用了管理员权限安装。我在实际环境里见过太多人安装报错后第一反应是“工具太差”结果最后发现是终端没重启或者 Node 版本太老。2.3 登录授权与密钥配置安装成功后下一步是登录或配置 API Key。如果你使用的是官方账号可以在终端执行codex login它会打开浏览器页面让你完成授权。这个流程只做一次登录状态会保存在本机配置里。如果你的使用方式是基于团队提供的 API Key通常需要把它设置到环境变量里。具体环境变量名要看你的服务商说明常见的是通过OPENAI_API_KEY这类名称传递。这里有一个容易被忽略的点不要在命令行里把密钥写死也不要把密钥提交到 Git 仓库。用环境变量或本地密钥文件更安全。登录成功后的验证方式是在练习目录里执行一句最简单的指令比如codex 列出当前目录下的所有文件如果它能正常理解并给出回复说明安装和授权都通了。2.4 桌面版和 IDE 扩展要不要装Codex 有 CLI也有桌面版和编辑器扩展。我的建议是新手先只用一个入口不要同时装三套。CLI 最适合学习排查问题因为所有错误信息都会直接出现在终端里。桌面版可以让你用更图形化的方式查看对话和变更适合不习惯终端的人。VS Code 扩展适合写代码时顺手调用但多一个入口就多一套配置逻辑。如果你刚开始先用 CLI 跑通流程再根据使用习惯决定要不要装图形版本。3. 从零跑通第一个任务小步慢跑比什么都重要3.1 先建一个最小练习项目很多人第一次使用时会犯同一个错误直接在真实项目目录里让 Codex 执行命令结果它改了一大堆文件你根本看不明白。更好的做法是建立一个最小练习项目。进入刚才创建的codex-demo目录先初始化 Gitcd codex-demo git init这一步非常重要。Codex 修改文件是批量性的没有版本控制时你很难看清它到底改了什么也无法一键回滚。写好配置文件、加好待修改的示例代码之后先提交一次初始版本。然后再创建几个示例文件比如一个 Python 脚本和一个 Markdown 说明文件。内容不需要复杂只要能让 Codex 有东西可以看、可以改就行。3.2 交互模式和执行模式的区别Codex 有两种常用使用方式。第一种是交互模式。直接执行codex它会进入一个像聊天界面一样的终端交互环境。你可以在里面连续提问让它解释代码、给出方案、修改文件。这个模式适合探索和调试因为你可以随时打断、追问、纠正方向。在交互模式下你可以直接问分析当前目录下的文件结构并指出 main.py 中存在哪些明显问题。它会先浏览文件再输出分析结果。你需要做的不是马上让代码执行而是看它给出的方案是否合理。第二种是执行模式。它的特点是直接跑一次任务然后退出codex exec 把当前目录下所有 .py 文件加上模块说明注释执行模式适合把任务交给它自动化处理但第一次使用不要直接加自动执行参数。你要先让它在每一步操作前征求你同意这样你能看到“它打算改哪里、执行什么命令、为什么这样改”。跑完一次没问题之后再考虑全自动模式。3.3 怎样判断第一次任务是否成功判断标准很简单看文件内容、看执行结果、看日志。假设你让它给代码文件加注释加完之后打开文件看看注释位置是否正确。如果它顺带改了别的无关内容就说明任务边界不清晰下次要加上“只处理指定目录”的约束。再比如你让它写测试写完后要真的跑一遍测试命令确认能够通过而不是只看它报告“已经完成”。执行模式跑完后Codex 会输出任务状态的摘要。你需要重点确认的有三点任务是否真正完成有没有半途中断哪些文件被修改目录里是否多出了不该出现的文件有没有一条命令执行失败却被它自动跳过了。我的习惯是第一次跑任务永远不要加“全自动执行”的参数先看它做一遍心里有底了再放开权限。4. 进阶落地多文件重构、批量任务与 Skill4.1 多文件重构的正确顺序当你想让 Codex 做跨文件重构时不能只丢一句“帮我把项目优化一下”。它需要知道目标、范围、约束和验证方式。更完整的指令结构是在 src 目录中找出所有重复的日期格式化逻辑统一抽到 src/utils/date_utils.py 并把原来调用处改成引用新函数。不要修改 tests 目录下的文件改完后运行测试并汇报结果。这样 Codex 才能清楚改哪里、怎么改、不能碰哪里、怎么验证。少了任何一环它都可能跑偏。多文件重构不应该一次性自动完成所有操作。我更推荐的分步方式是这样的先让 Codex 给出改动方案不实际执行你确认方案中涉及的文件范围让它在每个文件修改前征求同意修改完成后再运行一次测试或构建用git diff查看全部改动确认没问题后再提交。这个流程看起来比“一句话自动改完”慢但它能避免项目被改到不可收拾。4.2 批量任务不是简单地把任务列表丢进去很多人的目标是让 Codex 批量处理几十个文件。这个想法可行但要注意几个细节。第一先把单个任务跑通。你会遇到很多意想不到的问题文件名包含特殊字符、编码不一致、目录层级过深、某些文件内容不符合预设条件。单条路径没理顺之前不要直接放大范围。第二注意任务拆解。一次让它做“批量修改 50 个文件”看起来效率高但失败时很难定位。更稳妥的做法是让一个批次只做同一类改动比如“给所有配置文件增加超时字段”这类一致性强的任务适合批量。第三要考虑输出命名。如果任务是批量生成文件要提前约定文件名规则避免多个文件互相覆盖。特别要注意时间戳精度和重复任务处理。批量任务的判断标准不是“有没有跑起来”而是任务完成率是多少、失败文件有没有记录下来、失败原因是输入问题还是模型能力问题、重跑一遍能不能得到一致结果。如果你跑一次一个结果那这个流程还不可靠。4.3 用 Skill 把固定流程沉淀下来如果你发现自己在反复向 Codex 输入同一段长提示就可以考虑把它封装成 Skill。Skill 在 Codex 这里可以理解为一套可复用的技能描述告诉它遇到什么类型任务时按哪些步骤处理。最常见的例子是代码审查。每次代码改动后我都希望它先看 git diff再检查几个固定风险点最后按优先级输出问题。与其每次都打一遍完整提示不如约定一个目录和文件格式。一个通用示例结构长这样.codex/skills/review-code/SKILL.mdSKILL.md 的内容可以参考这种写法--- name: review-code description: 审查当前分支的代码改动并输出问题清单 --- 1. 查看当前分支的 git diff。 2. 检查是否有类型错误、越界访问、异常未处理等问题。 3. 按严重程度输出问题列表。 4. 不要直接修改代码只输出审查结果。实际字段和存放目录要以你本机 Codex 版本的支持情况为准。我这里给的是思路示范不是官方固定格式。封装 Skill 的意义在于让 Codex 的输出质量更稳定。你不需要每次重新解释规则它会在启动任务时自动读取这些流程说明。5. 配置模型、接入第三方服务与 IDE 使用5.1 用配置文件控制默认行为Codex 的很多行为通过配置文件管理。常见配置项包括默认模型、执行模式、输出格式、模型服务商等。配置文件位置在不同系统上略有差异macOS 和 Linux 通常放在用户目录下的.codex文件夹Windows 一般在用户目录下。落地时以当前版本文档为准。配置内容可以包含类似这样的示例model replace_with_your_model [model_providers.example_provider] name example-provider base_url https://your-api.example.com env_key YOUR_API_KEY如果你使用的是官方默认服务大多数配置甚至不需要改。但当你需要接入其他模型服务商时配置文件就变得重要了。这里有一个最常见的坑模型名称写错。很多人会凭记忆填写一个模型名结果请求直接失败。正确做法是从服务商文档或账号后台的模型列表里复制完整标识不要手打。5.2 接入 DeepSeek 或 OpenAI 兼容服务时要注意什么“Codex 接入 DeepSeek”是一个比较热门的用法。本质上Codex CLI 支持配置 OpenAI 兼容接口DeepSeek 提供的 API 也属于这类兼容服务。配置时需要确认三件事。第一确认服务商的 API 地址是什么。常见的是https://api.deepseek.com或者带版本路径的地址具体以服务商文档为准。配置到base_url之后Codex 会基于这个地址发起请求。第二确认服务商模型是否支持 Codex 需要的完整能力。Codex 作为智能体除了生成文本还需要模型能够理解工具调用、触发命令执行、读文件写文件。如果模型本身只适合普通聊天接入后可能出现“能聊天但不能干活”的情况。第三确认费用和限流。不同模型的价格差别很大批量执行任务时消耗可能会很快。不要拿本地小测试的数据去估算生产任务的成本。还要注意一点接入第三方服务时API Key 一定要通过环境变量配置不要写死在配置文件里。不要使用网上来历不明的“公共 Key”或“免费服务”这类渠道既不稳定也不安全。5.3 在 VS Code 里使用 Codex以及和 Spring AI 等框架配合VS Code 扩展适合在编写代码时顺手使用。它和 CLI 是同一套运行逻辑只是把界面搬到了编辑器里。第一次在 VS Code 里使用时建议先手动触发一个很小的任务确认它能正确读取当前工程再逐步放开权限。需要注意VS Code 扩展的配置可能和 CLI 配置共用也可能相互覆盖。如果发现命令行里有效的行为在 IDE 里不生效先检查两边加载的配置文件是否一致。另外如果你在写 Spring AI 相关项目Codex 可以帮你生成调用 AI 服务的接口代码、补日志、写测试。但要清楚边界Codex 是辅助编码的 agent它写出来的代码仍然需要你审查。不要把 AI 辅助编码工具直接当成生产环境的运行时依赖。6. 报错排查手册从现象快速定位问题6.1 几个常见报错和优先排查位置Codex 使用中遇到的报错大多数不是模型本身的问题而是环境、配置或输入格式的问题。我把常见情况按优先级整理成一张表现象优先排查位置命令找不到安装路径、PATH 环境变量、终端是否重启登录授权失败网络是否正常、账号权限、API Key 格式请求接口时提示本地服务连接失败网络连接、服务商服务状态、base_url 是否正确、本机安全软件是否拦截提示模型不支持模型名是否拼写错误、当前服务商是否提供该模型任务长时间不返回任务范围是否过大、输入文件是否过大、服务端限流输出为空输入提示是否太模糊、文件路径是否写错、日志中有没有隐藏错误自动执行失败但没报错权限问题、文件锁定、磁盘空间不足这里想专门说一下请求/responses接口时报本地服务连接失败的情况。不要一上来就怀疑模型能力先按顺序检查网络连接、服务商服务状态、接口地址是否正确。如果你在本地配置了额外的转发或调试服务先临时关掉或调整到标准环境排除干扰项后再测试。还有一个常见报错是模型 not supported。这类报错出现时优先检查配置里的模型名。Codex 请求的是你配置的模型标识如果该标识不存在、拼写错误、或者当前服务商并未支持就会直接拒绝。不要随便猜测模型名一定要从官方可用列表中复制。6.2 通用排查顺序日志、配置、环境、模型遇到任何异常我建议按固定顺序排查不要跳跃。第一步看日志。Codex 一般会把错误原因直接输出到终端。如果任务中途卡住按退出键后查看最后几条日志确认是不是请求超时、命令执行失败、还是文件解析问题。第二步查配置。检查当前使用的是哪个模型、哪个服务商、配置文件加载是否成功。很多“看起来是报错”的问题实际上是配置加载错了。第三步查环境。输入文件是否存在、路径是否正确、有没有权限读取、磁盘空间够不够、网络是否可达。如果在公司网络环境中还有额外的安全策略也要把它算进去。第四步查模型。确认当前模型是否支持工具调用上下文长度是否足够任务描述是否过于开放。如果你的任务真的很大那就拆分。日志永远是最重要的线索。不要只看“失败了”就重试先搞清楚失败发生在哪一步。6.3 防止 Codex 把项目改坏的好习惯最后分享几个我长期使用后保留的习惯。第一个习惯任何重要操作之前先提交一次代码。哪怕只是创建一个新分支也比一无所知重要。Codex 修改文件后你能用git diff看到每一处改动不满意还能整体回滚。第二个习惯给 Codex 限制明确的操作范围。比如“只修改 src 目录”“不要动数据库脚本”“不要提交代码”。边界越清楚翻车概率越低。第三个习惯不要让 Codex 在第一次解释方案时就立刻执行。先让它说打算怎么做你判断方向没问题再让它动手。第四个习惯如果一个任务连续失败三次以上不要再加并发或换参数硬试。更常见的原因是任务描述不够完整、项目结构太乱、或者当前模型不适合这类操作。这时候应该缩小范围、补足背景信息而不是继续重试。Codex 这类工具真正落地时最值得关注的不是它能列出多少功能而是你能不能控制它的执行边界、看懂它的运行日志、在它改坏代码之前有回滚手段。先把单任务跑稳再逐步放开权限比一开始就追求完美配置靠谱得多。