OpenAI Codex 完全指南：从诞生到用法，你需要知道的一切

彩旗工作室

2138人浏览 · 2026-03-16 07:00:00

彩旗工作室 · 2026-03-16 07:00:00 发布

一、什么是 Codex？

如果你关注 AI 编程工具的发展，「Codex」这个名字一定不陌生。但你可能不知道，这个词在过去几年里实际上指代了两个截然不同的东西——一个是 2021 年的代码补全模型，另一个是 2025 年以来横空出世的自主编程 Agent。了解它的来龙去脉，才能真正用好它。

简单一句话概括：OpenAI Codex 是 OpenAI 推出的 AI 编程助手体系，能够将自然语言指令转化为代码，并以 Agent 形式自主完成复杂软件工程任务。

二、Codex 的诞生与演变历程

第一代 Codex（2021）：GitHub Copilot 的引擎

2021 年 8 月 10 日，OpenAI 正式发布了 Codex。它是 GPT-3 的一个改进版本，使用来自数十种编程语言的大量源代码进行微调，也是最初驱动 GitHub Copilot 运转的底层模型。

这一代 Codex 拥有 120 亿参数，在来自 5400 万个 GitHub 仓库的 1590 亿字节 Python 代码上进行了训练。典型的使用方式是：开发者在编辑器里写一行注释，比如 // 计算数组在指定窗口大小下的移动平均值，然后 Codex 自动补全对应的代码块。

这一时期的 Codex 有明显局限性：OpenAI 表示 Codex 能完成约 37% 的请求，定位是加快人类编程速度，而非取代程序员。它在单步任务上表现尚可，但面对多步骤复杂提示往往力不从心，且生成的代码有时存在安全漏洞或风格问题。

尽管如此，它的出现验证了"AI 结对编程"的可行性，直接催生了 Amazon CodeWhisperer、Tabnine 等一批竞品的诞生。

2023 年 3 月，OpenAI 正式弃用了原始 Codex 模型。GitHub Copilot 也随着 Copilot X 升级而转向了更强的 GPT-4 模型。「Codex」这个名字就此沉寂了约两年。

第二代 Codex（2025 起）：自主编程 Agent 的新时代

2025 年 5 月 16 日，OpenAI 宣布推出全新 Codex 的研究预览版——一个基于云端的软件工程 Agent，能够并行处理多项任务。Codex 能够为你完成编写功能、回答代码库问题、修复 Bug、提出 Pull Request 供审查等工作；每个任务在独立的云端沙箱环境中运行，并预装了你的代码仓库。

2025 年 4 月 16 日，OpenAI 在 GitHub 上以 Apache 2.0 许可证发布了 Codex CLI，一个运行在用户本地计算机上的 AI Agent 框架。

此后，Codex 的能力升级一路狂飙：

2025 年 9 月：发布 GPT-5-Codex，这是一个针对 Codex 中 Agentic 编程场景进一步优化的 GPT-5 版本，同时支持 API 调用。
2025 年 12 月：发布 GPT-5.2-Codex，这是迄今为止最先进的 Agentic 编程模型，在长上下文理解、可靠工具调用、事实准确性以及原生上下文压缩（compaction）方面均有显著提升。
2026 年 2 月：发布 GPT-5.3-Codex，将 GPT-5.2-Codex 的前沿编程能力与更强的推理和专业知识能力结合在一起，并且比前代快 25%。值得一提的是，这是 OpenAI 第一个参与了自身创造过程的模型——Codex 团队用早期版本来调试自身的训练流程、管理部署，并诊断测试结果与评估数据。
2026 年 3 月：GPT-5.4 正式在 Codex 中上线，作为 OpenAI 最强大的前沿模型，它将推理、编程和 Agentic 工作流整合于一身，是目前大多数 Codex 任务的推荐首选。

目前，每周有超过 100 万名开发者在使用 OpenAI 的多 Agent 编程助手 Codex，自 2026 年 1 月以来，使用量已增长 5 倍。

三、Codex 的四种使用入口

现代 Codex 不是一个单一工具，而是一套跨平台的 Agent 体系。根据你的使用场景，有以下四种主要入口。

3.1 Codex Web（云端版）

访问地址：chatgpt.com/codex

这是最直接的方式。每个任务在独立的云端沙箱中运行，沙箱预装了你的代码仓库，Codex 可以并行执行多个任务。适合需要长时间运行、大规模重构或异步委托任务的场景。

操作步骤：

登录 ChatGPT，确保你有 Plus、Pro、Business、Edu 或 Enterprise 计划
在侧边栏找到 Codex 入口，或直接访问上述地址
连接你的 GitHub 仓库
用自然语言描述你想做的事情，比如"帮我给这个 Python 函数写单元测试"或"修复 Issue #42 中的 bug"

3.2 Codex CLI（命令行工具）

Codex CLI 是 OpenAI 出品的一个本地运行的编程 Agent，直接在你的终端运行。这是开发者日常使用最灵活的方式，完全开源，托管在 GitHub。

安装方式（二选一）：

# 方式一：npm 安装
npm i -g @openai/codex

