Codex CLI 源码架构全解剖

00全景架构：一个二进制，五层结构

先建立整体心智模型，后面每一章都是对其中一层的放大。

Codex CLI 和 Claude Code 解决的是同一个问题——「让模型在你的电脑上安全地写代码」——但技术选型几乎完全相反：Claude Code 是 TypeScript + React 渲染到终端，Codex 是纯 Rust + ratatui；Claude Code 的安全边界主要靠「权限提示系统」，Codex 的重头戏是操作系统级沙箱（macOS Seatbelt / Linux bubblewrap+seccomp / Windows Restricted Token）。

先解释几个贯穿全文的 Rust 术语：crate 是 Rust 的包/模块单元（类似 npm 包），一个 workspace 把多个 crate 组织在一个仓库里统一构建；tokio 是 Rust 最主流的异步运行时（类似 Node.js 的事件循环，负责调度所有 async 任务）；channel（通道）是异步任务之间传消息的管道，一端发送（tx）一端接收（rx）——Codex 的整个引擎就是围绕两条 channel 构建的。

仓库顶层：codex-rs/ 是 Rust workspace（全部核心实现，codex-rs/Cargo.toml:2-126 列出 123 个成员 crate）；codex-cli/ 是 npm 薄壳（只负责按平台挑选原生二进制并透传信号，codex-cli/bin/codex.js:15-22）；sdk/ 有 TypeScript 和 Python 两套 SDK；docs/ 的多数文档已外迁到官网、只剩重定向占位。

0.1 123 个 crate 怎么分组

01一条消息的一生 ★

这是全文的主线。从你按下回车，到回复完整出现，共 14 站。每一站在后面的章节里都有对应的放大详解。

02启动流程：进程启动 → TUI 出现

从 codex 命令敲下到界面出现，经过 npm 薄壳、arg0 分发、clap 解析、配置加载、onboarding、事件循环六步。

2.1 npm 薄壳：选平台二进制

如果你用 npm install -g @openai/codex 安装，实际执行的是 codex-cli/bin/codex.js：维护「平台 → 子包」映射（如 linux x64 → @openai/codex-linux-x64，codex.js:15-22），用 require.resolve 找到平台包里的原生二进制（codex.js:79-105），然后 spawn(binaryPath, argv, {stdio:'inherit'}) 启动并透传 SIGINT/SIGTERM 信号、复现退出码（codex.js:167-200）。一切逻辑都在 Rust 里，JS 层零业务。

2.2 arg0 多调用分发：一个二进制的多重身份

Rust 侧真正的 main()（cli/src/main.rs:956-962）不直接跑业务，而是先包一层 arg0_dispatch_or_else。这是经典的 busybox 技巧：同一个物理二进制，根据「自己被以什么名字调用」（argv[0]）决定扮演什么角色：

arg0/src/lib.rs:93-98（节选改排）
if exe_name == "codex-linux-sandbox" {
    codex_linux_sandbox::run_main();   // 变身 Linux 沙箱助手（never returns）
}
if exe_name == "apply_patch" || exe_name == "applypatch" {
    // 变身补丁应用器 —— 模型输出的 `apply_patch` 命令直接可执行
}

正常启动路径上还有两件事值得注意（arg0/src/lib.rs:292-312,327-437）：① 加载 ~/.codex/.env 时过滤一切 CODEX_ 前缀变量防注入；② 在 $CODEX_HOME/tmp/arg0/ 建临时目录，对自身可执行文件做 apply_patch、codex-linux-sandbox 等名字的 symlink 并 prepend 进 PATH——这样模型在 shell 里写 apply_patch <<'EOF'... 天然可执行，Linux 沙箱也能 re-exec 出助手进程。最后在一个 16 MiB 栈的专用线程上构建 tokio 运行时（arg0/src/lib.rs:208-237）。

2.3 clap 解析：28 个子命令

clap 是 Rust 事实标准的命令行解析库（用 derive 宏把 struct 变成 CLI 定义）。顶层 MultitoolCli（cli/src/main.rs:94-121）把 TUI 参数平铺进根命令、子命令设为可选——所以 codex "修个 bug"（无子命令）直接进交互 TUI（main.rs:988-1001），而 codex exec / codex login / codex mcp / codex app-server / codex resume / codex cloud / codex apply / codex sandbox 等 28 个子命令（main.rs:123-212）各走各路。

2.4 TUI 启动链：run_main 的十道工序

