很多朋友初次接触 Codex 时，可能都遇到过类似的情况：

你对它说：“请把桌面上的 notes.txt 也一并整理进来。”

结果呢？它只处理了当前项目里的文件，桌面上的文件毫无变化。

你的第一反应通常是——它是不是没理解？或者偷懒了？

但多数时候，真正的原因并非理解力不足，而是权限边界在起作用。Codex 并不是一个可以随意浏览你电脑所有文件的程序，它通常被限制在特定的工作范围内活动。这个范围就是所谓的“沙箱”。一旦它想要越界，必须先获得你的许可。

graph TD A[Agent 袋里] -->"在沙箱内执行| B[Sandbox 沙箱] B -->|超出边界时| C[Approval 审批] D[AGENTS.md] -->|开工前读取| A E[Memory / Chronicle] -->|跨会话复用| A B --> F[工作区文件] B --> G[外部资源
需审批] style A fill:#e3f2fd style B fill:#fff3e0 style C fill:#ffebee style D fill:#e8f5e9 style E fill:#f3e5f5

本章要讲解的核心，正是这些边界与规则：

• Agent：Codex 如何自主拆解步骤并执行指令？
• Sandbox：Codex 可以操作哪些内容，哪些区域属于禁区。
• Approval：在什么情况下它必须停下来等待你的确认。
• AGENTS.md：如何提前向 Codex 说明项目规范。
• Memory / Chronicle：哪些信息可以跨会话保留，哪些则不能依赖。

不必被这些概念吓到，本质上它们就像一套协作流程，而不是冷冰冰的术语堆砌。

一、Agent：不只是回答问题，更是推动任务执行

Agent 在 Codex 中可以被理解成一种能力——它不再是单纯的问答机器，而是会主动“动手干活”的帮手。

对比一下你就清楚了：

普通聊天模型是“你提出问题 → 它给出答案 → 对话结束”。

而 Codex 则是“你设定目标 → 它观察项目 → 它采取行动 → 它验证结果 → 如果不正确就继续调整”。

以一个代码任务为例：

如果你问：“为什么这个测试失败了？请修复它。”

普通 AI 可能会根据你贴出的报错信息猜测原因，然后提供一段修改建议。

但 Codex 可能会这样做：

1. 找到那个失败的测试文件。
2. 定位被测试的源代码。
3. 读取报错和断言内容。
4. 直接动手修改相关代码。
5. 重新运行测试。
6. 如果依然失败，继续排查。
7. 测试通过后，告知你修改了哪些地方以及如何修改的。

这就是 Agent 的核心——它不会只给出答案，而是沿着任务路线图一步步执行下去。

当然，这也意味着你给它的任务不能太模糊。如果你说“优化一下项目”，它会感到困惑，不清楚是要优化性能、代码结构、样式、测试覆盖率还是文档。但如果你说“为登录失败补一个密码错误的测试，并保持现有的返回格式”，它就能准确执行。

二、上下文：Codex 并非读心术

很多问题并非 Codex 不会，而是它缺少足够的上下文信息。

上下文，就是 Codex 当前可用来判断的所有信息。常见的信息来源包括：

• 你发出的任务描述
• 当前项目里的文件
• 报错日志
• Git 的差异对比（diff）
• README 文件
• AGENTS.md 文件
• 你在这个会话中补充的各种说明
• 工具返回的结果

这里有一条重要提醒：

比如说，“按照我们的项目规范补测试。”

如果项目里根本没有 AGENTS.md，测试文件也很少，Codex 可能完全不明白“项目规范”指的是什么。它只能凭常见习惯去猜测，而猜出来的结果未必符合你们团队的要求。

一个更好的说法是：“请先阅读 AGENTS.md 和 tests/ 目录中的现有测试。补测试时保持相同风格，不要新增测试框架。”

这样就清楚地指明了上下文的入口。

三、Sandbox：为 Codex 划定安全边界

Sandbox 就是沙箱。它决定了 Codex 在执行命令时，哪些事情可以做、哪些不行。

可以把它想象成发给临时同事的一张门禁卡：

• 只允许看资料，不能修改，这就是“只读”。
• 允许他在项目办公区内修改内容，这就是“工作区可写”。
• 把整栋楼的权限都给他，就是“完全访问”。

