冻结快照
本教材不是按模糊的“当前 Codex”写作，而是固定在下列研究基线：
| 字段 | 值 |
|---|---|
| 官方仓库 | openai/codex |
| 分支 | main |
| Commit | 61a44880a85d2fd0d8770908dea5733495e571c8 |
| Commit 日期 | 2026-07-26 |
| 研究日期 | 2026-07-26（Asia/Shanghai） |
| 当时最近公开 Release | rust-v0.145.0 |
| Release 日期 | 2026-07-21 |
正文的 GitHub 源码链接都锁定到完整 commit，而不是会移动的 main。行号只对该快照成立。
研究方法
1. 从入口追控制流
从 cli_main 开始，依次追到 ThreadManager、Session::spawn、submission_loop、run_turn、模型流处理和 Tool dispatch。
2. 用协议校正术语
通过 Op、EventMsg、AskForApproval、SandboxPolicy 的公开类型确认系统实际建模的边界。
3. 用 Handler 确认副作用
沿 Router、Registry、Orchestrator 到 Shell 与 Apply Patch，区分模型意图、策略决策和真实执行。
4. 用官方文档确认用户承诺
配置、AGENTS.md、CLI、沙箱与产品使用以研究日的官方文档为准。源码事实与文档承诺分别标记。
5. 不跨越公开边界
没有从客户端字段推断模型训练方式、隐藏 prompt、云调度拓扑或服务端基础设施。
证据标签
源码可证实
固定 commit 中的类型、函数、控制流或测试直接支持。
官方文档
公开文档描述的产品行为；可能随服务与版本更新。
分析
基于公开证据的工程解释，不代表 OpenAI 官方设计声明。
核心源码索引
| 主题 | 文件 / 符号 |
|---|---|
| CLI 入口 | codex-rs/cli/src/main.rs::cli_main |
| Thread 创建 | codex-rs/core/src/thread_manager.rs::spawn_thread |
| 对外句柄 | codex-rs/core/src/codex_thread.rs::CodexThread |
| Session 启动 | codex-rs/core/src/session/mod.rs::Session::spawn |
| Agent Loop | codex-rs/core/src/session/turn.rs::run_turn |
| Prompt 组装 | codex-rs/core/src/session/turn.rs::build_prompt |
| 输出分类 | codex-rs/core/src/stream_events_utils.rs::handle_output_item_done |
| Context | codex-rs/core/src/context_manager/history.rs::ContextManager |
| Tool 路由 | codex-rs/core/src/tools/router.rs::dispatch |
| 工具注册 | codex-rs/core/src/tools/registry.rs::ToolRegistry |
| 审批/沙箱编排 | codex-rs/core/src/tools/orchestrator.rs::run |
| Patch | codex-rs/core/src/tools/handlers/apply_patch.rs |
| AGENTS.md | codex-rs/core/src/agents_md.rs |
| Op/Event | codex-rs/protocol/src/protocol.rs |
官方文档索引
- Codex CLI
- Configuration reference
- AGENTS.md
- Sandboxing
- Agent approvals & security
- App Server
- Non-interactive mode
- Codex SDK
明确未确认的内容
以下内容不在本教材的可证实范围内：
- Codex 使用模型的训练数据、内部推理过程和隐藏系统；
- OpenAI 托管推理服务的内部拓扑、调度和缓存实现；
- Codex Cloud 的完整隔离与任务调度内部架构；
- Cursor Agent 与 Claude Code 未公开的 runtime 细节；
main在研究日之后的行为；- 不同账户、平台或灰度发布下的全部产品差异。
如何刷新这份研究
新版本发布后，按以下顺序复核：
- 记录新的 tag、commit 与日期；
- 对比
protocol.rs的 Op/Event 和权限类型； - 对比
run_turn、ToolRouter、Orchestrator； - 检查配置参考与 AGENTS.md 文档；
- 重跑本网站构建与全部内部链接检查；
- 只在证据变化时更新架构结论。
结束，也是起点
现在你应该能把 Codex 看成一个完整系统：模型负责选择动作，Runtime 管理 Context 和循环，Tool 把意图变成副作用，Sandbox 与 Approval 限制风险，Event 把过程交还给人。
真正掌握它的下一步，是打开固定快照，从 run_turn 开始亲自走一遍调用链。