外观
Codex 运行机制与工程优化：运行机制篇
分册导航： 本篇聚焦 Codex 的概念边界、Agent Loop、源码模块、工具、安全与状态机制；工程优化、项目实践、能力评测与选型见 Codex 运行机制与工程优化：工程实践篇。
目录
1. 学习目标
- 区分 Codex 模型、开源 Agent Runtime 与 CLI、IDE、Desktop App、Cloud 等产品形态；
- 能从 Thread 创建、上下文装配、Responses API 推理、工具路由、审批与沙箱、Observation 回灌、压缩、验证和终止完整解释一次运行；
- 能说明 OpenAI 官方
openai/codex仓库的入口、核心 crate、协议、工具、安全、持久化和客户端文件分别负责什么； - 能说明普通业务项目中的
AGENTS.md、.codex/config.toml、Rules、Skills、Hooks、MCP 与本机状态文件如何分工； - 能解释 Prompt Cache、Compaction、WebSocket、Tool Search、并行工具、Subagent、Worktree、容器缓存和 OpenTelemetry 分别优化什么；
- 能把“为什么强”拆成模型、Harness、上下文、工具、验证、安全、恢复、并行和交互九个可测维度；
- 能识别上下文压缩丢信息、错误完工、Prompt Injection、权限越界、工具结果过长、并行写冲突和外部副作用等风险；
- 能在面试中区分官方文档事实、开源源码事实、合理推断与当前未知。
2. 面试结论
2.1 30 秒回答
Codex 本质上不是“一个会写代码的 GPT”，而是“面向工程任务优化的模型 + 开源 Rust Agent Runtime + 真实开发工具 + 受约束执行环境 + 状态与多端协作”的完整系统。它把用户目标转成连续的“取证、行动、观察、验证”循环：模型提出工具调用，Runtime 负责上下文、路由、审批、沙箱、执行和结果回灌，直到有证据地结束。它在终端型长任务、工具协调、并行隔离、开源可审计和本地到云端协同上很有竞争力，但“比所有工具强”并不成立，必须在同一仓库、版本、权限、预算和隐藏测试下比较。
2.2 一分钟复述版
我会把 Codex 分成六层。第一层是模型，负责理解目标、推理和选择候选动作；第二层是 Agent Loop，负责在模型与工具之间持续循环；第三层是 Context，把基础指令、权限说明、AGENTS.md、Skills、环境、历史和工具定义按生命周期装入；第四层是 Execution，通过 Shell、Patch、搜索、MCP、浏览器或其他扩展作用于真实环境；第五层是 Control，用 Approval、Sandbox、Rules、Network Policy 和 Managed Requirements 限制副作用；第六层是 State 与 Surface，用 Rollout、SQLite、Thread Protocol、App Server、CLI、IDE、App 和 Cloud 支持流式展示、恢复、分叉和并行。
Codex 的优化不是一个神秘 Prompt。模型层会按任务复杂度分配推理预算；Harness 通过稳定前缀利用 Prompt Cache，通过自动 Compaction延长任务，通过 Tool Search、Skill 渐进披露和 Subagent 隔离控制 Context；执行层用 Rust 模块、WebSocket、并行只读工具和云容器缓存降低延迟；控制层用 OS Sandbox、审批、Auto-review 与遥测提高安全自治时长。最终是否更强，仍要看任务更像本地长调试、云端异步 PR、IDE 补全，还是高风险确定性流程。
2.3 一句话技术判断
Codex 的核心竞争力，是把模型的概率性推理放进一个开源、可执行、可观察、可恢复且受权限约束的工程循环，并把同一套能力延伸到本地、IDE、App、Cloud 与 SDK。
3. 面试官为什么问
- Agent 原理：是否知道模型只产生候选动作，Runtime 才负责执行、状态和终止；
- 源码能力：能否从真实入口、协议、Session、Turn、ToolRouter 和 Sandbox 文件还原调用链；
- Context Engineering：是否理解缓存、压缩、渐进披露、工具结果裁剪和子线程隔离的差别；
- 工程能力：是否关注退出码、测试、Diff、重试、超时、并发、日志、恢复和成本；
- 安全意识：是否知道 Prompt 指令、Approval、Rules、Sandbox、Network Policy 与服务端授权不是同一层；
- 系统设计：是否能把开源 Core、App Server、SDK、多端客户端与 Cloud 环境分层；
- 评测意识：是否会控制模型、版本、权限和预算，而不是用一次演示下结论；
- 事实纪律：是否能在开源 CLI 和闭源 Cloud、IDE、Desktop App 之间划清证据边界。
4. 概念、边界与证据等级
4.1 Codex 到底指什么
“Codex”至少有三种不同含义：
| 对象 | 负责什么 | 可以从哪里验证 |
|---|---|---|
| Codex 中使用的模型 | 理解目标、代码推理、规划、工具选择和结果修正 | OpenAI 模型发布、System Card 与公开评测 |
| Codex Agent Runtime | Thread、Turn、Context、模型请求、工具、审批、沙箱、状态和事件流 | Apache-2.0 的 openai/codex Rust 源码 |
| Codex 产品族 | CLI、IDE Extension、Desktop App、Cloud、SDK、App Server | OpenAI 产品文档；只有部分组件开源 |
OpenAI 对产品术语的公开说明把 Codex CLI、Codex Cloud 和 VS Code Extension 都归入 Codex 产品族；官方开源清单则明确 CLI、SDK 与 App Server 可审计，Cloud 服务端和 IDE Extension 并非完整开源实现。因此，本文能做源码级结论的是本地 Runtime 与公开接口，不能从 CLI 源码反推出所有托管实现。
来源定位： Unrolling the Codex agent loop、Codex Open Source（访问日期：2026-07-11）。
4.2 它不是什么
- 不是单独一个模型；同一模型放进不同 Harness，完成率、成本和安全边界都会变化；
- 不是普通代码补全；它能搜索、编辑、运行、观察和继续决策；
- 不是模型直接执行 Shell；模型只输出结构化动作，Runtime 决定能否、在哪里、以什么权限执行；
- 不是一次 Tool Calling；工具结果会进入下一轮推理，形成长链路；
- 不是“无限上下文”；Prompt Cache 不会删除内容，Compaction 也是有损压缩；
- 不是绝对安全系统；Sandbox、审批、网络策略、外部服务授权仍各有边界；
- 不是所有产品形态都开源；Cloud 调度、Desktop App 和 IDE 全部内部实现不能由 CLI 源码代替；
- 不是确定性编译器；测试不完整、需求模糊或工具环境错误时，它仍可能错误完工。
4.3 四类证据必须分开
| 证据等级 | 含义 | 本文示例 |
|---|---|---|
| 官方文档事实 | OpenAI 产品文档、工程文章或 System Card 明确说明 | Responses API Agent Loop、Container Cache、Auto-review、OpenTelemetry |
| 开源源码事实 | 固定 Commit 中能定位到类型、函数、注释或测试 | run_turn 循环、ToolRouter、Rollout、Protocol |
| 基于证据的推断 | 多条公开事实支持，但没有公开因果实验 | 模型、工具语义、Prompt 与 Runtime 联合迭代形成协同优势 |
| 当前无法确认 | 没有足够公开证据 | 完整训练数据、Reward 配比、Cloud 调度细节、各优化的单独增益 |
本文源码快照固定为 openai/codex@5c19155，提交时间为 2026-07-11。后续 main 的路径、类型和默认值可能变化。
4.4 “为什么更强”的正确问法
不要问“Codex 是否绝对最强”，而要先固定：
- 任务是 Inline Completion、跨模块修改、长调试、代码审查、Issue 到 PR，还是知识工作；
- 使用哪个模型、Reasoning Effort、版本和并发模式；
- 是否给予相同的 Shell、网络、浏览器、MCP、依赖和仓库指令；
- 预算按 Token、费用、墙钟时间、人工干预还是风险计算；
- 结果由最终文字、编译器、隐藏测试、安全扫描还是人工 Review 验收；
- 比较的是模型、开源 Harness、某个客户端，还是完整产品族。
这些变量不固定，“更强”只能是体验，不是工程结论。
4.5 小白直觉：隔离工位里的高级工程师
小林要修复支付系统的偶发退款错误。公司没有只给他一张“请修好”的纸，而是安排了一间隔离工位：
- 工单说明目标和范围；
- 项目手册告诉他架构、禁止事项和权威测试；
- 他先查现场、跑复现，再决定改哪块；
- 每次想用新工具，都要经过工位门禁和安全规则；
- 工具返回真实读数，他据此继续判断；
- 遇到可并行调查的问题，他把日志、数据库和前端分别交给同事；
- 每一步都写进工作日志，必要时恢复或从某个节点分叉；
- 最后不是小林口头说“修好了”，而是测试、Diff 和人工复核共同验收。
| 生活场景 | Codex 对应物 | 技术作用 |
|---|---|---|
| 工单 | 用户输入与验收条件 | 定义目标和边界 |
| 小林的判断 | Codex 中的模型 | 推理、规划和选择候选动作 |
| 隔离工位 | Codex Runtime 与 Sandbox | 提供工具并限制副作用 |
| 项目手册 | AGENTS.md | 注入项目事实、命令和约束 |
| 专项 Runbook | Skill | 按需加载领域流程 |
| 工位门禁 | Approval、Rules、Network Policy | 裁决动作是否允许 |
| 工具读数 | Tool Result / Observation | 为下一轮决策提供真实证据 |
| 独立同事 | Subagent | 并行调查并隔离噪声 Context |
| 工作日志 | Rollout、Event、Diff、Telemetry | 恢复、审计和排障 |
| 独立工位 | Worktree 或 Cloud Container | 隔离并行写入和依赖 |
回到专业机制：模型并不持有 Shell 权限，也不会在 API 请求之间自动保留完整世界状态；Runtime 负责重建 Context、执行动作、持久化轨迹和控制权限。
类比边界： 人类工程师能理解组织责任和隐含业务语义，模型只能基于输入、参数和工具结果近似判断。测试通过也只证明覆盖范围内的行为，不能自动证明安全、业务正确或远程副作用可恢复。
5. 运行机制与源码深度剖析
5.1 从聊天请求到 Agent Loop
一次 Codex 运行可以抽象为：
其中：
是用户目标； 是第 次采样时模型可见的指令、历史、环境和工具； 是模型产生回答或工具动作的策略； 是候选回答、Shell、Patch、搜索、MCP、浏览器、委派等动作； 是 Approval、Sandbox、Rules、Network Policy 与组织约束； 是受策略限制的执行环境； 是 stdout、stderr、退出码、Diff、拒绝原因或外部结果； 是追加、规范化、裁剪、压缩和持久化 Context 的 Runtime 逻辑。
这不是 OpenAI 的源码公式，而是对公开控制关系的准确抽象：模型提议，Runtime 裁决和执行，真实结果再影响模型。
固定快照中的 session/turn.rs 直接写明：每次采样后，模型要么请求函数调用，要么给出 Assistant Message；有工具调用就执行并把输出放进下一次采样，只有不再需要工具且没有待处理输入时，Turn 才能结束。
5.1.1 技术清单
| 技术点 ID | 技术点/环节 | 类型 | 采用方案 | 链路职责 | 版本/证据边界 |
|---|---|---|---|---|---|
| TP-CODEX-CONTEXT | 指令、能力与长上下文治理 | 运行时/配置 | AGENTS.md、Skill/Tool Search、Prompt Cache、Compaction 与 Steering | 合并稳定项目规则，按需加载能力，控制增长历史并支持长任务中途纠偏 | 依据固定源码快照和官方文档；模型内部训练、产品端私有实现与未来协议变化不在本文证明范围 |
| TP-CODEX-EXECUTION | 多端接入与工具执行 | Runtime/协议/基础设施 | Rust Core + 进程内/外部 App Server + Responses API + ToolRouter + Approval/Sandbox | 统一 Thread/Turn/Event 语义，把模型 Tool Call 路由到 Shell、Patch、MCP、浏览器和 Subagent | CLI/Core/App Server 开源可核验；Desktop、IDE 与 Cloud 并非全部开源，外部工具仍需自有授权 |
| TP-CODEX-RECOVERY | 轨迹、状态、并行与观测 | 存储/版本控制/可观测组件 | Rollout JSONL + SQLite State + Git/Worktree + OpenTelemetry | 保存 Response Item、Thread 元数据、Diff、事件和遥测，支持 Resume/Fork、重放调查与并行 Writer 隔离 | Git 与 Rollout 不能回滚数据库、部署或消息；外部副作用必须使用幂等、对账和补偿 |
5.2 启动阶段：建立模型能工作的世界
初次采样前，Runtime 大致装配以下信息：
- 模型对应的基础指令；
- 当前 Sandbox、可写目录、网络和 Approval 说明；
- 用户级或客户端级 Developer Instructions；
- 从全局到项目根，再到当前目录合并的
AGENTS.md/AGENTS.override.md； - Skill 的名称、描述和路径；选中后再加载完整
SKILL.md； - 当前工作目录、Shell、平台和环境选择；
- 内置、MCP、Plugin、App 或 Dynamic Tool 的可见规格；
- Thread 历史、先前 Tool Result、当前用户输入和中途 Steering；
- 模型、Reasoning Effort、Collaboration Mode、权限配置和 Context Window 状态。
官方工程文章说明，Codex 把静态内容放在前面、动态内容追加在后面，以尽量保持 Exact-prefix Prompt Cache；项目指令默认总大小上限为 32 KiB，Skill 初始列表还有独立 Context 预算。
图：架构｜Codex Runtime 的多端接入、执行与恢复组件边界
替代文本： 用户从 CLI、IDE、App 或 Cloud 提交目标，客户端通过 Core 或 App Server 创建 Thread；Context 装配基础指令、权限、项目规则、Skills、环境、历史和工具后请求 Responses API。模型返回文本或 Tool Call，ToolRouter 将调用交给审批和沙箱，再执行 Shell、Patch、MCP、浏览器等工具；Observation 回写历史并继续采样，直到验证完成或停止。Rollout、State、Diff 和 Telemetry 并行记录全过程。
图表加载中…
读图结论： Codex 的智能来自模型，但端到端完成能力来自 Runtime 把 Context、工具反馈、安全裁决、持久化和外部验证闭成一条可重复循环。
图中最重要的边界是：AGENTS.md 影响模型行为，Approval 和 Sandbox 才限制执行；Tool Result 是下一轮证据，最终消息只是结束候选，不是正确性的充分证明。
5.3 一轮执行的真实时序
以“修复一个失败测试”为例：
固定快照里，交互式 TUI 与非交互式 codex exec 都先启动同一套进程内 App Server。TUI 的 AppServerSession 经 app-server-client 的有界强类型 Channel 提交 turn/start；只有 IDE、自研客户端等跨进程接入才在 stdio、WebSocket 或 Unix Socket 边界序列化 JSON。这样，热路径复用 App Server 的认证、Thread、审批和 Event 语义，同时避免本地 UI 与 Core 之间反复 JSON 编解码。
当前主链不是旧文档中的 Op::UserTurn，而是 turn/start → TurnRequestProcessor → core::Op::UserInput。它进入 CodexThread 的有界 Submission Queue，再由 submission_loop → RegularTask → run_turn 执行。因此，一轮真实时序是：
- TUI、
codex exec或外部客户端向 App Server 创建或恢复 Thread，并提交turn/start； - App Server 把请求转换成
Op::UserInput，送入CodexThread的有界 Submission Queue； submission_loop选择RegularTask，建立本轮 Turn Context；- Runtime 规范化历史，并在必要时预先 Compaction；
- 构建 Skills、Plugins、Connectors 与 Tool Specs；
run_turn通过 Responses API 的 SSE 或 WebSocket 流请求模型；- 模型返回 Reasoning Summary、Assistant Message 或 Tool Call；
- ToolRouter 将 Response Item 解析成统一 Tool Call；
- Tool Orchestrator 检查 Approval、Network Approval、Sandbox 与安全升级；
- Handler 执行测试、读取文件、应用 Patch 或调用外部工具；
- stdout、stderr、退出码、拒绝或 Diff 被标准化为 Tool Result；
- Tool Result 写入 History，模型继续采样；
- 若达到 Context 阈值，Runtime 自动压缩后继续；
- 若无后续工具、无待处理输入且 Stop Hook 不要求继续，Turn 结束；
- Rollout、State、Event 和 Telemetry 保存可恢复轨迹。
图：技术调用流程｜Codex 修复失败测试的一轮交互时序
替代文本： 用户请求经客户端进入 Session Turn；Turn 向模型发出包含历史与工具的流式请求，模型提出运行测试；ToolRouter 先经过审批与沙箱，再由 Shell 返回失败日志。失败结果写回历史后，模型读取代码、申请 Patch、再次测试；只有测试证据和范围审查足够时才结束。
图表加载中…
读图结论： App Server 统一接入和事件语义，Core 承担 Agent Loop；模型每次只决定下一步候选动作，真正使修复可靠的是“执行后得到失败或成功证据，再继续决定”的反馈链。
5.4 Thread、Turn、Step 与 Event 如何分工
| 概念 | 主要职责 | 工程意义 |
|---|---|---|
| Thread | 一段可恢复、可分叉的长期工作上下文 | 保存配置、历史、来源、父子关系和持久化路径 |
| Turn | 一次用户输入触发的 Agent 工作 | 包含若干模型采样与工具回路 |
| Step Context | 某次采样和工具执行的不可变快照 | 避免运行中配置漂移导致同一步状态不一致 |
| Response Item | 消息、Reasoning、Tool Call、Tool Result、Compaction 等模型协议项 | 统一模型与 Runtime 的数据形态 |
| Submission / Op | UI 或客户端提交给 Core 的操作 | 用户输入、配置、停止、审批和其他控制 |
| Event / EventMsg | Core 发给 TUI、IDE、App Server 或 SDK 的结构化事件 | 流式展示、审计、遥测和客户端解耦 |
当前源码中 codex_thread.rs 把 CodexThread 定义为 Thread 双向消息流的通道；protocol.rs 维护共享操作与事件类型；session/turn.rs 承担主循环。
主 Thread 的一个 Turn 不能简单等同整个系统只做一件事：Subagent 会创建独立 Thread 并行工作，后台终端、Hook、MCP 和事件流也可能并行存在。正确理解是“每条 Thread 内要保持明确的活动 Turn 与历史边界，跨 Thread 再做协作”。
5.5 模型请求为什么既流式又保持状态可重建
Codex CLI 使用 Responses API。官方公开链路包括：
- 发送
instructions、tools与input； - 通过 SSE 或 WebSocket 接收增量 Reasoning Summary、文本、Tool Call 和完成事件；
- 把完成的 Response Item 与 Tool Result 追加到下一次请求；
- 默认保持请求可重建，而不是完全依赖服务端隐式会话；
- ZDR 场景可携带加密的 Reasoning 或 Compaction 内容，而不要求服务端保存原始会话数据。
源码中的 client.rs 负责模型请求、流式连接、压缩端点、重试与 Turn 级 Client Session；run_turn 会在同一 Turn 中复用 ModelClientSession，保留 WebSocket 和 Sticky Routing 状态。
5.6 ToolRouter：模型动作怎样变成真实执行
固定快照中的 Tool 链可分为五步：
- Tool Spec 规划：根据模型能力、配置、Skill、MCP、Plugin、Dynamic Tool 与 Multi-Agent 模式生成本轮可见工具；
- Response 解析：把 Function Call、Custom Tool Call 或 Tool Search 结果解析为统一
ToolCall； - Registry 查询：找到 Handler、是否允许并行、是否需要等待取消和工具可见性；
- Orchestrator 控制：处理审批、网络授权、Sandbox 首次执行与受控升级；
- Handler 执行：运行 Shell、Patch、搜索、MCP、图像、浏览器或 Subagent，并标准化输出。
关键源码：
tools/spec_plan.rs：本轮 Tool Spec；tools/router.rs：解析与路由；tools/registry.rs：注册、可见性和并行属性；tools/orchestrator.rs：审批、沙箱和重试控制；tools/handlers/：具体工具实现。
Codex 可以并行执行标记为支持并行的调用，但不是“所有工具一起跑”。tools/parallel.rs 对支持并行的工具使用共享读锁，不支持并行的工具使用写锁，从而让搜索和独立检查并发，同时避免状态写入互相踩踏。
5.7 Approval、Rules 与 Sandbox 是三层，不是一层
| 控制面 | 回答的问题 | 典型实现 | 不能替代什么 |
|---|---|---|---|
| Approval Policy | 什么时候必须暂停并取得许可 | on-request、never 等策略 | 不能形成 OS 级隔离 |
| Rules | 哪类命令允许、提示或禁止 | prefix_rule 与管理员限制 | 不能识别所有运行时副作用 |
| Sandbox | 进程技术上能访问哪些文件、网络和资源 | macOS Seatbelt、Linux 隔离、Windows Sandbox | 不能证明业务动作合理 |
| Network Policy | 能连接哪些域名、方法、地址或 Socket | 代理、Allow/Deny、私网限制 | 不能替代服务端 IAM |
| External Authorization | 外部系统允许谁做什么 | OAuth、Token Scope、RBAC、业务审批 | 不由本地 Prompt 或 Git 恢复提供 |
Approval 和 Sandbox 协同的价值是：边界内的低风险动作连续执行，跨边界动作再询问，避免“每条命令都弹窗”与“完全放权”两种极端。
关键边界： Codex 提供的 Shell Sandbox 只直接约束它所执行的本地进程；MCP、App 或其他外部工具必须自己实现权限和审计，不能因为工具出现在 Codex 中就假设自动受同一 OS Sandbox 保护。
官方安全文章还介绍了 Auto-review：跨 Sandbox 的请求可交给独立 Reviewer Agent 判断风险和用户授权，低风险或已充分授权动作可以自动通过，高风险动作仍停止。它优化的是审批摩擦，不会自动扩大可写根目录、开放网络或取消保护路径。
5.8 Context 为什么不会无限膨胀
Codex 同时使用多种机制，职责不同：
| 机制 | 主要解决什么 | 不能解决什么 |
|---|---|---|
| Exact-prefix Prompt Cache | 复用相同前缀的模型计算 | 不减少 Context 内容，也不保证长期命中 |
| Tool Result 裁剪与规范化 | 限制超长 stdout、孤立调用和不兼容内容 | 可能丢失低频但关键细节 |
| Automatic Compaction | 用较小的继续工作状态替代长历史 | 是有损压缩，不是无限无损记忆 |
| Skill 渐进披露 | 只在匹配任务时加载完整 Runbook | 依赖描述匹配，可能漏触发 |
| Tool Search / Deferred Tool | 避免全部工具 Schema 常驻 | 动态工具变化仍可能破坏 Cache |
| Subagent 隔离 | 把高噪声探索留在独立 Thread | 增加 Token 和协调成本 |
AGENTS.md 分层 | 让项目规则稳定、按目录生效 | 不是权限系统，也受大小上限约束 |
官方 Agent Loop 文章说明，Cache 只有在 Prompt 前缀完全一致时才能命中。中途改变模型、工具集合、Sandbox、Approval 或工作目录都可能造成 Cache Miss；Codex 尽量通过在历史末尾追加变更消息，而不是修改早期内容，保持旧前缀稳定。
当 Token 超过阈值，Runtime 使用 /responses/compact 或本地兼容路径生成可继续的较小输入。源码中的 compact.rs、context_manager/ 和 Compaction Prompt 分别负责压缩流程、历史治理和 Handoff 要求。
5.9 持久化、恢复和分叉
Codex 的“记住”至少分成四层：
| 状态 | 保存什么 | 主要用途 | 风险边界 |
|---|---|---|---|
| Thread Rollout | 消息、工具调用、结果、事件与上下文记录 | Resume、Fork、审计和故障恢复 | 体积可能增长，包含敏感上下文 |
| SQLite / Thread Store | Thread 元数据、索引、状态和派生信息 | 列表、检索、归档与客户端恢复 | 数据库损坏或索引漂移仍需恢复 |
| Memory | 从合格历史中提取的跨任务辅助信息 | 减少重复解释和召回经验 | 不是权威规则源，可能陈旧 |
| Git / Worktree | 代码、提交、分支和并行工作目录 | Patch 审查、回滚和 Writer 隔离 | 不能撤销数据库、部署或消息发送 |
对应源码包括 rollout/、state/、thread-store/ 与 Memory 扩展。强制规则仍应放入版本化的 AGENTS.md、测试或策略，而不是只依赖 Memory。
5.10 Multi-Agent、App 与 Cloud 如何协同
Subagent 工作流会把独立调查放进不同 Thread：
- 主 Agent 识别可并行且边界清楚的子任务；
- 每个 Subagent 拥有独立模型和工具工作；
- 探索日志、堆栈和中间输出留在子 Thread；
- 主 Thread 接收摘要和证据；
- Desktop App、CLI 与 IDE 可显示和切换 Agent Thread；
- 多个 Writer 应通过 Worktree 或职责边界隔离；
- 主 Agent 负责整合、冲突处理和最终验收。
Subagent 能减少主 Context 污染并缩短墙钟时间，但会增加总 Token、协调和合并成本。当前官方文档说明本地 Codex 默认具备 Subagent 工作流，Desktop App 还面向多个 Agent 的并行监督。
Cloud 则把执行环境换成托管容器：克隆仓库、Checkout 任务分支、运行 Setup，再进入 Agent Loop。当前官方文档说明 Container State 最长缓存 12 小时；Setup、Maintenance、环境变量或 Secrets 变化会使缓存失效，Agent 阶段网络默认关闭但可配置。
5.11 OpenAI Codex 官方仓库的主要文件与用途
以下表格基于 openai/codex@5c19155，不是对未来 main 的永久承诺。
| 路径 | 主要用途 | 阅读建议 |
|---|---|---|
README.md | 项目入口、安装与官方文档导航 | 先确认产品与开源边界 |
AGENTS.md | 官方仓库自身的开发与协作规则 | 贡献前必读 |
codex-cli/package.json | @openai/codex npm 包元信息 | 不是核心 Runtime |
codex-cli/bin/codex.js | 按 OS/CPU 找到原生 Rust 二进制并转发参数和信号 | 理解 npm 只是分发薄层 |
codex-rs/Cargo.toml | Rust Workspace、crate 与共享依赖 | 看全局模块边界 |
codex-rs/cli/src/main.rs | 原生命令入口，分发 TUI、Exec、Review、Login、MCP、App Server、Sandbox、Cloud 等命令 | 从入口追主链 |
codex-rs/tui/ | 终端交互 UI、消息、Diff、审批、模型和 Agent 状态 | UI 层，不承担核心决策 |
codex-rs/exec/ | codex exec 非交互模式、脚本/CI 与 JSONL 输出 | 自动化入口 |
codex-rs/app-server-client/ | TUI 与 Exec 共用的进程内 App Server Client，以有界强类型 Channel 传输请求、响应和通知 | 看本地热路径如何避免 JSON 往返 |
codex-rs/core/ | Thread、Turn、Context、模型、工具、安全、MCP、Skill、Hook、Diff 和 Compaction | 核心事实源 |
core/src/thread_manager.rs | 创建、恢复、Fork 和管理内存 Thread | 看生命周期入口 |
core/src/codex_thread.rs | Thread 双向操作/Event 通道、配置快照和持久化桥 | 看客户端与 Core 边界 |
core/src/session/session.rs | Session 状态、服务集合、配置与活动任务 | 看运行状态聚合 |
core/src/session/mod.rs | Session 模块入口、共享类型和任务装配 | 从模块边界进入 Session 主链 |
core/src/session/handlers.rs | 消费 Submission，运行 submission_loop 并分派用户操作 | 看 Op::UserInput 怎样进入任务 |
core/src/tasks/regular.rs | 普通用户 Turn 的任务实现，衔接 Session 与 run_turn | 看常规任务而非专项任务 |
core/src/session/turn.rs | 主 Agent Loop、采样、工具反馈、压缩与停止条件 | 最关键文件 |
core/src/client.rs | Responses API、流式连接、Compaction API、预热和重试 | 看模型 I/O |
codex-rs/codex-api/ 与 codex-client/ | Responses API 数据类型、请求构造和底层传输客户端 | 区分模型协议与 Core 编排 |
core/src/context_manager/ | 历史规范化、裁剪和 Token 估算 | 看 Context 治理 |
core/src/compact.rs | 手动/自动、Turn 前/Turn 中、Local/Remote Compaction | 看长会话续航 |
core/src/agents_md.rs | 发现与组合项目指令 | 看目录作用域 |
core/src/tools/ | Tool Spec、Registry、Router、并行、审批和 Handler | 看动作执行主链 |
codex-rs/protocol/ | Thread、Turn、Item、Approval、Permission、Tool 和 Model 共享类型 | 看跨客户端契约 |
codex-rs/app-server/ | 面向 IDE/富客户端的 JSON-RPC 服务，提供认证、历史、审批和流式事件 | 深度嵌入入口 |
codex-rs/app-server-protocol/ | App Server 消息 Schema 与版本协议 | 客户端生成/兼容 |
codex-rs/app-server-transport/ | stdio、WebSocket、Unix Socket 等跨进程传输边界 | JSON 序列化主要发生在这里 |
codex-rs/rollout/ | JSONL 轨迹记录、读取、压缩、归档和状态桥 | 恢复与审计 |
codex-rs/state/ | 本地 SQLite 状态与查询 | 元数据和索引 |
codex-rs/thread-store/ | Thread 持久化抽象与本地实现 | 解耦 Runtime 与存储 |
codex-rs/sandboxing/ | 跨平台 Sandbox Policy 抽象 | 看统一安全模型 |
codex-rs/bwrap/、linux-sandbox/、windows-sandbox-rs/ | Linux/WSL 与 Windows 具体隔离后端 | 看平台差异 |
codex-rs/execpolicy/ | Starlark prefix_rule 决策 | 看命令策略 |
codex-rs/network-proxy/ | Sandbox 网络代理与目标策略 | 看网络边界 |
codex-rs/rmcp-client/ | Codex 作为 MCP Client 连接外部工具 | 外部能力入口 |
codex-rs/mcp-server/ | Codex 作为 MCP Server 被其他客户端调用 | 反向嵌入入口 |
codex-rs/skills/ 与 plugin/ | Skill 发现、加载与 Plugin 分发 | 渐进披露与复用 |
codex-rs/features/ | Feature Flag、默认状态与能力成熟度 | 区分 Stable、实验和开发中能力 |
codex-rs/otel/ | OpenTelemetry Logs、Metrics 与 Traces | 生产可观测性 |
codex-rs/cloud-tasks/ | CLI 侧查看和拉取 Cloud Task 的客户端逻辑 | 不代表 Cloud 服务端源码 |
sdk/typescript/ 与 sdk/python/ | 程序化启动、恢复和驱动 Codex Thread | 自动化优先入口 |
docs/ | 仓库构建、贡献、安全和兼容文档 | 产品能力以 Learn 文档为准 |
图：Codex 开源 Runtime 的主要模块关系
替代文本： CLI 分发到 TUI 或 codex exec，两者通过进程内 App Server Client 的有界强类型 Channel 进入 App Server；IDE、SDK 或自研客户端经 stdio、WebSocket 或 Unix Socket 进入同一服务。App Server 把请求转为 Core Operation，经 Protocol、Thread Manager、Submission Queue、Session 与 Turn 进入 Context Manager 和 Model Client；模型动作再由 Tool Spec、Router、Registry、Orchestrator、安全边界和 Handler 执行。Rollout、State、Thread Store 与 OpenTelemetry 横向记录状态。
图表加载中…
读图结论： 当前 TUI 与 codex exec 也复用 App Server，只是本地热路径走强类型 Channel；多个客户端共享的不是一堆复制 Prompt，而是 App Server、Protocol、Core、Tool 和 State 原语。
5.12 普通项目接入 Codex 时的主要文件
这一节回答另一个常见歧义：不是 Codex 源码仓库，而是“我的业务项目里哪些文件会影响 Codex”。
| 文件或目录 | 主要用途 | 加载时机与优先级 | 是否建议提交 Git | 安全边界 |
|---|---|---|---|---|
AGENTS.md | 团队架构、命令、代码风格、验证和业务边界 | 从项目根到当前目录合并，越近越晚出现 | 是，适合团队共享 | 只是模型指令，不是 IAM |
AGENTS.override.md | 在某一层覆盖普通项目指令 | 同目录优先于 AGENTS.md | 团队覆盖可提交；个人覆盖谨慎 | 仍受总大小和 Prompt 遵循边界 |
.codex/config.toml | 项目模型、Approval、Sandbox、MCP、Hooks 等允许的项目级配置 | 只有 Trusted Project 才加载；离当前目录更近的层优先 | 可提交无秘密的团队配置 | 某些 Provider、Auth、Telemetry 键不能由项目覆盖 |
.codex/rules/*.rules | 控制 Sandbox 外命令的 Allow、Prompt 或 Forbidden 决策 | 启动时扫描 Active Config Layer；当前仍属实验能力 | 可提交团队规则与内联匹配测试 | 不能替代 OS Sandbox 和外部 RBAC |
.agents/skills/{name}/SKILL.md | 按需加载的工作流、知识和执行说明 | 启动先放名称/描述/路径，选中后读全文 | 是，适合团队 Runbook | 脚本仍需审批、Sandbox 和代码审查 |
.agents/skills/{name}/scripts/ | 复用确定性命令或转换逻辑 | Skill 指示时执行 | 是，但要测试和审计 | 不写秘密，不把危险动作藏在脚本中 |
.agents/skills/{name}/references/ 与 assets/ | 延迟读取资料、模板和资源 | Skill 需要时读取 | 是 | 避免把敏感大文件放进仓库 |
Hook 脚本与 .codex/config.toml 的 Hooks 配置 | 生命周期校验、日志过滤、通知和确定性门禁 | 对应事件发生时 | 可提交稳定脚本 | Hook 失败策略和超时必须明确 |
项目自身的 Makefile、package.json、justfile、scripts/ | 权威构建、测试、Lint、迁移和验收入口 | Codex 读取或调用时 | 原本就应版本化 | 这些命令才是可执行事实源 |
.gitignore | 阻止凭据、私有配置和运行状态误提交 | Git 层 | 是 | 应覆盖本地秘密与临时产物 |
本机或管理员范围的文件不要和项目事实混在一起：
| 本机或管理文件 | 用途 | Git 建议 |
|---|---|---|
~/.codex/config.toml | 用户默认模型、Provider、Approval、Sandbox、MCP、Telemetry 等 | 不提交 |
~/.codex/{profile}.config.toml | 可切换 Profile | 不提交，除非作为脱敏示例 |
~/.codex/rules/*.rules | 个人长期命令规则 | 不提交到业务仓库 |
requirements.toml | 管理员强制约束用户不能覆盖的安全设置 | 由组织管理，不当普通项目偏好 |
$CODEX_HOME/sessions/... | Rollout JSONL 与 Thread 历史 | 不提交，按敏感数据治理 |
$CODEX_HOME 下 SQLite、Logs、History | 本地 Thread 索引、状态、日志和输入历史 | 不提交 |
| Auth 与 MCP OAuth 凭据或 OS Keyring | 登录与外部工具授权 | 绝不提交 |
配置优先级： CLI Flags 与一次性 Overrides 最高，其次是从项目根到当前目录的 Trusted
.codex/config.toml，再是选中的 Profile、用户配置、系统配置和内置默认值；管理员requirements.toml作为不可被用户放宽的约束参与最终裁决。
最容易踩的坑是把所有内容都塞进 AGENTS.md。正确分层是：每轮都需要的事实进入 AGENTS.md，偶用流程进入 Skill，确定性命令进入脚本，工具连接进入 Config/MCP，安全边界进入 Approval、Rules、Sandbox 与外部授权，运行轨迹留在本机 State。
5.13 Rules 与 Skills：先消除同名歧义
“Rules 是每次请求都携带的边界提示词，Skill 是命中后才加载的方法和步骤”这个理解方向基本正确，但在 Codex 中需要拆成三层，否则容易把同名概念混在一起：
| 层次 | 典型载体 | 何时生效或加载 | 主要内容 | 不能替代什么 |
|---|---|---|---|---|
| 持久行为指令 | System / Developer Instructions、AGENTS.md | System 与 Developer Instructions 由宿主注入；Codex 在每次 Run 或 TUI Session 启动时构建一次 AGENTS.md 指令链，并在其目录作用域内持续适用 | 项目事实、必须/禁止事项、代码规范、验证要求和协作边界 | 不能替代 Sandbox、IAM、RBAC 或程序化校验 |
| Codex 命令 Rules | .codex/rules/*.rules、~/.codex/rules/*.rules | 启动时扫描；准备在 Sandbox 外执行命令时，根据参数前缀匹配 allow、prompt 或 forbidden | 命令执行策略和内联匹配测试 | 不是通用 Prompt，也不能表达完整业务工作流 |
| 按需 Skill | SKILL.md、scripts/、references/、assets/ | 初始只暴露名称、描述和路径；用户显式调用，或任务语义匹配描述后，才读取完整 SKILL.md 和必要资源 | 可复用方法、步骤、模板、脚本、检查清单和领域知识 | 不能作为不可绕过的安全策略，也不能保证一定被隐式命中 |
因此，“Skill 命中才加载”还要再精确一步：Skill 的发现元数据会先进入初始 Context，完整正文和资源才按需加载。 Skill 可以通过用户显式指定触发，也可以由 Codex 根据 description 隐式选择；描述写得模糊会漏触发或误触发。被选中后，Skill 中的步骤是当前任务应遵循的执行说明，并不只是可有可无的参考建议。
“Rules 每次请求都携带”也不宜理解成网络层一定在每次底层 API 调用中原样重复传输。对 AGENTS.md 更准确的说法是：Codex 每次 Run 或 TUI Session 启动时，从全局到当前目录构建一次指令链，使其成为当前作用域的持续上下文；具体产品可能通过会话状态或缓存复用稳定前缀。对 Codex 的 .rules 而言，它甚至不是模型 Prompt，而是命令执行前的策略判断。
工程上可以用下面三条判断：
- 删除后会让多数相关任务失去共同边界、项目事实或验收标准，放入
AGENTS.md等持久指令； - 只在某类任务出现时才需要，并且能写成可复用 Runbook，放入 Skill；
- 必须确定性地允许、询问或阻止某类外部命令，放入 Codex
.rules，并继续由 Sandbox 和外部权限兜底。
复杂项目常用“薄规则 + 厚 Skill”：持久指令只写“什么场景必须使用哪个 Skill、最终必须满足什么验收”，详细步骤、脚本和参考资料留在 Skill 中。这样既保证关键边界常驻，又避免每个任务都为偶用流程支付完整 Context 成本。
来源定位： Custom instructions with AGENTS.md、Rules、Build skills（访问日期：2026-08-20）。
继续阅读： 完成运行机制后，进入 工程实践篇，继续学习 Context、性能、安全自治、并行、故障演练与评测选型。
总结
一句话记忆： Codex 运行机制的本质，是由开源 Rust Runtime 把模型提出的候选动作组织成可执行、受约束、可观察、可恢复的 Agent Loop。
- 模型负责推理和提出动作，Runtime 负责 Context、工具路由、权限裁决、执行、结果回灌与终止；
- Thread、Turn、Response Item、Submission 和 Event 分别承载长期状态、单轮工作、协议数据、客户端操作与流式反馈；
- ToolRouter、Registry、Orchestrator 和 Handler 将模型输出转换为真实工具执行，并通过 Approval、Rules、Sandbox 与外部授权限制副作用；
- Prompt Cache、Compaction、Skill、Tool Search 和 Subagent 解决的是不同层次的 Context 成本与长任务续航问题；
- Rollout、SQLite State、Git/Worktree 和外部验证共同提供恢复与审计证据，但不能把测试通过等同于生产业务正确。