OpenAI Codex CLI 源码架构分析文档

目录

• 概述
• 整体架构
• 核心模块详解
  • 1. 代码库目录结构
  • 2. Rust Workspace 结构
• 通信协议架构
  • JSON-RPC 2.0 协议
  • 核心数据模型
• 核心引擎分析 (codex-core)
  • 核心组件
  • 核心流程
• 工具系统架构
  • 工具分类
  • 工具执行流程
• 沙箱安全机制
  • 安全架构
  • 沙箱策略类型
  • 文件系统策略示例
• App Server 架构
  • 组件结构
  • API 方法列表
• TUI 终端界面
  • 组件架构
  • TUI 依赖库
• 配置系统
  • 配置层级
  • 主要配置项
• 技术栈总结
  • Rust 技术栈
  • TypeScript 技术栈
• 数据流分析
• 总结
  • 架构特点
  • 核心优势
  • 适用场景
• 参考资料

---

概述

OpenAI Codex CLI 是一个本地运行的 AI 编程助手，由 OpenAI 开发并开源。它是一个基于 Rust 和 TypeScript 构建的复杂系统，提供终端用户界面(TUI)、VS Code 扩展集成、MCP (Model Context Protocol) 服务器等多种交互方式。

项目基本信息：

• 开源协议: Apache-2.0
• 主要语言: Rust (核心), TypeScript (CLI 封装)
• 安装方式: npm i -g @openai/codex 或 brew install --cask codex
• 认证方式: ChatGPT 账户登录 / API Key

---

整体架构

Codex 采用多层架构设计，核心逻辑由 Rust 实现，通过 JSON-RPC 2.0 协议与前端交互。

---

核心模块详解

1. 代码库目录结构

codex/
├── codex-cli/          # TypeScript CLI 封装 (npm 包入口)
│   ├── bin/codex.js    # CLI 入口脚本
│   └── package.json    # @openai/codex
│
├── codex-rs/           # Rust 核心实现
│   ├── core/           # 核心引擎 (最大模块)
│   ├── tui/            # 终端用户界面
│   ├── app-server/     # JSON-RPC 应用服务器
│   ├── app-server-protocol/  # 协议定义
│   ├── protocol/       # 内部通信协议
│   ├── tools/          # 工具系统
│   ├── mcp-server/     # MCP 服务器实现
│   ├── sandboxing/     # 沙箱安全机制
│   ├── exec/           # 执行引擎
│   ├── cli/            # Rust CLI 入口
│   └── utils/          # 工具库集合
│
├── sdk/                # SDK
│   ├── python/         # Python SDK
│   ├── typescript/     # TypeScript SDK
│
├── docs/               # 文档
└── .codex/             # Skills 配置

2. Rust Workspace 结构

项目使用 Cargo workspace 管理 80+ 个 crates：

---

通信协议架构

JSON-RPC 2.0 协议

Codex 使用 JSON-RPC 2.0 进行双向通信，支持两种传输方式：

核心数据模型

三层数据结构：

---

核心引擎分析 (codex-core)

核心组件

codex-core 是系统的核心引擎，包含以下主要组件：

核心流程

---

工具系统架构

工具分类

工具执行流程

---

沙箱安全机制

安全架构

Codex 实现了多层安全沙箱机制：

沙箱策略类型

策略类型	描述	适用平台
Seatbelt	macOS 系统级沙箱	macOS
Landlock	Linux 内核级沙箱	Linux
bubblewrap	Linux 容器沙箱	Linux
Windows Sandbox	Windows 系统沙箱	Windows

文件系统策略示例

---

App Server 架构

组件结构

API 方法列表

线程管理：

• thread/start - 创建新会话
• thread/resume - 恢复现有会话
• thread/fork - 分叉会话
• thread/list - 列出会话
• thread/read - 读取会话
• thread/archive - 归档会话
• thread/unarchive - 取消归档
• thread/unsubscribe - 取消订阅
• thread/rollback - 回滚会话
• thread/compact/start - 启动压缩

轮次管理：

• turn/start - 开始轮次
• turn/interrupt - 中断轮次
• turn/steer - 引导轮次

审批管理：

• applyPatchApproval - 补丁审批
• execCommandApproval - 命令审批
• requestPermissions - 权限请求
• mcpServerElicitationRequest - MCP 请求

---

TUI 终端界面

组件架构

TUI 依赖库

库名	用途
ratatui	终端 UI 框架
crossterm	终端控制
ansi-to-tui	ANSI 转义序列转换
nucleo	模糊匹配

---

配置系统

配置层级

主要配置项

配置类别	配置项	说明
模型	model	默认模型
	model_provider_id	模型提供商
审批	approvals_reviewer	审批审查者
	approval_presets	审批预设
沙箱	sandbox_policy	沙箱策略
	filesystem_policy	文件系统策略
	network_policy	网络策略
MCP	mcp_servers	MCP 服务器配置
技能	skills	技能配置

---

技术栈总结

Rust 技术栈

类别	库/框架
异步运行时	tokio
序列化	serde, serde_json, toml
HTTP/WebSocket	reqwest, tokio-tungstenite, axum
终端 UI	ratatui, crossterm
日志/追踪	tracing, tracing-subscriber, opentelemetry
测试	insta (snapshot), pretty_assertions
沙箱	landlock, seccompiler
MCP	rmcp
数据库	sqlx (SQLite)

TypeScript 技术栈

类别	库/框架
包管理	pnpm
构建	Node.js

---

数据流分析

用户输入到响应的完整流程

---

总结

架构特点

1. 模块化设计: 通过 Cargo workspace 组织 80+ 个 crates，实现高度模块化
2. 协议驱动: 使用 JSON-RPC 2.0 协议实现前后端解耦
3. 安全优先: 多层沙箱机制保护用户系统安全
4. 可扩展性: 支持 MCP 协议、Skills、Plugins 等扩展机制
5. 多模型支持: 支持 OpenAI、ChatGPT、LM Studio、Ollama 等多种模型提供商

核心优势

• 本地运行: 所有代码在用户本地执行，保护隐私
• 实时交互: 流式响应提供即时反馈
• 安全沙箱: 细粒度权限控制，防止恶意操作
• 多界面支持: TUI、VS Code、桌面应用、MCP 等多种交互方式
• 可配置性: 丰富的配置选项和策略控制

适用场景

• 本地代码助手
• IDE 集成开发
• 自动化任务执行
• 代码审查和修改
• 多 Agent 协作任务

---

参考资料

• Codex 官方文档
• GitHub 仓库
• VS Code 扩展
• MCP 协议

---