Codex 核心概念：Agent、Sandbox、Approval、AGENTS.md、Memory 与 Chronicle
这篇文章主要写给刚开始接触 Codex 的开发者。咱们跳过安装流程，直接聊几个最容易让人困惑的核心概念：Codex 到底是什么、为什么总被权限拦住、什么时候需要你点一下确认、项目规则到底该写在哪，以及 Memory 和 Chronicle 分别在什么场景下救场。
1. 背景
不少开发者第一次用 Codex 时，大概率遇到过这些情况：
- 让它改个文件，它却说权限不够；
- 让它联网查点资料，它停下来等你批准；
- 让它处理项目外的文件，完全碰不了；
- 让它按团队习惯写代码，结果它没完全遵守项目约定。
这些看起来像是“不稳定”的表现，其实大多和 Codex 的底层机制有关——搞清楚下面这几个概念，问题基本就明朗了：
Agent：Codex 是能执行任务的编程袋里，不是只会聊天的机器人；Sandbox：限制了 Codex 能读写哪些文件、能执行哪些操作；Approval：决定高风险或越界操作是否需要你确认；AGENTS.md：给 Codex 定义项目级规则的说明文件；Memory：用来保存个人偏好和长期经验；Chronicle：用来增强当前屏幕和任务上下文。
理解这些之后，再让 Codex 改代码、修测试、做项目分析，遇到问题就能快速定位根源。
2. Codex 为什么不是普通聊天机器人
普通聊天机器人主要负责“回答问题”。你问它一段代码怎么写，它给你一段代码；你问某个报错可能是什么原因，它给你几个排查方向。就这样。
但 Codex 的定位更接近一个编程袋里，也就是 Agent。
它的工作模式不是只回答，而是围绕一个目标完成闭环：
- 读取项目文件；
- 分析代码和报错；
- 修改相关文件；
- 执行命令或测试；
- 根据结果继续调整；
- 最后给出变更说明。
区别可以这样看：
| 类型 | 主要能力 | 典型交互 |
|---|---|---|
| ChatGPT | 回答、解释、生成片段 | “这个函数怎么写？” |
| Codex | 读代码、改文件、跑命令、验证结果 | “这个测试挂了，帮我定位并修复。” |
所以，Codex 的核心价值不只是“会生成代码”，而是能在代码库里完成从分析到验证的任务闭环。
3. Agent：从回答问题到执行任务
Agent 可以理解为“带目标执行能力的助手”。当你给 Codex 一个任务时，它通常经历这样的过程：
理解目标 -> 读取上下文 -> 执行动作 -> 查看结果 -> 继续修正
这和普通问答最大的区别就是：Codex 会动手。
举个例子，你输入：
修复当前项目里失败的单元测试。
一个典型的 Agent 流程可能是：
- 先查看测试失败输出；
- 找到相关测试文件；
- 阅读被测代码；
- 修改最小必要代码；
- 重新运行测试；
- 如果仍失败，继续分析；
- 最后说明修改了什么。
这也是为什么 Codex 需要权限控制——它不仅能给建议，还可能真正修改文件、执行命令。如果没有边界，风险会比普通聊天机器人高得多。
4. Sandbox：限制 Codex 的操作边界
Sandbox 可以理解为 Codex 的操作围栏。它决定了 Codex 能访问哪里、能不能写文件、能不能执行某些命令。
常见的沙箱模式大致如下：
| 沙箱模式 | 含义 | 适合场景 |
|---|---|---|
read-only | 只能读取，不能写入 | 分析陌生项目、做代码审查 |
workspace-write | 可以修改当前工作区内文件 | 日常开发、修复 bug、补测试 |
danger-full-access | 权限非常大，基本不受工作区限制 | 临时可信环境，不建议常态使用 |
如果 Codex 无法修改文件，先别急着判断它“没执行”。更合理的排查顺序是：
- 当前是不是
read-only； - 要修改的文件是否在工作区内；
- 命令是否需要访问工作区外资源；
- 是否需要联网或访问系统级路径。
对大多数日常开发任务来说，workspace-write 是比较合适的默认选择。
5. Approval：控制高风险操作是否需要确认
Sandbox 和 Approval 容易混在一起，但它们解决的是两个不同的问题。
Sandbox：这件事能不能做；Approval：做之前要不要问用户。
举个例子，当前环境是只读模式，Codex 想创建一个文件：
- Sandbox 先判断：写文件超出了只读模式；
- Approval 再判断：是否允许请求用户授权；
- 如果需要确认，Codex 会停下来说明原因；
- 用户确认后，Codex 才能继续。
比较稳妥的日常组合是：
workspace-write + on-request
这个组合的含义是：
- 工作区内的普通读写可以正常进行；
- 涉及联网、工作区外路径、高风险命令时，先请求确认；
- 既不会每一步都打断，也不会完全放开权限。
不建议在不熟悉的项目里直接使用高权限模式，尤其是项目中包含 .env、密钥、生产配置、客户数据时。
6. AGENTS.md：项目级规则应该写在这里
AGENTS.md 可以理解为给 Codex 的项目入职手册。
项目里的很多约定不适合每次都在对话里重复，比如：
- 使用什么包管理工具；
- 修改代码后运行什么测试；
- 新增模块放在哪个目录；
- 命名规范是什么；
- 哪些文件不能修改。
这些内容适合沉淀到 AGENTS.md。
一个简单的示例：
# Project Instructions ## Build and Test - After changing Kotlin code, run the related module tests. - Do not modify `.env`, signing files, or CI configuration unless explicitly requested. ## Structure - New Android screens should be placed under the matching feature module. - ViewModel classes must end with `ViewModel`.
AGENTS.md 不需要写得很长，重点是具体、可执行、可验证。
推荐写入：
| 内容 | 示例 |
|---|---|
| 构建命令 | 修改后运行 ./gradlew test |
| 测试命令 | 运行对应模块单测 |
| 目录约定 | 新页面放在对应 feature 模块 |
| 禁止事项 | 不修改 .env、签名文件、CI 配置 |
| 验证要求 | 改完说明验证命令和结果 |
不推荐写入：
- 大段背景介绍；
- 与项目无关的个人偏好；
- 模糊规则，例如“代码要优雅”；
- 密钥、token、账号密码。
如果 Codex 经常犯同一个项目级错误，不要只在对话里纠正一次，更应该把规则补进 AGENTS.md。
7. Memory 与 Chronicle：长期记忆和当前上下文
Memory 和 Chronicle 都和上下文有关，但适用范围不同。
可以这样区分：
| 概念 | 作用 | 适合保存什么 | 不适合保存什么 |
|---|---|---|---|
Memory | 长期记忆 | 个人技术栈、偏好、常用习惯 | 项目强约束、敏感信息 |
AGENTS.md | 项目规则 | 构建命令、测试要求、目录规范 | 私人偏好、密钥 |
Chronicle | 当前上下文增强 | 当前屏幕、当前任务、近期操作 | 敏感页面、密钥窗口 |
关键规则应该放在 AGENTS.md，而不是只依赖 Memory。
原因很简单：
AGENTS.md跟项目走；- Memory 更像个人习惯的补充；
- 项目协作中，规则应该明确、可见、可审查。
Chronicle 能增强 Codex 对当前工作状态的理解，但也意味着它可能接触更多屏幕上下文。处理包含密钥、客户数据、内部文档的场景时，需要谨慎开启。
8. 最小实验：观察沙箱如何拦截写文件
下面用一个最小实验来看看 Sandbox 和 Approval 到底怎么工作的。
创建一个空目录并启动 Codex：
mkdir -p ~/codex-demo cd ~/codex-demo codex
Windows PowerShell 也可以：
mkdir ~/codex-demo cd ~/codex-demo codex
进入 Codex 后，切换到只读或最严格权限模式：
/permissions
然后输入：
帮我新建一个 hello.txt，里面写一行 hello codex。
如果当前是只读模式，创建文件会被拦截——因为这是写操作。这时候你应该能看到 Codex 说明它需要更高权限，或者请求你确认。
再切换到工作区可写模式，让它重新创建文件。只要文件位于当前工作区内，这次应该能正常完成。
这个实验可以帮你直观看到：
- Sandbox 如何限制写文件；
- Approval 如何在越界操作前介入；
- 同一个任务在不同权限模式下行为完全不同。
9. 实际使用建议
用 Codex 的时候，可以按下面这个顺序检查：
| 检查项 | 说明 |
|---|---|
| 明确任务目标 | 不要只说“优化一下”，说明要修什么、验什么 |
| 确认沙箱模式 | 日常开发优先使用 workspace-write |
| 确认审批策略 | 高风险操作建议保留确认 |
写好 AGENTS.md | 项目规则不要只靠临时口头说明 |
| 保护敏感信息 | .env、密钥、token 不进提示、不进代码 |
| 要求验证结果 | 让 Codex 说明运行了哪些测试，结果是什么 |
如果你发现 Codex “不听话”，可以优先排查：
- 是否权限不足；
- 是否任务超出了工作区；
- 是否没有写清项目规则；
- 是否把长期偏好和项目约束混在一起；
- 是否要求它执行了需要审批的操作。
10. 总结
Codex 的核心不是“更会聊天”，而是能围绕代码库完成任务闭环。
这也决定了使用它之前必须理解边界：
Agent决定它能执行任务；Sandbox决定它能碰哪里；Approval决定越界时是否询问；AGENTS.md承载项目规则；Memory承载个人偏好；Chronicle增强当前上下文。
一句话总结：边界越清楚，自动化越可靠。
