你很可能用错了 Codex。

不是说你做了什么明显的蠢事。恰恰相反：Codex 的工作方式本身就反直觉。你以为它是一个更聪明的 ChatGPT，但它其实更像一个新来的同事，每次走进你的项目目录时都带有「失忆症」：它会写代码，但不知道你的项目结构长什么样、用哪个测试框架、哪些目录不能碰。

解开 Codex 全部潜能的关键，不是更花哨的提示词，而是给它持久化的记忆：关于你的代码仓库、你的编码规范、你的工作流程。

本文基于 OpenAI 官方 Codex 文档中的 「六支柱框架」 和 「八个常见错误」，结合我三个月的实战踩坑，帮你把 Codex 从「一个会写代码的聊天窗口」升级为「真正懂你项目的 AI 队友」。

先理解一个心理模型#

Codex 不需要更多的指令，它需要的是更稳定的上下文。

每次 Codex 开始处理你的任务时，它会读取文件、理解结构、然后动手。但如果没有持久化的配置，它会在每次会话结束后忘掉一切。解决这个问题的六个支柱是递进式的：

AGENTS.md → 配置文件 → MCP 连接 → 技能包 → 自动化

每个支柱都建立在前面之上。你不需要第一天就把六个全搞定，但理解了它们之间的关系，你就知道该从哪里开始。

支柱一：每个任务都给足上下文#

在开始一个任务之前，确保 Codex 知道：

  • 项目结构：源码在哪、测试在哪、配置在哪？
  • 技术栈：什么语言、什么框架、什么构建工具？
  • 编码规范：代码风格、命名约定、过往踩过的坑
  • 当前状态：最近改了什么、出了什么错？

你当然可以在每次对话里手动输入这些信息。但有一个好得多的办法：支柱二。

支柱二：AGENTS.md — 写给 AI 看的使用说明书#

AGENTS.md 是一份写给 AI Agent 的 README。 Codex 会在每次会话开始时自动读取它。这是你投入产出比最高的一件事，没有之一。

里面写什么？#

类别示例
目录结构src/ 是源码，db/schema/ 是禁区
启动命令pnpm dev，docker compose up
测试/构建/检查pnpm test，pnpm build，pnpm lint
工程规则TypeScript 禁用 any 类型
约束条件不要修改 db/schema/ 目录
完成标准「通过 pnpm test 才算做完」

三层优先级#

~/.codex/AGENTS.md        → 个人全局默认设置
repo-root/AGENTS.md       → 团队共享规范
subdirectory/AGENTS.md    → 局部规则（优先级最高）

越靠近工作目录的文件优先级越高。你可以给前端和后端设置不同的规则。

怎么开始？#

在 Codex CLI 中输入 /init，它会自动生成一个初始版本。然后根据你的项目定制。

怎么演化？#

一份简短精确的 AGENTS.md，比一份长篇模糊的 AGENTS.md 有用得多。

从最基础的开始。只有当 Codex 重复犯同样的错误时，才往里面加规则。

实战例子： 你的 TypeScript 项目里，Codex 两次用了 any 类型。往 AGENTS.md 加一行：

修复：不要用 `any` 类型。用 `unknown` 配合类型守卫替代。

经验法则： 如果你纠正过 Codex 同一个问题两次，它就值得写进 AGENTS.md。

支柱三：配置文件，让行为保持一致#

AGENTS.md 告诉 Codex 你的项目怎么运作，配置文件告诉 Codex 它自己该怎么表现。

三层配置系统：

~/.codex/config.toml      → 个人默认值
.codex/config.toml        → 仓库级配置
CLI 参数                  → 一次性覆盖

你可以配置：默认模型、推理深度、沙盒模式、审批策略、MCP 服务器等。

支柱四：MCP，打通外部连接#

MCP（Model Context Protocol，模型上下文协议）让 Codex 连接到数据库、API、Jira、Notion，甚至可以接入任何外部服务。