从安全角度出发，日常开发中最常见的思路是：让 Codex 在当前项目中有足够的权限进行工作，但不要让它随意触碰项目之外的内容。

常见的几种模式大致如下：

这里不必死记硬背配置名称。先记住判断方法：

• 如果你只是想让 Codex 查看项目，使用只读模式。
• 如果希望它修改当前项目，使用工作区可写模式。
• 如果它需要访问项目外的文件、联网、安装依赖，就需要更加谨慎。

还有一个细节值得注意：沙箱不仅影响 Codex 自身的文件操作，也会影响它调用的命令。换句话说，如果 Codex 执行 git、测试命令、包管理器，这些命令同样会受到沙箱边界的约束。

这也是为什么你偶尔会看到：命令本身看起来没问题，却被权限拦住了。不是命令坏了，而是它越界了。

四、Approval：它为何突然停下来问你？

Approval 是审批机制。它和沙箱的概念是两回事。

可以这样区分：

• 沙箱决定“技术上能不能做”。
• 审批决定“做之前，是否要先问一下你”。

拿生活中的例子来比喻：

沙箱就像办公室的门禁卡。你手里有什么卡，就能进哪些房间。

审批就像门口的多一道确认流程。普通会议室刷卡就能进；机房可能需要主管在系统里审批；财务室可能直接禁止进入。

在 Codex 中，常见的审批策略大致如下：

对于新手，建议先用一个比较保守的组合：

sandbox_mode = "workspace-write"
approval_policy = "on-request"

这套配置的意思是：项目内的常规工作可以放手去做，但一旦越界，就停下来问你。

一个更稳妥的流程是：

1. 新项目，先用只读模式分析。
2. 方案确认后，再切换到工作区可写模式。
3. 看到审批请求时，先仔细看看它要执行什么命令。
4. 如果不太懂，就拒绝，然后让 Codex 解释一下潜在风险。

审批弹窗不是故意打扰你，而是在帮你把控风险。

五、AGENTS.md：给 Codex 的“项目入职手册”

每个项目都有一些不成文的规矩，不会写在代码里：

• 使用 npm 还是 pnpm
• 测试命令是什么
• 哪些目录绝对不能动
• 提交代码前是否需要先跑 lint
• API 的返回格式有什么约定
• 单元测试应该放在哪个目录下

如果每次新开一个会话，都需要把这些规矩重新说一遍，不仅麻烦，还容易遗漏。

AGENTS.md 就是用来存放这些规则的。你可以把它看作 Codex 的“项目入职手册”。每次一开工，Codex 就会先读取这个文件，以了解在项目中应该如何开展工作。

一个初版 AGENTS.md 不需要写得很长。比如：

# 项目说明 这是一个 Node.js 后端项目。 ## 常用命令 - 安装依赖：`pnpm install` - 运行测试：`pnpm test` - 运行 lint：`pnpm lint` ## 修改规则 - 不要新增依赖，除非先说明理由。 - API 返回格式不要随意变更。 - 改完后优先跑相关测试。

编写 AGENTS.md 的关键不是“内容全面”，而是“真正有用”。

一条好规则通常是这样的：

• “测试使用 pnpm test。”
• “不要修改 fixtures/ 中的快照文件，除非任务明确要求。”
• “前端组件统一放在 src/components/。”

而差规则往往是这样的：

• “代码要优雅。”
• “注意质量。”
• “尽量写好一点。”

后面这些话，听着没错，但 Codex 难以执行，也难以验证。

把 AGENTS.md 当成一个反馈回路

AGENTS.md 最有价值的用法，就是把 Codex 反复犯过的错误沉淀下来。

比如，Codex 第一次把测试命令猜成了 npm test，但你的项目实际用的是 pnpm test。这时候，你不仅可以在当前会话里纠正它，还可以直接说：

“请把‘本项目测试命令是 pnpm test，不是 npm test’补充到 AGENTS.md。”

这样一来，下次再开新会话，它大概率就不会再犯同样的错误了。

这才是“项目越用越顺手”的关键所在。

六、Memory 和 Chronicle：记住偏好，但不能替代规则

