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

---

先从一个常见误会说起

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

你说：

代码语言：javascript

复制

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

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

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

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

代码语言：javascript

复制

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 里，你可以把它理解成：

普通聊天模型更像这样：

代码语言：javascript

复制

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

Codex 更像这样：

代码语言：javascript

复制

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

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

如果你问：

代码语言：javascript

复制

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

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

Codex 则可能会：

1. 找到失败的测试文件。2. 找到被测试的源码。3. 读取报错和断言。4. 修改相关代码。5. 运行测试。6. 如果测试没过，继续排查。7. 测试通过后，告诉你改了什么。

这就是 Agent 的核心：它不是只给答案，而是会沿着任务往前走。

不过这也意味着，你给它的任务不能太含糊。你说“优化一下项目”，它会很难判断该优化性能、结构、样式、测试，还是文档。你说“给登录失败补一个错误密码测试，并保持现有返回格式”，它就容易做对。

---

二、上下文：Codex 不是读心术

很多问题不是 Codex 不会，而是它缺上下文。

上下文就是 Codex 当前能看到、能用来判断的信息。常见上下文包括：

• 你发的任务描述• 当前项目文件• 报错日志• Git diff• README• AGENTS.md• 你在当前会话里补充过的说明• 可用工具返回的结果

这里有个重要提醒：

比如你说：

代码语言：javascript

复制

按我们项目规范补测试。

如果项目里没有 AGENTS.md，测试文件也很少，Codex 可能不知道“项目规范”到底是什么。它会根据常见习惯去猜，猜出来的东西不一定符合你的团队。

更好的说法是：

代码语言：javascript

复制

请先阅读 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	尽量不问，自己跑到底	自动化或隔离环境，慎用

新手建议先用保守组合：

代码语言：javascript

复制

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 不需要很长。比如：

代码语言：javascript

复制

# 项目说明这是一个 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。你不要只在当前会话里纠正它。你可以说：

代码语言：javascript

复制

请把“本项目测试命令是 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 和基础权限用好。• 处理敏感信息时，不要随便开启屏幕上下文能力。

---

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

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

你可以新建一个空目录：

代码语言：javascript

复制

mkdir -p ~/codex-democd ~/codex-democodex

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

接着对 Codex 说：

代码语言：javascript

复制

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

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

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

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

这个实验说明两件事：

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

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

代码语言：javascript

复制

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

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

---

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

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

代码语言：javascript

复制

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

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

代码语言：javascript

复制

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

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

---

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

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

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

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

---

参考资料说明

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

• Sandbox / sandboxing：沙箱与权限边界• Agent approvals & security：审批策略与安全机制• Config basics / config reference：配置文件与权限配置• AGENTS.md / custom instructions：项目说明文件• Memories：跨会话记忆• Chronicle：屏幕上下文相关记忆能力本文参与腾讯云自媒体同步曝光计划，分享自微信公众号。原始发表：2026-07-01，如有侵权请联系[email protected] 删除