02 · Codex 核心概念速览
📚 系列导航：上一篇 01 · 认识 Codex 与四种入口 带你认全了 Codex 的四张脸——桌面 App、命令行、IDE 扩展、云端。这一篇往里走一层，把后面所有章节都要反复用到的几个核心概念，一次性讲透。下一篇 03 · 安装与登录 再正式动手装。
先说个之前我自己干的蠢事，刚开始用 Codex 那会儿，张口就问它「帮我把这三个文件批量重命名」，它噼里啪啦改完，一看傻眼了——它只动了当前项目目录里的，桌面上那两个纹丝没动。我当时还纳闷：不是说能跑命令吗，咋还挑食？后来翻文档才反应过来：那是**沙箱（Sandbox）**在拦着，它默认只能在你指定的工作区里动手，出了这个圈得先问你。
那一刻我才明白：用 Codex 之前不搞懂这几个概念，你会一直觉得它「时灵时不灵」——其实它一点没乱，是你不知道它头上戴着几道紧箍咒。
这一篇就把这几道紧箍咒、外加它的几样独门配置，掰开揉碎讲清楚。
看完这一篇，你会拿到：
- 一句话讲明白 Codex 的「代理（Agent）」是什么，以及它和聊天机器人差在哪
- 彻底搞懂沙箱和审批这对兄弟——为什么我那次重命名会失败，以及怎么放开它
- 认识
AGENTS.md：让 Codex 记住你项目规矩的那张「入职手册」 - 知道**记忆（Memory）**和 Chronicle 是什么、默认开没开、能不能用
- 一个能照着跑的小实验，亲眼看清沙箱拦你那一下
⚠️ 下文凡涉及具体命令、配置项、默认行为，都以 Codex 官方文档 为准；模型名、套餐这类会随版本变的东西，看到时以你本地实际显示为准。
01 代理（Agent）：它会自己动手，不只是回你话
先说结论，一句话：Codex 是 OpenAI 的「编程代理（coding agent）」，能自己读代码、改文件、跑命令，而不只是给你回一段文字。 官方原话就是 "OpenAI's coding agent that can read, edit, and run code"。
这里的「代理（Agent）」是关键词，第一次见得解释一句：代理 = 能自己拆解任务、调工具、看结果、再决定下一步的 AI，不是一问一答的聊天框。
官方描述 Codex 干活的方式是这么一句：「代理在一个循环里跑终端命令，它改代码、跑检查、尝试验证自己的工作」（原文：The agent runs terminal commands in a loop. It edits code, runs checks, and tries to validate its work）。
翻译成大白话，还是那三个动作——想 → 做 → 看：
- 想：读相关文件、看报错、搞清楚状况
- 做：改代码、建文件、跑命令
- 看：跑测试、看输出，不对就回头再来一轮
类比：一个肯自己跑腿的代购。 普通聊天机器人像个只会查价格的客服——你问它「这件衣服多少钱」，它告诉你，完事。Codex 像个代购：你说「帮我买件均码的黑卫衣」，它自己去翻货、比价、下单、收到货还拆开检查尺码对不对，不对再退换。「自己跑完整个流程」才是代理和聊天框的本质区别。
几个你真会遇到的场景：
- 你说「这个测试为啥挂了」，它自己跑测试 → 读报错 → 找到 bug → 改 → 再跑一遍确认，全程你就看着。
- 你扔给它一个没文档的老项目说「理一下结构」，它自己
ls、自己搜关键字、读一堆文件，最后给你画张图——你一个文件都没指定。 - 你说「把这个函数加上缓存」，它改完顺手把相关调用处也一起捋了，因为它能跨文件看全局。
💡 一句话总结：Codex 是「代理」不是「聊天框」——它在「想→做→看」的循环里自己把活干完，这套机制和 Claude Code 一模一样，换了个壳而已。
02 沙箱（Sandbox）：它动手的圈，画在哪
来了，重点。开头我那次重命名失败，罪魁祸首就是它。
沙箱（Sandbox）：官方定义是「让 Codex 能自主行动、又不至于对你整台机器有无限权限的那道边界（boundary）」。说白了，它就是给 Codex 画的一个圈——圈内的事它自己干，要出圈，先问你。
类比：商场里的儿童乐园。 你把娃放进围栏，里头的滑梯海洋球随便玩，你不用每个动作都盯着；但娃想翻出围栏跑到停车场，警报就响了，得你点头。沙箱就是这个围栏：圈内自由活动免打扰，出圈才拦你——既省得你一惊一乍，又不怕它闯祸。
这道围栏管两样东西：它能改哪些文件、能不能联网。官方给了三种常见的沙箱模式：
| 沙箱模式 | 能改文件吗 | 能联网吗 | 啥时候用 |
|---|---|---|---|
read-only（只读） | ❌ 不能（要改得先批） | ❌ | 只想让它读代码、做审查、出方案，别动我东西 |
workspace-write（工作区可写） | ✅ 仅限工作区内 | ❌ 默认不行 | 日常开发最常用；版本控制目录下 Codex 默认推荐这个，非版本控制目录默认 read-only |
danger-full-access（完全访问） | ✅ 全机器 | ✅ | 完全信任的环境，名字带 danger 不是吓你的，慎用 |
看到 workspace-write 那行「仅限工作区内」没有？这就是我桌面文件没被改的原因——它们不在我启动 Codex 的那个项目目录里，压根不在围栏内。不是 Codex 偷懒，是它真的够不着。
还有个细节官方特意强调了：沙箱不只管 Codex 自己的读写，它派生出去的命令也一样受限。也就是说，哪怕它调用 git、包管理器、测试脚本，这些命令也都被关在同一个圈里——不会有「主进程被关着、子命令却越狱」的漏子。
平台上各有各的实现，这点你装的时候会碰到（细节留到 03 安装与登录 讲）：
- macOS：用系统自带的 Seatbelt 框架，开箱即用，啥都不用配。
- Windows：直接在 Windows 原生环境运行，用原生 Windows 沙箱（分
elevated和unelevated两种模式）；用 WSL2 则走 Linux 那套实现。 - Linux / WSL2：得先自己装一个叫
bubblewrap的东西，沙箱才正常工作（这是官方明确要求的前置条件）。
💡 一句话总结：沙箱是 Codex 头上的第一道紧箍咒——默认（
workspace-write）只让它在你的工作区里改文件、还不许联网；想让它管更宽，得自己把圈画大。
03 审批（Approval）：到了围栏边，谁来点头
沙箱画好了圈，那「出圈的时候找谁批」——这是另一码事，叫审批（Approval）。
很多人（包括当初的我）会把这俩搞混，官方专门点了一句，值得记住：沙箱定义的是技术边界，审批策略决定的是 Codex 何时必须停下来、跨界之前先问你。
类比：门禁卡 + 保安。 沙箱是那道门禁（物理上拦着你出不去），审批是门口那个保安的脾气——有的保安见谁都放（never），有的只拦陌生人（untrusted），有的是你想出门就喊一嗓子问一下（on-request）。门是死的，保安的松紧是你能调的。
官方给的三种常见审批策略：
| 审批策略 | Codex 的行为 | 大白话 |
|---|---|---|
untrusted | 不在「可信集合」里的命令，跑之前先问 | 只防陌生命令 |
on-request | 默认在沙箱里干，需要出圈时才停下来问 | 最常用的平衡档 |
never | 不弹审批，闷头干 | 全自动，配合完全访问才有意义 |
注意：这里的 untrusted / on-request / never 是官方文档里的三种审批策略——它们和沙箱模式是两个独立的维度，分开配置、分开理解。
这俩怎么搭？官方给了两个现成组合，记这两个就够用：
- 低风险本地自动化（推荐日常）：
sandbox_mode = "workspace-write"配approval_policy = "on-request"。围栏锁着、出圈才问，安全又不烦。 - 完全放开（慎用）：
sandbox_mode = "danger-full-access"配approval_policy = "never"。等于把门拆了、保安也放假——只在你 100% 信任的环境用。
我自己的习惯是：新项目、不熟的代码库，一律先 read-only 让它只读只分析，等我看完它的方案、心里有底了，再切到 workspace-write 放它动手。有次我图省事直接上 danger-full-access 跑一个批量脚本，它在我半个 home 目录里翻文件，看得我手心冒汗——从那以后我再没在不该用的地方开过完全访问。
怎么切？日常你不用碰配置文件，在 CLI 会话里一句 /permissions 就能当场换模式（桌面 App 和 IDE 里则是输入框旁边的权限选择器）。想让它每次启动都用同一套，再去写配置文件——那是 18 config.toml 配置详解 的活，这里先知道有这么个开关。
下面这张图把沙箱和审批的关系理一遍：
这张图在干什么：它说清了一件事——Codex 每要做一步，先看「在不在沙箱圈内」（沙箱说了算），出圈了再看「要不要问你」（审批说了算）。两道关卡，各管各的。
💡 一句话总结：沙箱管「能不能」、审批管「问不问」，两个旋钮分开拧；日常
workspace-write+on-request这套组合，安全和省心兼顾。
04 AGENTS.md：给 Codex 的项目入职手册
前三节讲的是「权限」。这一节换个话题：怎么让 Codex 记住你这个项目的规矩，省得每次都得重新交代一遍。
答案是一个叫 AGENTS.md 的文件。
类比：给新员工的入职手册。 新人来公司，你不会每天追在屁股后面念叨「咱们用 pnpm 不用 npm」「提交信息要写中文」——你给他一本手册，他自己看。AGENTS.md 就是给 Codex 的这本手册：放进项目里，它每次开工前先读，按里头的规矩办。
官方对它的定位是「durable project guidance」——跟着仓库走、在代理开始干活之前就生效的持久指引。一句话嘱咐：保持精简（Keep it small），别把它写成长篇大论。
里头通常写这些（官方给的例子）：
- 构建和测试命令（比如「测试用
pytest -q」） - 代码审查的期望（比如「改完必须跑 lint」）
- 这个仓库特有的约定（比如目录怎么放、命名怎么取）
它能放在两个层级，离工作目录越近的越优先（这点和优先级判断很关键）：
| 层级 | 放哪 | 管谁 |
|---|---|---|
| 全局 | ~/.codex/AGENTS.md | 你这个人的偏好（比如「回我话简洁点」），跨所有项目生效 |
| 项目 | 仓库根目录或子目录里的 AGENTS.md | 这个项目 / 团队的规矩，可以提交进 Git 全队共享 |
最妙的用法官方点了出来，我自己也最爱用——把它当反馈回路（feedback loop）：当 Codex 对你的代码库做了错误假设，你别光在对话里纠正（那是一次性的，下次它又忘），直接让它把这条修正写进 AGENTS.md，下回开新会话它自己就继承了。我给一个 Python 项目调了两周，AGENTS.md 从空白长到二十来行，全是它踩过、被我逮住、然后自己记下来的坑——现在新会话基本不犯重复错误了。
AGENTS.md之于 Codex，约等于CLAUDE.md之于 Claude Code——同一个概念，换了个文件名。
💡 一句话总结：
AGENTS.md是 Codex 的项目入职手册——写下你项目的规矩，它每次开工先读；把它当反馈回路，犯一次错就记一条，越用越顺手。
05 记忆（Memory）与 Chronicle：它能不能「记住」你
最后这组概念，是 Codex 比较新、也容易让人误会的地方——它到底能不能记住你之前聊过的东西？
先把两个词分清楚：
记忆（Memory）：让 Codex 把早先会话里学到的有用信息带到后面的工作里——比如你的技术栈、项目惯例、踩过的坑，省得每开一个会话都重新交代。
类比：一个跟久了的老搭档。 新来的助理你得反复教「我们用 TypeScript、不写分号」；跟你三年的老搭档，你一个眼神他就懂——因为他记着你的习惯。Memory 就是把 Codex 从「新来的」往「老搭档」上带。
但有几个关键的事实你必须知道，不然又会觉得它「时灵时不灵」：
- 默认是关的（off by default）。 不主动开，它不会记任何东西。开的方式：在 Codex App 设置里打开，或在
~/.codex/config.toml的[features]段里写memories = true。 - 有地区限制。 官方明说：发布时欧洲经济区、英国、瑞士暂不可用。
- 不是实时更新的。 它会等一个会话「闲置足够久」、确认你不是还在干活，才在后台悄悄总结成记忆——所以你刚结束会话，记忆可能还没写进去。
- 存在本地：默认放在
~/.codex/memories/下，是一堆生成的 markdown 文件。 - 能逐会话控制：在 App 和 CLI 里用
/memories决定「当前这个会话要不要用已有记忆、要不要拿来生成新记忆」。
官方还补了句要紧的：真正必须每次都生效的团队规矩，老老实实写进 AGENTS.md，别指望记忆——记忆是「锦上添花的本地回忆层」，不是规则的唯一来源。这话我深有体会：记忆这东西是概率性的，靠它兜底重要规矩，迟早翻车。
💡 一句话总结：记忆是「老搭档」模式，但默认关着、有地区限制——重要规矩还是靠
AGENTS.md，记忆只管锦上添花的部分。
再说 Chronicle，开头先标清楚：
⚠️ 实验性，可能变化。 Chronicle 目前是「需主动开启的研究预览（opt-in research preview）」，只对 ChatGPT Pro 用户、且只在 macOS 上可用，欧盟、英国、瑞士同样还没有。
Chronicle 是给记忆「喂屏幕」的。 普通记忆是从你和 Codex 的对话里学；Chronicle 更进一步，用你屏幕上的内容帮 Codex 理解你最近在忙啥——你正看着哪个文件、哪个 PR、哪个文档，它能顺着接上，省得你从头解释。
类比：一个能看你屏幕的搭档。 普通搭档只能听你说；Chronicle 这个搭档还能瞟一眼你的显示器，「哦你在看这个报错」，于是不用你复述。听着很爽，但代价也实在——官方明明白白警告了三条：吃配额很快、会增加提示注入（prompt injection）的风险、记忆是不加密地存在你本地的。换句话说，方便和风险都摆在台面上，自己掂量。我个人态度：尝鲜可以，敏感屏幕内容（密码、私信、客户数据）面前，记得用菜单栏的「Pause Chronicle」暂停它。
| 维度 | 记忆（Memory） | Chronicle |
|---|---|---|
| 信息从哪来 | 之前的对话会话 | 你的屏幕内容 |
| 成熟度 | 正式功能（默认关） | 研究预览（实验性） |
| 平台 | 跟随 App / CLI | 仅 macOS、仅 Pro |
| 我的建议 | 想省事可以开 | 尝鲜可以，敏感场景记得暂停 |
💡 一句话总结：记忆让 Codex 从「新人」变「老搭档」，但默认关着、有地区限制、还别拿它替代
AGENTS.md；Chronicle 是实验性的「看屏幕」增强，方便但风险也明摆着。
五个概念单独讲完了，在进入动手环节之前，用一张图把它们串起来看一眼——单独理解每个概念容易，但它们怎么协作才是关键：
这张图在干什么：中间那个「代理」是主角，它被关在「沙箱」这个圈里干活；想出圈到外部世界（你整台机器、网络），得先过「审批」这道关卡；左边的 AGENTS.md 在它开工前把项目规矩喂进去；下边的「记忆 / Chronicle」则跨会话帮它攒经验、下次复用——五个概念全是围着中间这个代理转的。
06 动手：亲眼看沙箱拦你那一下
光读概念记不住。跑个一分钟的小实验，亲眼看沙箱在 read-only 模式下怎么拦住一次写操作——这是这一篇最该有体感的地方。实验不依赖任何现成项目，新建个空文件夹就行。
第一步：建个空目录，进去启动 Codex。
在终端里跑（Mac / Linux；Windows 用 PowerShell，把 mkdir -p 换成 mkdir）：
bash
mkdir -p ~/codex-demo && cd ~/codex-demo
codex还没装 Codex？没关系，这一篇先建立概念，03 安装与登录 会手把手带你装好再回来跑。
第二步：切到只读模式。
在 Codex 会话里输入斜杠命令，把权限调到只读：
text
/permissions然后在弹出的选项里选只读那一档（Read Only / read-only）。预期看到：界面提示当前进入只读模式，类似——
text
Permissions updated: read-only第三步：让它干一件「要写文件」的事，看它被拦。
丢这么一句给它：
text
帮我新建一个文件 hello.txt，里面写一行字 "hello codex"。预期看到：它不会默默把文件建好，而是停下来请求你的批准——因为「写文件」这一步突破了 read-only 的边界，按审批策略它必须先问你。大意是：
text
我需要创建文件 hello.txt，这超出了当前只读模式的权限，
是否允许？(y/n)看到这个「停下来问」的瞬间，你就亲眼见到沙箱 + 审批联手干活了：沙箱判定「这步要出圈」，审批接着弹出来找你点头。这正是第 02、03 节讲的两道关卡，在屏幕上活生生跑了一遍。
第四步：对比一下放开后的样子。
回 /permissions 切到工作区可写（workspace-write），再让它建一次 hello.txt。这回预期它直接建好、不再问你——因为在工作区里写文件本就在沙箱圈内，无需审批。
text
已创建 hello.txt跑完用 /status 看一眼当前会话的模型、审批策略这些信息，心里就更有数了：
text
/status同一个建文件的请求，只读时被拦、可写时放行——这就是沙箱模式实打实的区别。比起读十遍「沙箱是安全边界」，亲眼看它在只读模式下停下来问你那一下，理解得快得多。
💡 一句话总结：跑一遍这个最小实验，你会亲眼看到——同一个写文件请求，
read-only拦下来问、workspace-write直接放行，沙箱和审批就是这么联手的。
07 小结
这一篇把 Codex 后面所有章节都要用到的核心概念，一次铺平了：
| 概念 | 一句话记住 | 对应 Claude Code 的啥 |
|---|---|---|
| 代理（Agent） | 会自己想→做→看的 AI，不是聊天框 | 代理循环，一模一样 |
| 沙箱（Sandbox） | 给它画的圈，管「能改哪、能不能联网」 | 类似权限边界，但更显式 |
| 审批（Approval） | 出圈时问不问你，和沙箱是两个旋钮 | 类似权限模式 |
| AGENTS.md | 项目入职手册，写下规矩它每次先读 | 就是 CLAUDE.md 换名 |
| 记忆 / Chronicle | 让它记住你的偏好；Chronicle 看屏幕、实验性 | 类似 memory，Chronicle 是新东西 |
你现在应该能看懂：为什么 Codex 有时「不肯」改某个文件（不在沙箱圈内）、为什么它会突然停下来问你（要出圈、审批拦着）、以及怎么用 AGENTS.md 让它记住你的规矩、用 /permissions 当场调松紧。
最该带走的一句话：Codex 不是个许愿池，而是个戴着紧箍咒的能干搭档——你的活儿是给方向、画好它能动手的圈、跑偏时拉一把。把这几个概念吃透，后面学各个入口、配置、扩展，都是在这套地基上添砖加瓦。
下一篇 03 · 安装与登录：概念懂了，该真刀真枪把 Codex 装到你机器上了。下一篇带你在 Mac / Windows / Linux 上装好 Codex、登录账号、跑通第一句话——尤其 Linux 用户，还记得本篇说的那个 bubblewrap 吗？装的时候你就知道它派什么用场了。