2.5 AGENTS.md 什么时候被读

Codex 的「项目记忆文件」是 AGENTS.md（对应 Claude Code 的 CLAUDE.md）。发现算法在 core/src/agents_md.rs:1-16 头注释写明：以 project_root_markers（默认 .git）向上找到项目根，然后从项目根到 cwd 沿途收集所有 AGENTS.md 顺序拼接（不越过项目根）；支持 AGENTS.override.md 本地覆盖（agents_md.rs:38-39）。用户级全局指令来自 $CODEX_HOME/AGENTS.md（codex-home/src/instructions/mod.rs:9-26），合并时用户层在前、项目层在后，以 --- project-doc --- 分隔（agents_md.rs:43-56）。

03Agentic 主循环：Session / Task / Turn

整个产品的心脏。Claude Code 的心脏是一个 1729 行的 query.ts；Codex 把同样的逻辑拆成了一条清晰的对象链和两层嵌套循环。

3.1 持有关系：谁管着谁

core 内核对象链
ThreadManager                [thread_manager.rs:182]  进程级工厂+注册表：HashMap<ThreadId, CodexThread>
 └─ CodexThread              [codex_thread.rs:160]    一个会话线程的外壳（旧称 conversation）
     └─ Codex                [session/mod.rs:389]     SQ/EQ 队列对：tx_sub 发提交、rx_event 收事件
         └─ Arc<Session>     [session/session.rs:28]  运行时骨架：事件出口、活跃任务、输入队列、服务
             ├─ SessionState [state/session.rs:26]    Mutex 保护的可变数据：history、限流、压缩窗口
             └─ TurnContext  [session/turn_context.rs:102] 每 turn 快照生成、turn 内不可变

几个 Rust 概念：Arc 是原子引用计数的共享指针（多个异步任务共享同一对象）；Mutex 是互斥锁（保证同一时刻只有一个任务改数据）；trait 类似接口。Session 的注释直说设计约束：「一个会话同一时刻最多一个运行中的任务，且可被用户输入打断」（session/session.rs:27）。注意 SessionState 里的 history: ContextManager 才是对话历史的真正持有者（state/session.rs:26-47）。

3.2 SQ/EQ 协议：引擎的唯一入口和唯一出口

引擎与外界的全部交互收敛为两条 channel（session/mod.rs:538-539）：SQ（Submission Queue）收 Submission { id, op }，EQ（Event Queue）发 Event { id, msg }（事件的 id 关联回触发它的提交）。这是一个刻意的「协议化」设计——引擎不知道也不关心对面是 TUI、IDE 还是 CI 脚本。

消费端是常驻的 submission_loop（session/handlers.rs:703-853）：while let Ok(sub) = rx_sub.recv().await 后对 sub.op 做大 match 分发。枚举标了 #[non_exhaustive]（未来可加变体），未知 op 直接忽略。

3.3 steer：中途发消息不再是「排队」而是「转向」

这个版本最有意思的语义变化：Op::UserInput 到达时若已有活跃的 Regular turn，不会中断也不会排队等下一轮，而是先尝试 steer_input——把新消息塞进 input_queue，正在跑的 run_turn 循环会在下一轮迭代开头把它吸收进对话（handlers.rs:183-275 · session/mod.rs:3827-3900）。只有「无活跃 turn」时才真正 spawn 新任务。这让「模型干活时你补一句话」变成自然的转向，而不是打断重来。

3.4 Task 与两层循环

任务抽象是 SessionTask trait（tasks/mod.rs:214-253）：run(session, ctx, input, cancellation_token) → Result<Option<String>>，返回值就是最终的 assistant 消息。四个实现：RegularTask（普通对话）、CompactTask（压缩）、ReviewTask（代码评审）、UserShellCommandTask（用户直发 shell）。spawn_task 先以 Replaced 理由中止一切旧任务再起新的（tasks/mod.rs:314-323）——「一个会话一个任务」的机制保证。

RegularTask 的外层循环极短（我亲自核实过）：

core/src/tasks/regular.rs:73-89
loop {
    let last_agent_message = run_turn(
        Arc::clone(&sess), Arc::clone(&ctx), ...,
        next_input, prewarmed_client_session.take(),
        cancellation_token.child_token(),
    ).await?;
    // turn 跑完但期间用户 steer 进了新输入 → 再跑一个 turn 消化它
    if !sess.input_queue.has_pending_input(&sess.active_turn).await {
        return Ok(last_agent_message);
    }
    next_input = Vec::new();
}

