129. codex-cli 工程概览及技术栈分析

2026.06.02

·codexagent

1. 一句话总结 ​

  • codex-cli/ 只是 npm 启动壳，真正主体在 codex-rs/。
  • 第一遍只看一条链路：codex.js -> cli -> exec / tui -> app-server -> core -> tools -> terminal。
  • 先别平均理解所有 crate，先搞清楚入口、命令分发、Agent Loop、工具和权限。
  • 这篇只当源码入口索引，详细模块后面一篇篇拆。

2. 一图甚千言 ​

2.1 从哪里入手（信息图） ​

1-20260601035200.webp

2.2 项目结构全景（Node.js 视角） ​

codex-project-structure-node-view.webp

2.3 一条命令从 npm 走到终端 ​

codex-overall-architecture-flow.webp

3. 顶层结构 ​

3.1 npm 壳 ​

  • 关键文件：codex/codex-cli/bin/codex.js。
  • 它做三件事。
  • 判断 process.platform / process.arch。
  • 找对应平台的原生 binary。
  • 用 spawn() 把参数、stdio、环境变量交给 Rust 主程序。
text
codex-cli/bin/codex.js
  ├─ 找平台包
  ├─ 找 native binary
  └─ spawn(codex-rs binary, argv)

3.2 Rust 主体 ​

  • 关键文件：codex/codex-rs/Cargo.toml。
  • 第一遍只关注这些目录：
text
codex-rs/
├── cli/                    # 命令入口和分发
├── tui/                    # 交互式终端 UI
├── exec/                   # 非交互执行入口
├── app-server/             # Thread / Turn 协议服务
├── app-server-protocol/    # 请求和事件类型
├── core/                   # Agent 核心逻辑
├── tools/                  # 工具定义
├── shell-command/          # shell 命令解析
├── execpolicy/             # 执行策略
├── sandboxing/             # 沙箱
├── apply-patch/            # patch 应用
└── git-utils/              # Git 辅助能力

4. 一条命令怎么走 ​

4.1 codex exec 主链路 ​

text
codex exec "帮我改一个组件"
  │
  ▼
codex-cli/bin/codex.js
  │  ① 找 native binary
  │  ② spawn
  ▼
codex-rs/cli/src/main.rs
  │  ③ clap 解析到 exec
  ▼
codex-rs/exec/src/lib.rs
  │  ④ 创建 thread
  │  ⑤ 发起 turn/start
  ▼
app-server
  │  ⑥ 管 Thread / Turn 生命周期
  ▼
core
  │  ⑦ 拼上下文
  │  ⑧ 请求模型
  │  ⑨ 执行工具
  │  ⑩ 回填结果
  ▼
exec event processor
  │  ⑪ 渲染到 stdout / JSONL
  ▼
terminal

4.2 关键源码 ​

  • codex/codex-rs/cli/src/main.rs：MultitoolCli、Subcommand、cli_main()。
  • codex/codex-rs/exec/src/lib.rs：ClientRequest::ThreadStart、ClientRequest::TurnStart。
  • codex/codex-rs/app-server-protocol/src/protocol/common.rs：ThreadStart、TurnStart、ServerNotification。
  • codex/codex-rs/exec/src/event_processor_with_human_output.rs：把事件流渲染成人能读的终端输出。