#Codex 核心概念

本章建立使用 Codex 的心智模型：一次任务是怎么跑起来的、指令从哪来、Skills 为什么不会撑爆上下文、沙箱/审批/规则三者如何分工。读完后你就能解释「为什么 AGENTS.md 要短」「为什么有时它会停下来问我」。

无论你用桌面应用、CLI、IDE 还是 Cloud，底层都是同一套 Agent，这些概念通用。

#1. Agent 循环（Reason + Act）

Codex 是典型的 ReAct 风格 Agent：规划 → 行动 → 观察结果 → 再规划，直到完成。

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

与「单次聊天补全」的本质区别是：状态在工具反馈中延续。它会读文件、写 patch、跑 shell、调 MCP、用 Skill，循环往复，而不是一轮对话就结束。

#2. 指令链（Instruction Chain）

每次会话开始时，Codex 会按顺序拼接一条指令链，作为模型的持久上下文：

1. 全局：~/.codex/AGENTS.override.md 或 ~/.codex/AGENTS.md（二选一）
2. 项目：从 Git 根目录沿路径走到当前工作目录，每层目录最多取一个文件 （AGENTS.override.md → AGENTS.md → 自定义 fallback 名）
3. 合并：自根向叶拼接，越靠近当前目录优先级越高（出现在 prompt 更靠后）

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

详见 AGENTS.md。

#3. 渐进式披露（Progressive Disclosure）

Skills、参考文档、脚本不会一次性塞满上下文，而是按需加载：

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

好处：仓库里可以挂很多 Skills，启动时只占用少量「目录」级元数据，真正用到才展开。这也是为什么 description 要写清「何时使用」——它决定了隐式触发的命中率。详见 Agent Skills。

#4. 三道权限闸门：沙箱 / 审批 / 规则

这是 Codex 与「全权限 Shell Agent」的关键差异——它有三层独立的安全控制：

任务里要跑某命令
      │
      ▼
[规则] 命中 forbidden? ──► 拒绝
      │ 否
      ▼
[沙箱] 在允许范围内? ──否─► 触发[审批] ──► 询问/拒绝
      │ 是
      ▼
    执行

桌面应用把沙箱+审批包装成更友好的预设（Auto / Read-only / Full access），见 权限设置；细粒度命令控制见 规则与钩子。

#5. 五层定制（Customization Stack）

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

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

#6. Local 与 Cloud：执行位置

Codex 的同一个任务可以在两个地方执行：

通过 Hand off 可把一个本地线程交给云端（或移动端）继续，再用 codex apply 把云端 diff 拉回本地。详见 工作流与 Worktrees 与 云端版本。

#7. 模型与推理强度

Codex 在每次会话可选择模型（如 GPT-5.5、GPT-5.4、5.4-mini、Codex Spark）与推理强度（reasoning effort：低 / 中 / 高 / Extra High）。两者共同决定：

• 指令遵循与多文件重构的稳定性
• 延迟与成本

长链路重构选更强模型 + 高推理强度；简单脚本/快速迭代选更快的型号。详见 模型选择。

#8. 心智模型小结

• Agent 循环：不是一问一答，而是「规划—行动—观察」的闭环
• 指令链：靠近目录的规则优先，所以规则写在最相关的地方
• 渐进式披露：能力很多但按需加载，不会一上来就爆上下文
• 三道闸门：沙箱定范围、审批定是否问、规则定单条命令
• 五层定制 + Local/Cloud + 模型选择：把通用 Agent 调成「你的工程师」

#下一步

• 安装与使用：把这套能力装到本机
• 权限设置：把三道闸门调到合适的松紧
• AGENTS.md：写下第一份项目规范