vibe-coding-cn/research/openai-codex/deep-dive.md

openai/codex 深度研究

研究级别

• 当前级别：L2 源码/结构深度研究。
• 研究对象：openai/codex。
• 证据来源：本目录 raw/ 下的 GitHub 元数据、README 快照和本地仓库工作树。
• 观察日期：2026-07-03。

L2 结论

openai/codex 不是简单的 CLI 包，而是一个以 Rust 工作区为核心的 coding agent 控制面。它把协议、配置、沙箱、工具、提示词、技能、TUI、CLI 包装和 MCP 服务拆成相对清晰的 边界，说明成熟 coding agent 的核心不是“会调用模型”，而是把模型能力放进可配置、可审计、 可限制、可交互的执行系统里。

对本仓最有价值的不是复制实现，而是学习它的边界设计：执行策略、沙箱策略、Agent 指令、 技能、配置和交互文档都被显式建模，避免把高风险行为藏在零散脚本或提示词里。

源码证据

• raw/repository/codex-rs/protocol/：协议层，说明 agent 运行时需要稳定消息边界。
• raw/repository/codex-rs/config/：配置层，承载运行参数、模型和权限相关配置。
• raw/repository/codex-rs/sandboxing/：跨平台沙箱抽象，说明执行权限是核心产品能力。
• raw/repository/codex-rs/linux-sandbox/：Linux 沙箱实现，说明本地命令执行必须有边界。
• raw/repository/codex-rs/tools/：工具层，说明 agent 能力通过显式工具接口接入。
• raw/repository/codex-rs/skills/：技能层，说明可复用操作经验被工程化为独立对象。
• raw/repository/codex-rs/tui/：终端交互层，承载人机协作的主要用户界面。
• raw/repository/codex-cli/bin/codex.js：npm 分发入口，本质上是对核心运行时的包装。
• raw/repository/docs/exec.md：命令执行文档，说明执行行为需要公开契约。
• raw/repository/docs/execpolicy.md：执行策略文档，说明权限策略需要独立表达。
• raw/repository/docs/sandbox.md：沙箱文档，说明安全边界不是实现细节。
• raw/repository/docs/agents_md.md：Agent 指令文档，说明项目级上下文是正式接口。
• raw/repository/docs/skills.md：技能文档，说明技能不是杂项 prompt，而是可治理能力单元。

关键机制

协议优先

Codex 将 agent 运行时拆成协议、客户端、服务和界面等层次。这个结构把“模型说了什么”与 “系统如何执行”分开，降低了 CLI、TUI、MCP 和未来其他入口之间互相污染的概率。

沙箱和审批是核心对象

本地 agent 的最大风险来自命令执行、文件写入、网络访问和外部工具调用。Codex 把 sandbox、 exec policy 和配置作为显式层，而不是把风险控制埋进一段提示词。这是企业级 agent 的底线： 风险必须是系统能力，不是靠模型自觉。

文档就是运行契约

docs/exec.md、docs/execpolicy.md、docs/sandbox.md、docs/agents_md.md 和 docs/skills.md 共同构成运行契约。它们不是营销文档，而是告诉使用者和贡献者： 哪些行为可执行，哪些行为受限，哪些上下文会被读取，技能如何介入系统。

分发壳和核心运行时分离

codex-cli/ 更像分发入口，核心复杂度集中在 codex-rs/。这种结构适合长期维护： 包管理、安装体验和跨平台入口可以变化，但 agent 核心边界保持稳定。

可迁移模式

• 把 agent 执行相关内容分成 config、sandbox、exec policy、tools、skills 和 agent context 六类，不混在一个 README 或提示词里。
• 对任何会执行命令、改文件或访问网络的脚本，增加风险等级、dry-run、审批策略和审计说明。
• 将 AGENTS.md 视为项目级上下文接口，而不是临时提示词。
• 将 skills 视为可复用能力单元，要求有触发条件、边界、输入输出和验证方式。
• 对本仓 scripts/、skills/、research/ 建立类似的控制面文档。

对本仓的影响

本仓已经有 AGENTS.md、skills/、scripts/、research/ 和 raw 事实层，下一步应把这些 对象之间的运行关系写得更明确：

• scripts/ 是仓库控制面，不是杂物间。
• skills/ 是 Agent 可复用能力层，不是提示词收藏夹。
• research/ 是研究对象网络，不是外链列表。
• AGENTS.md 是 AI 协作的项目级接口，不是单纯贡献指南。

风险和待验证项

• Codex 是官方产品仓库，行为可能随版本快速变化；动态事实必须以 domain.yml 观测日为准。
• 本地源码只能说明公开实现和文档，不能完整代表云端模型、服务端策略或私有运行逻辑。
• 本轮没有运行 Codex 自身测试，结论只覆盖结构研究，不覆盖性能、稳定性或真实使用体验。

下一步 L3 验证任务

• 把本仓 scripts/ 的风险分级和可执行入口整理成 manifest.yml 或等价登记表。
• 为高风险脚本补齐 dry-run、输入输出、owner、CI 状态和审计说明。
• 从 Codex 的 exec policy 和 sandbox 文档中抽象本仓可用的脚本治理检查清单。
• 在 docs/references/ 沉淀“coding agent 控制面”模板，避免研究结论长期滞留在 research。