# 方式二：Homebrew（macOS）
brew install --cask codex

启动 Codex CLI：

codex

首次使用需要登录 ChatGPT 账号或配置 API Key。

常用命令示例：

# 指定模型启动
codex -m gpt-5.4

# 非交互式执行（适合脚本自动化）
codex exec "给 src/utils.py 写文档字符串"

# 在会话中切换模型
/model

CLI 还支持在会话中直接发送补充指令（mid-turn steering），你可以在 Codex 工作的过程中随时发送消息来调整它的行为方向。

3.3 Codex IDE 扩展（VS Code / Cursor / Windsurf）

新的 IDE 扩展将 Codex 带入 VS Code、Cursor 及其他 VS Code 分支中，让你可以无缝预览本地更改并编辑代码。

安装步骤（以 VS Code 为例）：

打开 VS Code 扩展市场，搜索「OpenAI Codex」
安装后，用 ChatGPT 账号登录
在编辑器底部的输入框选择模型（如 GPT-5.4）
直接在编辑器内提交任务

IDE 扩展的优势在于它与本地文件系统深度集成，可以直接预览 diff、审查代码修改，同时享受云端 Agent 的强大算力。

3.4 Codex 桌面应用（macOS / Windows）

自 2025 年 4 月 Codex 发布以来，开发者与 Agent 的协作方式已发生根本性变化——模型现在能够端到端处理复杂的长时运行任务，开发者正在跨项目编排多个 Agent：委托工作、并行运行任务，并信任 Agent 承担可能跨越数小时、数天甚至数周的大型项目。

Codex 桌面应用正是为这种"多 Agent 指挥中心"场景而生。每个任务在独立线程中运行，按项目归类，你可以一边等某个重构任务跑完，一边让另一个 Agent 写测试用例。

下载方式：

命令行安装后运行 codex app
或从 OpenAI 官网下载 macOS / Windows 安装包

四、Codex 能做什么：核心能力详解

4.1 代码生成与功能开发

这是最基础的用法。给 Codex 一个清晰的需求描述，它会直接写出完整的代码，包括函数、模块乃至整个功能模块。例如：

帮我用 FastAPI 写一个用户注册接口，包含邮箱验证、密码加密（bcrypt），并写好 OpenAPI 文档注释。

4.2 Bug 修复与调试

把报错信息、堆栈追踪或测试失败的输出直接粘贴给 Codex，它能分析根本原因并给出修复方案，甚至直接应用到代码文件上。

4.3 代码库级别的重构与迁移

GPT-5.2-Codex 在大型代码变更（如重构和迁移）方面的表现有显著提升。Codex 能够理解整个仓库的结构，跨文件执行大规模重命名、架构调整、依赖升级等操作。

4.4 自动生成测试

描述你的函数或模块，Codex 会分析代码逻辑，生成覆盖边界条件的单元测试、集成测试，并可以直接执行验证通过率。

4.5 代码审查与 PR 辅助

在 GitHub 中，你可以直接 @Codex 触发代码审查，让它分析 PR 的改动是否符合预期功能，并给出具体的改进建议。

4.6 回答代码库问题

对于刚接触陌生代码库的开发者，Codex 是极好的"导游"。你可以问"这个项目的鉴权逻辑在哪里实现的？"或者"这个接口的调用链是什么？"，Codex 会基于你的实际仓库给出准确的回答。

4.7 技能扩展（Skills）

通过技能（Skills）扩展，Codex 可以将 Web 应用部署到 Cloudflare、Netlify、Render 和 Vercel 等流行云服务；使用 GPT Image 驱动的图片生成技能来创建和编辑图片；还可以读取、创建和编辑 PDF、Excel 和 Word 文件。

五、模型选择指南

对于 Codex 中的大多数任务，推荐从 GPT-5.4 开始。它将强大的编程能力、推理能力、原生计算机使用能力和更广泛的专业工作流整合在一个模型中。

模型	适用场景	备注
GPT-5.4	日常编程、多模态任务、长期 Agent 任务	当前推荐默认选择
GPT-5.3-Codex	复杂软件工程、大型重构	前沿编程能力
GPT-5.2-Codex	API 集成、长上下文任务	API 用户的稳定选择
GPT-5.3-Codex-Spark	需要极速迭代的实时编程	仅 Pro 用户研究预览

CLI 中指定模型的方式：

codex -m gpt-5.4
codex -m gpt-5.2-codex

六、定价与订阅方案

Codex 包含在 ChatGPT Plus、Pro、Business、Edu 和 Enterprise 计划中，无需额外付费。使用量根据计划有所差异：Plus、Edu 和 Business 每周可以覆盖几次专注的编程会话，而 Pro 则可以支撑整个工作周内跨多个项目的使用。Business 计划可以购买额度以突破包含的限制，Enterprise 计划则提供共享额度池，只为开发者实际使用的部分付费。

对于通过 API Key 使用 Codex CLI 的开发者，gpt-5.2-codex 目前是 API 侧的稳定选择。

七、配置文件详解

