发布日期：2026-06-25 | 话题：AI 编程工具 | 适用人群：开发者、大型项目负责人、Codex 用户

Codex 底层使用 gpt-5.5 模型，官方上下文窗口为 200 万 token，单次对话理论上可装入约 150 万汉字或 5 万行代码——"上下文太短"的问题在大多数场景下并非窗口绝对不够，而是窗口被低效使用了：Codex 每次启动会扫描当前目录的全部文件，遇到没有 AGENTS.md 的大型项目时，光读文件就能消耗几十万 token，真正留给推理和代码生成的空间大幅压缩。根治方案有五类：AGENTS.md 精准引导（告诉 Codex 只读什么、不读什么）、任务拆分（一次只做边界清晰的一件事）、Subagent + Worktree 并行（多线程独立上下文，互不污染）、模型切换（轻量任务用 gpt-5.4-mini，省上下文消耗给复杂任务）、.codexignore 文件排除（从根源减少扫描量）。OpenAI 内部团队用 88 个 AGENTS.md 文件、7 人 5 个月完成 100 万行代码、合并 1500 个 PR，核心在于把上下文管理变成一种工程纪律，而不是依赖更大的窗口。

---

先诊断：你的上下文是真不够，还是被浪费了

在着手优化前，区分两种不同的根因：

症状	根因	对应方案
Codex 频繁说"已超过上下文限制"	窗口绝对不足	任务拆分 + Subagent 并行
回答质量下降、忘记前面说的内容	上下文被低效填满（读了太多无关文件）	AGENTS.md + .codexignore
每次都要重新说项目背景	没有持久化项目知识	AGENTS.md 全局配置
大型重构中途失去一致性	单线程上下文不足以覆盖全局	Subagent + Worktree 架构
简单任务也消耗大量额度	用旗舰模型做简单任务	模型分层（mini 处理简单任务）

快速自查命令——看当前会话的 token 消耗情况：

codex /status    # 查看当前窗口剩余额度和 token 使用量

---

方法一：AGENTS.md——最高性价比的上下文管理工具

AGENTS.md 是 Codex 的项目级指令文件，放在项目根目录，每次 Codex 启动时优先读取。它的核心价值是：用几百 token 的精准说明，替代 Codex 自行探索项目结构消耗的几万 token。

基础结构

# AGENTS.md

## 项目概述
这是一个 Next.js 14 + Prisma + PostgreSQL 的 SaaS 管理后台。
主要业务模块：用户管理、权限控制、数据报表、消息通知。

## 目录结构（只需了解这些）
- src/app/          → Next.js App Router 路由和页面
- src/components/   → 可复用 React 组件
- src/lib/          → 工具函数和 API 封装
- prisma/           → 数据库 Schema 和迁移文件
- tests/            → Vitest 测试文件

## 不要读取的目录
- node_modules/、.next/、dist/、coverage/（构建产物）
- prisma/migrations/（已有迁移不要修改）

## 技术约定
- 样式：Tailwind CSS，不引入其他 CSS 框架
- 状态管理：Zustand，不使用 Redux
- 测试：Vitest，测试文件放 tests/ 目录，命名 *.test.ts

## 每次任务前
1. 先读本文件确认范围
2. 只修改任务明确指定的文件
3. 完成后运行 npm test 验证

多层级 AGENTS.md

Codex 支持全局、项目根目录、子目录三级 AGENTS.md，越靠近文件的指令优先级越高：

~/.codex/AGENTS.md          → 全局规则（所有项目通用）
项目根目录/AGENTS.md         → 项目规则（覆盖全局）
src/components/AGENTS.md    → 子模块规则（覆盖项目级）

子目录 AGENTS.md 的典型用法——限定 Codex 在特定模块内的行为：

# src/components/AGENTS.md

## 组件模块说明
这里只放展示型 React 组件，不包含业务逻辑。
修改组件时不要引入新依赖，不要修改 API 调用逻辑。
样式只用 Tailwind，不写 CSS-in-JS。

OpenAI 内部的 AGENTS.md 实践

腾讯云开发者社区报道（2026-06-19）：OpenAI 内部一个 7 人团队，5 个月用 Codex 写了 100 万行代码，合并了 1500 个 PR，人工 review 比例接近零。他们的核心差异不是模型，是写了 88 个 AGENTS.md 文件——每个模块一份，精确控制 Codex 在每个上下文中能看到和能做的事。

---

方法二：.codexignore——从源头减少扫描量

类似 .gitignore，在项目根目录创建 .codexignore 文件，列出不需要 Codex 读取的目录和文件：