内层 run_turn（session/turn.rs:142-459）才是 agentic 循环本体，每轮迭代：

和 Claude Code 完全一致的核心洞察：没有任何计划器。「agent 自主多步工作」的全部秘密就是 needs_follow_up 这一个布尔值——模型不停要工具、循环不停喂结果。

3.5 中断：CancellationToken 与优雅降级

Ctrl-C 从 TUI 一路变成 Op::Interrupt（tui interaction → JSON-RPC turn/interrupt → turn_processor.rs:1383），引擎侧 interrupt_task → abort_all_tasks(Interrupted)（session/mod.rs:3913-3920）。handle_task_abort（tasks/mod.rs:829-905）的次序体现了「优雅优先」：先 cancellation_token.cancel()（协作式取消，流消费点用 .or_cancel() 响应）→ 等一个宽限期 → 超时才 handle.abort() 硬杀 tokio 任务 → 最后往 history 写一个 <turn_aborted> 标记并 flush rollout——这样 resume 恢复会话时模型能知道上一轮是被打断的，不会误以为工具调用凭空消失。

3.6 history 记录与 rollout 落盘

统一写入口 record_conversation_items（session/mod.rs:2777-2794）一次做三件事：写内存 history、包成 RolloutItem 落盘、回发客户端。落盘由 RolloutRecorder（rollout/src/recorder.rs:78-119）后台任务串行化，每条带时间戳序列化为一行 JSON，追加到 ~/.codex/sessions/rollout-<日期>-<thread_id>.jsonl（recorder.rs:1519,1811-1833）。codex resume 恢复时从新到旧反向扫描 JSONL，处理压缩检查点/回滚/中断标记后重建 history（session/rollout_reconstruction.rs:113-150）。这与 Claude Code 的 transcript JSONL 思路一致，但 Codex 把「重建」做成了显式的逆向重放算法。

04工具系统

契约与运行时分离：tools crate 定义「发给模型的长相」，core/tools 定义「在本机怎么跑」。工具表不是静态的——每个 turn 按模型和配置现算。

4.1 ToolExecutor 与四态曝光

tools/src/tool_executor.rs:50-70（trait 核心）
pub trait ToolExecutor<Invocation>: Send + Sync {
    fn tool_name(&self) -> ToolName;
    fn spec(&self) -> ToolSpec;                      // 发给 API 的 JSON 契约
    fn exposure(&self) -> ToolExposure { Direct }   // 四态曝光
    fn supports_parallel_tool_calls(&self) -> bool { false }  // fail-closed：默认串行
    fn handle(&self, invocation: Invocation) -> ToolExecutorFuture;
}

ToolExposure 四态（tool_executor.rs:15-37）：Direct（初始工具表可见）/ Deferred（不进初始表，模型用 tool_search 工具按需发现——节省上下文的「延迟加载工具」）/ DirectModelOnly（排除出 code mode）/ Hidden（只可内部路由，模型看不见）。「模型看不到 ≠ 不能执行」：注册表收下全部 runtime，可见表只含 Direct（tools/spec_plan.rs:250-260）。

ToolSpec（tools/src/tool_spec.rs:15-53）序列化后就是 Responses API 的 Tool 对象，有两种关键形态：function（JSON Schema 参数，全部 strict:false）和 custom/freeform——不用 JSON，模型直接输出符合 Lark 语法（一种描述文法的 DSL）的原始文本，apply_patch 和 code-mode 的 exec 都走这种（免去了「往 JSON 字符串里塞多行 diff 还要转义」的痛苦）。

4.2 执行链：router → registry(hooks) → parallel → orchestrator

4.3 五个代表性工具

handlers/apply_patch.lark（全文法）
start: begin_patch hunk+ end_patch
begin_patch: "*** Begin Patch" LF
add_hunk:    "*** Add File: " filename LF add_line+
delete_hunk: "*** Delete File: " filename LF
update_hunk: "*** Update File: " filename LF change_move? change?
change_move: "*** Move to: " filename LF
change_context: ("@@" | "@@ " /(.+)/) LF
change_line: ("+" | "-" | " ") /(.*)/ LF

4.4 输出回填与截断：头尾保留，中间截断

