本页解决什么问题
Codex 的一次工作不是一条孤立的问答,而是一条持续推进的会话。它会读取文件、运行命令、查看结果,并把这些内容带入后续决策。会话越长,信息越多;信息越多,越需要知道哪些内容仍在上下文窗口里、何时应该压缩、怎样从旧会话继续,或者怎样从一个节点分叉出另一条方案。 本页专门讲四个容易混淆的概念:- 上下文窗口:当前一次模型调用能够使用的信息预算。
- 会话(session/thread):你的消息、Codex 的回答和工具调用组成的可恢复工作记录。
compact:把较早的详细过程压缩为摘要,给后续任务释放上下文空间。- Memories / Chronicle:跨会话的本地记忆层。它们不是当前会话的完整历史,也不能替代项目规则。
- 判断“继续当前会话”“
resume原会话”还是“fork新分支”。 - 在上下文接近上限时主动
compact,并检查摘要是否保留了关键事实。 - 分清
AGENTS.md、会话历史、Memories 和 Chronicle 各自从哪里获得信息。 - 在敏感项目中关闭记忆、清理本地产物,并验证没有把秘密带入下一轮工作。
- 为长任务制作可交接的状态记录,让另一个会话或同事能够接着做。
命令、菜单名称和默认值可能随 Codex CLI、桌面 App 或 IDE 扩展版本变化。本文使用常见命令形式说明工作方法;执行前先运行codex --help、codex resume --help、codex fork --help,以及会话内的/help。本页不把某个版本的界面文案当成稳定 API。
先建立四层模型
不要把“上下文”“会话”“记忆”当成同一个东西。可以用下面四层来理解:
这四层的优先级和可靠性也不同:
- 必须每次遵守的规则写进项目内的
AGENTS.md,必要时提交到 Git。 - 只对当前任务成立的事实留在当前会话或任务状态文件里,不要期待 Memories 及时更新。
- 需要完整过程时保存会话 ID、Git 检查点和验证结果。
- 稳定且非敏感的长期信息才考虑交给 Memories。
- 屏幕上出现的内容只有在明确接受额外隐私风险时,才考虑启用 Chronicle。
上下文窗口是什么
上下文窗口是模型在一次响应时可使用的信息容量。它通常包括系统指令、项目规则、你的消息、Codex 的历史回答、工具调用及其输出、已读取的代码片段,以及可能注入的记忆。不同模型和版本的窗口大小不同,界面显示方式也可能不同。 它不是“磁盘空间”,也不是“会话总长度”:- 会话记录可以继续存在,但较早内容可能不再逐字放入当前请求。
- 文件仍然在磁盘上,但 Codex 不会因为文件存在就自动记得全部内容。
- 一段很长的测试日志可能比几十轮简短对话更快耗尽窗口。
- 一次压缩通常保留摘要,而不是保证每个旧工具输出逐字符可回忆。
哪些内容最占上下文
以下内容通常会快速消耗窗口:- 整个大型文件被多次重复读取。
- 未截断的构建日志、堆栈、数据库导出和生成文件。
- 一次任务同时讨论多个互不相关的目标。
- 把大段第三方文档、网页和二进制转储直接贴进对话。
- 让代理反复尝试同一个失败方案,却没有记录失败原因。
- 多个并行子任务把相似的结果全部汇总到主会话。
窗口接近上限时的表现
不同版本的表现不完全相同,常见信号包括:- Codex 提示上下文接近限制,建议压缩。
- 回复开始遗漏较早的约束,或重新询问已经确认的事实。
- 工具输出被截断,模型只看到日志尾部或摘要。
- 任务还没有完成,却频繁出现“重新读取文件”的动作。
- 自动压缩后,Codex 能继续工作,但对早期决策的细节不再准确。
/compact(如果本版本提供),或使用 CLI 帮助中显示的对应压缩操作。
会话的生命周期
会话是连续的工作线程:你提出请求,Codex 返回说明并可能调用工具;你继续补充,Codex 在同一个线程中使用可用上下文继续推进。会话适合以下情况:- 任务目标仍然相同。
- 当前工作区和分支没有变化。
- 之前的决策、错误和工具结果仍对下一步有帮助。
- 你还没有把会话变成一堆互不相关的问题。
fork 就认为文件改动自动隔离。需要隔离代码时,使用 Git 分支或 worktree,并在会话中确认当前目录。
在开始重要任务前先记录身份和工作区:
resume:从原会话继续
resume 的用途是找回原来的会话记录,继续同一项工作。常见形式如下,实际参数以本机帮助为准:
resume 失败时怎么处理
找不到会话:检查是否使用了不同的 CODEX_HOME、不同的操作系统用户或不同的工作目录;再运行 codex resume --help 和会话列表命令。不要为了“找回”而删除 ~/.codex。
恢复后上下文不完整:会话记录可能经过压缩,或者旧工具输出不再完整。让 Codex重新读取关键文件,并从 Git、测试输出和任务状态记录补齐事实。
恢复到了错误的会话:立即停止修改,查看会话标题、时间、项目路径和当前分支。确认无误前不要运行写入、提交或删除命令。
本地状态与会话不一致:以实际工作区和 Git 为准。会话只能说明过去发生过什么,不能证明当前文件仍然相同。
fork:从一个节点分出新路线
fork 适合保留当前上下文,同时尝试另一种实现、另一套策略或一个实验性方向。常见形式可能是:
fork 的场景:
- 同一个 bug 有两种修复方案,需要分别评估。
- 想让一个会话做实现,另一个会话只做代码审查。
- 原会话方向基本正确,但需要保留一个实验分支。
- 需要从一个已完成的分析节点开始,提出不同的设计问题。
fork 解决的场景:
- 需要两条路线同时写同一批文件。
- 需要保护主工作区不被实验改动污染。
- 需要并行运行相互冲突的依赖安装或迁移。
compact:压缩过程,保留方向
compact 的目的不是删除会话,也不是提交代码,而是把较早的对话和工具过程提炼成较短的摘要,释放后续上下文空间。常见入口是:
/help。压缩前先主动写一份“不可丢失事实”,比依赖自动摘要更可靠:
什么时候主动压缩
- 同一会话已经跨越多个独立阶段,早期原始日志不再需要。
- Codex 开始重复读取相同文件或忘记已确认的约束。
- 接下来要处理的模块与早期讨论关系不大。
- 大量测试日志、网页内容或生成代码已经占据窗口。
- 你准备把任务交接给另一个人,但还没有形成简洁状态摘要。
什么时候不要急着压缩
- 正在分析一个需要逐行对照的失败测试。
- 还没有保存关键错误输出、接口契约或迁移步骤。
- 当前 diff 尚未审查,且你需要追溯每次修改的原因。
- 会话中有尚未写入任务状态文件的临时决定。
四种操作怎么选
典型决策:先
resume 找回会话;恢复后如果只是空间不足,先保存摘要再 compact;如果要比较方案,建立隔离的 Git 工作区后 fork;如果任务边界已经改变,开新会话并显式提供状态摘要。
Memories:从哪里来,怎么用
Memories 是跨会话的本地记忆层。它和当前会话历史不同:当前会话保存任务过程,Memories 试图从有价值、可复用的历史会话中提炼稳定信息。生成通常是后台异步的,不保证在你刚说完后立刻出现,也可能跳过过短的会话或配额不足的生成任务。 参考资料给出的常见配置形式是:[memories] 或某个键,运行 codex --help、查看配置参考,并以启动时的错误信息修正;不要为了消除错误而随意切换到完全访问权限。
会话内通常可以使用:
config.toml。菜单名称可能变化,先阅读选项说明。
Memories 的适用内容
适合的内容具有三个特征:稳定、低敏感、可重复使用。例如:- 你长期使用的语言、测试框架和格式化工具。
- 反复出现的项目背景,例如某个服务的职责边界。
- 多次验证过的工作习惯,例如提交前运行哪组检查。
- 已经确认且不会泄露安全信息的排错经验。
- API key、密码、令牌、私钥、Cookie、数据库连接串。
- 客户姓名、联系方式、内部工单和未公开业务数据。
- 一次性端口、临时分支、当前任务的中间状态。
- 尚未确认的猜测、未经审查的代码结论。
- 必须每次生效的团队规则,尤其是权限和发布禁令。
Memories 的存放、检查和清理
默认记忆目录通常位于:CODEX_HOME,应检查实际路径:
~/.codex,因为其中可能有登录状态、配置或其他会话数据。
/memories 或状态信息确认是否仍在使用旧记忆。不要用“Codex 没有再次提到它”作为唯一证据;让它说明当前启用状态,并检查实际配置。
Chronicle:从屏幕上下文获得线索
Chronicle 是比普通 Memories 更敏感的实验性能力。普通 Memories 主要从会话中提炼信息;Chronicle 可以使用屏幕内容、屏幕中的文字和相关应用上下文帮助形成记忆或识别更合适的信息来源。它不是当前会话的完整录屏,也不等于你明确选择的项目文件。 参考资料指出,Chronicle 的可用平台、订阅和地区有限,且入口会变化;通常需要 macOS 的屏幕录制和辅助功能权限。Windows、Linux 或不符合订阅与地区条件时,看不到开关不一定是安装故障。请以官方页面和当前 App 设置为准,不要通过修改权限或网络位置绕过限制。 启用前应理解三项代价:- 后台代理可能快速消耗速率限额。
- 屏幕内容可能包含网页、文档或消息中的提示注入内容,扩大攻击面。
- 生成的记忆在本地通常是不加密的 Markdown 或类似文本状态。
CODEX_HOME 下的扩展目录,参考资料给出的示例是:
何时禁用记忆
以下情况建议临时禁用本会话的记忆使用和生成:- 正在处理个人隐私、客户数据、公司内部资料或安全事件。
- 使用了 MCP、网页搜索、外部文档或其他不受你完全控制的上下文。
- 任务是一次性实验,不希望错误结论影响未来会话。
- 你正在迁移项目,旧的技术栈和目录约定会误导后续操作。
- 你怀疑现有记忆过期、冲突或包含不该保留的内容。
- 需要把会话交给不同权限或不同组织边界的人。
/memories,关闭当前会话使用或生成;长期做法是在 config.toml 中关闭对应项。修改后重启 Codex,并用 /status、/help 或设置界面确认状态。配置键名和默认值以当前版本为准。
如果要完全停用,采用“配置、会话、文件”三步检查:
长任务交接:不要只交一个会话 ID
会话 ID 有帮助,但不是完整交接材料。长任务应在仓库或安全的任务目录里维护一个短状态文件,例如TASK-STATUS.txt;是否提交由团队规则决定。它至少包含:
AGENTS.md、任务状态和相关 diff,再恢复会话或开新会话。第一条消息应要求复述和验证,而不是直接继续写文件:
一套可重复的工作流
1. 开始前建立检查点
2. 明确会话策略
在第一条消息中写清目标、范围、验收标准和禁止事项:3. 分阶段推进
把探索、实现和验证分开。每个阶段结束时记录已确认事实。探索阶段输出太长时先摘要,再compact;实现阶段保持单一目标;验证阶段让 Codex 展示命令、退出码和关键输出。
4. 每次恢复都做现实检查
无论是普通继续、resume、fork 还是 compact 后继续,都执行:
5. 结束时形成可交付状态
失败处理清单
Codex 说“记得”,但行为不对:先检查AGENTS.md 和当前会话上下文;再确认 Memories 是否启用、是否可能尚未异步生成。必须生效的规则移入项目规则文件。
压缩后漏掉关键约束:不要继续猜。让 Codex列出不确定项,重新读取规则、状态文件和目标代码;必要时从 Git 历史或测试输出恢复事实。
resume 后改错目录:立即停止。打印当前路径、分支和 git status,确认会话关联的项目;不要用会话标题推断工作区。
fork 后两个会话互相覆盖:停止其中一个写入任务,比较当前 diff;使用 Git worktree 或独立目录重新隔离,不要依靠会话名称隔离文件。
记忆目录没有新文件:检查功能开关、地区和平台可用性、会话是否过短、会话是否被设置为不生成,以及速率限额;后台记忆本来就不是即时反馈。
记忆中出现敏感内容:立即关闭记忆生成和 Chronicle,断开可能的分享或同步,保留取证需要的最小信息,然后选择性删除本地产物。若秘密已经暴露,按该秘密所属服务的流程轮换或撤销,不能只删除 Markdown。
配置报错:删除未经当前版本确认的键,保留最小配置,运行 codex --help 或官方配置参考逐项恢复。不要把配置错误误判为上下文或权限问题。
最终验收
完成一个长任务或会话交接时,至少确认:git status、当前分支和实际工作区与摘要一致。- diff 只包含预期文件,
git diff --check通过。 - 关键测试、构建或静态检查有明确命令和结果。
AGENTS.md中的硬规则没有被只写进 Memories 的临时建议替代。- 没有把密码、令牌、私钥、客户资料或内部屏幕内容写进代码、日志、状态文件或记忆。
resume使用了正确会话;fork的文件隔离方式已经验证;compact后的摘要经过复述检查。- 不再需要时,敏感会话已关闭记忆;Chronicle 已暂停或关闭,相关本地产物已检查。
- 尚未验证的假设、剩余风险和回滚点已经明确写出。
小结
把 Codex 的上下文管理记成一条链:当前上下文负责眼前的细节,会话记录负责恢复过程,compact 负责在窗口受限时保留方向,Memories 负责跨会话复用稳定且低敏感的信息,Chronicle 则以更高隐私成本补充屏幕线索。
实际工作中按下面的顺序最稳:先用 AGENTS.md 固化必须遵守的规则;用 Git 和状态文件保存可验证事实;用 resume 找回同一任务;用 fork 比较方案并隔离工作区;用 compact 管理窗口;在敏感场景关闭和清理记忆;每次恢复后都用路径、分支、diff 和测试重新验收。
参考资料:参考/codex/19-memory.md、参考/codex/02-core-concepts.md、参考/codex/06-first-task.md。动态命令和配置以本机 Codex 的 --help、/help 及官方文档为准。