# .codexignore

# 构建产物（通常最大）
node_modules/
.next/
dist/
build/
coverage/
*.min.js
*.min.css

# 自动生成文件
prisma/migrations/
*.lock
package-lock.json
yarn.lock
pnpm-lock.yaml

# 资源文件（Codex 不需要读图片和字体）
public/images/
public/fonts/
assets/

# 测试快照（频繁变化，上下文噪音）
**/__snapshots__/

实际效果：一个中型 Next.js 项目，排除 node_modules 和 .next 后，Codex 需要扫描的文件从 5 万+ 降到几百个，上下文消耗减少 90%+ 。

---

方法三：任务拆分——一次只做一件事

上下文不够的最常见原因，不是项目太大，而是一次给了太多任务。

问题写法：

帮我把整个项目的 axios 调用统一封装成 fetchClient，
顺便把所有组件的 TypeScript 类型补全，
再把单测覆盖率提升到 80%

→ Codex 需要读取整个项目，三类任务互相干扰，上下文很快爆满。

正确写法——按边界拆分为三个独立任务，分别新开对话：

任务 1（新对话）：
只修改 src/lib/api/ 目录下的文件，把所有 axios 直接调用
封装成 fetchClient，不修改调用方（组件文件）。

任务 2（新对话）：
只处理 src/components/UserTable.tsx 这一个文件，
补全所有 TypeScript 类型，不修改其他文件。

任务 3（新对话）：
为 src/lib/auth.ts 补充单测，测试文件放 tests/lib/auth.test.ts，
只覆盖 login、logout、refreshToken 三个函数。

任务拆分原则：

• 每个任务明确指定文件范围（最好具体到目录或文件名）
• 每个任务有清晰的完成标准（改什么、不改什么）
• 任务之间无依赖（任务 A 的输出不是任务 B 的输入）

---

方法四：Subagent + Worktree 并行——多线程独立上下文

当项目确实需要同时推进多个模块时，Codex 桌面版支持 Subagent + Worktree 架构：每个子任务运行在独立的 Git Worktree 分支上，拥有完全独立的上下文窗口，互不污染。

主 Codex 实例（Orchestrator）
│
├── Subagent 1 → Worktree branch: feature/auth-refactor
│   └── 上下文：只加载 src/lib/auth/ 相关文件
│
├── Subagent 2 → Worktree branch: feature/api-types
│   └── 上下文：只加载 src/types/ 相关文件
│
└── Subagent 3 → Worktree branch: feature/unit-tests
    └── 上下文：只加载 tests/ 相关文件

关键优势：

• 每个 Subagent 的上下文互相隔离，不会因为一个任务的文件读取"污染"其他任务
• 各分支并行推进，不用等待串行完成
• 主实例随时可以查看各 Subagent 的进度，汇总后合并

Worktree 模式适合的场景：

• 前后端同时重构，文件不重叠
• 多个功能模块并行开发
• 大型重构 + 同步补测试

---

方法五：模型分层——轻量任务用 mini 保留旗舰额度

gpt-5.5 和 gpt-5.4-mini 面对同样的项目时，加载上下文的 token 消耗是相同的，但 mini 的额度是 gpt-5.5 的 4-8 倍（同一套餐下）。用旗舰模型做"修改注释"或"格式化"这类简单任务，是典型的资源浪费。

# ~/.codex/mini.config.toml（轻量任务专用）
model = "gpt-5.4-mini"
model_reasoning_effort = "low"
approval_policy = "on-request"

# 日常简单任务（注释、格式化、写单测）
codex --profile mini "为 src/utils/format.ts 的所有函数补上 JSDoc 注释"

# 复杂任务（架构重构、多文件理解）
codex "重构 src/lib/auth/ 目录，把 JWT 验证逻辑提取成独立模块"

任务与模型对应关系：

任务类型	推荐模型	理由
补注释、格式化、修 lint	gpt-5.4-mini	不需要深度推理
写单测（已有实现）	gpt-5.4-mini	模式固定，mini 够用
单文件重构（< 500 行）	gpt-5.4	中等理解力
多文件重构、架构分析	gpt-5.5	需要全局理解
理解陌生大型项目	gpt-5.5	需要强推理能力

---

进阶：/goal 拆解长期任务

Codex CLI 的 /goal 命令支持输入高层目标，由 Codex 自动拆解成多个子任务并逐步执行——每个子任务在独立上下文中运行，总任务不受单次上下文限制：

