OPENAI CODEX · DEEP DIVE

Codex 原理、运行流程
与代码架构

一个运行在本地的编码 Agent 如何把"模型 + 循环 + 工具 + 沙箱"组合成可靠的软件工程助手

基于 github.com/openai/codex（codex-rs）源码与官方文档

AGENDA

内容概览

1Codex 产品形态

2核心原理：Agent Loop

3整体架构分层

4Session / Task / Turn

5Prompt 组装与缓存

6SQ/EQ 协议与 App Server

7工具系统

8审批策略 × 沙箱策略

9平台沙箱实现

10Orchestrator 升级流程

11上下文压缩与持久化

12完整时序与代码地图

01 · WHAT IS CODEX

同一个引擎，多种前端

本地

CLI / TUI

codex 交互式终端界面；codex exec 无头运行，适合脚本与 CI。

本地

IDE / 桌面 App

VS Code、Cursor 插件与 codex app，通过 app-server JSON-RPC 驱动。

云端

Codex Web

chatgpt.com/codex，在云端容器中并行执行任务并生成 PR。

模型

Codex 模型

面向软件工程训练的 GPT 变体，擅长长时程工具调用与补丁编辑。

开源实现 codex-rs：由 TypeScript 迁移到 Rust，单一静态二进制，原生集成各平台沙箱。核心 codex-core 与 UI 完全解耦。

02 · CORE PRINCIPLE

Agent Loop：输出即下一轮输入

用户输入Op::UserTurn

→

组装 Promptbuild_prompt()

→

流式采样Responses API

→

执行工具ToolRouter

→

回填历史FunctionCallOutput

↺

最终回答TurnComplete

loop {
  let prompt = build_prompt(history, tools);
  let r = run_sampling_request(prompt).await;
  // 工具调用 → 执行 → 输出写回 history
  if token_limit_reached { run_auto_compact(); }
  if !r.needs_follow_up { break; }
}

循环终止条件只有一个

只要模型本轮发出任何工具调用，结果就必须回传给模型，因此 needs_follow_up = true，继续采样。模型只输出文本消息时循环自然结束。

源码：core/src/session/turn.rs · run_turn()

03 · ARCHITECTURE

五层架构

① 前端

tuiexecIDE 插件桌面 Appmcp-server

② 接入 / 协议

cli + arg0app-server (JSON-RPC)protocol: Op / EventMsg / ResponseItem

③ 引擎 core

ThreadManagerSessionSessionTaskrun_turnContextManagercompactrollout

④ 工具 / 执行

ToolRouterToolRegistryToolOrchestratorunified_exec (PTY)apply-patchcodex-mcpexecpolicy

⑤ 平台 / 外部

Seatbeltbubblewrap + seccompWindows sandboxnetwork-proxyResponses APIOllama / LM Studio

04 · ENTITIES

Session · Task · Turn

实体	含义	关键约束
`Codex`	核心引擎，后台线程或独立进程运行	只通过 SQ / EQ 与 UI 通信
`Session`	当前配置与状态：模型、cwd、策略、历史	同一时刻最多一个 Task；重新配置会中止执行
`Task`	响应一次用户输入的完整工作	新输入或 `Op::Interrupt` 会终止它
`Turn`	一次"采样 → 执行工具 → 回填"迭代	上一轮输出是下一轮输入；无输出则结束
`Model`	Responses API 或兼容 Provider	SSE / WebSocket 流式返回 ResponseItem

来源：codex-rs/docs/protocol_v1.md。需要并行时，为每条工作线运行独立的 Thread 或子 Agent。

05 · PROMPT

Prompt 组装与前缀缓存

// 每次采样都是一次完整请求
instructions: <基础系统指令>
tools: [exec_command, apply_patch,
        update_plan, view_image, mcp__*]
input: [
  developer: <权限 / 沙箱说明>
  user:      <AGENTS.md 指令>
  user:      <environment_context>
  ...history (只追加)
  user:      "本次输入"
]

AGENTS.md 发现

从 cwd 向上找到项目根（默认 .git），再从根到 cwd 逐层收集 AGENTS.md 并拼接，越靠近 cwd 优先级越高；再合并 ~/.codex/AGENTS.md。

