Codex 实战知识档案

1. Codex 是什么？

Codex 是 OpenAI 推出的智能编程助手。它和传统代码补全最大的区别是：Codex 能自己读代码、改文件、跑测试、查错误、调用外部工具，完成一整个开发任务，而不只是帮你补一行代码。

你可以把它理解为一位能在你电脑里直接干活的实习生。你给它需求，它自己规划步骤、动手实现，并在关键节点找你确认。

2. 四种使用方式

• 终端命令行（CLI）：最常用。直接在当前项目目录里输入指令，Codex 就能理解上下文并执行开发任务。
• IDE 插件：在 VS Code 等编辑器里实时查看修改、Diff 对比和内联编辑，适合喜欢图形界面的人。
• 桌面应用：多任务面板、多项目会话、长期计划视图，适合同时管理多个复杂任务。
• 云端/远程沙箱：需要长时间运行、隔离环境或高并发时，可以把任务放到云端执行。

3. 适合谁用？

• 独立开发者 / 一人公司：把重复开发工作交给它，比如写脚本、做页面、跑测试。
• 产品经理：快速把想法做成可运行的原型，验证业务逻辑。
• 技术负责人：做代码审查、重构旧系统、整理测试用例。

4. 核心能力

• 端到端功能开发：从需求描述到可运行代码，自动规划并分步执行。
• Bug 排查与修复：读取报错信息，定位问题文件，提出补丁并自动跑测试验证。
• 多智能体协作：把大任务拆给多个子 Agent 并行处理，比如一个写前端、一个写后端。
• MCP 工具调用：能连接数据库、浏览器、第三方 API，扩展它的工作范围。

5. 使用边界与提醒

• 高风险操作要确认：修改数据库、发邮件、转账、改密钥这些动作默认需要人工二次确认。
• 上下文会疲劳：任务越长，模型越容易忽略早期要求。建议把大任务拆小，并用 AGENTS.md 等文件固化规则。
• 它不会替你负责：最终代码仍需人工 review，特别是涉及安全和生产的改动。

1. 安装与登录

在终端里运行安装命令，完成后用 OpenAI 账号登录。建议先在非核心项目里试手。

首次使用前确认两点：

• 当前目录就是你要操作的项目根目录。
• 项目已有 Git 提交或备份，方便回滚。

2. 第一次任务

最简单的开始方式是说人话：

给这个项目加一个 /health 接口，返回当前服务状态。

Codex 会：

1. 先读项目结构和相关文件。
2. 给出修改计划。
3. 开始改代码。
4. 运行测试或启动服务验证。

如果计划不是你想要的，直接说“先不要改，我们用另一种方式”。

3. 规划模式（Planning Mode）

复杂任务建议先开规划模式。Codex 会先把整体方案写成结构化文档，包括：

• 要改哪些文件
• 每一步做什么
• 可能的风险

确认后再执行，避免它盲目动手改坏现有逻辑。

4. MCP 工具扩展

MCP 是一种通用接口，让 Codex 能调用外部工具，比如：

• 读取本地数据库
• 操作浏览器
• 调用公司内部 API

配置好 MCP 服务器后，Codex 会在需要时自动选用。

5. 多智能体协作

大任务可以拆成多个子任务并行：

• 一个子 Agent 调研现有代码
• 一个子 Agent 写前端页面
• 一个子 Agent 写后端接口
• 最后由主 Agent 合并结果

你可以在配置里给不同 Agent 分配角色、模型和权限。

6. 安全建议

• 给 Codex 设置最低必要权限。
• 涉及支付、密钥、生产数据库的操作强制人工确认。
• 定期 review 它产生的提交记录。

实战手册 1：从需求到可运行原型

目标：用一小时把一个产品想法变成能点的原型。

1. 写清楚需求：用一段自然语言描述用户场景和页面流程。
2. 让 Codex 生成方案：先要求它输出 plan.md，包含页面清单和数据结构。
3. 分模块实现：一次只生成一个页面或一个接口，避免一次性改动太多。
4. 本地验证：让 Codex 启动本地服务并截图或 curl 验证。
5. 人工验收：检查交互细节，必要时手动微调。

实战手册 2：旧系统无痛重构

目标：在不破坏现有功能的前提下，改善一段老代码。

1. 让 Codex 先读测试：确认当前有哪些测试覆盖。
2. 要求补测试：如果测试不足，先让它补全关键路径的测试。
3. 小步重构：每次只改一个函数或一个模块，跑测试通过后再下一步。
4. 提交并回滚：每完成一小步就提交 Git，方便随时退回。

实战手册 3：复杂 Bug 排查

目标：定位一个报错背后的根因。

1. 贴出完整报错：包括堆栈信息和复现步骤。
2. 让 Codex 列出假设：要求它给出 3 个最可能的原因。
3. 逐一验证：让它加日志、跑测试、缩小范围。
4. 修复并回归：修复后跑完整测试套件，确认没引入新问题。

2026-09 当前状态

• 多智能体 v2 稳定：可以配置不同角色的子 Agent，支持并发和任务交接。
• 作为 MCP 服务器运行：Codex CLI 能被其他 Agent 调用，方便搭建复杂工作流。
• 会话历史与记忆：支持分页历史、持久化命名和跨会话恢复。
• 迁移助手：可以把 Cursor 和 Claude Code 的设置、MCP 配置、记忆导入到 Codex。

2026-08（v0.152.0）

• Vim 模式增强：在草稿里支持 / 和 ? 搜索、n/N 跳转。
• MCP 服务器名字支持 :、@、/、. 等包名风格。
• 单个 MCP 工具可设置 output_token_limit，避免长输出撑爆上下文。
• App-server 的线程和 shell 命令超时支持超过一小时。

2026-07（v0.149.0 / v0.145.0）

• 多智能体 v2 进入实验阶段，支持模型覆盖、推理级别、并发数配置。
• 引入 /import 命令迁移其他编辑器的设置和记忆。
• 凭证刷新可视化，支持 Amazon Bedrock 重新认证提示。

2025 年底

• 全面支持 MCP 标准，可连接本地和云端工具。
• 规范化 Planning Mode，强制复杂任务先输出方案再执行。

对用户意味着什么

Codex 正从“帮你写代码”走向“能独立完成开发任务”。但工具越强，越需要人把边界、权限和 review 流程管好。

1. 权限被拦截

现象：Codex 提示无法执行某条命令或写入某个文件。

处理：

• 检查当前目录是否是项目根目录。
• 确认 Codex 的权限策略设置，必要时临时放宽或手动执行。
• 生产环境、敏感文件建议永远人工确认。

2. 上下文太长，开始“失忆”

现象：任务后期，Codex 忽略了最开始的约束。

处理：

• 把大任务拆成多个小任务，每个任务单独启动。
• 在 AGENTS.md 或 README 里固化项目规则，让它每次都能读到。
• 使用检查点或重启会话，清理不相关的历史消息。

3. 多智能体协作混乱

现象：子 Agent 之间重复工作，或者输出格式不一致。

处理：

• 给每个 Agent 明确的角色和输出目录。
• 主 Agent 负责协调，不要同时让多个 Agent 写同一个文件。
• 在交接时要求子 Agent 输出结构化状态说明。

4. 测试跑不过

现象：Codex 改完后测试失败。

处理：

• 先看失败日志，确认是改坏了还是测试本身脆弱。
• 要求 Codex 先修复测试，再修复代码。
• 如果反复失败，考虑回退到上一个检查点，换更小的改动粒度。