Codex
内核剖面

Codex 不是「一个终端程序」，而是一个横跨四种产品的同一个 harness——那套 agent 循环与执行逻辑。差别只在外壳。

开源边界：引擎开源，外壳不全开

为什么值得看源码

2025 年 4 月 CLI 上线时它还只是一个终端程序；到 2026 年，它已经变成 JetBrains、Xcode 等第三方愿意依赖的平台级协议。这条演化路径的技术决策，大部分都留在了公开仓库与 PR 里——这是本文的主要材料。

把同一个内核塞进 IDE、桌面和云端，需要一个稳定的接缝。App Server 就是那条接缝：既是协议，也是一个长期驻留的进程。

它从哪来：一次失败的 MCP 尝试

给 VS Code 扩展复刻内核时，团队先试过「把 Codex 暴露成 MCP server」，但发现 MCP 语义很难表达 VS Code 需要的丰富交互（探索工作区、流式渲染推理、发 diff）。于是改成一个镜像 TUI 循环的 JSON-RPC 协议——这就是 App Server 的第一版。当时没打算对外，所以并没有设计成稳定 API。后来 JetBrains、Xcode 和桌面 App 都想要它，才被正式当作平台接口来维护。

一个 App Server 进程的四个部件

关键在于翻译层：core 内部是细粒度事件，App Server 把它们收敛成一小撮稳定的、面向 UI 的 JSON-RPC 通知再推给客户端。协议完全双向——一次客户端请求可以换来许多事件，反过来服务器也能在需要审批时主动发起请求，并暂停该 turn 直到客户端回答。

三个对话原语

客户端开场必须先发一次 initialize 握手，服务器借此声明能力、对齐协议版本与特性开关。传输层只要支持双向流即可——实现上默认是 stdio 上的 JSONL，但设计上兼容 TCP / HTTP2 / gRPC。

协议是怎么「定稿」的

# 从 Rust 类型生成 TypeScript 定义
$ cargo run -p codex-app-server-protocol --bin export-ts

# 其他语言：导出 JSON Schema 交给各自的代码生成器
$ cargo run -p codex-app-server-protocol --bin export-json-schema

正因为有这套生成链，社区与内部已用 Go、Python、TypeScript、Swift、Kotlin 写出各自的客户端绑定——协议是「一份来源、多语言投影」的。

所有智能都在这一个循环里：组装提示词 → 请求模型 → 拿到工具调用 → 执行 → 把结果拼回输入 → 再请求，直到模型不再调工具、而是吐出一条给用户的消息。

一个 Turn 的骨架

用的是 Responses API，服务端以 SSE 流式返回；response.output_text.delta 之类事件驱动 UI 的流式渲染，response.output_item.* 则被转成对象追加进下一轮输入。

提示词是怎么拼出来的

面向 Responses API 的 payload 里，角色按权重降序为 system > developer > user > assistant。在用户消息之前，Codex 会插入这几层：

1. developer 沙箱说明——由 workspace_write.md、on_request.md 等模板拼成。它只约束 Codex 自带的 shell 工具；MCP 等外部工具不受 Codex 沙箱保护，需自行负责边界。
2. developer 可选：配置里的 developer_instructions。
3. user 用户指令聚合：$CODEX_HOME 的 AGENTS.md，再从项目根一路向下找到 cwd 的各级 AGENTS.md（默认 32 KiB 上限），最后拼上已配置 skills 的前言、元数据与用法说明——越具体的越靠后。
4. user 环境上下文：当前工作目录与用户的 shell。

这套顺序不是随便排的——它直接决定了下面这件事。

为什么它「故意保持无状态」

Responses API 有 previous_response_id 可以让历史留在服务端，但 Codex 刻意不用：这样每个请求都无状态，能支持要求零数据留存（ZDR）的客户。代价是每轮都要把整段历史重新发一遍——网络流量接近平方级增长。解法是提示词缓存：只要前缀完全一致，采样就能复用上一次的算力，回到线性。

于是「保持前缀稳定」成了硬约束。以下操作会造成 cache miss，团队必须极度小心：

• 对话中途改变了可用工具集（MCP 服务器的 tools/list_changed 尤其危险）；
• 换了模型（第三个 prompt 条目里含模型专属指令）；
• 改变了沙箱 / 审批模式 / cwd。

对后两类，Codex 的处理不是「改前面的消息」，而是在后面追加一条新消息来表达变化——保持旧前缀不动。仓库里那个「MCP 工具枚举顺序不一致」的 bug（PR #2611）就是这条原则的反面教材。

上下文不够了怎么办：压缩

当 token 超过 auto_compact_limit，Codex 会调用 Responses API 的 /responses/compact 端点，把整段 input 换成一份更短的表示。返回里含一个特殊的 type=compaction 条目，携带一段加密的 encrypted_content，用来保留模型对原对话的「潜在理解」。早期这需要用户手动敲 /compact，现在自动触发。

模型端点可替换