只追加，不改写

静态前缀在前、历史在后，最大化 prompt cache 命中。配置变化以追加消息表达。请求默认无状态，推理以 encrypted_content 回传，兼容 ZDR。

06 · PROTOCOL

SQ / EQ 队列对与 App Server

UI → Codex · Op

Submission Queue

UserTurn 用户输入 + 每轮上下文
Interrupt 中断
ExecApproval / PatchApproval 审批回复
UserInputAnswer 回答提问
Compact / Review / Shutdown

Codex → UI · EventMsg

Event Queue

TurnStarted / TurnComplete
AgentMessageContentDelta 流式文本
ExecApprovalRequest 请求审批
ExecCommandBegin/End、PatchApplyBegin/End
TokenCount / Warning / Error

IDE / 桌面 App

⇄

app-serverJSON-RPC · stdio / WebSocket

⇄

Threadstart / resume / fork

Turnstart / interrupt

Itemstarted → delta → completed

07 · TOOLS

工具系统

工具	作用
`exec_command` / `write_stdin`	unified_exec：基于 PTY 的命令执行，支持长驻进程与交互输入，输出头尾截断
`apply_patch`	自定义 diff 语法（`*** Begin Patch`）增删改文件，Codex 的主要编辑方式
`update_plan`	维护步骤与状态的任务计划，UI 显示为 TODO 列表
`view_image` / `web_search`	附加本地图片；服务端执行的网页搜索
MCP 工具 / `tool_search`	rmcp-client 连接 MCP Server；工具多时延迟加载 schema
`request_user_input` / 多 Agent	结构化提问；派生子 Agent 并互相通信

arg0 分发：同一个 codex 二进制，argv[0]=codex-linux-sandbox 时变身沙箱 helper，argv[1]=--codex-run-as-apply-patch 时变身补丁工具。

08 · SECURITY MODEL

审批策略 × 沙箱策略

AskForApproval：何时问人
`untrusted`	除 execpolicy 允许的命令外都要审批
`on-request`	默认；模型按需申请提权（`on-failure` 为别名）
`granular`	按类别细粒度开关
`never`	从不询问，失败直接返回模型

SandboxPolicy：系统允许做什么
`read-only`	全盘只读，默认断网
`workspace-write`	cwd 与 writable_roots 可写，`.git`/`.codex` 只读
`danger-full-access`	无限制
`external-sandbox`	已在容器内，全盘访问

再叠加 execpolicy（Starlark prefix_rule：allow / prompt / forbidden）与 network-proxy，形成纵深防御。

09 · OS SANDBOX

各平台沙箱实现

macOS

Seatbelt

/usr/bin/sandbox-exec 加载动态生成的 SBPL profile：按可写根放开 file-write*，拒绝网络，保留偏好设置读取。

Linux

bubblewrap + seccomp

--ro-bind / / 默认只读，--bind 叠加可写根，受保护子路径重新只读；PR_SET_NO_NEW_PRIVS + seccomp 屏蔽网络与 io_uring。Landlock 为旧路径。

Windows

Restricted Token

非提权模式用受限令牌；提权模式支持精确读写根与只读子目录。无法强制执行的策略 fail closed。

10 · TOOL ORCHESTRATOR

审批 → 沙箱 → 升级重试

execpolicy + 策略Skip / NeedsApproval / Forbidden

→

请求审批ExecApprovalRequest

→

沙箱内首次执行SandboxManager

→

沙箱拒绝?SandboxErr::Denied

→

再审批 + 无沙箱重试escalated

审批决策 ReviewDecision

Approved、ApprovedForSession（会话缓存）、ApprovedExecpolicyAmendment（写入规则）、Denied、Abort。也可由 Guardian 自动审查代为决定。

谁来决定升级

untrusted：沙箱失败后自动请求无沙箱重试。
on-request：不自动升级，拒绝信息返回模型，由模型带 require_escalated 显式申请审批。
never：从不询问，失败直接交给模型处理。

11 · CONTEXT & PERSISTENCE

上下文压缩与会话持久化

1触发：token 超过 model_auto_compact_token_limit 且仍需继续；采样前或切换小窗口模型时也会检查

