02 · Codex 核心概念：袋里、沙箱、审批和项目说明书

不少朋友刚接触 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 在当前项目里有足够的权限去工作，但不要让它随便触碰项目之外的东西。

常见的几种模式大致是这样的：

模式	白话理解	适合场景
read-only	只读为主，写文件通常需要额外确认	新项目分析、代码审查、理解架构
workspace-write	可以在当前工作区内自由读写	日常改代码、补测试、改文档
danger-full-access	权限很大，风险也很大	仅在隔离环境或你完全清楚后果时使用

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

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

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

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

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

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

可以这样区分：

• 沙箱
  决定“技术上能不能做”。

• 审批
  决定“做之前，要不要先问问你”。

拿生活里的例子来打比方：

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

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

在 Codex 里，常见的审批策略大致是这样的：

策略	白话理解	适合谁
untrusted	非常保守，很多操作都要先问	不熟悉项目、不熟悉命令的新手
on-request	在允许范围内自动执行，越界时问你	日常开发中最常用
never	尽量不问，自己跑到底	自动化任务或隔离环境，要慎重使用

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

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 更多是充当一个本地的“回忆层”，不应该被当作唯一的规则来源。

一句话总结：

。

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. 新手最稳妥的流程是：

   先只读分析 → 再确认计划 → 再做小范围修改 → 再验证 → 最后审查代码
   。

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