也就是说：harness 与模型是解耦的。这也是为什么「Codex 开源」和「Codex 模型开源」是两件完全不同的事。

模型只能「说」；真正动到磁盘的是工具层。Codex 的工具面已经远超最初的「shell + patch」。

Code Mode：为什么仓库里塞了个 V8

翻 crate 列表会看到 third_party/v8、code-mode-runtime、v8-poc——Codex 会在内嵌的 V8 里执行模型写的代码，用它来编排多个工具调用。好处是把「几十次工具往返」压成一段程序；代价是要背进一整个 JS 引擎（还有 setup-rusty-v8 这类 CI 步骤）。这是一个明确的权衡，不是顺手加的。

MCP 与 skills 的边界

MCP 服务器提供的工具不经过 Codex 的沙箱——它们各自负责自己的护栏。skills 则是「给模型看的说明书」：Codex 会把每个 skill 的元数据与用法渲染进提示词，让模型知道什么时候该用哪个。两者都由同一套策略模型纳管，但安全责任划分不同。

这是 Codex 最值得抄的一层。它把「要不要问你」和「就算你同意了，它能碰什么」拆成两个正交的机制。

三种沙箱模式

read-only 不给工作区写权限　·　workspace-write 只开放工作区与显式 writable_roots　·　danger-full-access 不设限。写权限不等于网络权限——网络是另一条独立策略，默认关闭。

平台后端：不是一个通用的容器方案

注意这些是内核原语，不是 Docker 那种 VM/命名空间容器——它们约束的是宿主上的一个进程树。所以「沙箱」在这里的含义更接近 capability 收缩，而不是「隔离出一个新世界」。

execpolicy：把「哪些命令要拦」写成规则

沙箱之外还有一层命令级策略。规则是 .rules 文件（Starlark 语法），放在配置层旁的 rules/ 目录里：

~/.codex/rules/default.rules# 碰到 `gh pr view …` 时先问一句，再放它出沙箱
prefix_rule(
    pattern   = ["gh", "pr", "view"],
    decision  = "prompt",
    justification = "看 PR 可以先问一下",
    match     = ["gh pr view 7888"],          # 内联样例，加载时自检
    not_match = ["gh pr --repo openai/codex view 7888"],
)
# decision ∈ { allow, prompt, forbidden }

• 最严优先：多条同时命中时，forbidden > prompt > allow。
• 命令被当作参数列表比对（近似 execvp(3) 收到的形态）。
• 项目本地 .codex/rules/ 只有在项目层被信任时才加载；管理员可用 requirements.toml 强制约束。
• 权限模型本质是前缀匹配——对 bash -lc "…" 这种包装调用会失效，文档也点明了这个弱点。

亲手试一下这道门

下面这个模拟器把上面两层机制合到一起。选沙箱模式与一个动作，看命令的结局（示意，用于理解规则）：

注：真实结果还叠加了 execpolicy 规则、是否 on-request / never 等审批策略，以及 writable_roots 等配置。这里只演示「沙箱模式 × 动作」这一层。

一个能跑几小时的 agent，必须能记住自己做过什么、并在放手之前先审自己一遍。

落盘：SQLite + rollout

codex-rs/state 是一套 SQLite 存储，带分域迁移脚本（goals / logs / memory / queue / thread_history）；rollout 与 rollout-trace 负责把一次执行写成可回放的轨迹。线程历史另有 thread-store 与 thread_history。这是 App Server「客户端断开也能续上」的底气。

Guardian：它自己先审自己

仓库里有 guardian-reviewer、guardian-v2（含 async_scorer、sync_reviewer）与 guardian-context。这是一套自动审查机制：在动作执行前后做评估与打分。它还带熔断——auto_review.circuit_break_action = "strict" 时，否决次数超限会把 TooManyDenials 作为 turn.error 上报。换句话说，「人类审批」之外还有一条机器审批路径。

从单 agent 到多个 agent

core/src/tools/handlers/multi_agents(_v2)、agent-roles、collaboration-mode-templates、agent-message-board、ext/agent 共同构成多智能体能力。桌面 App 卖点之一就是「并行编排多个 agent」，而这套并行的底座就在 core 里——一个 turn 内可以派生子 agent、按角色分工、通过消息板通信。

记忆与目标

memories/read、memories/write 与 ext/memories 让 agent 读写长期记忆；ext/goal 则是目标系统。配合 skills，这构成一个「跨会话累积」的闭环——也解释了为什么 Codex core 的体积远超一个聊天循环。

把上面几层拼起来，会看到一组互相牵制的选择。它们不是「最佳实践」，而是有代价的赌注。

正在发生的变化

最值得盯的一条：TUI 正在被改造成 App Server 的普通客户端（PR #10192）。一旦完成，TUI 就能连到远端机器上的 Codex server——agent 贴近算力运行，笔记本合盖也不中断，本地只负责渲染与审批。这会把「App Server 是唯一稳定接缝」从一句设计宣言，变成一个可验证的事实。