Codex 上下文窗口与会话管理实战指南：让 AI 编程助手记住你的整个项目

引言

在使用 AI 编程助手时，开发者最常遇到的痛点之一就是"失忆"——当你和 Codex 协作写了一个小时的代码，它突然忘记了之前讨论过什么，或者当你重新打开终端后，上一轮会话的上下文荡然无存。理解 Codex 的上下文窗口机制和会话管理策略，是告别这类烦恼的关键。

本文将深入解析 Codex CLI 的上下文管理体系，包括上下文窗口的工作方式、会话持久化机制、项目记忆的文件策略，以及在实际开发中如何高效利用这些特性。

上下文窗口：AI 的"工作记忆"

什么是上下文窗口

上下文窗口（Context Window）是 Codex 和底层 LLM 在单次对话中能够"看到"的全部内容。它就像一个滑动窗口，包含了你发送的提示词、Codex 的回复、工具调用的结果、读取的文件内容等。

Codex 运行在你本机，使用你的 ChatGPT 账号或 API Key 调用模型。根据你选择的模型不同，上下文窗口大小也不同：

| 模型 | 上下文窗口（tokens） |
|------|---------------------|
| GPT-4o | 128K |
| GPT-4o-mini | 128K |
| GPT-4.1 | 1M |
| o3 | 200K |
| o4-mini | 200K |

128K tokens 大约相当于 250 页英文文本或 9 万多个中文汉字。对于大多数单个功能或模块的开发任务，这个窗口完全够用。

上下文窗口的组成

当你和 Codex 对话时，上下文窗口由以下几部分组成：

系统提示词（System Prompt）：Codex 的核心行为指令，告诉模型它是什么角色、有哪些工具可用、遵循什么规则。这部分通常是固定的，占用一定比例的 tokens。

AGENTS.md / CODEOWNERS 等配置文件：你项目中的 AGENTS.md、CODEOWNERS 文件会在会话启动时被读取并注入到系统提示中，让 Codex 理解你的项目规范。

当前工作目录的文件树：Codex 会自动感知项目结构，知道有哪些文件和目录。

对话历史：你和 Codex 之间的每一轮交互——你的指令、Codex 的思考、工具调用结果，都累积在上下文中。

工具输出：Codex 执行 bash 命令、读取文件、搜索代码等操作产生的结果。

理解这个结构很重要，因为它决定了 Codex 在长时间对话中何时会"遗忘"早期内容——当对话历史 + 工具输出超出窗口上限时，最早的内容会被截断。

如何识别上下文窗口已满

Codex 会在上下文中自动管理窗口填充。当接近上限时，你可能会观察到以下信号：

• Codex 开始遗忘早期讨论过的设计方案或决策
• 回复中引用的代码片段不是最新版本的
• 需要你重复之前已经提供过的信息
• 回复质量下降，出现更多"幻觉"

当你发现这些信号时，最好的做法是开始一个新的会话，并用一段清晰的总结告诉 Codex 当前的进度和下一步计划。

会话管理

会话恢复机制

Codex CLI 支持会话持久化。当你使用 codex 命令进入交互模式后，Codex 会自动保存你的会话状态，包括对话历史和项目上下文。如果你意外退出终端，重新运行 codex 通常可以恢复上一次的会话。

# 启动 Codex 交互会话
codex

# 在会话中，你可以使用 Ctrl+C 退出
# 下次启动 codex 时，会提示是否恢复上次会话

对于长周期开发任务，这个机制让你可以分多个阶段完成工作，而不必每次从零开始。

主动管理会话的最佳实践

1. 分阶段工作，每个会话聚焦一个目标

不要在同一个会话中让 Codex 帮你写前端页面、设计数据库 Schema、又去修 CI 配置。每个会话聚焦一个清晰的目标，上下文利用效率最高。

# 好的做法：一个会话专注一个模块
Session 1: 实现用户认证模块的 JWT 逻辑
Session 2: 编写用户认证相关的单元测试
Session 3: 集成认证模块到 API 路由

2. 善用"进度总结"

当一个会话任务过半，或者你感觉上下文有点"混乱"时，让 Codex 为当前会话做一个结构化总结：

请帮我总结当前会话的进度：
1. 已完成的部分
2. 当前正在进行的工作
3. 下一步计划
4. 关键决策和注意事项

请将总结保存到 .opencode/session_summary.md

这个总结文件可以作为下一个新会话的起点，让 Codex 快速进入状态。

3. 利用 AGENTS.md 做持久化记忆

AGENTS.md 是 Codex 的"长期记忆"文件。它会随每个新会话启动而加载。在 AGENTS.md 中，你可以定义：

# AGENTS.md

## 项目概述
这是一个基于 Gin 的 Go 博客系统后端。

## 技术栈
- Go 1.22 + Gin 框架
- MySQL 8.0 + GORM
- Redis 缓存层
- JWT 鉴权

## 代码规范
- 错误处理必须显式，不使用 panic
- API 返回值统一使用 `{ "code": 0, "data": {}, "msg": "" }` 格式
- 数据库查询必须传 context

