OpenAI Codex 原理与代码架构详解基于 openai/codex 开源仓库（codex-rs）源码与官方文档整理

01Codex 是什么

"Codex" 在 OpenAI 产品线里指一组共享同一 Agent 引擎的产品形态：

02整体架构分层

从外到内可以分成五层。每一层只通过明确的协议与相邻层通信：

03核心原理：Agent Loop

官方协议文档（codex-rs/docs/protocol_v1.md）定义了四个核心实体，理解它们就理解了 Codex 的运行模型：

主循环伪代码（对应 core/src/session/turn.rs）

// run_turn(): 一个 Task 内的循环（已简化）
async fn run_turn(sess, turn_ctx, input) {
    run_hooks_and_record_inputs(input);            // 记录用户输入，执行 hooks
    run_pre_sampling_compact();                     // 采样前若超出 token 上限，先压缩
    loop {
        let prompt = build_prompt(history, tools, instructions);
        let result = run_sampling_request(prompt).await;   // 流式请求 Responses API
        // 流中每个 OutputItemDone:
        //   Message / Reasoning  → 推送 AgentMessage 事件，记入历史
        //   FunctionCall / CustomToolCall / LocalShellCall → ToolRouter 分发执行
        //      → 生成 FunctionCallOutput 记入历史，needs_follow_up = true
        let needs_follow_up = result.model_needs_follow_up || has_pending_input;
        if token_limit_reached && needs_follow_up { run_auto_compact(); }
        if !needs_follow_up { break; }               // 模型只给出最终回答 → 结束
    }
    emit(EventMsg::TurnComplete { last_agent_message });
}

流式事件处理

try_run_sampling_request 消费 ResponseEvent 流：Created 记录 response_id；OutputItemAdded 提前通知 UI（例如开始显示工具调用）；OutputItemDone 是完整 item，交给 handle_output_item_done 决定是记录消息还是分发工具；文本增量通过 AgentMessageContentDelta 实时推给 UI。多个支持并行的工具调用会被并发执行（tools/parallel.rs），在 drain_in_flight 中统一等待结果。

04Prompt 组装与缓存

每次采样请求都是对 Responses API 的一次完整调用，主要包含三部分：

AGENTS.md 发现规则（core/src/agents_md.rs）

1. 从 cwd 向上查找，直到遇到 project_root_markers（默认 .git），确定项目根目录。
2. 从项目根到 cwd（含）沿路收集每一层的 AGENTS.md（支持 AGENTS.override.md 和 project_doc_fallback_filenames）。
3. 按从根到叶的顺序拼接，越靠近 cwd 的指令越靠后，因而优先级越高。
4. 再与 ~/.codex/AGENTS.md 等用户级全局指令合并，作为一条 user 角色消息注入。

为什么顺序很重要：Prompt Caching

Responses API 的提示缓存基于前缀精确匹配。Codex 刻意让 Prompt 只"追加"不"修改"：静态的 instructions、tools、权限与 AGENTS.md 放在最前面，历史按时间追加在后面。这样每轮采样都能命中前一轮的缓存前缀，推理成本和首 token 延迟都随之下降。中途改变沙箱/模型等配置时，Codex 会追加一条新的上下文更新消息，而不是改写旧消息，同样是为了保护缓存。

05通信协议：SQ / EQ 与 App Server

core 不直接操作 UI。UI 把 Submission（带 sub_id 的 Op）推入 Submission Queue，core 把 Event（EventMsg）推入 Event Queue。这让同一引擎可以运行在跨线程 channel、stdin/stdout、TCP、WebSocket 等任意双向流之上。

App Server：给富客户端的 JSON-RPC 层

IDE 插件和桌面 App 需要更稳定的接口，于是 codex app-server 在 core 之上包了一层 JSON-RPC 2.0（stdio 或 WebSocket），把对话抽象成三个原语：

06工具系统

模型返回的 FunctionCall / CustomToolCall / LocalShellCall 被 ToolRouter::build_tool_call 解析为统一的 ToolCall，再由 ToolRegistry 找到对应 handler（core/src/tools/handlers/）执行。

07审批与沙箱：安全模型

Codex 的安全由两个正交维度组合而成：审批策略决定"什么时候问人"，沙箱策略决定"操作系统层面允许做什么"。

审批策略 AskForApproval

沙箱策略 SandboxPolicy

平台实现

ToolOrchestrator：审批 → 沙箱 → 升级重试

core/src/tools/orchestrator.rs 的注释写得很直接："Coordinates tool approval, sandbox selection, and retries after sandbox denial."

