Codex不听话怎么办？5大核心概念一文搞懂

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 增强当前上下文。

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