工具输出回填为 ResponseInputItem::FunctionCallOutput { call_id, output }。截断策略与 Claude Code 的「保尾截断」不同：Codex 用 truncate_middle——预算对半分给前缀和后缀，中间插省略标记（utils/string/src/truncate.rs:7-36；token 按 4 字节 ≈ 1 token 估算）。模型级默认预算 10000 字节（protocol/src/openai_models.rs:680），exec 输出外壳统一附 Exit code / Wall time / Total output lines（core/src/tools/mod.rs:77-102）。

4.5 code_mode：把工具调用变成写 JavaScript

Codex 特有的实验能力：开启后模型拿到一个 freeform 的 exec 工具，直接写 JS 代码在嵌入的 V8 隔离环境（deno_core，无 Node、无文件系统、无网络，code-mode-protocol/src/description.rs:12-18）里执行；所有普通工具变成全局 tools.* 对象上的异步函数——await tools.exec_command(...)。JS 里的嵌套调用经 DispatchBroker 回灌到同一套工具运行时（tools/parallel.rs:395-398）。这就是「工具编排编程化」：模型可以用循环、条件、变量把 10 次工具调用写成一段代码一次跑完，省下 9 轮模型往返。CodeModeOnly 模式下普通工具从可见表隐藏、只留 exec 入口（spec_plan.rs:460-471）。

05权限与沙箱 ★

Codex 的重头戏。Claude Code 的安全主线是「权限提示系统」（沙箱是辅助）；Codex 反过来：OS 级沙箱是默认防线，审批弹窗是沙箱之外的例外通道。

5.1 两个正交的策略轴

第一轴 AskForApproval（何时问人），定义在 protocol/src/protocol.rs:901-925：

第二轴 SandboxPolicy（能碰什么）（protocol.rs:988-1036）：danger-full-access / read-only / workspace-write（cwd 可写 + 网络默认禁）/ external-sandbox（进程已在外部沙箱内）。workspace-write 下每个可写根自动挂上受保护子路径——.git、.codex、.agents 保持只读（protocol/src/permissions.rs:23-31,991-1031），注释明说这是防 agent 改 .git/hooks 之类的提权入口。

5.2 一条命令的安全判定链

5.3 审批弹窗的握手：oneshot channel

需要问人时，引擎在 request_command_approval 里创建一个 oneshot channel（一次性管道，等价于 Claude Code 那个「Promise + 队列」握手）：把发送端存进 pending map、发 EventMsg::ExecApprovalRequest 给 UI，然后 rx.await 挂起等待（session/mod.rs:2122-2194）。用户在 TUI 弹窗里选择后，决定以 Op::ExecApproval { id, decision } 走 SQ 回来，handler 按 id 找到 oneshot 回填（handlers.rs:364-404）。ReviewDecision 有 7 个变体（protocol.rs:4043-4078）：Approved / ApprovedForSession / Denied / Abort，外加两个「顺便落规则」变体（ApprovedExecpolicyAmendment、NetworkPolicyAmendment）和 TimedOut。收不到回复默认 Abort——fail-closed。

5.4 三平台沙箱实现

统一入口 SandboxType = None / MacosSeatbelt / LinuxSeccomp / WindowsRestrictedToken（sandboxing/src/manager.rs:36-76）。

Linux：内嵌 bubblewrap + seccomp（Landlock 已降级为 legacy）

• 文件系统：bubblewrap（bwrap，容器技术里常用的无特权命名空间沙箱）构建「默认只读 + 显式可写根叠加 + .git/.codex 保持只读」的文件系统视图（linux-sandbox/src/bwrap.rs:1-11，注释明说语义对齐 macOS Seatbelt）。妙处在 bwrap/build.rs:14-19：bubblewrap 的 C 源码被 vendor 进仓库直接编译进 Codex 二进制——不依赖各发行版千差万别的系统 bwrap。
• 网络与危险系统调用：seccomp（内核的系统调用过滤器）默认拒绝 connect/bind/listen 等网络调用、socket 仅放 AF_UNIX；并无条件封杀 ptrace 和 io_uring_*（io_uring 是绕过 seccomp 网络拦截的知名通道）（linux-sandbox/src/landlock.rs:165-240）。被 seccomp 击杀的进程退出码 159（128+SIGSYS）会被识别为「沙箱拒绝」。
• 为什么要独立入口：seccomp/bwrap 的限制必须在目标子进程自身、exec 前施加且不可逆——所以命令被改写成 codex-linux-sandbox --permission-profile ... -- 原命令，经 arg0 分发由同一个二进制的「沙箱人格」执行（sandboxing/src/landlock.rs:6,23-60），父进程不被自己的 seccomp 污染。
• Landlock（Linux 5.13+ 的无特权文件系统 LSM）保留为 legacy 后备，仅 feature 开启时使用（linux-sandbox/src/landlock.rs:1-11,139-163）。