## 当前迭代信息
- 正在实现文章标签功能（2026-08-02）
- Tags API 路由：/api/v1/tags
- 数据模型定义在 models/tag.go

每次会话结束前，如果产生了新的架构决策或项目约定，及时更新 AGENTS.md。

文件感知与项目记忆

Codex 如何"看懂"你的项目

当你运行 codex 时，它会对当前工作目录做扫描，建立对项目结构的认知。Codex 会自动：

• 读取目录树（通过 os 调用或工具执行 ls、find 等命令）
• 发现包管理文件（package.json、go.mod、Cargo.toml 等），推断技术栈
• 读取项目根目录的配置文件（.gitignore、README.md 等）
• 加载 AGENTS.md、CODEOWNERS 等特殊文件

这些信息在会话启动时被注入到上下文，帮助 Codex 理解"这是什么项目"。

用 .codexignore 控制上下文范围

对于大型项目，你不需要让 Codex 看到所有文件。.codexignore 文件可以排除不需要的内容，减少上下文噪音：

# .codexignore
node_modules/
vendor/
dist/
*.log
*.min.js
coverage/
.git/

排除无关文件有两个好处：一是减少 Codex 扫描项目的时间，二是避免无用的文件信息占满上下文窗口。想象一下，让 Codex 在 node_modules 的几十万个文件里搜索代码——这不仅慢，而且毫无意义。

临时注入文件到上下文

在对话过程中，你可以主动让 Codex 读取特定文件来刷新它的"项目记忆"。比如在你的架构调整后：

我刚刚重构了 models/user.go，把 User 结构体拆成了 User 和 UserProfile。
请读取 models/user.go 和 models/user_profile.go 了解新的数据结构，
然后更新 services/user_service.go 中所有相关的方法。

这种显式的"喂文件"策略比依赖 Codex 自动感知更加可靠。

多轮对话策略

复杂任务的分步拆解

对于复杂功能，不要一次性抛出所有需求。使用"逐步细化"的策略：

第一轮：
"请帮我实现一个用户注册的 API 接口，返回文档大纲即可，先别写代码。"

第二轮：
"大纲没问题。请先实现 models/user.go 中的 User 数据模型。"

第三轮：
"好的，现在实现 handlers/user.go 中的 Register 处理函数。"

这样做的好处是：每一轮对话都聚焦在一个小而清晰的目标上，Codex 消化上下文的速度更快，输出质量更高。

利用"记忆锚点"

当上下文非常庞大时，Codex 可能难以定位早期讨论中的关键信息。你可以使用"记忆锚点"来帮助它：

关于之前讨论的认证中间件，我们的决定是：
1. 使用 JWT，不引入 session
2. Token 有效期 2 小时，支持 refresh
3. 中间件注册在中间件链的第 3 个位置

基于以上决定，请实现 auth/middleware.go

这种做法相当于在对话中插入了"书签"——即使早期上下文被截断，关键决策也保留在最新的对话轮次中。

高级技巧

利用 codex exec 做单次任务

对于不需要上下文积累的独立任务，使用 codex exec 比交互模式更高效：

# 单次任务：检查代码中是否有未处理的错误
codex exec "检查 handlers/ 目录下所有 .go 文件，找出那些没有正确处理 error 返回值的函数"

# 与管道结合
git diff main | codex exec "审查这些代码变更，找出潜在的安全问题和逻辑错误"

单次 exec 调用不需要维护长上下文窗口，执行速度快，适合 CI/CD 集成。

上下文切换时的交接策略

当你需要把当前会话的工作交给另一个会话（或另一个开发者）继续时，使用结构化的交接格式：

请生成一份交接文档，包含以下内容：
---
会话目标: [原始目标]
已完成:
  - [文件路径]: [完成的工作]
  - ...
当前进度:
  - [正在做什么]
待完成:
  - [下一步任务]
关键决策:
  - [决策内容和理由]
已知问题:
  - [尚需解决的问题]
---

将这个交接文档作为新会话的初始上下文，无缝衔接。

监控 Token 使用

在 Codex 会话中，你可以通过以下方式了解上下文消耗情况：

# 在 Codex 会话中执行
/status

这个斜杠命令会显示当前会话的状态信息，包括已使用的 token 数量、剩余空间等。定期检查可以帮助你判断是否需要开启新会话。

总结

Codex 的上下文窗口和会话管理，本质上是人类-AI 协作中的"沟通质量"问题。一个会管理上下文的开发者，和一个有什么需求就丢进去的开发者，在 AI 辅助效率上可能是数量级的差距。

核心要点回顾：

理解上下文窗口结构——知道哪些内容占据了有限 token，才能有针对性地管理

分而治之——每个会话聚焦单一目标，用 codex exec 处理独立任务

善用 AGENTS.md——它是 Codex 的长期记忆，随每个会话启动而加载

及时做会话总结——在上下文"爆满"前主动整理，作为新会话的起点

控制文件范围——用 .codexignore 排除无用内容，减少上下文噪音

使用内存锚点——在长对话中重复关键决策，帮助 Codex 定位重要信息

掌握这些策略后，Codex 将不再是"只有 10 分钟记忆"的 AI 助手，而是一个真正理解你项目全貌的编程伙伴。