2025 年底 OpenAI 发布了 Codex CLI，一个运行在终端里的 AI 编程助手。它和 Claude Code 定位相似，都是"在终端里帮你写代码"，但两者的设计哲学有微妙的差别。
这篇文章不会告诉你"Codex 比 Claude Code 强"或者反过来。我会从实际使用的角度出发，讲清楚 Codex 的核心能力、典型场景、以及它在你的工具链里应该放在什么位置。
一句话剧透： Claude Code 像"项目搭档"，Codex CLI 像"命令行搭档"。各有各的甜点区。
一、 Codex CLI 到底是什么？
Codex CLI 是 OpenAI 推出的命令行 AI 编程工具。它的核心卖点是用 GPT-5 的代码能力直接在你的终端里工作——能读代码、写代码、执行命令、操作文件、甚至管理 git 工作流。
和网页版 ChatGPT 最大的区别在于：它不只是"对话"，而是能"动手"。它可以直接在你的项目目录里创建文件、修改代码、运行测试、提交 commit。你不用来回复制粘贴，所有的操作都在终端里一气呵成。
Codex CLI 的核心能力
-
本地文件系统访问：可以读取你的整个项目结构，理解文件之间的关系，直接创建、修改、删除文件。
-
终端命令执行：可以在你的 shell 里运行任何命令——安装依赖、启动服务、跑测试、操作 git。每一步执行前都会征求你的确认。
-
沙箱模式：默认在一个隔离的沙箱环境中运行，不会影响你的实际文件系统，直到你确认"写入"。这个设计对新手非常友好。
-
自我纠错能力：当它执行的命令报错时，能自动分析错误原因并尝试修复。比如跑测试失败了，它会看报错信息、修改代码、重新运行，直到通过为止。
-
多模型支持：可以选择不同的底层模型，在速度、成本、能力之间做平衡。对于简单任务用小模型省钱，复杂任务切到大模型提高质量。
二、安装与初始化
安装
| # 前置要求：Node.js 18+ 和 npm # 全局安装 Codex CLInpm install -g @openai/codex # 验证安装codex --version # 首次使用需要认证codex login# 会打开浏览器，登录你的 OpenAI 账号并授权 |
|---|
初始化项目
进入你的项目目录，直接运行 codex：
| cd my-projectcodex |
|---|
首次启动时，Codex 会自动扫描你的项目结构，生成一个项目上下文文件（类似 Claude Code 的 CLAUDE.md）。这个文件记录了项目技术栈、目录结构、关键依赖等信息，是 Codex 理解你的项目的认知基础。
| 和 Claude Code 一样，花 5 分钟做好项目初始化，后面每一分钟都能得到更好的产出。不要跳过这一步。 |
|---|
三、 Codex CLI 的独特功能
Sandbox 沙箱模式
这是 Codex CLI 最让我眼前一亮的功能。默认情况下，Codex 的所有文件操作都在一个虚拟沙箱中执行，不会触及你的真实文件。它会先展示"如果执行的话，你的文件会变成什么样"，等你确认之后才真正写入。
这个设计的意义： 你可以大胆地让 Codex 尝试各种激进的改动——大规模重构、删除文件、修改核心逻辑——而不必担心搞坏你的代码库。不满意就不确认，代码毫发无损。
| # Codex 的推荐执行流程1. 你发出指令："重构整个用户认证模块"2. Codex 在沙箱中执行所有修改3. Codex 生成 diff 摘要给你审查4. 你确认后，修改才写入真实文件 # 如果你想跳过确认（不推荐新手用）codex --no-sandbox # 直接操作真实文件 |
|---|
多模型切换
Codex CLI 允许你在不同模型之间切换。这个功能的价值在于"按需选择"——简单任务不需要最强的模型，省钱又省时间。
| # 查看可用模型codex models list # 切换到特定模型codex --model gpt-5 # 设置默认模型codex config set model gpt-5-mini # 使用场景建议# gpt-5-mini：简单修改、格式化、注释生成（快 + 便宜）# gpt-5：复杂重构、新功能开发、bug 排查（强 + 贵） |
|---|
Git 原生集成
Codex CLI 对 git 工作流有深度集成。它不仅能执行 git 命令，还能理解你的分支策略、生成规范的 commit message、自动创建 PR 描述。
| # 自动生成 commit messagecodex commit # Codex 会分析你的改动，生成符合规范的 commit# 示例输出：# feat(auth): add JWT refresh token rotation## - Add /auth/refresh endpoint# - Rotate refresh tokens on each use# - Invalidate old tokens after rotation # 生成 PR 描述codex pr# 自动对比当前分支与 main，生成完整的 PR 内容 |
|---|
这个功能在团队协作场景下特别实用。你不用再纠结 commit message 怎么写、PR 描述要列什么，Codex 帮你生成一个符合团队规范的版本，你只需要微调。
Agent 模式：自动执行
Codex CLI 有一个 Agent 模式，可以让它自动完成多步骤的复杂任务。你可以给它一个高层目标，它会自己拆解成子任务、逐步执行、遇到错误自动修复。
| # 开启 Agent 模式codex agent # 示例：自动完成一个完整的功能开发> 给项目添加用户头像上传功能。要求： 1. 支持 jpg/png，最大 2MB 2. 上传后自动裁剪为 200x200 3. 存储到 AWS S3 4. 添加对应的 API 端点和前端组件 |
|---|
Agent 模式下，Codex 会自己规划步骤：先读代码了解项目结构 → 安装图片处理库 → 写上传接口 → 配置 S3 → 写前端组件 → 跑测试验证。整个过程它会持续输出进度，遇到问题自动分析修复。你只需要在关键节点确认。
四、 Codex CLI vs Claude Code ：怎么选？
这是被问得最多的问题。我两个都在用，以下是基于实际使用的对比：
| 维度 | Codex CLI | Claude Code |
|---|---|---|
| 底层模型 | GPT-5 系列 | Claude 4 系列 |
| 沙箱模式 | 默认开启，必须确认才写入 | 直接操作文件，无沙箱隔离 |
| Git 集成 | 原生深度集成，自动生成 commit/PR | 支持 git 命令，但没有专用集成 |
| 多 Agent 协作 | Agent 模式，单 Agent 多步骤 | Workflow 架构，可编排多 Agent 并行 |
| Skill 系统 | 无 | 有完整的 Skill 创建和管理体系 |
| 代码审查 | 基础支持 | 支持多 Agent 多角度审查 |
| 学习曲线 | 较平缓，沙箱降低试错成本 | 较陡，但功能上限更高 |
| 适合人群 | 新手、重视安全性、git 重度用户 | 进阶用户、需要多 Agent 编排、Skill 定制 |
| 费用 | 按 OpenAI API 计费 | 按 Anthropic API 计费 |
我的建议： 两个都装。日常的代码修改、commit 生成、简单重构用 Codex CLI（沙箱模式让你放心试）。复杂的功能开发、需要多 Agent 协作审查、需要 Skill 定制化的场景用 Claude Code。
它们不是竞争关系，是互补关系。就像你的工具箱里既有螺丝刀也有扳手——不同的活，用不同的工具。
五、 4 个实战场景
场景 1 ：快速修复一个 bug
| # 1. 用自然语言描述 bugcodex "用户登录接口在输入超长密码时会返回500错误， 帮我定位原因并修复" # Codex 会：# - 读取登录接口的代码# - 分析错误处理和输入验证逻辑# - 找到问题（密码没有长度限制，传入数据库时溢出）# - 添加输入验证# - 跑测试确认修复 |
|---|
场景 2 ：生成规范的 commit
| # 做完改动后，一键生成 commitcodex commit # Codex 会分析所有改动，自动生成类似：# fix(login): add password length validation## Prevent 500 error when password exceeds DB column limit.# Added max length check (128 chars) before hashing. # 你只需要检查并确认 |
|---|
场景 3 ：大规模重构
| # 用沙箱模式大胆重构codex "把项目中所有 import 路径从相对路径改为别名路径" # Codex 在沙箱中执行，给你看 diff 摘要# 确认没问题后写入# 如果有问题，沙箱丢弃，代码毫发无损 |
|---|
场景 4 ：生成测试用例
| # 给已有模块补充测试codex "给 src/services/payment.py 补充单元测试， 覆盖正常支付、支付失败、余额不足、网络超时 4 种情况" # Codex 会读取 payment.py，分析函数签名和逻辑# 生成完整的测试文件，包含 mock 和断言 |
|---|
六、新手避坑指南
坑 1 ：在正式环境中不用沙箱模式。 沙箱模式是 Codex 最核心的安全设计。新手建议永远保持沙箱开启，确认 diff 没问题再写入。熟练之后，简单的单行修改可以直接关沙箱，但涉及多文件改动的操作建议保留沙箱。
坑 2 ：不给足够的上下文。 和所有 AI 编程工具一样，Codex 的表现取决于你对项目描述的质量。启动后先让它了解项目结构，或者在 prompt 中明确指定相关文件路径。"帮我改一下那个接口"不如"帮我改一下 src/api/users.py 里的 get_user_profile 函数"。
坑 3 ：在 Agent 模式下不设边界。 Agent 模式强大但也容易"跑偏"。使用 Agent 模式时，明确告诉它：要做什么、不能做什么、什么情况下停下来问你。比如"只修改后端代码，不要动前端"、"不要修改配置文件"。
坑 4 ：过度信任 AI 生成的测试。 Codex 生成的测试用例通常能覆盖常见场景，但可能遗漏你业务中的特殊边界情况。尤其是金额计算、权限校验、状态流转相关的测试，一定要人工审查并补充你的业务特有场景。
七、配置文件与常用设置
| # 1. 项目级配置（在项目根目录创建 .codex.json）{ "model": "gpt-5", "sandbox": true, "git": { "autoCommit": false, "commitStyle": "conventional" }, "ignore": ["node_modules", ".env", "*.log"]} # 2. 设置全局别名（加到 ~/.bashrc 或 ~/.zshrc）alias cx="codex"alias cxa="codex agent"alias cxc="codex commit" # 3. 配置自动补全codex completion >> ~/.bashrcsource ~/.bashrc |
|---|
八、日常工作流中使用技巧
技巧 1 ：用 " 分阶段指令 " 控制复杂任务
很多人的指令是一次性把所有需求丢给 Codex。但对于复杂任务，更好的方式是分阶段下达指令——先让它调研，再给方案，最后执行。每一步你都可以审核和调整方向。
| # 错误做法：一次性全丢codex "把用户模块重构为微服务架构，提取独立的认证服务"# 范围太大，中间容易跑偏 # 正确做法：分三步走# 第1步：先调研现状codex "分析当前用户模块的代码结构、依赖关系、数据库表， 输出一份重构可行性报告" # 第2步：审核报告，确认方向后让它出方案codex "基于刚才的分析，给出拆分为微服务的详细方案， 包括服务边界、API 设计、数据迁移步骤" # 第3步：审核方案，确认后执行codex "按照刚才的方案，执行第1阶段：提取认证逻辑到独立服务"# 每一步都可控，方向不会偏 |
|---|
技巧 2 ：善用上下文文件做 " 知识注入 "
如果你有团队内部的技术文档、编码规范、API 设计标准，可以把这些文件放在项目目录中，Codex 启动时会自动读取。这样它生成的代码风格和你的团队规范天然一致，不需要每次都在 prompt 里重复描述规范。
| # 把这些文件放在项目根目录，Codex 会自动读取my-project/├── .codex.json # Codex 配置├── CODING_STANDARDS.md # 团队编码规范├── API_DESIGN_GUIDE.md # API 设计标准├── ARCHITECTURE.md # 架构决策记录└── src/... # 然后直接下指令，Codex 会遵守你的规范codex "按照团队的编码标准，给用户模块添加分页查询接口"# 不需要在 prompt 里再描述"分页格式用 cursor-based" |
|---|
技巧 3 ：用自然语言做代码搜索定位
Codex 能理解自然语言描述的代码逻辑。当你不确定某段逻辑在哪个文件里时，直接描述它做了什么，Codex 比 grep 好用得多。
| # 传统 grep：你得知道关键字grep -r "sendEmail" src/ # Codex：描述逻辑就行codex "找到项目中负责发送邮件的代码， 特别是在用户注册成功后触发的那段" # Codex 会追踪调用链，准确定位到相关代码 |
|---|
技巧 4 ：用 Codex 做 " 代码翻译 "
Codex 在不同语言和框架之间转换代码的能力很强。如果你想把一段逻辑从 Python 迁移到 TypeScript，或者从一个 ORM 换成另一个，直接让它翻译，比手动改写快得多。
| # 跨语言翻译codex "把 src/utils/date_helper.py 转成 TypeScript 版本， 放到 frontend/src/utils/ 下" # 跨框架翻译codex "把这个用 Express 写的登录接口改成 Fastify 版本， 保持业务逻辑不变，只改框架层" # 迁移时，Codex 会自动处理：# - 类型系统差异# - 异步模型差异# - 框架约定差异# - 测试框架替换 |
|---|
技巧 5 ：用 " 对抗模式 " 让 Codex 自我检查
这是一个高阶技巧。让 Codex 完成一个任务后，再让它以"审查者"的身份重新审视自己的产出。这种自我对抗往往能发现第一轮忽略的问题。
| # 第1轮：让它完成任务codex "实现一个用户积分兑换的函数 exchange_points(user_id, points, reward_id)" # 第2轮：让它自我审查codex "刚才你写的 exchange_points 函数，请你以代码审查者的身份， 从以下角度重新审视： 1. 并发安全：多个请求同时兑换时会不会出问题？ 2. 事务完整性：扣积分和发奖励是否在同一个事务中？ 3. 边界条件：积分为0、库存不足、重复请求分别怎么处理？ 4. 安全性：是否存在用户可以通过参数篡改获益的漏洞？ 列出每个角度的问题和改进建议" # 这种自我审查能揪出 80% 的第一轮盲区 |
|---|
技巧 6 ：用 Codex 生成和更新项目文档
让 Codex 阅读你的代码库，自动生成或更新 README、API 文档、架构图描述。代码改完后顺手让 Codex 更新文档，文档和代码永远同步。
| # 生成 READMEcodex "根据项目代码生成一份 README.md， 包括：项目简介、技术栈、本地运行步骤、目录结构说明" # 更新 API 文档codex "我刚才新增了 /api/users/export 接口， 更新 API_DOCS.md 中对应的部分" # 生成架构描述codex "分析项目结构，输出一份 ARCHITECTURE.md， 描述各模块职责、数据流、关键设计决策 |
|---|
技巧 7 ：用管道将 Codex 嵌入脚本流程
Codex CLI 支持管道输入输出，这意味着你可以把它嵌入到 bash 脚本、CI 流程、git hooks 中，实现自动化的 AI 辅助环节。
| # 在 CI 中自动检查代码质量echo "检查以下 git diff 中的代码安全问题:" | \cat - <(git diff main) | \codex --stdin >> security_report.txt # 在 git hook 中自动生成 commit message#!/bin/bash# .git/hooks/prepare-commit-msgif [ "1"fi # 批量处理：给所有旧代码加类型注解find src/ -name "*.py" -exec sh -c ' codex "给 $1 中的所有函数添加完整的类型注解，保持其他代码不变" ' _ {} ; | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
九、 4 个进阶实战案例
案例 1 ：全栈功能开发 —— 用户收藏夹
需求：给电商项目添加用户收藏夹功能，包括数据库表、后端 API、前端组件。按传统方式，这是一个涉及三层架构的全栈任务，前后端开发加联调至少半天。
用 Codex 的分阶段指令法，完整过程只用了 45 分钟：
| # 阶段1：数据库设计（5分钟）codex "设计用户收藏夹的数据库表结构。 用户可以看到自己的收藏列表，按收藏时间排序。 每个收藏关联一个商品。输出 SQL 迁移脚本。"# Codex 输出了 favorites 表 + 索引 # 阶段2：后端 API（15分钟）codex "基于刚才的 favorites 表，实现以下 API： POST /api/favorites 添加收藏 DELETE /api/favorites/:id 取消收藏 GET /api/favorites 获取收藏列表（支持分页） 使用项目现有的 Express + Prisma 架构"# Codex 生成了路由、控制器、数据验证 # 阶段3：前端组件（15分钟）codex "给商品详情页添加收藏按钮， 用项目现有的 React + Tailwind 技术栈。 按钮状态根据是否已收藏切换（实心/空心）。 点击时调用刚才写的 API。" # 阶段4：合并收尾（10分钟）codex "审查我们刚才做的所有改动，生成一个完整的 commit message 和 PR 描述" |
|---|
案例 2 ：线上故障排查 —— 支付回调异常
真实案例：某天监控告警显示支付回调的成功率突然从 99.7% 降到了 94%。手动排查需要翻日志、读代码、查数据库、找根因，通常要 1-2 小时。用 Codex 辅助，25 分钟定位问题。
| # 第1步：让 Codex 读日志（5分钟）codex "分析 logs/payment-errors.log 中最近2小时的错误日志， 归类错误类型，统计每种错误的频率"# 输出："签名验证失败"占 78%，"金额不匹配"占 15% # 第2步：追踪根因（10分钟）codex "重点分析'签名验证失败'的情况。 对比成功和失败的请求，找出签名差异。 检查第三方支付平台的文档是否有最近的变更。"# 发现：某个支付渠道悄悄改了签名算法 # 第3步：生成修复方案（5分钟）codex "针对签名算法变更，给出兼容方案。 要求：同时兼容新旧两种签名算法， 旧算法在30天后废弃。" # 第4步：部署修复（5分钟）codex "按照刚才的方案，实现并部署修复代码。 生成 hotfix commit。" |
|---|
案例 3 ：遗留代码现代化 ——Express 升级 Fastify
有一个 3 年前的 Express 项目需要升级到 Fastify。项目有 40+ 个 API 端点，手动迁移每个端点的路由定义、中间件配置、错误处理机制，预估工作量 3-5 天。
用 Codex 批量处理，加上人工验证，实际耗时 4 小时：
| # 策略：不是一次性全丢，而是逐批迁移 + 逐批验证 # 第1批：先迁移基础框架（30分钟）codex "把项目的入口文件 server.js 从 Express 改为 Fastify。 保留所有中间件的逻辑，但用 Fastify 的插件机制重写。 先不改任何路由文件。" # 第2批：迁移路由（2小时，分4次，每次约10个端点）codex "把 src/routes/users.js 中的 Express 路由 改为 Fastify 路由格式。保持业务逻辑不变， 只改路由注册方式和请求/响应对象引用。" # 每批迁移后跑测试验证npm test # 第3批：迁移错误处理（30分钟）codex "把项目中所有 Express 风格的错误处理 (req, res, next) 改为 Fastify 的 setErrorHandler 模式。" # 第4批：更新测试文件（1小时）codex "测试文件中的 supertest 调用改为 Fastify 的 inject 方法。 逐文件更新，保持测试覆盖率。" |
|---|
案例 4 ：自动化开发流水线 —— 从 Issue 到 PR
把 Codex CLI 嵌入一个完整的开发流水线：从 GitHub Issue 自动生成实现代码、写测试、创建 PR。这是目前我效率最高的使用方式。
| # 完整流水线脚本：issue-to-pr.sh#!/bin/bashISSUE_NUM={ISSUE_NUM}" # 1. 创建开发分支git checkout -b BRANCH # 2. 获取 Issue 内容，让 Codex 生成实现gh issue view ISSUE_NUM --json title,body | \codex "根据这个 Issue 的需求，在当前项目中实现功能。 先分析需要改哪些文件，再逐个修改。 每改一个文件就跑一次测试。" # 3. 运行完整测试套件npm test # 4. 用 Codex 生成 commit 和 PRcodex commitcodex pr --base main # 5. 推送git push origin BRANCH | | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
十、日常使用高频技巧速查
| 场景 | 指令模板 | 适用说明 |
|---|---|---|
| 添加功能 | 给 {模块名} 添加 {功能描述}，使用项目现有的 {技术栈} | 最常用，先让它读代码再写 |
| 修复 Bug | 当 {触发条件} 时出现 {错误现象}，帮我定位并修复 | 把报错日志贴在后面效果更好 |
| 代码解释 | 解释 {文件路径} 中 {函数名} 的逻辑，画出数据流 | 接手他人代码时特别好用 |
| 重构优化 | 重构 {模块名}，目标：{可读性/性能/可测试性}，约束：{不动什么} | 加上约束避免过度重构 |
| 写测试 | 给 {文件路径} 补充测试，覆盖 {几种场景} | 告诉它项目用的测试框架 |
| 更新依赖 | 把 {包名} 从 {旧版本} 升级到 {新版本}，处理 breaking changes | 让它帮你读 changelog |
| 代码审查 | 审查 {文件} 的 {关注角度}，输出问题列表和修复建议 | 指定角度比泛泛审查准 |
| 文档生成 | 根据 {模块} 的代码生成/更新 {文档类型} | 改完代码顺手更新文档 |
总结
Codex CLI 的核心价值可以归结为三点：沙箱模式让 AI 编程从"小心翼翼"变成"放心试错"，Git 深度集成让日常开发流程更规范更流畅，Agent 模式让复杂多步骤任务能端到端自动完成。
怎么判断 Codex CLI 适不适合你？ 如果你每天在终端里写代码、做 git 操作、处理各种重复性的编程任务，Codex CLI 几乎一定能帮你提效。如果你主要是做架构设计、代码审查、技术方案评审，Claude Code 的多 Agent 能力可能更匹配。
最理想的姿态： 不要把任何一个 AI 编程工具当成"唯一正确答案"。Codex CLI 的快和稳、Claude Code 的深和广、GitHub Copilot 的实时和轻量——它们各有所长。学会根据任务特点切换工具，才是真正的效率最大化。
核心公式： Codex CLI（日常开发 + git 流 + 沙箱安全） + Claude Code（复杂重构 + 多 Agent 审查 + Skill 定制）= 完整的 AI 编程工具链
关注公众号，了解更多