macOS：Seatbelt（sandbox-exec）

用硬编码路径 /usr/bin/sandbox-exec（防 PATH 投毒，sandboxing/src/seatbelt.rs:26-30）加载 SBPL（一种 Lisp 语法的沙箱策略语言）profile 执行命令。base policy 开头即「默认全拒」：

sandboxing/src/seatbelt_base_policy.sbpl:7-14（节选）
(deny default)
(allow process-exec)
(allow process-fork)
(allow signal (target same-sandbox))
(allow file-write-data
  (require-all (path "/dev/null") (vnode-type CHARACTER-DEVICE)))

可写根不写进策略文本，而是经 -D WRITABLE_ROOT_0=... 参数传入、策略里用 (subpath (param "WRITABLE_ROOT_0")) 引用——避免路径转义注入（seatbelt.rs:623-769）。放网时才叠加 network profile（只放 DNS/证书校验等系统服务）。

Windows：Restricted Token（默认关闭）

不是 AppContainer，而是 CreateRestrictedToken + WRITE_RESTRICTED 旗标（只对写操作检查受限 SID，实现「读多写受限」，windows-sandbox-rs/src/token.rs:459-472）；文件系统靠 ACL、网络靠 WFP（Windows 过滤平台）block 过滤器（windows-sandbox-rs/src/wfp.rs:1-30）。三档配置默认 Disabled（protocol/src/config_types.rs:269-274）——Windows 沙箱是最新、默认不启用的一块。

5.5 沙箱拒绝之后：升权重试的安全阀

命令在沙箱里失败且判定为「沙箱拒绝」（靠关键词 + 退出码识别，避免把业务错误误判，sandboxing/src/denial.rs:6-53）时，orchestrator 的重试路径（tools/orchestrator.rs:289-440）层层把关：工具须声明 escalate_on_failure；审批策略须允许问人（never/on-request 下默认不重试）；最关键的安全阀——若策略含 denied-read 路径，禁止用「去沙箱重试」变相提权（denied reads 只在沙箱里存在，去沙箱等于绕过，tools/sandboxing.rs:281-289）。通过全部关卡后带着理由（"command failed; retry without sandbox?"）再次征询用户，批准才裸跑。

5.6 网络：不是开关，是受管代理

workspace-write 下网络默认禁。放行不是「打开开关」，而是走 network-proxy crate 的受管代理：Linux 沙箱切到 ProxyRouted 模式（seccomp 只放本地代理桥的连接），出网统一由代理裁决；被拦请求带原因码翻译成人话，on-request 下触发带 host 的审批，用户批准可沉淀为 execpolicy 网络规则（allow https_connect access to <host>）持久化（core/src/network_policy_decision.rs:26-100 · exec_policy.rs:426-470）。

06模型 / API 层：Responses API、WebSocket、认证

core/src/client.rs（2402 行）+ codex-api crate。这一版只支持 OpenAI Responses API——Chat Completions 已被物理删除。

6.1 WireApi 只剩一条路

model-provider-info/src/lib.rs:55-82（节选）
pub enum WireApi {
    /// The Responses API exposed by OpenAI at `/v1/responses`.
    #[default]
    Responses,
}
// 反序列化 "chat" 直接报错：
"chat" => Err(custom("wire_api = \"chat\" is no longer supported..."))

这意味着 Ollama / LM Studio 这类本地模型也走 Responses API 形态的端点（内置 provider gpt-oss，localhost:11434/1234，lib.rs:422-423,495-534）。自定义 provider 只能新增不能覆盖内置（lib.rs:462-493）。

6.2 stream()：WebSocket 优先，HTTP SSE 兜底

对象分两级：session 级 ModelClient 和 turn 级 ModelClientSession——后者缓存 WebSocket 连接和从响应头拿到的 x-codex-turn-state 粘性路由 token（client.rs:246-280）。stream()（client.rs:1734-1786）先试 WS，失败或不支持则落回 stream_responses_api（HTTP + SSE）。降级是单向棘轮：流级重试预算耗尽后 force_http_fallback 把本 session 永久钉在 HTTP 上（client.rs:492-511,1793-1803）。