Codex CLI 和 IDE 扩展共用同一个 config.toml 配置文件，通常位于 ~/.codex/config.toml。

一个典型的配置如下：

# 指定默认模型
model = "gpt-5.4"

# 审批模式：suggest（仅建议）、auto-edit（自动编辑）、full-auto（全自动）
approval_mode = "suggest"

# 启用 Fast 模式（默认开启）
fast_mode = true

审批模式说明：

suggest：Codex 只提出建议，所有修改需要你手动确认，最安全。
auto-edit：Codex 可以直接修改文件，但涉及命令执行仍需确认。
full-auto：完全自主，适合在沙箱或测试环境中使用。

八、使用注意事项与避坑指南

✅ 最佳实践

1. 任务描述要具体，边界要清晰

越具体越好。"帮我优化代码"这样的需求太模糊。好的写法是："重构 src/auth/jwt.py 中的 verify_token 函数，用 python-jose 替代 PyJWT，保持现有测试通过。"

2. 把大任务拆成多个并行的小任务

根据早期测试者的经验，OpenAI 建议同时给多个 Agent 分配边界清晰的任务，并尝试不同类型的任务和提示来探索模型的能力。

3. 附上截图、设计稿或错误截图

你现在可以在 CLI 中直接附带或拖入任何文件类型——截图、线框图、设计图——建立共同上下文，以便获得你真正想要的结果。

4. 善用 mid-turn steering（中途引导）

如果 Codex 工作方向跑偏了，不必等它跑完整个任务再纠正。直接在会话中发消息引导它："等等，先不要动数据库层，只修改 API 层就好。"

5. 在代码库根目录放置 AGENTS.md 文件

这是 Codex 的"工作说明书"。你可以在其中写明：项目架构约定、编码规范、常用命令（如何运行测试、如何构建）、哪些文件不能动等。Codex 会在任务开始时读取它，大幅提升理解准确度。

⚠️ 注意事项与风险

1. 务必审查所有生成代码再合并

用户在集成和执行之前，对所有由 Agent 生成的代码进行手动审查和验证仍然至关重要。Codex 提供引用、终端日志和测试结果供你核查，但最终判断责任在人。

2. 不要将生产环境密钥上传到 Codex 的沙箱

任务运行在云端隔离沙箱中，但敏感凭据（数据库密码、API Secret）依然不应该直接放在仓库或提示词里。使用环境变量或 Secrets 管理工具。

3. 网络安全相关任务需谨慎

GPT-5.3-Codex 是 OpenAI 在准备框架下首个被评为网络安全"高能力"的模型，也是第一个经过直接训练以识别软件漏洞的模型。这意味着它在安全研究方面能力极强，但也意味着相关请求会被额外的安全系统审查，部分请求可能被路由到能力较弱的模型以防滥用。

4. 注意版权与开源协议问题

Codex 训练数据来自公共代码仓库，极少数情况下生成代码可能与训练数据高度重合。在将生成代码用于商业产品时，建议做必要的代码审计。

5. 长任务注意上下文压缩

对于运行时间极长的任务，Codex 会启用原生上下文压缩（context compaction）来维持上下文完整性，但在任务中间切换太多方向可能导致上下文混乱。尽量在任务开始前把需求说清楚。

九、典型使用场景案例

场景一：独立开发者快速出 MVP

你有一个 App 创意，用 Codex 描述整体架构，让多个 Agent 并行负责前端、后端、数据库 Schema 的搭建，最后让它部署到 Vercel——整个过程可以在几小时内完成原型。

场景二：技术债务清理

在大型遗留项目中，直接告诉 Codex："把所有用 requests 库的同步调用改成 httpx 的异步版本，保持现有 API 接口不变，并更新测试。" Codex 能跨文件理解依赖关系并系统性地完成修改。

场景三：CI/CD 集成自动修复

Codex Autofix 可以集成到 CI 流程中，实现自动化修复模式。当 CI 检测到测试失败或 lint 错误时，自动触发 Codex 分析并提交修复 PR，大幅减少人工介入。

场景四：安全研究（需申请 Trusted Access）

安全研究人员使用 GPT-5.1-Codex-Max 配合 Codex CLI，通过高频迭代提示的方式，发现并负责任地披露了 React 中一个可能导致源代码泄露的漏洞。

十、总结

OpenAI Codex 走过了从 GPT-3 微调代码补全模型，到今天支持多 Agent 并行、长时运行任务的自主编程系统的完整历程。它不再只是一个"聪明的自动补全"，而是一个真正意义上的 AI 软件工程师——你可以委托它完成从写代码、跑测试、提 PR 到部署上线的完整闭环。

对于独立开发者、小型团队来说，掌握 Codex 的正确用法，意味着你可以用一个人的时间干多个人的活。关键在于：给清晰的任务边界，并行利用多 Agent，审查所有产出再合并。

工具已经准备好了，接下来就看你怎么用了。

参考资料：

OpenAI 官方文档：developers.openai.com/codex

OpenAI Codex GitHub：github.com/openai/codex

Codex Changelog：developers.openai.com/codex/changelog