?

本文將帶你深入了解 OpenAI Codex 的內(nèi)部架構(gòu)、設(shè)計思路和實現(xiàn)原理。無論你是初學(xué)者還是有經(jīng)驗的開發(fā)者，都能從中獲得對 AI 編程助手的深刻理解。

什么是 Codex？

想象一下，你有一個超級聰明的編程助手，它不僅能理解你的需求，還能直接幫你寫代碼、運行命令、修改文件。這就是?Codex?—— OpenAI 推出的本地 AI 編程代理。

用大白話解釋

如果把編程比作做菜：

• 普通的 AI 助手（如 ChatGPT）就像一本菜譜，告訴你怎么做，但你需要自己動手
• Codex?就像一個真正的廚師，不僅告訴你怎么做，還能直接幫你把菜做出來

核心能力

• Codex 能做什么？
• 理解代碼：閱讀和分析你的項目代碼
• 編寫代碼：自動編寫新功能或修復(fù) bug
• 執(zhí)行命令：運行測試、構(gòu)建項目、git 操作等
• 修改文件：直接編輯、創(chuàng)建、刪除文件
• 搜索信息：在代碼庫中搜索，甚至進(jìn)行網(wǎng)絡(luò)搜索
• 調(diào)用外部工具：通過 MCP 協(xié)議連接各種外部服務(wù)

整體架構(gòu)概覽

Codex 采用了?Monorepo（單一代碼倉庫）?的組織方式，主要由 Rust 和 TypeScript 兩種語言構(gòu)建。

為什么選擇 Rust？

項目結(jié)構(gòu)圖

codex/├── codex-rs/ ? ? ? ? ? # Rust 核心代碼（45+ 個模塊）│ ? ├── core/ ? ? ? ? ? # ?? 核心引擎 - AI 的"大腦"│ ? ├── tui/ ? ? ? ? ? ?# ?? 終端界面 - 用戶交互│ ? ├── cli/ ? ? ? ? ? ?# ?? 命令行入口│ ? ├── exec/ ? ? ? ? ? # ?? 非交互式執(zhí)行│ ? ├── mcp-server/ ? ? # ?? MCP 服務(wù)器│ ? └── ... ? ? ? ? ? ? # 其他支持模塊│├── sdk/typescript/ ? ? # TypeScript SDK（給開發(fā)者用的庫）├── shell-tool-mcp/ ? ? # Shell 工具 MCP 實現(xiàn)└── docs/ ? ? ? ? ? ? ? # 文檔

架構(gòu)分層圖

Codex 的架構(gòu)可以分為四層：

1. 用戶接口層：你與 Codex 交互的入口（CLI、TUI、SDK）
2. 核心引擎層：處理 AI 推理、工具調(diào)用、上下文管理
3. 執(zhí)行層：實際執(zhí)行命令、修改文件、調(diào)用外部服務(wù)
4. 安全層：沙箱隔離、權(quán)限控制、執(zhí)行策略

核心特性詳解

1. 多模式交互

Codex 支持三種使用模式：

2. 會話管理

每次與 Codex 的對話都是一個”會話”（Session）。Codex 會：

• 記住你們的對話歷史
• 保存執(zhí)行過的命令和結(jié)果
• 支持暫停和恢復(fù)對話

3. 智能審批

