Codex Source Notes

Codex 源码阅读系列

这个系列从 openai/codex 的公开源码进入，不先贴功能清单，而是跟一条普通请求走：它怎样从一句话变成有类型的任务，怎样进入 session 和 turn，怎样整理上下文、暴露工具、经过权限关口，并把过程留下给客户端展示、后续恢复、长期记忆召回和平台沙箱执行。

源码证据固定到同一个 openai/codex 公开快照；产品契约来自 OpenAI 官方文档。每篇只描述公开客户端代码和协议可见的机制。

先把一个普通修 bug 请求拆成几道关口：入口、protocol、session、turn、上下文、工具权限、事件和持久记录。

从 ContextManager、TurnContext、for_prompt() 和 compaction replacement 读懂上下文管理。

从 TurnStartParams、Submission、Op、EventMsg 到 app-server v2 projection 和 rollout 恢复。

从 ToolSpec、ToolRouter、ToolRegistry、ToolInvocation 到 approval、sandbox、events 和 history。

从 approval_policy、permission hooks、ToolOrchestrator、SandboxAttempt 和 retry 读懂副作用边界。

从 EventMsg、TurnItem、ThreadItem、ServerNotification、TUI history cell 和 rollout 恢复读懂客户端状态。

从 skills、plugins、MCP tool exposure、tool_search、dynamic tools 和 AgentControl 读懂扩展入口。

从 HookEventName、hook discovery、HookStarted、HookCompleted、prompt gate、tool gates 和 Stop 读懂 hooks。

从 OpenAI prompt caching 契约、prompt_cache_key、stable prefix、dynamic tail、compaction 和 token usage 指标读懂性能路径。

从 RolloutItem、JSONL writer、InitialHistory、reverse scan、replay suffix、rollback marker 和 fork snapshot 读懂恢复。

从 app-server 的 initialize、typed ClientRequest、thread/start、turn/start、listener 和 SDK 读懂外部入口。

从 Feature::MemoryTool、memory_mode、Phase 1 / Phase 2、 memories/ workspace、read path、citation 和 polluted thread 读懂长期召回层。

从 SandboxAttempt、sandbox users、ACL、防火墙、command runner 和 restricted token 读懂 Windows 本地执行边界。