codex
> /goal 把 src/api/ 目录下所有的直接 fetch 调用统一封装成 apiClient，
  完成后运行 npm test 确认所有测试通过，
  每个文件改完后提交一个独立的 git commit

# Codex 会自动拆解为：
# 1. 扫描 src/api/ 找出所有 fetch 调用
# 2. 创建 apiClient 封装层
# 3. 逐文件替换（每文件一个 commit）
# 4. 运行 npm test 验证

/goal 适合的场景：

• 明确的最终状态（“所有文件都完成 X”）
• 任务可以被分解为重复的子步骤
• 允许 Codex 自主规划执行路径

---

最佳实践组合

针对不同项目规模，推荐的组合策略：

小型项目（< 1 万行代码）：

• 基础 AGENTS.md（项目根目录一份）
• 任务拆分（按功能模块分对话）
• 模型：gpt-5.4 日常 + gpt-5.5 复杂重构

中型项目（1-10 万行代码）：

• AGENTS.md（根目录 + 2-3 个主要模块子目录）
• .codexignore（排除构建产物和依赖）
• 任务拆分 + 每个大功能新开对话
• Worktree 并行处理前后端

大型项目（> 10 万行代码）：

• AGENTS.md 分模块（参考 OpenAI 内部的 88 文件实践）
• .codexignore 精细化
• Subagent + Worktree 架构（主实例只做协调，子实例做具体工作）
• /goal 拆解跨模块任务
• 模型路由（模块复杂度决定用哪层模型）

---

常见问题 FAQ

Q1：gpt-5.5 的 200 万 token 上下文窗口够用吗？
200 万 token 约等于 150 万汉字，或 4-5 万行代码，对绝大多数单次任务来说绰绰有余。真正的问题是 Codex 在没有引导的情况下会"贪婪"读取——遇到大型项目会扫描全部文件，轻松把窗口填满。AGENTS.md 和 .codexignore 的作用不是扩大窗口，而是把有限的窗口用在刀刃上。

Q2：AGENTS.md 写太长会不会反而浪费上下文？
会。AGENTS.md 本身也会占用 token，建议控制在 200-500 字以内，重点写：目录结构（只列关键目录）、不要读的文件、技术约定、每次任务的前置步骤。不需要写完整的项目介绍或所有文件的作用。

Q3：Subagent 和直接开多个 Codex 窗口有什么区别？
手动多窗口是完全独立的进程，没有协调机制，也没有文件冲突保护。Subagent + Worktree 是有托管的并行：主实例知道每个子实例在做什么，每个子实例工作在独立的 Git 分支上，不会互相改同一个文件，完成后可以有序合并。手动多窗口适合任务完全独立的场景；Subagent 适合有内在关联、需要最终合并的并行工作。

Q4：.codexignore 和 .gitignore 可以复用同一份吗？
大部分可以复用，但有区别：.gitignore 排除的是不追踪到 git 的文件；.codexignore 排除的是不需要 Codex 读取的文件。两者内容高度重叠（node_modules、dist、.next 等），但 .codexignore 通常还需要额外排除一些 git 追踪但 Codex 不需要读的文件（比如 pnpm-lock.yaml、生成的 API 类型文件）。建议以 .gitignore 为基础，根据项目情况额外添加几行。

Q5：/goal 和普通任务提示词有什么实质区别？
普通提示词是"告诉 Codex 做什么"，Codex 用单次上下文完成任务。/goal 是"告诉 Codex 要达到什么目标"，Codex 自主规划步骤，每步在独立的上下文中执行，步骤之间传递的只是结构化的中间结果而非完整对话历史。本质上是把长上下文任务拆成多个短上下文任务的自动化手段，适合有明确终止条件的重复性工作。

---

小结

Codex 上下文管理的核心原则是：不要依赖更大的窗口，而是告诉 Codex 用最小的上下文完成最精准的任务。五种方法的优先级排序：AGENTS.md（每个项目必备，10 分钟配置）→ .codexignore（中大型项目必备）→ 任务拆分（最直接的提升）→ 模型分层（节省额度）→ Subagent + Worktree（大型项目并行架构）。OpenAI 内部团队 88 个 AGENTS.md 的实践说明：上下文管理是一种工程能力，不是临时应对措施。本文数据来源：腾讯云开发者社区《Prompt Engineering 已死》（2026-06-19）、知乎《AGENTS.md 全流程落地实操》（2026-06-18）、OpenAI Codex 官方文档（developers.openai.com/codex）。

---

参考来源：

• OpenAI Codex 官方文档（developers.openai.com/codex）
• Fenno 官网：AI 编程