除了 AGENTS.md，Codex 还具备一些与记忆相关的能力。对于新手来说，先搞清楚它们之间的区别就足够了。

Memory：记住稳定的偏好和历史经验

Memories 可以让 Codex 把一些有用的背景信息带到未来的会话中，比如：

• 你常用的技术栈
• 你喜欢的工作方式
• 某个项目里常见的坑
• 你反复强调过的偏好

但它并非万能。官方也强调过：团队必须遵守的硬性规则，仍然应该写在 AGENTS.md 或项目的其他文档里。Memory 更多是充当一个本地的“回忆层”，不应被视为唯一的规则来源。

一句话总结：Memory 管偏好，AGENTS.md 管规矩。

Chronicle：从屏幕上下文里生成记忆

Chronicle 更进一步，它能利用你最近屏幕上的内容，帮助 Codex 理解你正在做什么。比如，你正在查看某个 PR、某个文件、某段文档，它就能省去你重复解释的工夫。

但这类能力也更敏感。官方文档明确提醒过：Chronicle 目前仍是一个 opt-in research preview（可选的研究预览功能），只在特定平台和订阅条件下才可用，并且会更快消耗额度、增加提示注入（prompt injection）风险，同时还会在本机保存未加密的记忆数据。

给新手的建议是：

• 先别急着依赖 Chronicle。
• 先把 AGENTS.md 和基础权限配置用好。
• 涉及敏感信息时，不要随意开启屏幕上下文相关的功能。

七、一个小实验：亲手感受沙箱和审批

理解权限最好的方式，不是背概念，而是亲手做个小实验。

你可以新建一个空目录：

mkdir -p ~/codex-demo cd ~/codex-demo codex

接着，先切换到只读模式。不同客户端的操作入口可能不一样，CLI 里通常可以通过权限相关的菜单或命令来调整。

然后对 Codex 说：

“请创建一个 hello.txt，内容为 hello codex。”

如果当前是只读模式，它通常不会直接创建文件，而是会提示需要你的批准，或者告知权限不足。

然后，再切换到工作区可写模式，重复同样的请求。

这一次，它就应该能在当前目录中成功创建文件了。

这个实验主要说明两件事：

1. 同样一句话，在不同权限模式下，得到的结果完全不同。
2. Codex 没有“想不想做”的问题，它首先受权限边界的约束。

做完实验后，还可以让 Codex 自己来解释：

“请用新手能听懂的话解释一下：刚才为什么只读模式不能创建文件，而工作区可写模式就可以？”

这比死记硬背概念要管用得多。

八、新手最推荐的工作方式

如果你还没有形成自己的习惯，可以先试试这个流程：

flowchart LR A["只读分析"] --> B["确认计划"] B --> C["工作区内修改"] C --> D["运行相关验证"] D --> E["你审查 diff"] E --> F["接受或继续修改"]

把这个流程转化为提示词，可以这样跟 Codex 说：

“请先只读分析，不要修改文件。请告诉我：
1. 你需要查看哪些文件？
2. 你理解的任务目标是什么？
3. 你计划如何修改？
4. 哪些操作可能需要更高权限？
等我确认后，你再开始修改。”

这个提示词对新项目特别有用，也适合在你拿不准 Codex 会改动太多内容时使用。

九、这一章你真正需要记住什么？

不用一次性背下所有配置名称。先记住这几条核心原则：

1. Agent 是会主动推进任务的 Codex，而不只是回答问题。
2. 上下文 决定了它能否真正理解你的意图。
3. Sandbox 决定了它能触碰哪些领域。
4. Approval 决定了它什么时候必须停下来等你点头。
5. AGENTS.md 是存放项目规则的主要文件，比口头重复要可靠得多。
6. Memory 可以帮忙记住一些偏好，但不能替代项目的硬性规则。
7. 新手最稳妥的流程是：先只读分析 → 再确认计划 → 再做小范围修改 → 再验证 → 最后审查代码。

理解了这些概念之后，你再去看安装、配置、模型、权限这些细节，就不会觉得它们只是一堆零散的按钮了。本质上，它们都是在回答同一个问题：

如何让 Codex 在安全可控的范围内，帮助我们做更多有价值的事。