请求体组装 build_responses_request（client.rs:812-892）的关键字段：

6.3 SSE 事件与超时

SSE 解析下沉到 codex-api crate。事件循环 process_sse_with_treatment（codex-api/src/sse/responses.rs:478-583）每次 timeout(idle_timeout, stream.next())——默认 300 秒无事件判死（model-provider-info/src/lib.rs:26）；流在 response.completed 之前关闭视为错误。response.failed 按 error.code 分类（上下文超限/配额/过载/无效请求），限流错误的重试延迟是用正则从错误文案里抠出来的（"Please try again in 11.054s"，sse/responses.rs:585-609）。

6.4 三层重试

• 单请求 HTTP 层：默认最多 4 次，退避 = 200ms × 2^(n-1) × 0.9~1.1 抖动；只重试 5xx 与传输错误，429 不在这层重试（交上层按服务端指示的延迟处理）（codex-client/src/retry.rs:23-73 · model-provider-info/src/lib.rs:261-267）。
• 流级重连：流中断整个请求重发，默认 5 次，UI 显示 "Reconnecting... n/5"（core/src/responses_retry.rs:22-79）。
• 传输降级：WS → HTTP 永久降级（见 6.2）；401 触发 token 刷新后重试（client.rs:1432-1451）。

6.5 认证：ChatGPT OAuth 或 API key

AuthMode（protocol/src/auth.rs:9-30）主线两条：ApiKey（环境变量 OPENAI_API_KEY）和 Chatgpt（订阅计划直接用）。OAuth 细节：本地起 127.0.0.1:1455 回调服务器（占用则退 1457，login/src/server.rs:54-56），标准 PKCE S256（login/src/pkce.rs:12-27），issuer auth.openai.com。token 存 $CODEX_HOME/auth.json（新版优先系统 keyring，成功后删除文件回退，login/src/auth/storage.rs:38-61）；主动刷新条件 = JWT 过期前 5 分钟或距上次刷新超 8 天（login/src/auth/manager.rs:177-178,2520-2542）。ChatGPT 计划用户不走 api.openai.com，而是 https://chatgpt.com/backend-api/codex（model-provider-info/src/lib.rs:38,241-258）。这与 Claude Code 的「API key vs Claude 订阅 OAuth」双轨一模一样，连 localhost 回调监听的手法都相同。

07上下文管理与压缩：四种 compact

上下文窗口有限。Codex 的续命手段从 Claude Code 的「客户端三级压缩」演化成了「归一化 + 四种压缩实现按能力分发」。

7.1 history 归一化：发请求前的清洗

ContextManager 是内存 history 的持有者，发请求前 for_prompt() 做三步清洗（core/src/context_manager/history.rs:121-146,359-367）：① 为没有输出的工具调用合成 "aborted" 输出（API 要求 call 与 output 严格配对，中断后的孤儿 call 会 400——与 Claude Code 的「合成 tool_result」同款问题同款解法；合成 id 用固定 UUID 命名空间，注释警告改了会「改变模型可见 ID、炸掉 prompt cache」，normalize.rs:15-63）；② 删孤儿输出；③ 模型不支持图片时把图片换成占位文本。

7.2 触发条件：90% 水位

每次采样前检查（session/turn.rs:797-821）：token 用量 ≥ auto_compact_token_limit 即触发。该上限默认 = 模型上下文窗口的 90%（protocol/src/openai_models.rs:441-452），context_window 元数据来自 models-manager（内置表 + 服务端 /models 目录 + 本地缓存，兜底 272000，models-manager/src/model_info.rs:95-97）。此外切换到更小窗口的模型也会触发预压缩（turn.rs:835-909）。

7.3 四种实现按能力分发

本地压缩（④）的细节：摘要 prompt 开头是 "You are performing a CONTEXT CHECKPOINT COMPACTION. Create a handoff summary for another LLM that will resume the task."（prompts/templates/compact/prompt.md，可用 compact_prompt 配置覆盖）；压缩请求本身超窗则从头删 item 重试（保住前缀缓存）；成功后重建 history = 最近的用户消息（倒序回填、总预算 20000 token）+ 摘要作为一条 user 消息（compact.rs:53,598-656），并向用户发警告「长会话多次压缩会降低模型准确性」。分发逻辑在 session/turn.rs:917-977。

08TUI 层：ratatui 的 inline viewport

