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

" 适合读者：已经知道 Codex 是“会动手的编程代理”，但还分不清 Agent、Sandbox、Approval、AGENTS.md、Memory 这些词的人。 本文目标：把这些概念讲成可以上手判断的东西。读完后，你应该知道：Codex 为什么会自己跑命令，为什么有时会停下来问你，为什么有些文件它不能改，以及项目规则应该写在哪里。 注：本文用的是入门视角。具体配置项、可用功能和权限策略会更新，实操前请以 OpenAI 官方文档为准。

先从一个常见误会说起

很多新手第一次用 Codex，会遇到类似场景：

你说：

帮我把桌面上的 notes.txt 也一起整理一下。

Codex 却只处理了当前项目里的文件，桌面文件没有动。

这时很容易误会它“没听懂”或者“偷懒”。但很多时候，真正原因不是理解问题，而是权限边界在起作用。

Codex 不是一个能随便碰你电脑所有文件的程序。它通常会在一个受限制的范围里工作。这个范围就叫沙箱。它如果想越过这个范围，就可能需要审批。

graph TD     A[Agent 代理] -->|在沙箱内执行| B[Sandbox 沙箱]     B -->|超出边界时| C[Approval 审批]     D[AGENTS.md] -->|开工前读取| A     E[Memory / Chronicle] -->|跨会话复用| A     B --> F[工作区文件]     B --> G[外部资源<br/>需审批]     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 里，你可以把它理解成：

" 一个能围绕目标持续工作的 AI 助手。

普通聊天模型更像这样：

你问一个问题 -> 它回答一段内容 -> 对话结束

Codex 更像这样：

你给一个目标 -> 它观察项目 -> 它采取行动 -> 它验证结果 -> 不对就继续调整

用代码任务举例更容易理解。

如果你问：

为什么这个测试失败了？请修一下。

一个普通 AI 可能会根据你贴出来的报错猜原因，然后给你一段建议。

Codex 则可能会：

1. 1. 找到失败的测试文件。
2. 2. 找到被测试的源码。
3. 3. 读取报错和断言。
4. 4. 修改相关代码。
5. 5. 运行测试。
6. 6. 如果测试没过，继续排查。
7. 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. 1. 新项目先只读分析。
2. 2. 确认方案后再给工作区写权限。
3. 3. 看到审批请求时，先看它要运行什么命令。
4. 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，只在特定平台和订阅条件下可用，并且会更快消耗额度、增加提示注入风险，还会在本机保存未加密的记忆数据。

新手建议是：

• • 先不要依赖 Chronicle。
• • 先把 AGENTS.md 和基础权限用好。
• • 处理敏感信息时，不要随便开启屏幕上下文能力。

七、一个小实验：亲眼看懂沙箱和审批

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

你可以新建一个空目录：

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

然后先切到只读模式。不同入口的界面不同，CLI 里通常可以通过权限相关菜单或命令调整。

接着对 Codex 说：

请创建一个 hello.txt，内容是 hello codex。

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

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

这次它就应该可以在当前目录里创建文件。

这个实验说明两件事：

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

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

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

这比只看概念更容易记住。

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

如果你还没形成习惯，可以先照这个流程走：

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

对应到提示词，可以这样写：

请先只读分析，不要修改文件。

请告诉我：
1. 你需要看哪些文件？
2. 你理解的任务目标是什么？
3. 你计划怎么改？
4. 哪些操作可能需要更高权限？

等我确认后，你再开始修改。

这个提示词适合新项目，也适合你不确定 Codex 会不会改太多的时候。

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

不用一次背下所有配置名。先记住这几条：

1. 1. Agent 是会推进任务的 Codex，不只是回答问题。
2. 2. 上下文决定它能不能理解你的真实意图。
3. 3. Sandbox 决定它能碰哪里。
4. 4. Approval 决定它什么时候停下来问你。
5. 5. AGENTS.md 是项目规则的主要落点，比口头重复可靠。
6. 6. Memory 可以帮忙记偏好，但不能替代项目硬规则。
7. 7. 新手最稳流程是：先只读，再计划，再小改，再验证，再 review。

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

" 怎样让 Codex 在足够安全的范围内，尽可能高效地帮你完成任务？

参考资料说明

本文参考 OpenAI Codex 官方文档中的以下主题整理：

• • Sandbox / sandboxing：沙箱与权限边界
• • Agent approvals & security：审批策略与安全机制
• • Config basics / config reference：配置文件与权限配置
• • AGENTS.md / custom instructions：项目说明文件
• • Memories：跨会话记忆
• • Chronicle：屏幕上下文相关记忆能力