Codex 不會盲目執(zhí)行所有命令。對于危險操作，它會執(zhí)行?rm -rf ./logs/*，這會刪除所有日志。[允許執(zhí)行] [拒絕] [白名單此命令]

底層協(xié)議與通信機(jī)制

提交隊列/事件隊列（SQ/EQ）模式

Codex 內(nèi)部使用了一種高效的異步通信模式：

用大白話解釋：

想象一家餐廳：

• 提交隊列（SQ）?就像顧客下單的窗口
• Codex 核心引擎?就像廚房
• 事件隊列（EQ）?就像出餐窗口

顧客下單后不需要等在窗口，可以去座位上等。廚房做好菜后，通過出餐窗口通知顧客取餐。

核心代碼結(jié)構(gòu)

// 簡化版的 Codex 核心結(jié)構(gòu)pubstructCodex?{// 提交隊列：接收用戶輸入? ? tx_sub: Sender<Submission>,// 事件隊列：發(fā)送處理結(jié)果? ? rx_event: Receiver<Event>,}

事件類型

Codex 定義了豐富的事件類型來描述各種操作：

記憶系統(tǒng)：如何記住對話

問題：AI 的”健忘癥”

大語言模型本身是”無狀態(tài)”的，每次調(diào)用都是全新的開始。就像一個失憶的人，每天早上醒來都不記得昨天發(fā)生了什么。

解決方案：持久化歷史

Codex 通過多層記憶系統(tǒng)解決這個問題：

三層記憶架構(gòu)

1. 短期記憶：上下文管理器（ContextManager）

pubstructContextManager?{// 當(dāng)前對話的所有項目（從舊到新排序）? ? items:?Vec<ResponseItem>,// Token 使用信息? ? token_info:?Option<TokenUsageInfo>,}

作用：管理當(dāng)前對話中的所有消息、工具調(diào)用和結(jié)果。

2. 中期記憶：消息歷史（Message History）

存儲位置：~/.codex/history.jsonl

{"session_id":?"abc123",?"ts":?1699123456,?"text":?"幫我寫一個排序函數(shù)"}{"session_id":?"abc123",?"ts":?1699123460,?"text":?"好的，這是冒泡排序的實現(xiàn)..."}

特點：

• 使用 JSONL 格式（每行一個 JSON）
• 原子寫入（不會出現(xiàn)寫一半的情況）
• 自動管理大小（超過限制會清理舊記錄）

3. 長期記憶：會話持久化

存儲位置：~/.codex/sessions/

每個會話保存為獨立的 JSON 文件，包含完整的對話狀態(tài)，支持隨時恢復(fù)。

項目文檔記憶：AGENTS.md

Codex 還會讀取項目中的?AGENTS.md?文件，了解項目的特殊規(guī)則：

# AGENTS.md## 項目規(guī)范-?使用 TypeScript 編寫-?所有函數(shù)必須有注釋-?測試覆蓋率要求 80% 以上## 禁止操作-?不要修改 .env 文件-?不要刪除 migrations 文件夾

上下文工程：智能管理有限的”腦容量”

問題：上下文窗口的限制

大語言模型有一個”上下文窗口”限制，就像人的工作記憶一樣有限。如果對話太長，模型就會”記不住”前面的內(nèi)容。

解決方案：智能上下文管理

Codex 采用多種策略來最大化利用有限的上下文：

策略 1：Token 估算

不使用精確的 tokenizer（太慢），而是用簡單的啟發(fā)式算法：

const?APPROX_BYTES_PER_TOKEN:?usize?=?4;// 估算 token 數(shù)量：每 4 個字節(jié)約等于 1 個 tokenfnapprox_token_count(text: &str) ->?usize?{? ? (text.len() +?3) /?4// 向上取整}

策略 2：智能截斷

對于過長的輸出，保留頭尾，刪除中間：

原始輸出（10000 字符）：┌───────────────────────────────────────────────────────┐│ [頭部 1000 字符] [...中間內(nèi)容...] [尾部 1000 字符] ? ? ? ?│└───────────────────────────────────────────────────────┘截斷后（2500 字符）：┌───────────────────────────────────────────────────────┐│ [頭部 1000 字符] ... [省略 7500 字符] ...[尾部 1000 字符] │└───────────────────────────────────────────────────────┘

策略 3：對話壓縮（Compaction）

當(dāng)上下文接近滿時，Codex 會請求 AI 對之前的對話進(jìn)行”摘要”：

壓縮前：用戶: 幫我看看為什么測試失敗AI: 好的，讓我運行測試... 測試結(jié)果是... 問題在于...用戶: 修復(fù)它AI: 我修改了文件... 現(xiàn)在測試通過了用戶: 還有其他問題嗎？...（很多輪對話）壓縮后：[摘要] 用戶請求修復(fù)測試失敗問題，經(jīng)過分析發(fā)現(xiàn)是類型錯誤，已修改 src/utils.ts 第 42 行，測試現(xiàn)已通過。

策略 4：環(huán)境上下文差異

只發(fā)送變化的部分，而不是每次都發(fā)送完整的環(huán)境信息：

<!-- 首次發(fā)送完整上下文 --><environment_context><cwd>/path/to/project</cwd><sandbox_mode>workspace-write</sandbox_mode><shell>bash</shell></environment_context><!-- 之后只發(fā)送變化 --><environment_context_diff><cwd>/path/to/project/src</cwd><!-- 只有工作目錄變了 --></environment_context_diff>

工具系統(tǒng)：讓 AI 能夠”動手”

為什么需要工具？

大語言模型本身只能”說”，不能”做”。工具系統(tǒng)就是給 AI 裝上”手”，讓它能夠：

• 執(zhí)行 shell 命令
• 讀寫文件
• 搜索代碼
• 調(diào)用外部服務(wù)

工具架構(gòu)

內(nèi)置工具列表

工具調(diào)用流程

1. AI 決定使用工具? ?└── "我需要運行測試來驗證修復(fù)"2. 生成工具調(diào)用? ?└── { tool: "shell", command: "npm test" }3. 權(quán)限檢查? ?└── 檢查執(zhí)行策略和沙箱規(guī)則4. 執(zhí)行工具? ?└── 在沙箱中運行命令5. 返回結(jié)果? ?└── 將輸出返回給 AI6. AI 繼續(xù)推理? ?└── "測試通過了，修復(fù)成功！"

工具注冊機(jī)制

Codex 使用統(tǒng)一的工具注冊表來管理所有工具：

pubstructToolRegistry?{? ? handlers: HashMap<ToolType,?Box<dyn?ToolHandler>>,}pubtraitToolHandler:?Send?+?Sync?{asyncfnhandle(? ? ? ? &self,? ? ? ? invocation: ToolInvocation? ? ) ->?Result<ToolOutput, ToolError>;}

安全沙箱：給 AI 一個安全的”游樂場”

為什么需要沙箱？

讓 AI 執(zhí)行命令是危險的。想象一下：

用戶: 幫我清理項目AI: 好的，我來執(zhí)行 rm -rf / ?# 危險！會刪除整個系統(tǒng)！

沙箱就是為了防止這種災(zāi)難性的操作。

沙箱原理

三種沙箱策略

跨平臺沙箱實現(xiàn)

Codex 針對不同操作系統(tǒng)使用不同的沙箱技術(shù)：

macOS: Seatbelt

// 生成 SBPL（Seatbelt Profile Language）策略let?profile =?format!(r#"? ? (version 1)? ? (deny default)? ? (allow file-read* (subpath "{writable_root}"))? ? (allow file-write* (subpath "{writable_root}"))? ? (deny network*)"#);

Linux: Landlock + Seccomp

// Landlock：限制文件系統(tǒng)訪問let?ruleset = Ruleset::new()? ? .handle_access(AccessFs::ReadFile)?? ? .create()?;// Seccomp：阻止危險的系統(tǒng)調(diào)用seccomp_rule_add(ctx, SCMP_ACT_ERRNO(EPERM),? ? SCMP_SYS(connect),?0)?; ?// 禁止網(wǎng)絡(luò)連接

Windows: RestrictedToken

使用 Windows 的受限令牌和 ACL（訪問控制列表）來限制權(quán)限。

沙箱繞過機(jī)制

有時候確實需要執(zhí)行受限的操作，Codex 提供了安全的升級路徑：

1. AI 請求執(zhí)行需要額外權(quán)限的命令2. 向用戶顯示權(quán)限提升請求3. 用戶確認(rèn)后，在沙箱外執(zhí)行4. 記錄操作日志

MCP 協(xié)議：連接外部世界的橋梁

什么是 MCP？

MCP（Model Context Protocol）?是一個開放協(xié)議，讓 AI 助手能夠與外部工具和服務(wù)交互。可以把它想象成 AI 世界的”USB 接口”。

MCP 的角色

Codex 可以同時作為：

• MCP 客戶端：調(diào)用其他 MCP 服務(wù)器提供的工具
• MCP 服務(wù)器：讓其他應(yīng)用調(diào)用 Codex 的能力

連接外部服務(wù)示例

# ~/.codex/config.toml[mcp_servers.github]enabled = true[mcp_servers.github.transport]type = "stdio"command = "npx"args = ["@modelcontextprotocol/server-github"]

配置后，Codex 就能使用 GitHub 的功能：

用戶: 幫我創(chuàng)建一個 issue 報告這個 bugCodex: 好的，我來調(diào)用 GitHub MCP 服務(wù)器創(chuàng)建 issue...? ? ? ?[調(diào)用 mcp__github__create_issue 工具]? ? ? ?Issue 已創(chuàng)建：https://github.com/xxx/xxx/issues/123

MCP 通信流程

┌─────────────┐ ? ? JSON-RPC ? ? ?┌─────────────┐│ ? Codex ? ? │ ?──────────────? │ ?MCP 服務(wù)器 ?││ ?(客戶端) ? │ ? ?over stdio ? ?│ ?(GitHub) ? │└─────────────┘ ? ? ? ? ? ? ? ? ? └─────────────┘1. 初始化握手：交換能力聲明2. 工具列表：獲取可用工具3. 工具調(diào)用：執(zhí)行具體操作4. 返回結(jié)果：獲取執(zhí)行結(jié)果

支持的傳輸方式

執(zhí)行策略：智能的權(quán)限管理

問題：如何判斷命令是否安全？

不是所有命令都同樣危險：

• ls?完全安全
• npm test?通常安全
• rm -rf /?絕對危險
• git push?需要確認(rèn)

解決方案：執(zhí)行策略引擎

Codex 使用基于規(guī)則的執(zhí)行策略系統(tǒng)：

策略文件格式

策略文件使用類 Python 的 Starlark 語言：

# ~/.codex/policy/default.codexpolicy# 允許常見的安全命令prefix_rule(? ? pattern = ["ls"],? ? decision =?"allow",)prefix_rule(? ? pattern = ["cat"],? ? decision =?"allow",)# 需要確認(rèn)的命令prefix_rule(? ? pattern = ["git", ["push",?"pull",?"fetch"]],? ? decision =?"prompt",)# 禁止危險命令prefix_rule(? ? pattern = ["rm",?"-rf"],? ? decision =?"forbidden",)

決策優(yōu)先級

當(dāng)多個規(guī)則匹配時，采用最嚴(yán)格的決策：

forbidden（禁止） > prompt（提示） > allow（允許）

內(nèi)置安全檢測

除了顯式規(guī)則，Codex 還有內(nèi)置的啟發(fā)式安全檢測：

// 已知的安全命令（27個）const?SAFE_COMMANDS: &[&str] = &["cat",?"echo",?"ls",?"pwd",?"grep",?"head",?"tail","wc",?"sort",?"uniq",?"diff",?"file",?"which",?"date","env",?"printenv",?"hostname",?"uname",?"whoami",// ...];// 危險命令檢測fnis_dangerous_command(cmd: &[String]) ->?bool?{? ? matches!(cmd,? ? ? ? ["rm",?"-rf", ..] |? ? ? ? ["git",?"reset",?"--hard", ..] |? ? ? ? ["sudo", ..] |// ...? ? )}

動態(tài)白名單

當(dāng)你批準(zhǔn)一個命令后，可以選擇”白名單此命令”，Codex 會自動更新策略文件：

# 自動添加的規(guī)則prefix_rule(pattern=["npm", "test"], decision="allow")

如何使用 Codex

安裝方式

# 方式 1：通過 npm 安裝npm install -g @openai/codex# 方式 2：通過 Homebrew 安裝（macOS）brew install --cask codex

登錄認(rèn)證

# 使用 ChatGPT 賬戶登錄（推薦）codex login# 或者使用 API Keyexport?CODEX_API_KEY=sk-xxx

基本使用

# 啟動交互式界面codex# 直接執(zhí)行任務(wù)（非交互式）codex?exec"幫我寫一個快速排序函數(shù)"# 在特定目錄工作codex --cd?/path/to/project

TypeScript SDK 使用

import?{ Codex }?from"@openai/codex-sdk";const?codex =?new?Codex();const?thread = codex.startThread({? ? model:?"gpt-4",? ? sandboxMode:?"workspace-write",? ? workingDirectory:?"./my-project"});// 同步模式：等待完成const?turn =?await?thread.run("幫我修復(fù)所有的 TypeScript 錯誤");console.log(turn.finalResponse);// 流式模式：實時獲取事件const?{ events } =?await?thread.runStreamed("運行測試");forawait?(const?event of events) {if?(event.type ===?"item.completed") {console.log("完成:", event.item);? ? }}

配置文件

# ~/.codex/config.toml# 默認(rèn)模型model = "gpt-4-turbo"# 沙箱策略sandbox_policy = "workspace-write"# 審批策略approval_policy = "on-request"# MCP 服務(wù)器配置[mcp_servers.github]enabled = true[mcp_servers.github.transport]type = "stdio"command = "npx"args = ["@modelcontextprotocol/server-github"]

總結(jié)

Codex 的設(shè)計哲學(xué)

1. 安全第一：多層沙箱、執(zhí)行策略、用戶審批
2. 可擴(kuò)展性：工具系統(tǒng)、MCP 協(xié)議、插件架構(gòu)
3. 智能管理：上下文壓縮、記憶持久化、Token 優(yōu)化
4. 用戶體驗：交互式界面、流式輸出、斷點續(xù)傳

技術(shù)亮點

未來展望

Codex 代表了 AI 編程助手的一個重要方向：從”建議”走向”執(zhí)行”，從”對話”走向”協(xié)作”。隨著 AI 能力的提升和工具生態(tài)的完善，我們可以期待更加智能、安全、高效的編程助手。

附錄：關(guān)鍵文件路徑速查

• 作者【前端領(lǐng)秀】一個喜歡探索前端領(lǐng)域AI賦能的開發(fā)者，喜歡我的可以關(guān)注我，私信我邀請進(jìn)入技術(shù)群，我會時刻分享最新前沿AI技術(shù)；