OpenAI Codex DEEP

🏗️ 核心架构

Codex CLI 是 OpenAI 官方编码 Agent，采用 Rust monorepo 架构，核心设计理念：Protocol-First + 深度 Sandbox + Guardian 安全。

架构分层

• codex-rs/exec/ — 核心执行引擎（非交互式 Agent 入口）
• codex-rs/cli/ — 交互式 CLI（含 desktop app 支持）
• codex-rs/protocol/ — SQ/EQ 协议定义（Submission Queue / Event Queue）
• codex-rs/core/ — 核心配置、上下文、prompt 模板
• codex-rs/linux-sandbox/ — Linux 沙箱（Landlock + seccomp）
• codex-rs/windows-sandbox-rs/ — Windows 沙箱
• codex-rs/app-server*/ — App Server 架构（in-process + remote）
• codex-rs/state/ — Agent Job 状态管理

♻️ 主循环（Protocol 驱动）

Turn 生命周期

• ThreadStartParams → 创建新对话线程
• TurnStartParams → 开始一轮 agent turn
• Agent 执行：LLM 调用 → tool execution → approval (如需) → 继续或完成
• TurnCompletedEvent / TurnFailedEvent → turn 结束
• TurnInterruptParams → 用户可随时中断
• ThreadResumeParams → 恢复已有线程

与 Goose 的流式 BoxStream<AgentEvent> 不同，Codex 的协议是消息队列模型，更适合远程/分布式场景。

🔒 Sandbox 与 Guardian 系统

多层 Sandbox

Guardian 系统（审批层）

• GuardianAssessmentEvent — 风险评估事件
• GuardianRiskLevel — 风险等级
• GuardianUserAuthorization — 用户授权
• Network approval：NetworkApprovalProtocol、NetworkPolicyAmendment
• Exec approval：ExecApprovalRequestEvent、ExecPolicyAmendment
• 支持 on_request / on_failure / never 审批模式

📝 提示词工程（331 行 System Prompt）

Codex 的 system prompt 定义在 codex-rs/core/gpt_5_1_prompt.md，是所有分析框架中最详细的：

核心指令

• Personality：简洁、直接、友好，像资深工程师
• Autonomy：持续执行直到任务完全完成，不要停在分析阶段
• Responsiveness：长时间工作时发送简短更新（1-2 句），不能"消失"
• Planning：使用 update_plan 工具跟踪进度，支持 step 状态管理
• Validation：完成代码后主动运行测试验证，但根据审批模式调整策略
• Ambition vs Precision：新项目可大胆创意，现有代码库需精准手术

AGENTS.md 规范

Codex 定义了完整的 AGENTS.md 规范——这是比 OpenClaw 更早的 AGENTS.md 标准化尝试：

• AGENTS.md 可出现在仓库任意目录
• 作用域 = 包含该文件的目录树
• 深层 AGENTS.md 优先级更高
• 系统/开发者/用户指令优先级 > AGENTS.md

审批模式策略

• never / on-failure：可主动运行测试/lint
• untrusted / on-request：等用户确认后再运行耗时命令
• 测试相关任务：无论何种模式都可主动运行

🛠️ 工具系统

• apply_patch — 自定义 patch 格式（非标准 diff），支持 Add/Delete/Update 文件
• shell — 终端命令执行，受 sandbox 和审批策略约束
• update_plan — 进度跟踪工具，最多 5-7 步，每步 ≤7 词
• Dynamic tools：DynamicToolSpec 支持运行时注册工具
• MCP tools：支持 MCP server 的工具调用和 elicitation
• Web search：WebSearchAction 内置搜索

🔄 Collaboration 模式

Codex 支持 CollaborationMode：

• ModeKind — 不同协作模式定义
• Thread 可被订阅/退订：ThreadSubscribeParams / ThreadUnsubscribeParams
• Review 系统：ReviewStartParams → 代码审查流程
• 支持多 agent 在同一 thread 协作

🔐 登录与认证

最新 PR (#23093) 新增 first-class login 支持：

• codex_login crate — 认证模块
• AuthConfig — 认证配置
• Residency requirement 控制
• Originator 追踪
• Login restrictions enforcement

📂 关键文件

• codex-rs/protocol/src/protocol.rs — SQ/EQ 协议定义
• codex-rs/core/gpt_5_1_prompt.md — System prompt（331 行）
• codex-rs/core/gpt-5.1-codex-max_prompt.md — Codex Max 变体 prompt
• codex-rs/core/review_prompt.md — Review 模式 prompt
• codex-rs/exec/src/lib.rs — 执行引擎入口
• codex-rs/exec/src/event_processor_with_human_output.rs — 人类可读输出
• codex-rs/exec/src/event_processor_with_jsonl_output.rs — JSONL 输出
• codex-rs/linux-sandbox/src/exec_util.rs — Linux 沙箱执行
• codex-rs/cli/src/login.rs — 登录模块
• codex-rs/protocol/src/permissions/ — 文件系统/网络沙箱策略
• codex-rs/protocol/src/approvals/ — Guardian 审批系统
• codex-rs/state/src/runtime/agent_jobs.rs — Agent Job 管理

🔑 核心类型

💡 架构洞察

• Protocol-First 设计：SQ/EQ 模式比 stream 模型更适合远程部署和多客户端接入，是"企业级"设计
• Sandbox 深度领先：Landlock + Seccomp + Network Namespace 三重隔离，比容器级沙箱更细粒度
• Guardian = 安全 Meta-Agent：审批不是简单的 allow/deny，而是独立的风险评估系统
• Prompt 工程极致：331 行 system prompt 覆盖了 personality、autonomy、responsiveness、planning、validation 全维度，是目前分析中最完善的 prompt 工程
• AGENTS.md 标准化：Codex 在 prompt 中定义了完整的 AGENTS.md 规范，这比 OpenClaw 的实践更系统化
• App Server 架构：in-process 和 remote 两种 runtime，支持 CLI 和桌面应用两种入口
• vs Goose：Codex 更"重"（完整 sandbox + guardian + protocol），Goose 更"轻"（ACP + extension 动态加载）。Codex 适合企业场景，Goose 适合开发者工具场景