1. 评估审批需求：execpolicy 规则（Starlark prefix_rule，decision 为 allow / prompt / forbidden）与审批策略共同得出 Skip、NeedsApproval 或 Forbidden。
2. 请求审批：需要时发出 ExecApprovalRequest，用户可选 Approved、ApprovedForSession（会话内缓存）、ApprovedExecpolicyAmendment（写入规则）、Denied、Abort。也可由 Guardian 自动审查代为决策。
3. 首次沙箱内执行：按 SandboxManager 选出的平台沙箱运行。
4. 沙箱拒绝后的升级：若执行因沙箱失败，在 untrusted（或 granular 中开启 sandbox_approval）下会再次请求审批，批准后脱离沙箱重试（wants_no_sandbox_approval）；在 never / on-request 下不会自动升级，而是把精简的拒绝信息返回给模型，由模型自行决定是否通过 require_escalated 参数显式申请提权。

08上下文管理与压缩

历史由 ContextManager（core/src/context_manager/history.rs）维护，存储的是 Responses API 原生的 ResponseItem，并在发送前做归一化（normalize.rs），例如确保每个工具调用都有对应输出、截断超长工具输出。

自动压缩（Auto Compaction）

1. 触发：每次采样后统计 token；当已用 token 超过 model_auto_compact_token_limit 且仍需继续（needs_follow_up）时触发。采样前也会检查（run_pre_sampling_compact），切换到上下文更小的模型时同样会压缩。
2. 生成摘要：本地模式下用压缩提示词让模型总结当前进展；远程模式下调用 Responses API 的压缩能力，返回不透明的 Compaction item（可保留加密的推理状态）。
3. 替换历史：以 SUMMARY_PREFIX + 摘要 + 最近用户消息（上限约 2 万 token）构成新历史，并在正确位置重新插入初始上下文（权限、AGENTS.md、环境）。
4. 继续循环：压缩后同一个 Turn 接着采样，用户无感知。用户也可用 /compact 手动触发（Op::Compact）。

09会话持久化与多端

• Rollout：每个会话以 JSONL 写入 ~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl，记录所有 ResponseItem 与关键事件。codex resume 通过重放 rollout 重建历史（rollout_reconstruction.rs）。
• 配置：~/.codex/config.toml 定义模型、Provider、审批/沙箱默认值、MCP Servers、profiles、features 开关；项目可声明信任级别。
• ThreadManager：同一进程可管理多个线程（Thread），支持 fork、子 Agent（thread_spawn.rs、agent_communication.rs），每个线程仍遵守"一次只有一个 Task"的规则。
• 可观测性：otel crate 输出 OpenTelemetry 指标，涵盖工具决策来源、沙箱结果（denied / escalated）、采样耗时等。

10codex-rs 代码地图

codex-rs 是一个 Cargo workspace，包含上百个 crate。下面是理解主流程最关键的部分：

11一次请求的完整时序

示例：用户在 TUI 中输入"修复失败的单元测试"，审批策略 on-request，沙箱 workspace-write。

1. TUI 发送 Op::UserTurn（文本 + cwd + 模型 + 策略）到 SQ。
2. Session 若无运行中任务，启动 RegularTask，发出 TurnStarted。
3. run_turn 记录输入，组装 Prompt：instructions + tools + [权限说明, AGENTS.md, 环境上下文, 历史..., 用户消息]。
4. ModelClient 流式调用 Responses API；模型先输出推理，再发出 exec_command {"cmd":"cargo test"}。
5. ToolRouter 解析调用；Orchestrator 判断为工作区内只读类命令，Skip 审批，在 Seatbelt / bwrap 中执行。
6. 测试输出（截断后）作为 FunctionCallOutput 写回历史，needs_follow_up = true，进入下一次采样。
7. 模型阅读失败信息，发出 apply_patch 修改源文件；补丁在可写根内，自动通过；UI 收到 PatchApplyBegin/End 和 diff。
8. 模型再次调用 cargo test 验证；全部通过。
9. 模型输出总结消息且无工具调用 → needs_follow_up = false，循环结束。
10. 发出 TurnComplete，rollout 落盘，TUI 显示最终回答和 token 用量。

若第 5 步命令需要联网（如 npm install），沙箱会拒绝网络；模型可带 require_escalated 重新调用，此时 Orchestrator 发出 ExecApprovalRequest，用户批准后在沙箱外执行。

12设计取舍总结

13参考资料

• github.com/openai/codex：源码仓库（codex-rs）
• codex-rs/docs/protocol_v1.md：Session / Task / Turn 与 SQ/EQ 协议
• codex-rs/core/README.md：各平台沙箱依赖说明
• codex-rs/linux-sandbox/README.md：bubblewrap + seccomp 实现
• codex-rs/execpolicy/README.md：命令策略语言
• developers.openai.com/codex：官方文档（CLI、配置、安全、AGENTS.md）
• Unrolling the Codex agent loop：OpenAI 官方博客，Agent Loop 与 Prompt 缓存