2摘要：本地用压缩提示词总结；远程模式由 Responses API 返回不透明的 Compaction item

3替换：SUMMARY_PREFIX + 摘要 + 最近用户消息，重新插入初始上下文

4继续：同一 Turn 接着采样；也可 /compact 手动触发

Rollout

JSONL 会话记录

~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl，codex resume 重放恢复。

Config

config.toml

模型、Provider、策略默认值、MCP Servers、profiles、features。

OTel

可观测性

工具决策来源、沙箱结果、采样耗时等指标。

12 · END-TO-END

一次请求的完整时序

1TUI 发送 Op::UserTurn

2Session 启动 RegularTask → TurnStarted

3组装 Prompt，流式请求 Responses API

4模型调用 exec_command: cargo test

5Orchestrator：Skip 审批，沙箱内执行

6失败输出回填，needs_follow_up=true

7模型发出 apply_patch，自动批准写入

8重新测试，需联网 → 沙箱拒绝

9模型 require_escalated → 用户批准

10无沙箱执行通过；超阈值自动压缩

11模型输出总结，无工具调用 → 退出循环

12TurnComplete，rollout 落盘

逐步动画演示见 codex-animation.html

13 · CODE MAP

codex-rs 关键代码

入口

cli 多功能入口
arg0 二进制角色分发
tui ratatui 界面
exec 无头模式
app-server JSON-RPC

core/src

session/turn.rs 主循环
tasks/ regular · review · compact
context_manager/ 历史
compact*.rs 压缩
agents_md.rs · client.rs

core/src/tools

router.rs 解析分发
registry.rs 注册表
orchestrator.rs 审批沙箱
parallel.rs 并行调用
handlers/* 各工具实现

执行

unified_exec/ PTY 进程
apply-patch 补丁
execpolicy Starlark 规则

沙箱

sandboxing 策略转换
linux-sandbox · bwrap
network-proxy

生态

protocol 共享类型
codex-mcp · rmcp-client
model-provider · ollama

14 · TAKEAWAYS

设计取舍

引擎与 UI 解耦

SQ/EQ 让 TUI、IDE、App、MCP Server 共享同一个 core。

单 Task 模型

每个 Session 一次只跑一个 Task，避免并发编辑冲突。

纵深防御

规则 + 审批 + OS 沙箱 + 网络代理；不能强制执行就 fail closed。

只追加 Prompt

最大化前缀缓存命中；无状态请求兼容 ZDR。

补丁式编辑

输出更短、更易审阅，UI 直接渲染 diff。

Rust 单二进制

启动快、无运行时依赖，沙箱 helper 与补丁工具内置。

REFERENCES

谢谢

github.com/openai/codex：codex-rs 源码
codex-rs/docs/protocol_v1.md：Session / Task / Turn 与 SQ/EQ
codex-rs/core/README.md、linux-sandbox/README.md：沙箱实现
codex-rs/execpolicy/README.md：命令策略语言
developers.openai.com/codex：官方文档
OpenAI Blog · Unrolling the Codex agent loop

配套：Codex-架构原理详解.html · codex-animation.html

Codex 原理、运行流程与代码架构

内容概览

同一个引擎，多种前端

CLI / TUI

IDE / 桌面 App

Codex Web

Codex 模型

Agent Loop：输出即下一轮输入

循环终止条件只有一个

五层架构

Session · Task · Turn

Prompt 组装与前缀缓存

AGENTS.md 发现

只追加，不改写

SQ / EQ 队列对与 App Server

Submission Queue

Event Queue

工具系统

审批策略 × 沙箱策略

各平台沙箱实现

Seatbelt

bubblewrap + seccomp

Restricted Token

审批 → 沙箱 → 升级重试

审批决策 ReviewDecision

谁来决定升级

上下文压缩与会话持久化

JSONL 会话记录

config.toml

可观测性

一次请求的完整时序

codex-rs 关键代码

设计取舍

引擎与 UI 解耦

单 Task 模型

纵深防御

只追加 Prompt

补丁式编辑

Rust 单二进制

谢谢

Codex 原理、运行流程
与代码架构