不是全屏应用。Codex 把「定稿的历史」直接写进终端原生回滚缓冲，底部只保留一个动态高度的活动视口——这是与 Claude Code（fork 版 Ink 整屏管理）最有辨识度的架构差异。

8.1 渲染模型：两条正交路径

ratatui 是 Rust 主流的 immediate-mode 终端 UI 库：没有持久 widget 树，每帧由代码把 UI 画进离屏 Buffer，库对比前后帧只重画变化的单元格（和 Ink 的帧 diff 殊途同归）。crossterm 是底层终端驱动（raw mode、按键流、ANSI 命令）。

两条渲染路径
① 活动视口（每帧重画）
schedule_frame() → TuiEvent::Draw → chat_widget.desired_height(width) 动态定高
  → tui.draw(...) 在 SynchronizedUpdate 内重画底部视口     tui.rs:880-935

② 定稿历史（一次性注入 scrollback，之后不再管）
InsertHistoryCell → 设置滚动区域 DECSTBM("\x1b[r") 限定在视口上方
  → 逐行 Print，行被"顶进"终端原生回滚缓冲                  insert_history.rs:216-245,332-337

好处：历史滚动交给终端本体（鼠标滚轮、搜索、复制都是原生体验），Codex 只需渲染当前活动区；tui::init() 的注释直说「inline viewport; history stays in normal scrollback」（tui/src/tui.rs:375-376）。alt-screen（全屏）只在 Ctrl+T 转录浏览等 overlay 时按需进入（tui.rs:734-766）。帧率由 FrameRequester 合并调度（actor 模式，多次请求合并成一次 draw）。

8.2 事件循环与流式渲染

主循环是四路 select!（tui/src/app.rs:1169）：UI 内部事件 / 活跃会话事件 / 终端按键流 / app-server 通知。流式文本的渲染节奏很讲究（tui/src/chatwidget/streaming.rs:388-427）：Markdown 增量先进 MarkdownStreamCollector，只在换行边界提交整行（未完成的尾行留在活动视口里实时变化）；提交动画由专用线程发 CommitTick、平滑模式一 tick 一行，落后时批量泄洪。流结束后整段流式单元被替换为持有原始 Markdown 源、可随终端 resize 重排的 AgentMarkdownCell（app_event.rs:671-683）。历史区渲染单元统一实现 HistoryCell trait（history_cell/mod.rs:189，按 approvals/exec/patches/plans 等分类）。

8.3 底部面板与输入

• composer 是自研 textarea（含 Vim 模式、kill buffer、粘贴突发检测，bottom_pane/textarea.rs:1-40）；弹窗/模态是压在 composer 之上的 view 栈（bottom_pane/mod.rs:208）。
• 斜杠命令是一个 enum（/model /permissions /review /new /resume /fork /diff /status /usage /quit...，注释特意写「不要按字母排序！枚举顺序即弹窗展示顺序」，tui/src/slash_command.rs:12）。注意命令叫 /permissions 而非旧文档里的 /approvals。
• @文件补全：光标处检测 @ 前缀 token → 异步 FileSearchManager 模糊搜索 → 弹窗回填（chat_composer.rs:2371-2373）。
• 审批弹窗：ExecApprovalRequest 转成列表选择视图，用户选择后经 AppCommand::ExecApproval 回流引擎（bottom_pane/approval_overlay.rs:72-80,349-386）。
• Ctrl-C 分层消费：弹窗先吃（关自己）→ 有任务在跑则中断 → 空闲双击退出（chatwidget/interaction.rs:373-420）。
• 渲染质感：Markdown 用 pulldown-cmark 解析 + 自研表格排版；语法高亮包的是 syntect（约 250 种语言）；diff 渲染带行号 gutter、背景色随终端明暗自适应（tui/src/markdown_render.rs · render/highlight.rs:1-4 · diff_render.rs:1-32）。

09app-server：所有前端的统一协议层

Codex 特有的关键子系统。这一版最大的架构演进：TUI、codex exec、IDE 插件、SDK 全部收敛为同一个 JSON-RPC 协议的客户端。

9.1 为什么多此一层

