02 · Codex 核心概念速览
代理、沙箱、审批、AGENTS.md 和记忆，到底分别管什么
📚 系列导航 上一篇〈01 · 认识 Codex 与四种入口〉，咱们弄清了 Codex 是什么，以及桌面端、CLI、IDE 扩展和云端入口分别适合什么场景。 这一篇再往里走一层，把后面会反复出现的几个核心概念一次捋顺。下一篇〈03 · 安装与登录〉再正式动手安装。
刚开始用 Codex 时，我干过一件挺蠢的事。
我在一个项目目录里启动 Codex，然后让它：
把项目里的文件和桌面上的两个文档一起整理一下。
它把项目里的东西改完了，桌面上的文件却纹丝不动。
我第一反应是：这玩意儿怎么干一半就停了？
后来才明白，不是它偷懒，而是沙箱把它拦住了。
Codex 默认不是想碰哪里就碰哪里。它能访问哪些文件、能不能联网、什么时候必须停下来问你，背后都有明确的权限规则。
所以在真正使用之前，你至少要认识五个概念：
- 代理：它为什么会自己执行任务；
- 沙箱：它能在哪里动手；
- 审批：什么时候需要你点头；
- AGENTS.md：怎么把项目规矩提前告诉它；
- 记忆：它能不能把以前学到的东西带到新会话里。
这几样东西一旦搞懂，Codex 很多看似“时灵时不灵”的行为，就都有解释了。
⚠️ 本文涉及的命令、权限名称和默认行为，按 OpenAI 当前官方文档整理。Codex 更新较快，实际界面和选项名称以你本机版本为准。
01 代理：它会自己动手，不只是回复你
先给结论：
代理，也就是 Agent，是能够围绕一个目标自行调用工具、观察结果并继续行动的 AI。
普通聊天机器人通常是一问一答：
- 你提出问题；
- 它生成答案；
- 对话暂时结束。
代理不一样。
你给它的不是一道单纯的问答题，而是一个需要完成的任务。它会在执行过程中不断重复下面这套循环：
理解 → 行动 → 检查 → 再行动
例如你告诉 Codex：
找出登录测试失败的原因，修复以后重新运行测试。
它可能会这样工作：
- 阅读测试文件；
- 执行测试命令；
- 查看错误信息；
- 搜索相关函数；
- 修改代码；
- 再次运行测试；
- 如果仍然失败，继续排查；
- 最后汇报修改结果。
这就是所谓的代理循环。
一个简单类比
普通聊天机器人像一个远程顾问。
你把问题告诉它，它给你分析和建议，但实际操作仍然要你自己完成。
Codex 更像一个会自己跑现场的技术人员。
你告诉它目标，它会查看环境、使用工具、执行操作、检查结果，遇到问题再调整方案。
Codex CLI 能够读取选定目录中的代码、修改文件并运行本机命令；官方也把它定位为可以检查、编辑和执行代码的编程代理。(OpenAI Help Center )
不过，“会自己行动”并不代表“想做什么都能做”。
它的行动范围，首先会被沙箱限制。
💡 一句话总结：
代理不是只会回答问题的聊天框，而是会围绕目标反复“理解、行动、检查”，直到完成任务或遇到权限边界。
02 沙箱：给 Codex 画一个能动手的圈
沙箱，英文叫 Sandbox。
它可以理解成一条技术边界：
Codex 在边界里面可以做什么，又不能越过边界碰什么。
沙箱主要限制两类能力：
- 能读取或修改哪些文件；
- 运行的命令能不能访问网络和其他系统资源。
类比：儿童乐园的围栏
你把孩子放进儿童乐园以后，围栏里面的滑梯、积木和海洋球，可以让他自己玩。
但他要翻出围栏跑到停车场，就必须被拦下来。
Codex 的沙箱就是这道围栏。
工作区以内的常规操作可以自动完成，工作区以外的文件、网络或者其他敏感资源，则会受到限制。
而且这道限制不只管 Codex 自己的文件操作。
如果 Codex 调用了：
- Git；
- npm、pnpm 或 pip；
- 测试程序；
- Shell 脚本；
- 编译器；
这些派生出来的命令同样运行在沙箱边界里，不会因为换了一个工具就绕过权限。(OpenAI Developers )
三种常见沙箱模式
| 沙箱模式 | 能做什么 | 适合什么场景 |
|---|---|---|
read-only |
可以查看文件；修改文件或执行相关命令通常需要申请权限 | 阅读代码、代码审查、分析问题、制定方案 |
workspace-write |
可以读取文件、修改当前工作区并运行常规本地命令 | 日常开发最常用 |
danger-full-access |
不再受到常规文件系统和网络沙箱限制 | 仅限完全可信、已隔离的环境 |
read-only：先看，别动
只读模式适合刚接触一个陌生项目时使用。
例如：
先分析这个项目为什么启动失败，只给出排查结论，不要修改文件。
Codex 可以阅读代码和配置，但遇到写文件、执行受限命令等操作时，不能直接悄悄完成。
workspace-write：在项目里自由干活
这是本地开发最常用的模式。
Codex 可以在当前工作区内：
- 创建文件；
- 修改代码；
- 执行测试；
- 运行常规开发命令。
但它想修改工作区之外的文件，或者让命令访问网络时，通常需要进一步获得许可。
官方当前推荐的自动模式，就是 workspace-write 配合 on-request 审批。对于受版本控制的目录，Codex通常会推荐这套组合；没有版本控制的目录，则可能先以只读模式启动。(OpenAI Developers )
danger-full-access：把围栏拆掉
这个名字里的 danger 不是装饰。
启用后，Codex 不再受到常规沙箱边界限制，可以接触更大范围的文件和网络资源。
这不代表它一定会做危险操作，但意味着：
阻止它做危险操作的技术围栏已经被你拆掉了。
因此，只应该在下面这类环境中考虑使用：
- 临时虚拟机；
- 容器；
- 专门创建的测试环境；
- 没有重要数据和凭据的隔离机器。
不要因为嫌审批弹窗麻烦，就在自己的主力电脑和整个用户目录里长期打开完全访问。
不同系统怎样实现沙箱
沙箱背后的实现会随操作系统不同而变化：
| 平台 | 主要实现 |
|---|---|
| macOS | 系统自带的 Seatbelt |
| Windows 原生环境 | Windows 本机沙箱机制 |
| Linux | bubblewrap 与 seccomp |
| WSL2 | 使用 Linux 沙箱实现 |
macOS 通常开箱即可使用。Windows 在 PowerShell 中使用原生实现，在 WSL2 中则按照 Linux 方式工作。
Linux 和 WSL2 用户目前建议先通过包管理器安装 bubblewrap。Codex缺少 bwrap 时可能尝试备用实现，但系统不支持相关用户命名空间时会出现警告或无法正常启用沙箱。(OpenAI Developers )
💡 一句话总结：
沙箱决定 Codex 在技术上能碰什么——默认让它在工作区里干活，出了这个圈就会受到限制。
03 审批：到了边界，要不要先问你
沙箱和审批经常被人混为一谈，但它们其实是两个不同的开关。
- 沙箱管“能不能”；
- 审批管“什么时候问你”。
类比：门禁和保安
沙箱像一扇门禁。
它从技术上决定哪些区域能进去，哪些区域进不去。
审批策略像站在门口的保安。
它决定遇到跨界请求时：
- 直接放行；
- 停下来问你；
- 还是不再弹窗，但仍然按照现有边界执行。
官方也明确把安全控制分成两层：沙箱模式决定命令能够访问的文件和网络资源，审批策略决定 Codex 在执行某类动作之前是否必须暂停并请求许可。(OpenAI Developers )
三种常见审批策略
| 审批策略 | Codex 的行为 | 大白话 |
|---|---|---|
untrusted |
已知安全的读取操作可以直接执行，其他命令先询问 | 陌生或有副作用的命令先问 |
on-request |
默认在沙箱内工作，需要越过边界时申请权限 | 日常最平衡 |
never |
不弹出审批请求，在当前沙箱范围内尽力完成 | 不问你，但不会自动突破沙箱 |
最后一行特别容易理解错。
never 不等于完全访问
never 只表示：
不要弹出审批窗口。
它并不表示：
自动授予所有权限。
例如你使用：
approval_policy = "never"
sandbox_mode = "read-only"
Codex 仍然只能读取文件。
它不能修改文件，也不会停下来问你要不要放行，只会在只读边界内尽力完成任务，或者告诉你任务无法继续。
因此：
never控制的是“问不问”；danger-full-access控制的是“有没有沙箱边界”。
两者不是一回事。(OpenAI Developers )
两套最常见的组合
日常开发：推荐
sandbox_mode = "workspace-write"
approval_policy = "on-request"
效果是：
- 工作区内可以正常读写和运行常规命令；
- 想访问工作区外的文件或网络时，再停下来询问。
这套组合安全性和使用体验比较平衡。
只读分析
sandbox_mode = "read-only"
approval_policy = "on-request"
适合：
- 陌生项目；
- 代码审查；
- 只想让它分析、不想让它立刻修改；
- 先看方案，再决定是否开放写权限。
完全放开：慎用
sandbox_mode = "danger-full-access"
approval_policy = "never"
这相当于：
- 沙箱围栏被拆掉；
- 审批弹窗也被关闭。
官方还提供了跳过审批与沙箱的危险参数，并明确不推荐在普通环境使用。(OpenAI Developers )
日常操作不需要手写配置文件。
在 Codex CLI 中输入：
/permissions
就可以打开权限选择器。
桌面端和 IDE 扩展里，一般也能在输入框附近找到权限控制。当前权限、沙箱范围和工作目录，则可以通过：
/status
查看。(OpenAI Help Center )
💡 一句话总结：
沙箱决定“能不能越界”，审批决定“越界前问不问”；日常使用优先选择 workspace-write + on-request。
04 AGENTS.md：给 Codex 的项目入职手册
权限解决的是“它能不能做”。
接下来还有一个问题：
怎么让它知道这个项目应该怎么做？
例如你的项目可能有这些规矩：
- 安装依赖必须使用 pnpm；
- 修改代码后必须运行 lint；
- 测试命令是
pytest -q； - 接口返回值不能随便改变；
- 新组件必须放在指定目录；
- 不允许新增生产依赖。
你当然可以每次开新会话都重新说一遍。
但更好的方法，是把这些规则写进：
AGENTS.md
Codex 会在开始工作前读取相关的 AGENTS.md，把里面的内容作为项目指引。(OpenAI Developers )
类比：新员工入职手册
一个新人第一天进公司，你不会每天重复告诉他：
我们用 pnpm，不用 npm。 提交前必须跑测试。 数据库迁移不能直接改旧文件。
更合理的做法，是给他一份入职手册。
AGENTS.md 就是 Codex 的入职手册。
一个最小示例
在项目根目录创建：
# AGENTS.md
## 项目约定
- 安装依赖统一使用 pnpm。
- 修改 TypeScript 文件后运行 pnpm lint。
- 修改业务逻辑时补充对应测试。
- 不要在未经确认的情况下新增生产依赖。
- 完成任务后总结修改文件和测试结果。
以后 Codex 进入这个项目时，就会先读这些规则。
全局规则和项目规则
Codex 可以读取不同层级的指引。
| 层级 | 常见位置 | 适合放什么 |
|---|---|---|
| 全局 | ~/.codex/AGENTS.md |
你个人长期不变的工作习惯 |
| 项目 | 仓库根目录的 AGENTS.md |
整个项目共同遵守的规则 |
| 子目录 | 子目录中的 AGENTS.md 或 AGENTS.override.md |
某个模块的特殊要求 |
Codex 会从全局配置开始，再从项目根目录一路读取到当前工作目录。
越靠近当前目录的指引，优先级越高。
如果某个目录里存在 AGENTS.override.md，它会优先使用覆盖文件。官方默认还会限制合并后的指引大小，因此不要把 AGENTS.md 写成一本几万字的项目百科。(OpenAI Developers )
最好用的技巧：让错误变成规则
假设 Codex 总是使用 npm，但你的项目要求 pnpm。
不要只在当前会话里说：
你用错了，改成 pnpm。
因为这句话可能只对当前对话有效。
更好的处理方式是：
把“本项目只能使用 pnpm”补充到 AGENTS.md。
以后新会话再次进入项目，这条纠正仍然存在。
官方最佳实践也建议：当 Codex 重复犯同一种错误时，让它复盘并更新 AGENTS.md。(OpenAI Developers )
不过要保持克制。
适合写进 AGENTS.md 的，是稳定、明确、需要长期遵守的规则。
不适合写进去的，是：
- 当前任务的一次性需求；
- 一大段历史聊天记录；
- 已经过期的临时方案；
- 可以直接从代码看出来的废话。
💡 一句话总结：
AGENTS.md 是 Codex 的项目入职手册：稳定规矩写进去，犯过的重复错误也写进去，让它下次少踩同一个坑。
05 记忆：它能不能记住以前的事
AGENTS.md 是你主动写下的明确规则。
记忆，也就是 Memories，则是 Codex 从过去的工作中提取并保留的有用上下文。
例如：
- 你常用的技术栈；
- 稳定的个人偏好；
- 某个项目经常踩到的坑；
- 之前任务中形成的背景信息；
- 你常用的工具和工作方式。
类比：从新人变成老搭档
刚来的同事，每次都要重新告诉他：
这个项目用 TypeScript。 测试跑这一条命令。 我喜欢先给方案，再改代码。
合作久了以后，他会逐渐记住你的习惯。
Codex 的记忆，就是尝试把这种跨会话的熟悉感保存下来。
本地 Codex 记忆的几个关键事实
1. 默认关闭
本地 Codex 记忆目前默认不会自动启用。
在桌面端可以进入个性化设置打开，也可以在 config.toml 中加入：
[features]
memories = true
2. 不会立即生成
一个会话结束后，Codex 不一定马上产生记忆。
它会等待会话闲置一段时间，避免你还没完成任务时就过早总结。短暂会话、仍在进行的会话或者不符合条件的内容，也可能被跳过。(OpenAI Developers )
3. 保存在本地
本地 Codex 的主要记忆文件默认存放在：
~/.codex/memories/
这些文件属于自动生成的状态信息，可以在排查问题时查看，但不建议把手工修改这些文件当成主要管理方式。(OpenAI Developers )
4. 可以按会话控制
在 Codex CLI 或桌面端会话中输入：
/memories
可以控制当前会话：
- 能不能读取已有记忆；
- 能不能被用于生成以后的记忆。
会话级设置不会改变全局开关。(OpenAI Developers )
记忆不能代替 AGENTS.md
这一点一定要记住。
假设你的团队有一条铁规矩：
修改支付模块后必须运行完整支付测试。
这条规则不能只寄希望于记忆。
因为记忆是一层辅助召回机制，不保证每条内容在每次任务中都以同样方式出现。
真正必须稳定执行的规则，应该写在：
AGENTS.md；- 仓库文档；
- 测试脚本；
- CI 检查；
- 团队规则配置中。
OpenAI 官方也明确建议：必须始终生效的团队指引应放在 AGENTS.md 或受版本控制的文档里，记忆只作为辅助回忆层。(OpenAI Developers )
💡 一句话总结：
记忆负责让 Codex 更像熟悉你的老搭档，但重要规则仍然必须写进 AGENTS.md，不能只靠它“想起来”。
06 Chronicle：让记忆参考最近的屏幕内容
Chronicle 可以理解成记忆系统的屏幕上下文增强功能。
普通记忆主要从过去的会话中提取信息。
Chronicle 则会参考近期屏幕内容，帮助 Codex 理解你最近在做什么，减少你重复解释背景的次数。
例如你刚刚一直在查看：
- 某个报错页面；
- 一个 Pull Request；
- 一份需求文档；
- 某个设计稿；
- 一套内部工具。
之后你对 Codex 说：
帮我继续处理刚才那个问题。
Chronicle 生成的记忆可能帮助它更快判断，你说的“刚才那个问题”指向什么。
但它目前仍是实验功能
Chronicle 当前是需要主动开启的研究预览功能，仅面向 macOS 上符合条件的 ChatGPT Pro 用户。
启用时需要授予 macOS：
- 屏幕录制权限；
- 辅助功能权限。
官方同时明确提醒了几个风险：
- 会较快消耗 Codex 使用额度；
- 屏幕内容可能增加提示词注入风险；
- 生成的记忆以未加密文件形式保存在本机。
因此，不要在显示密码、客户数据、私人聊天、密钥或其他敏感内容时毫无防备地开启。(OpenAI Developers )
| 维度 | Memories | Chronicle |
|---|---|---|
| 主要信息来源 | 以前的会话 | 最近的屏幕上下文 |
| 作用 | 跨会话保留有用信息 | 帮助理解你最近在做什么 |
| 默认状态 | 本地功能默认关闭 | 必须主动开启 |
| 当前成熟度 | 常规可选功能 | 研究预览 |
| 使用建议 | 可按需开启 | 敏感场景谨慎使用 |
💡 一句话总结：
Memory 从过去的会话中积累经验，Chronicle 再给它补充屏幕上下文；后者更方便，但隐私和提示注入风险也更高。
07 五个概念怎么串在一起
现在把整篇内容串起来看。
中间的主角：代理
代理负责：
- 理解任务；
- 读取信息；
- 调用工具；
- 执行动作；
- 检查结果。
外面的围栏：沙箱
沙箱决定：
- 哪些文件能读；
- 哪些文件能改；
- 命令能不能联网；
- 能访问多大的系统范围。
围栏边的门卫：审批
审批决定：
- 哪些操作直接执行；
- 哪些操作必须停下来问你；
- 是否完全不弹审批。
开工前的说明书：AGENTS.md
它告诉代理：
- 项目怎么启动；
- 测试怎么运行；
- 代码应该怎么写；
- 哪些规矩不能违反。
跨会话的经验：记忆和 Chronicle
它们负责：
- 带回以前的有用上下文；
- 减少重复解释；
- 帮助 Codex 更熟悉你的工作方式。
可以把它们记成一句话：
代理负责干活，沙箱负责画圈，审批负责点头，AGENTS.md 负责立规矩，记忆负责攒经验。
08 小结
这一篇把后面会反复出现的核心概念铺平了。
| 概念 | 一句话记住 |
|---|---|
| 代理 | 会围绕目标反复理解、行动和检查 |
| 沙箱 | 决定它在技术上能访问哪些文件和资源 |
| 审批 | 决定执行某些动作前是否需要问你 |
| AGENTS.md | 项目入职手册，保存稳定规则 |
| 记忆 | 把过去工作中的有用上下文带到新会话 |
| Chronicle | 用近期屏幕上下文增强记忆的实验功能 |
现在你应该能够解释几个常见现象：
为什么 Codex 不肯修改某个文件
文件可能不在当前工作区内，或者当前处于只读模式。
为什么它突然停下来问我
接下来的操作可能要越过沙箱边界，而审批策略要求先征得你的许可。
为什么它下次又忘了我的项目规矩
你可能只在聊天里临时告诉过它，却没有把稳定规则写进 AGENTS.md。
为什么开启记忆后没有立刻生效
本地记忆在后台生成，不一定会在会话刚结束时马上更新。
这一篇最该带走的一句话是：
Codex 不是一个没有边界的许愿池，而是一个戴着安全护栏、能够主动干活的搭档。
你负责给目标、定规则和做判断。
沙箱负责限制范围，审批负责守住边界，AGENTS.md 负责告诉它项目规矩，记忆负责让合作逐渐变顺。
把这套地基搞懂以后，后面的安装、配置、Skills、MCP、自动化和多代理工作流，才不会越学越乱。
下一篇〈03 · 安装与登录〉，咱们正式把 Codex 装到 macOS、Windows 和 Linux 上，完成登录，并跑通第一个本地任务。