AIGCBot
EN领取验证清单
Codex 原理与日常使用

AI 编程助手 / 工程工作流 / LESSON 00

Codex 原理与架构

先把 Codex 理解成由上下文、模型推理、工具调用、文件编辑、验证和汇报组成的工程代理循环。

阅读时间
14 分钟
学习路径
Codex 原理与日常使用
内容来源
Codex 专题教程

预计阅读时间: 14 分钟

学习 Codex 的第一步，不是背命令，而是把它看成一个可以进入仓库、理解上下文、执行工具、修改文件并验证结果的工程代理。它和普通聊天助手的差异在于：普通助手主要给建议，Codex 可以把建议变成工作区里的可审查变更。

这篇先建立一张心智地图：Codex 为什么能做工程任务、它的 agentic loop 如何运转、哪些边界必须由人来控制，以及为什么一个好用的 Codex 工作流通常由提示、项目规范、权限、验证和复盘共同决定。

一句话模型

可以把 Codex 理解成下面这条循环：

目标 -> 上下文 -> 计划 -> 工具调用 -> 文件变更 -> 验证 -> 汇报 -> 下一轮反馈

其中最关键的不是“模型很聪明”，而是它能在一个受控工作区里反复完成这几个动作：

阶段Codex 做什么人需要把关什么
目标解析你要改什么、为什么改、完成标准是什么目标是否真实、范围是否清楚
上下文读取文件、搜索符号、查看测试、理解已有约定哪些资料是事实，哪些只是历史假设
计划拆任务、选择实现路径、判断风险方向是否符合产品和工程优先级
工具调用运行 shell、读文件、打补丁、调用 MCP 或插件权限是否合理、是否触碰敏感系统
文件变更修改代码、文档、配置、测试变更是否最小、是否破坏用户已有修改
验证运行 lint、test、build、浏览器检查或手工检查验证是否覆盖真实风险
汇报说明改了什么、哪里验证了、还有什么风险是否可以合并、部署或继续迭代

这条循环决定了 Codex 最适合的工作：有明确产物、能被验证、上下文主要在仓库或已连接工具中的工程任务。

Codex 的几个界面

Codex 可以出现在不同界面里，但底层思路相似：

  • CLI：适合在终端里处理本地仓库、自动化、脚本化和非交互任务。
  • IDE 扩展：适合贴近编辑器做局部修改、解释、重构和快速检查。
  • ChatGPT 桌面应用：适合长任务、计划、文件编辑、差异审查、多工具协作和部署操作。
  • Cloud 或远程任务：适合把相对独立的工作放到托管环境中并行处理。

选择界面时，不要先问“哪个最强”，而要问“上下文在哪里、风险在哪里、我想多强地参与过程”。

如果任务需要看本地服务、浏览器截图、部署脚本和同机文件，桌面应用更自然。如果任务只是“在一个干净仓库里修一个清晰 bug”，CLI 或 Cloud 都可以。若任务高度依赖你当前编辑器焦点，IDE 扩展更顺手。

上下文不是越多越好

Codex 能读取仓库并搜索文件，但它仍然需要方向。一个有效提示通常包括四类信息：

目标：我要达成什么结果。
上下文：哪些文件、错误、截图、接口或业务规则重要。
约束：不能破坏什么，必须遵守什么。
完成标准：通过哪些检查，看到什么现象才算完成。

例如：

帮我把学习页新增 Codex 专题，放在 Flink 前面。
要求：
- 继续使用现有 Next.js 静态导出和 learning.ts 数据模型。
- 不移除备案号。
- 新增文章必须进入 sitemap。
- 完成后运行 lint 和 build，并部署到 aigc-bot.com。

这样的提示不需要很长，但它把目标、边界和验收都交代清楚了。Codex 仍然会自己读代码，但不会在一开始就猜错方向。

权限边界决定信任边界

Codex 的工程能力来自工具调用，工具调用必须被权限边界包住。常见边界包括：

  • 只读：适合解释代码、做方案、审查设计，不允许修改文件。
  • 工作区写入：适合大多数本地开发任务，可以读写当前仓库。
  • 网络访问：适合查官方文档、安装依赖、访问服务，但要防止不受信任内容注入。
  • 更高权限：例如写工作区外文件、操作服务器、部署生产环境，应该只在明确任务中使用。

默认应该让 Codex 在最小权限下工作。要部署生产、修改 Nginx、连接数据库或读取私密系统时，需要把动作和风险说清楚，并留下验证记录。

AGENTS.md 是项目级“工作协议”

如果你每次都要提醒 Codex“别改这个目录”“跑这个命令”“文档要同步”，说明这些规则应该进入 AGENTS.md。它适合承载：

  • 仓库结构和重要目录。
  • 本地启动、lint、test、build、部署命令。
  • 代码风格、提交规则和验收标准。
  • 明确的禁止事项，比如不能删除备案号、不能覆盖用户未提交修改。
  • 特定子目录的额外规则。

AGENTS.md 不是越长越好。最有价值的规则通常来自真实摩擦：Codex 犯过一次错，你纠正；犯第二次，就把规则沉淀下来。

Codex 擅长什么

适合交给 Codex 的任务有明显共同点：

  • 产物能落到文件、命令输出、部署结果或可见页面。
  • 代码库里能找到足够上下文。
  • 能通过测试、构建、截图、日志或接口结果验证。
  • 失败可以回滚，变更可以用 Git 审查。

典型场景包括：

  • 实现一个页面、组件、接口或脚本。
  • 修 bug 并补回归测试。
  • 阅读大段代码并写出调用链说明。
  • 根据截图调整 UI。
  • 同步内容、生成文档、写迁移计划。
  • 对 uncommitted diff 或 PR 做代码审查。
  • 把重复流程沉淀为 Skill、Hook 或自动化任务。

Codex 不应该替你判断什么

Codex 可以给建议，但不应该替你最终承担这些判断：

  • 是否发布到生产。
  • 是否删除数据、轮换密钥或改变权限边界。
  • 是否把未经复核的商业、法律、医疗、安全结论当成事实。
  • 是否引入长期维护成本很高的新依赖。
  • 是否接受一个没有验证、只有“看起来对”的大改动。

工程代理的价值是放大你的执行和审查能力，而不是替你取消判断。

好的 Codex 工作流长什么样

一个成熟的工作流通常长这样：

  1. 任务开始前：目标、上下文、约束和完成标准清楚。
  2. 读代码阶段：Codex 先理解现有模式，而不是直接重写。
  3. 计划阶段：复杂任务先列计划，简单任务直接做。
  4. 实现阶段：改动集中在必要文件，不做顺手重构。
  5. 验证阶段：运行与风险匹配的检查。
  6. 汇报阶段：说明变更、验证和剩余风险。
  7. 复盘阶段：把反复出现的规则写回 AGENTS.md、文档或 Skill。

这也是后面几篇教程的主线：把 Codex 从“能帮忙写代码”升级为“能嵌入你的工程系统”。

参考资料