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 才能继续。

比较稳妥的日常组合是：

这个组合的含义是：

• 工作区内的普通读写可以正常进行；
• 涉及联网、工作区外路径、高风险命令时，先请求确认；
• 既不会每一步都打断，也不会完全放开权限。

不建议在不熟悉的项目里直接使用高权限模式，尤其是项目中包含 .env、密钥、生产配置、客户数据时。

6. AGENTS.md：项目级规则应该写在这里

AGENTS.md 可以理解为给 Codex 的项目入职手册。

项目里的很多约定不适合每次都在对话里重复，例如：

• 使用什么包管理工具；
• 修改代码后运行什么测试；
• 新增模块放在哪个目录；
• 命名规范是什么；
• 哪些文件不能修改。

这些内容适合沉淀到 AGENTS.md。

一个简单示例：

AGENTS.md 不需要写得很长。重点是具体、可执行、可验证。

推荐写入：

不推荐写入：

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

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

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

Memory 和 Chronicle 都和上下文有关，但适用范围不同。

可以按下面方式区分：

关键规则应该放在 AGENTS.md，而不是只依赖 Memory。

原因是：

• AGENTS.md 跟项目走；
• Memory 更像个人习惯补充；
• 项目协作中，规则应该明确、可见、可审查。

Chronicle 能增强 Codex 对当前工作状态的理解，但也意味着它可能接触更多屏幕上下文。处理包含密钥、客户数据、内部文档的场景时，需要谨慎开启。

8. 最小实验：观察沙箱如何拦截写文件

下面用一个最小实验观察 Sandbox 和 Approval 的效果。

创建一个空目录并启动 Codex：

Windows PowerShell 可以使用：

进入 Codex 后，切换到只读或最严格权限模式：

然后输入：

如果当前是只读模式，创建文件会被拦截，因为这是写操作。此时你应该能看到 Codex 说明它需要更高权限，或者请求你确认。

再切换到工作区可写模式，让它重新创建文件。如果文件位于当前工作区内，这次应该可以正常完成。

这个实验可以帮助你直观看到：

• Sandbox 如何限制写文件；
• Approval 如何在越界操作前介入；
• 同一个任务在不同权限模式下行为不同。

9. 实际使用建议

使用 Codex 时，可以按下面顺序检查：

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

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

10. 总结

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

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

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

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