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

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. 最后给出变更说明。

可以把区别理解成：

类型	主要能力	典型交互
ChatGPT	回答、解释、生成片段	“这个函数怎么写？”
Codex	读代码、改文件、跑命令、验证结果	“这个测试挂了，帮我定位并修复。”

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

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

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

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

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

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

例如你输入：

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

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

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

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

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

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

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

沙箱模式	含义	适合场景
read-only	只能读取，不能写入	分析陌生项目、做代码审查
workspace-write	可以修改当前工作区内文件	日常开发、修复 bug、补测试
danger-full-access	权限非常大，基本不受工作区限制	临时可信环境，不建议常态使用

如果 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 不需要写得很长。重点是具体、可执行、可验证。

推荐写入：

内容	示例
构建命令	修改后运行 ./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 “不听话”，可以优先排查：

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

10. 总结

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

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

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

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