架构与运行机制

本章从工程视角说明 Codex 如何完成一次任务：指令从哪来、工具如何被调用、沙箱与审批如何介入。读完后你应能解释「为什么 AGENTS.md 要短」「Skills 为何不会一次性占满上下文」。

1. 一次任务的宏观流程

Codex CLI 是典型的 ReAct 风格 Agent 循环（Reason + Act）：

flowchart LR
  A[用户 Prompt] --> B[加载指令链]
  B --> C[模型规划]
  C --> D{需要工具?}
  D -->|是| E[工具调用]
  E --> F[沙箱/审批检查]
  F --> G[执行并观察结果]
  G --> C
  D -->|否| H[输出总结 / Patch]

关键点：

会话启动时构建「指令链」（全局 AGENTS.md + 仓库路径上的 AGENTS.md）
模型根据任务选择工具：读文件、写 patch、跑 Shell、调 MCP、启用 Skill 等
Shell 与越界写文件会经过 sandbox_mode + approval_policy
循环直到任务完成、用户中断或达到限制

这与「单次 Chat 补全」的本质区别是：状态在工具反馈中延续，而不是一轮对话结束。

2. 指令链（Instruction Chain）

Codex 在每次 run（TUI 中通常每个新 session）开始时解析指令，顺序为：

全局：~/.codex/AGENTS.override.md 或 ~/.codex/AGENTS.md（二选一，非空即用）
项目：从 Git 根目录沿路径向下走到当前工作目录，每层目录最多纳入一个文件：
- AGENTS.override.md → AGENTS.md → project_doc_fallback_filenames 中的别名
合并：自根向叶拼接，越靠近 CWD 的段落 优先级越高（出现在 prompt 更靠后）

默认上限： 合并后约 32 KiB（project_doc_max_bytes），超出会截断。

设计含义

现象	原因
子目录规则覆盖根目录	后拼接 = 高优先级
AGENTS.md 不宜过长	与系统提示、Skills 元数据共享上下文预算
应把规则写在「最近的相关目录」	减少噪音，提高命中率

系统/开发者/用户即时指令优先于 AGENTS.md；AGENTS.md 优先于模型默认编码习惯。

3. Skills：渐进式披露

Skills 基于 Agent Skills 开放标准（SKILL.md + YAML frontmatter）。Codex 采用 Progressive Disclosure：

发现阶段          选中阶段              执行阶段
─────────        ─────────            ─────────
name/description → 加载 SKILL.md 全文 → 按需读 references / 跑 scripts/
（常驻元数据）      （仅当选中该 Skill）   （仅当步骤需要）

好处：

仓库里可以挂很多 Skills，不会一开始就把全部正文塞进上下文
$skill-name 显式调用与任务匹配时的 隐式调用 并存
description 写清楚「何时使用」，能显著提高触发准确率

Plugin 是 Skills 的分发单元：可捆绑 MCP 配置、App 元数据（agents/openai.yaml）等。

4. MCP 在架构中的位置

MCP（Model Context Protocol） 把 Codex 与仓库外系统连接：

┌──────────┐    MCP Client     ┌─────────────┐
│  Codex   │ ◄──────────────► │ MCP Server  │
│  Agent   │   tools/resources │ (GitHub等)  │
└──────────┘                   └─────────────┘

Host：Codex
Server：外部服务（工具、资源、可选 prompt 模板）
配置在 ~/.codex/config.toml 的 [mcp_servers]（项目级还可有 .codex/config.toml，需 trust 项目）

与 Skills 的分工：

Skill = 流程（先做什么、后做什么、用哪些工具名）
MCP = 能力（真正访问 Issue、浏览器、内部文档 API）

5. Subagents：并行与专责

复杂任务可拆给 Subagents（例如专门跑测试配置、专门拉生产日志的 MCP 组合）。每个子代理：

拥有更窄的工具集与提示词
可并行探索，降低主线程上下文膨胀

典型场景：代码审查（独立 Agent 读 diff，不继承主会话的「实现偏见」）、大规模仓库探索。

6. 沙箱与审批：两道独立闸门

这是 Codex 与其他「全权限 Shell Agent」的重要差异。

概念	回答的问题
sandbox_mode	技术上允许读写的范围（如 `read-only`、`workspace-write`）
approval_policy	越过边界时是否必须停下来问人（`untrusted` / `on-request` / `never`）

推荐本地日常组合：

codex --sandbox workspace-write --ask-for-approval on-request

或在 config.toml：

sandbox_mode = "workspace-write"
approval_policy = "on-request"

含义简述：

工作区内：可读、可改、可跑多数命令
写工作区外、开网络、跑「不可信命令」：触发审批
--yolo（dangerously-bypass-approvals-and-sandbox）：仅在隔离 VM 中使用

TUI 内可用 /permissions 临时切换模式（例如只读规划）。

7. 模型与推理

CLI 支持 /model 切换模型（如 GPT-5.x、Codex 优化型号等，以当前账户可用列表为准）。不同模型在：

指令遵循
多文件 refactor 稳定性
延迟与成本

上存在权衡。长链路重构可选推理能力更强的型号；简单脚本生成可用更快型号。

8. 与 Cloud / IDE 的关系

入口	执行位置	典型用途
CLI / App Local	本机沙箱	即时迭代、敏感内网代码
IDE 扩展	本机 + 编辑器上下文	小步修改
Cloud	远程容器 + GitHub	异步 PR、@codex 评论触发

AGENTS.md、Skills、MCP 配置可在多入口间迁移（见官方 Migrate to Codex）。

9. 心智模型小结

把 Codex 想象成一位 受雇工程师：

AGENTS.md = 员工手册与仓库 README 里的「怎么构建/测试」
Skills = 标准作业程序（SOP）
MCP = 公司内网系统账号
沙箱/审批 = 物理门禁与变更审批流
Subagents = 临时拉来的专项同事

Agent 强不强，不只看模型，还看这套 工程化约束 是否配齐。

下一步

AGENTS.md 项目指令：写第一份团队规范
沙箱与安全：按风险级别选预设
Agent Skills：把重复流程封装成 Skill

#架构与运行机制

#1. 一次任务的宏观流程

#2. 指令链（Instruction Chain）

#设计含义

#3. Skills：渐进式披露

#4. MCP 在架构中的位置

#5. Subagents：并行与专责

#6. 沙箱与审批：两道独立闸门

#7. 模型与推理

#8. 与 Cloud / IDE 的关系

#9. 心智模型小结

#下一步