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。

它的工作方式不是只回答，而是可以围绕一个目标完成闭环：

1. 读取项目文件；
2. 分析代码和报错；
3. 修改相关文件；
4. 执行命令或测试；
5. 根据结果继续调整；
6. 最后给出变更说明。

可以把区别理解成：

因此，Codex 的关键价值不只是“会生成代码”，而是能在代码库里完成从分析到验证的任务闭环。

3. Agent：从回答问题到执行任务

Agent 可以理解为“带目标执行能力的助手”。

当你给 Codex 一个任务时，它通常会经历这样的过程：

理解目标 -> 读取上下文 -> 执行动作 -> 查看结果 -> 继续修正

这和普通问答最大的区别是：Codex 会动手。

例如你输入：

修复当前项目里失败的单元测试。

一个典型的 Agent 流程可能是：

1. 先查看测试失败输出；
2. 找到相关测试文件；
3. 阅读被测代码；
4. 修改最小必要代码；
5. 重新运行测试；
6. 如果仍失败，继续分析；
7. 最后说明修改了什么。

这也是为什么 Codex 需要权限控制。它不仅能给建议，还可能真正修改文件、执行命令。如果没有边界，风险会比普通聊天机器人高得多。

4. Sandbox：限制 Codex 的操作边界

Sandbox 可以理解为 Codex 的操作围栏。它决定 Codex 能访问哪里、能不能写文件、能不能执行某些命令。

常见沙箱模式可以这样理解：

如果 Codex 无法修改文件，先不要直接判断它“没执行”。更合理的排查顺序是：

1. 当前是不是 read-only；
2. 要修改的文件是否在工作区内；
3. 命令是否需要访问工作区外资源；
4. 是否需要联网或访问系统级路径。

对大多数日常开发任务来说，workspace-write 是比较合适的默认选择。

5. Approval：控制高风险操作是否需要确认

Sandbox 和 Approval 容易被混在一起，但它们解决的是两个问题。

• Sandbox：这件事能不能做；
• Approval：做之前要不要问用户。

例如，当前环境是只读模式，Codex 想创建一个文件：

1. Sandbox 先判断：写文件超出了只读模式；
2. Approval 再判断：是否允许请求用户授权；
3. 如果需要确认，Codex 会停下来说明原因；
4. 用户确认后，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 不需要写得很长。重点是具体、可执行、可验证。

推荐写入：

不推荐写入：

• 大段背景介绍；
• 与项目无关的个人偏好；
• 模糊规则，例如“代码要优雅”；
• 密钥、token、账号密码。

如果 Codex 经常犯同一个项目级错误，不要只在对话里纠正一次，更应该把规则补进 AGENTS.md。

7. Memory 与 Chronicle：长期记忆和当前上下文

Memory 和 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 时，可以按下面顺序检查：

如果你发现 Codex “不听话”，可以优先排查：

1. 是否权限不足；
2. 是否任务超出了工作区；
3. 是否没有写清项目规则；
4. 是否把长期偏好和项目约束混在一起；
5. 是否要求它执行了需要审批的操作。

10. 总结

Codex 的核心不是“更会聊天”，而是能围绕代码库完成任务闭环。

这也决定了使用它之前必须理解边界：

• Agent 决定它能执行任务；
• Sandbox 决定它能碰哪里；
• Approval 决定越界时是否询问；
• AGENTS.md 承载项目规则；
• Memory 承载个人偏好；
• Chronicle 增强当前上下文。

一句话总结：边界越清楚，自动化越可靠。