Codex CLI 是什么：代理循环、工具与沙箱

本节帮你建立对 OpenAI Codex CLI 的整体认知：它是什么、由什么构成、和其他 AI 编程工具的差别在哪里，以及一次代理循环（agent loop）内部大致发生了什么。读完本节，你会知道为什么要学习审批策略、沙箱与计划模式，也能判断哪些任务适合交给 Codex CLI。

一、定义：终端里的开源编程代理

Codex CLI 是 OpenAI 推出的开源命令行编程代理（Coding Agent），运行在终端中，直接面向本地代码库工作。你用自然语言下达开发任务，它会读取项目文件、规划修改方案、编辑代码、在沙箱中执行命令与测试，并把结果反馈给你。

与只在网页里生成代码片段的工具不同，Codex CLI 的核心特征是：

• 能在本地项目目录中自主探索文件结构与代码实现；
• 具备工具调用能力，可以读写文件、运行 shell 命令；
• 在审批策略（approval policy）与沙箱（sandbox）的约束下执行动作，把"代理能做什么"这件事显式地交给你控制；
• 支持交互式会话与 codex exec 非交互执行两种形态，可嵌入自动化流程。

二、代理循环：Codex 在内部做了什么

理解 Codex 的关键是理解"代理循环"。一个典型循环由下面几步构成，并反复迭代直到任务完成：

1. 接收任务与上下文：模型读取你的指令、项目文件与已执行命令的输出。
2. 规划下一步：判断需要查看哪些文件、执行什么命令、是否先制定计划。
3. 调用工具：通过内置的 shell、文件等工具完成读取、修改或执行；工具返回结果。
4. 根据结果继续：遇到报错就分析、调整方案，再进入下一轮循环。
5. 收敛并汇报：任务达成后总结改动、指出待你验证的部分。

正因为存在"调用工具 + 执行命令"这一层，Codex CLI 才需要审批策略与沙箱：它不是纯文本生成器，动作可能真实作用于你的文件系统与终端环境，必须在可控边界内运行。

三、Codex CLI 与相关产品的区别

对比维度	ChatGPT 网页 / IDE 聊天	Codex 云端任务 / IDE 集成	Codex CLI（本地终端）
运行位置	网页或编辑器内对话框	云端或编辑器工作区	你的本地终端与项目目录
文件系统	受限于手动上传与插件	受限于工作区授权	直接访问本地项目，受沙箱约束
命令执行	通常不直接执行本地命令	在受管环境执行	本地 shell 工具，按审批策略放行
典型用法	问答、解释、生成片段	IDE 内结对编程、云端任务	终端结对、脚本化与 CI 自动化
可控性重点	提示与上下文管理	项目授权与权限	审批策略、沙箱与配置文件

本教程聚焦 Codex CLI 这条命令线路；云端 Codex 与编辑器集成共享相近的任务理念，但界面与权限模型不同，不在本教程主线内。

四、四个必须先认识的核心概念

4.1 审批策略（Approval Policy）

审批策略决定"哪些动作需要你点头才能执行"。官方常用三档：

• untrusted：面对陌生仓库时的保守模式，多数操作都先征求批准，适合第一次接触的项目；
• on-request：常规开发模式，只有越过既定边界的操作才需要批准；
• never：全自动模式，不再请求批准，适用于 CI/CD 等受控自动化场景。

4.2 沙箱（Sandbox）

沙箱定义代理能在多大范围内读写文件、是否允许网络访问。常见档位包括只读（read-only）与工作区可写（workspace-write）等。审批策略回答"要不要人批准"，沙箱回答"物理上允许碰到哪里"，两者配合形成安全边界。

4.3 计划模式（Plan Mode）

计划模式下，Codex 先收集上下文、向你澄清问题、产出修改方案，确认后才开始写代码。它适合需求不够明确、改动范围较大或风险较高的任务，能避免代理一上来就进行大规模修改。

4.4 项目配置（配置文件与指令规则）

项目可以通过配置文件固定模型、审批策略、沙箱、构建命令与测试命令等约定，让 Codex 在每次进入项目时遵循统一规则，而不是每次都靠你在对话里重复说明。

五、适合用 Codex CLI 完成的任务

• 在现有仓库中定位问题、修复报错与缺陷；
• 实现边界清晰的新功能、脚本与工具；
• 跨文件重构、批量修改与代码清理；
• 编写、运行并调试测试；
• 把重复性编码流程封装到脚本或 CI 中，通过 codex exec 自动执行。

六、使用边界与安全意识

七、本节小结

读完本节，你应当能够：说出 Codex CLI 的定位；描述代理循环的基本步骤；区分审批策略与沙箱；理解计划模式与项目配置的作用，并清楚它适合与不适合的任务边界。下一节我们完成安装与 ChatGPT 账号登录，在终端中启动第一次会话。