黄金法则： 从 1 到 2 个高价值的 MCP 服务器开始。不要一口气接十几个，那样只会让 Codex 晕头转向。

支柱五：Skills，封装可复用的工作流#

当一个工作流开始重复时，不要再依赖长篇提示词。把它封装成一个 Skill：一份 SKILL.md 文件，在 CLI、IDE 和 Codex App 中都能用。

场景Skill 名称
标准调试流程debug-standard
PR 审查清单pr-review
发布说明生成generate-release-notes
日志分析analyze-logs
迁移方案规划migration-plan

存放位置：

  • 个人：$HOME/.agents/skills
  • 团队：.agents/skills（放在仓库里，可提交、团队共享）

Skills 的核心理念是：把一次性的经验变成可复用的资产。 你写得越多，Codex 就越像一个训练有素的团队成员，而不是一个每次都要从头教起的实习生。

支柱六：自动化，让 Codex 自主运行#

当一个工作流稳定可靠之后，就可以让它自动运行了。

在 Codex App 的 Automations 面板中，你可以配置：绑定哪个项目、执行什么提示词（可以调用 Skills）、运行频率、运行环境。

任务频率建议
汇总最近提交每天
扫描潜在 Bug每周
起草发布说明每次发版
检查 CI 失败原因每次 CI 运行
生成站会摘要每天

Skills 定义了方法，Automations 定义了节奏。

八个常见错误，看看你中招几个？#

错误一：把持久化规则塞进提示词里#

每次都在提示词里重写规范。忘写一次，Codex 就放飞自我。

✅ 规则写进 AGENTS.md，写一次，永久生效。

错误二：不给 Codex 验证手段#

没有告诉 Codex 怎么运行构建和测试，它等于蒙着眼睛写代码。

✅ 在 AGENTS.md 里写清楚构建和测试命令，每项任务都有「做完的标准」。

错误三：复杂任务跳过规划阶段#

Codex 什么都实现完了才想起来问问题，方向偏了，只能全部回滚。

✅ 用 /plan 模式，或者要求 Codex 先解释方案再动手。

错误四：一上来就给完整权限#

默认给 Codex 全套系统访问权限，出了问题才后悔。

✅ 从受限权限开始，逐步放宽。你了解了它的工作方式之后再放开。

错误五：不使用 git worktree 隔离#

多个会话同时修改同一批文件，冲突到你怀疑人生。

✅ 每个并行线程使用独立的 git worktree。

错误六：验证之前就自动化#

把一个不稳定的流程设成自动化，等于把混乱放大了十倍。

✅ 先稳定成 Skill，手动验证通过，再自动化。

错误七：事无巨细地微管理#

盯着 Codex 的每一步操作，等于浪费了它异步工作的最大优势。

✅ 布置完任务就去做别的事。把 Codex 当成后台任务，不要当成实时聊天。

错误八：整个项目塞进一个线程#

所有东西都堆在一个线程里，上下文膨胀，输出质量断崖式下跌。

✅ 一个任务一个线程。用 /fork 在保持上下文的前提下分支出新线程。

模型选对，配额翻六倍#

Plus/Pro 用户：配额比美元更重要#

大多数人不是在按 API token 付费，而是在用 ChatGPT Plus（$20/月）或 Pro（$200/月）的订阅。真正重要的是你的配额消耗速度，而不是花了多少钱。

不同模型消耗配额的速度天差地别：

模型输入（每千 token）输出相对消耗
GPT-5.5 🏆125 额度750 额度基准（100%）
GPT-5.4 ⭐62.5 额度375 额度5.5 的一半
GPT-5.4 Mini 🏃18.75 额度113 额度约为 5.5 的 1/6

简单算一笔账：用 GPT-5.4 Mini 替代 GPT-5.5，同样一份订阅，你的使用量能撑 6 倍时长。

