Codex 不听话？一文带你搞懂5大Codex核心概念

对于刚接触 Codex 的开发者而言，理清其核心概念是顺畅使用的第一步。本文将绕过安装流程，聚焦于 Agent、Sandbox 等五个容易混淆的核心概念，帮助你快速理解其本质与正确用法。

1. 背景

许多初次使用 Codex 的开发者，常常会遇到以下状况：

1. 要求修改文件，它却提示权限不足；
2. 指令其联网查询资料，它中途停下请求确认；
3. 让它处理项目文件夹之外的文件，它回应无法直接访问；
4. 期望它遵循团队编码习惯，它未能完全遵守项目约定。

这些看似“不稳定”的表现，绝大部分都与 Codex 特有的几个基础机制有关：

1. Agent：Codex 是能执行实际任务的编程代理，并非单纯的聊天机器人；
2. Sandbox：用于限制 Codex 能够读写哪些文件、执行何种操作；
3. Approval：控制高风险或越界操作在运行前是否需要用户确认；
4. AGENTS.md：为 Codex 设定的项目级规则说明文件；
5. Memory：用来存储个人的编码偏好与长期经验；
6. 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 经常被混淆，但它们解决的是两个不同层面的问题。

1. Sandbox：判断这件事能不能做；
2. 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 无须写得冗长，重点在于具体、可执行、可验证。推荐写入的内容包括：

不推荐写入的内容包括：

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

如果 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. 是否没有在 AGENTS.md 中写清项目规则；
4. 是否将个人长期偏好与项目约束混为一谈；
5. 是否要求它执行了需要审批的高风险操作。

10. 总结

Codex 的核心价值不在于“更会聊天”，而在于它能够围绕代码库完成从分析到验证的完整任务闭环。这种能力决定了在使用前必须清晰理解其边界机制：Agent 决定它能执行任务；Sandbox 决定它能触及的范围；Approval 决定越界时是否询问；AGENTS.md 承载项目规则；Memory 承载个人偏好；Chronicle 则增强当前任务上下文。归根结底，边界越清晰，自动化执行就越可靠。