引擎内部的 SQ/EQ 是 Rust 类型的 channel 协议，进程外用不了。app-server 把它包装成双向 JSON-RPC（双向 = 客户端能调服务器方法，服务器也能反过来请求客户端，比如审批弹窗）。于是同一个引擎能被四种前端驱动：TUI（进程内嵌，tui/src/lib.rs:1348-1370）、codex exec（进程内客户端，exec/src/lib.rs:787）、IDE 扩展（codex app-server 子进程 stdio）、Python SDK（app-server --listen stdio://）。协议类型还能一键导出 TypeScript 定义和 JSON Schema 给前端用（app-server-protocol/src/lib.rs:8-13）。

9.2 协议长什么样

概念映射：thread（会话线程）/ turn（一次用户输入触发的完整回合）/ item（回合内的条目：消息、命令执行、文件变更、推理）。app-server 内部有事件泵把引擎的 EventMsg 翻译成 v2 通知（app-server/src/request_processors/thread_lifecycle.rs:302-309）。对比 Claude Code：其 SDK 走的是自定义 stdin/stdout 控制协议且只服务 SDK；Codex 让自家 TUI 也吃自家协议（dogfooding），保证协议永远是完整的一等公民。

10扩展生态

无头模式、MCP 双向、SDK、云任务、hooks/skills/plugins——Codex 的生态位与 Claude Code 高度同构，但落点各有取舍。

10.1 codex exec：为 CI 而生的无头模式

参数面（exec/src/cli.rs）：--json 输出 JSONL 事件流（thread.started / turn.completed / item.completed / error 每行一个 JSON，exec/src/exec_events.rs:11-36）；--output-schema 用 JSON Schema 约束最终回答形状；-o 把最后一条消息写文件；- 从 stdin 读 prompt（与位置参数同给时 stdin 作为 <stdin> 块追加）；--ephemeral 不落盘会话。CI 友好的硬性设计：turn 失败/中断或收到错误 → 进程退出码 1（exec/src/lib.rs:988-1050）。子命令 codex exec resume --last 恢复上次会话继续跑。

10.2 MCP：既当客户端又当服务器

• 当客户端：config.toml [mcp_servers] 配置外部 server（stdio 或 streamable HTTP 两种 transport；required=true 时初始化失败直接让 codex exec 报错退出，config/src/mcp_types.rs:156-201,434-462）。底层用官方 Rust SDK（rmcp 1.8.0），OAuth/elicitation/重试齐全。工具命名已核实：发给模型的是 {server}__{tool}（双下划线），mcp__ 前缀只在 hooks 视角保留为 legacy 兼容（core/src/tools/handlers/mcp.rs:29-65）。
• 当服务器：codex mcp-server 把 Codex 自己暴露为 stdio MCP server，提供 codex（起会话跑任务）和 codex-reply（按 thread_id 续聊）两个工具（mcp-server/src/codex_tool_config.rs:117-120,224-237）——其它 agent 可以把 Codex 当工具调。审批经 MCP elicitation 机制回传调用方。

10.3 SDK：两种语言两种接法

TypeScript SDK 的 Thread.runStreamed() 返回异步生成器，底层 spawn codex exec --experimental-json 消费 JSONL（sdk/typescript/src/exec.ts:86,151-152）；Python SDK 则 spawn codex app-server --listen stdio:// 走 JSON-RPC（sdk/python/src/openai_codex/client.py:213,252-263）。同一引擎，两种传输——也侧面印证了 app-server 是终态方向。

10.4 hooks / skills / plugins / 云任务

与 Claude Code 生态对照：斜杠命令 Codex 是内置 enum（不可用 markdown 自定义；旧版的 ~/.codex/prompts 自定义 prompt 机制在本快照中未找到实现，疑似已被 skills 吸收——此点未完全核实）；子 agent 机制存在（multi_agents 工具族、spawn_subagent，thread_manager.rs:711）但本文未深入展开。

11文件索引速查

按「我想看 X」检索，路径相对 codex-rs/。

11.1 未核实与存疑清单

• 仓库内 config.md 的配置项清单已外迁在线文档，本文以 core/config.schema.json 佐证配置键存在性。
• ~/.codex/prompts 自定义斜杠 prompt 机制在本快照中未找到实现（疑似被 skills 体系吸收），未核实。
• network-proxy 的 MITM/证书注入、Windows 沙箱 ACL 布点、guardian 自动审批子系统只做了机制定性，未逐行核实。
• WebSocket 传输的具体 URL 路径、SUBMISSION_CHANNEL_CAPACITY 数值、TUI CommitTick 间隔毫秒值未查。
• spawn_task 中连续两次 abort_all_tasks（tasks/mod.rs:320-321）疑似防御式写法，意图未考证。