Codex CLI 项目介绍

项目定位

Codex CLI 是 OpenAI 发布的开源编码 Agent，直接在你的本地终端中运行。它可以理解自然语言指令，执行代码编辑、文件操作、命令运行等任务，是开发者的 AI 编程助手。

一句话：Codex CLI 将 ChatGPT 的代码能力打包成一个可以在终端中直接对话、执行命令的本地 Agent。

核心能力

自然语言编程：用日常语言描述需求，Codex 自动分析、计划并执行代码修改
安全沙箱执行：所有命令在多层沙箱中运行（Linux: bwrap+seccomp，macOS: Seatbelt），保护主机安全
MCP 生态集成：既可以使用外部 MCP 工具，也可以将自身暴露为 MCP 服务器供其他应用调用
多模型支持：支持 OpenAI、Amazon Bedrock、Ollama、LM Studio 等多种模型提供商
丰富的 TUI 界面：基于 ratatui 的终端界面，支持 Markdown 渲染、代码差异高亮、流式输出
状态持久化：基于 SQLite 的会话持久化，支持会话恢复、分叉和多 Agent 协作

技术栈

维度	技术选择
核心语言	Rust（edition 2024）
CLI 入口	TypeScript/Node.js（轻量包装器）
构建系统	Bazel + Cargo
TUI 框架	ratatui + crossterm
异步运行时	Tokio
状态存储	SQLite（sqlx，WAL 模式）
沙箱技术	Linux: bubblewrap + seccomp + landlock；macOS: Seatbelt
协议层	OpenAI Responses API、MCP (Model Context Protocol)
认证	OAuth 2.0 (PKCE)、API Key、JWT (Ed25519)、AWS SigV4

架构概览

快速体验

安装

# 使用 npm
npm install -g @openai/codex

# 或使用 Homebrew
brew install --cask codex

运行

# 交互式 TUI 模式
codex

# 非交互式执行单条指令
codex exec "给这个项目添加一个 README"

# 使用 MCP 工具
codex --mcp-servers ./mcp-servers.json

源码结构

codex-rs/                    # Rust 核心代码（100+ crates）
- core/                      # Agent 引擎：Session、Turn 循环、工具执行
- cli/                       # 命令行入口
- tui/                       # 终端界面
- protocol/                  # 协议定义（Op、Event、消息模型）
- tools/                     # 工具规格定义
- sandboxing/                # 沙箱抽象层
- linux-sandbox/             # Linux 沙箱实现（bwrap + seccomp）
- bwrap/                     # Bubblewrap 集成
- execpolicy/                # 执行策略引擎（Starlark DSL）
- shell-escalation/          # 权限提升控制
- codex-mcp/                 # MCP 客户端聚合
- mcp-server/                # Codex 作为 MCP 服务器
- rmcp-client/               # 底层 MCP 协议客户端
- model-provider/            # 模型提供商抽象
- backend-client/            # 后端 API 客户端
- codex-api/                 # OpenAI API 封装
- state/                     # SQLite 状态持久化
- message-history/           # 消息历史管理
- ext/memories/              # 长期记忆系统
- agent-graph-store/         # Agent 图存储（多 Agent 协作）
- ...

codex-cli/                   # TypeScript CLI 包装器（轻量）

教程导读

本项目的教程分为 AI 应用 和 编程核心 两个系列：

AI 应用系列

聚焦 Codex 中体现的 AI Agent 通用知识：

章节	内容	引用的 Common 教程
01	Codex 的 Agent 核心循环实现	Agent 核心循环设计
02	Codex 的工具调用系统	工具调用协议与执行模型
03	Codex 的 MCP 集成方案	MCP 协议与生态集成
04	Codex 的安全沙箱实现	安全沙箱设计
05	Codex 的上下文压缩策略	上下文压缩与 Token 优化
06	Codex 的记忆系统设计	记忆系统设计
07	Codex 的多模型适配方案	多模型适配架构

编程核心系列

聚焦 Codex 的工程实践和架构决策：

章节	内容
01	大型 Rust Workspace 的模块化架构设计
02	事件驱动架构：SQ/EQ 模式实践
03	TUI 工程实践：ratatui + crossterm
04	安全策略引擎：Starlark DSL 的设计与实现
05	SQLite 状态持久化：三库拆分与 WAL 模式
06	认证系统的多策略架构
07	传输层抽象：HTTP/SSE/WebSocket/WebRTC 统一

版本信息：本教程基于 Codex 20fedaff 分析。