聪明的分配策略：

  • 日常简单任务 → GPT-5.4 Mini（读代码、小 Bug、写测试、问问题）
  • 中等复杂度 → GPT-5.4（重构、调试、功能开发）
  • 只有高风险场景 → GPT-5.5（架构审查、安全检查、跨模块复杂修改）

推理深度也分级别#

级别适用场景
低 🏃快速、明确的小任务
中 ⭐日常默认，性价比最高
高 🧠复杂修改、深度调试
极高 🚀长时间自主运行的 agentic 任务

缓存的黑魔法：几乎免费#

复用相同的系统提示词和项目上下文会触发缓存，成本降低高达 90%。

真实数据（处理 1000 万 token）：

  • GPT-5.5 无缓存：约 $22
  • GPT-5.5 高缓存：约 $1.25（降低了近 20 倍）
  • GPT-5.4 Mini 高缓存：约 $0.24（几乎不要钱）

实操建议： 在同一个线程里持续对话，不要无谓地创建新会话。上下文缓存是省钱又提速的利器。

会话管理：一个任务，一个线程#

核心原则：一个线程对应一个任务，而不是一个线程对应整个项目。

上下文膨胀是 Codex 输出质量的头号隐形杀手。一个线程里堆积的东西越多，Codex 找到相关信息就越难。

关键命令#

命令用途
/fork从当前线程分支，适合工作拆分成多个方向时
/compact上下文太长时压缩精简
/plan进入规划模式，先讨论方案再动手
/status查看当前会话状态

并行工作的智慧#

✅ 可以并行❌ 不适合并行
后端改动 + 文档更新多个 Agent 修改同一批文件
一个写测试，一个做调研需求未确认就开始多个实现
一个负责实现，一个负责审查数据库 schema 和调用方同时改动

成熟的 Codex 工作流全景#

一次性搭建#

① /init → 自动生成 AGENTS.md
② 编辑 AGENTS.md → 补全构建命令、约束条件、编码模式
③ 配置 ~/.codex/config.toml → 模型、推理深度、审批策略
④ 接入 1 到 2 个高价值 MCP 服务器

日常使用节奏#

① 每个任务开新线程
② 四要素提示词：目标 → 上下文 → 约束 → 完成标准
③ 复杂任务先用 plan 模式
④ 布置完任务就去干别的
⑤ 回来审查 diff
⑥ 稳定的模式封装成 Skill

持续优化循环#

① Codex 同一个错误犯了两次 → 更新 AGENTS.md
② Skill 验证稳定 → 设为自动化
③ 定期回顾会话 → 调整配置

完整的开发闭环#

Codex 不应该只是生成代码。有了正确的指令，它还可以帮你测试、检查、审查。

让 Codex 跑完整个循环：

改代码 → 写/更新测试 → 运行测试 → 检查 lint/类型 → 验证行为 → 审查 diff → 发现回归

这种端到端的闭环，才是 Codex 区别于其他 AI 编程工具的本质优势。

写在最后#

如果这篇文章你只能记住三件事，那就是：

第一：AGENTS.md 是你投入产出比最高的一步。 花 10 分钟写，每天省 30 分钟。它把 Codex 从一个记不住事的工具，变成一个记得你项目规范、能独立做判断的队友。

第二：按任务选模型。 日常简单任务用 GPT-5.4 Mini 加低推理深度，复杂工作再用 GPT-5.4 或 5.5 加高推理深度。光这一个习惯，就能帮你省掉 60% 到 80% 的配额。

第三：一个任务一个线程，拆分时用 fork。 上下文膨胀是输出质量的头号杀手，不要贪图方便把什么都堆在一个线程里。

进阶路径很清晰：AGENTS.md → 配置 → Skills → 自动化

Skills 定义方法，Automations 定义节奏。一步一步来，不急。

参考来源：Hiroki Ii, “You’re Only Using 30% of Codex — Here’s the Other 70%”, dev.to, 2026-06-16. 基于 OpenAI 官方 Codex 文档和社区实践经验撰写。定价信息截至 2026 年 6 月，最新价格请查看 openai.com。