Codex 核心概念教程

📚 系列导航：上一篇 Codex 入门教程 带你认全 Codex 的四张脸；这一篇往里走一层，把代理、沙箱、审批、AGENTS.md 和记忆这些核心概念一次讲透；下一篇 Codex 安装教程 再正式动手安装、登录和验证。

Codex 核心概念教程就解决一个问题：它为什么有时直接动手，有时突然停下来问你？代理负责想、做、看，沙箱限制能做什么，审批决定何时问你，AGENTS.md 和记忆则给它长期上下文。

先说个之前我自己干的蠢事，刚开始用 Codex 那会儿，张口就问它「帮我把这三个文件批量重命名」，它噼里啪啦改完，一看傻眼了——它只动了当前项目目录里的，桌面上那两个纹丝没动。我当时还纳闷：不是说能跑命令吗，咋还挑食？后来翻文档才反应过来：那是沙箱（Sandbox）在拦着，它默认只能在你指定的工作区里动手，出了这个圈得先问你。

那一刻我才明白：用 Codex 之前不搞懂这几个概念，你会一直觉得它「时灵时不灵」——其实它一点没乱，是你不知道它头上戴着几道紧箍咒。

这一篇就把这几道紧箍咒、外加它的几样独门配置，掰开揉碎讲清楚。

看完这一篇，你会拿到：

• 一句话讲明白 Codex 的「代理（Agent）」是什么，以及它和聊天机器人差在哪
• 彻底搞懂沙箱和审批这对兄弟——为什么我那次重命名会失败，以及怎么放开它
• 认识 AGENTS.md：让 Codex 记住你项目规矩的那张「入职手册」
• 知道记忆（Memory）和 Chronicle 是什么、默认开没开、能不能用
• 一个能照着跑的小实验，亲眼看清沙箱拦你那一下

这张图先把地基铺出来：中间那个代理是主角，沙箱给它画圈，审批守着出口，AGENTS.md 喂规矩，记忆负责把经验带到下一次。 后面六节，就是把这张图一块一块拆开看。

Codex 代理机制是什么

先说结论，一句话：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 → 改 → 再跑一遍确认，全程你就看着。
• 你扔给它一个没文档的老项目说「理一下结构」，它自己查看当前目录里有哪些文件、自己搜关键字、读一堆文件，最后给你画张图——你一个文件都没指定。
• 你说「把这个函数加上缓存」，它改完顺手把相关调用处也一起捋了，因为它能跨文件看全局。

💡 一句话总结：Codex 是「代理」不是「聊天框」——它在「想→做→看」的循环里自己把活干完；Claude Code 也属于这类代理，但具体模型、工具和权限实现各有各的路子。

Codex 沙箱如何限制文件与网络权限

来了，重点。开头我那次重命名失败，罪魁祸首就是它。

沙箱（Sandbox）：官方定义是「让 Codex 能自主行动、又不至于对你整台机器有无限权限的那道边界（boundary）」。说白了，它就是给 Codex 画的一个圈——圈内的事它自己干，要出圈，先问你。

类比：商场里的儿童乐园。 你把娃放进围栏，里头的滑梯海洋球随便玩，你不用每个动作都盯着；但娃想翻出围栏跑到停车场，警报就响了，得你点头。沙箱就是这个围栏：圈内自由活动免打扰，出圈才拦你——既省得你一惊一乍，又不怕它闯祸。

这道围栏管两样东西：它能改哪些文件、能不能联网。官方给了三种常见的沙箱模式：

看到 workspace-write 那行「仅限工作区内」没有？这就是我桌面文件没被改的原因——它们不在我启动 Codex 的那个项目目录里，压根不在围栏内。不是 Codex 偷懒，是它真的够不着。

还有个细节官方特意强调了：沙箱不只管 Codex 自己的读写，它派生出去的命令也一样受限。也就是说，哪怕它调用 git、包管理器、测试脚本，这些命令也都被关在同一个圈里——不会有「主进程被关着、子命令却越狱」的漏子。

平台上各有各的实现，这点你装的时候会碰到（细节留到 Codex 安装教程 讲）：

• macOS：用系统自带的 Seatbelt 框架，开箱即用，啥都不用配。
• Windows：在 PowerShell 里走原生 Windows 沙箱；用 WSL2 则走 Linux 那套实现。
• Linux / WSL2：建议先用系统包管理器安装 bubblewrap。没找到 bwrap 时 Codex 会尝试内置辅助程序，但它还依赖系统允许创建非特权用户命名空间；所以提前装好，少踩一层系统坑。

💡 一句话总结：沙箱是 Codex 头上的第一道紧箍咒——日常常用的 workspace-write 只让它在你的工作区里改文件、还不许联网；想让它管更宽，得自己把圈画大。

Codex 审批策略如何与沙箱配合

沙箱画好了圈，那「出圈的时候找谁批」——这是另一码事，叫审批（Approval）。

很多人（包括当初的我）会把这俩搞混，官方专门点了一句，值得记住：沙箱定义的是技术边界，审批策略决定的是 Codex 何时必须停下来、跨界之前先问你。

类比：门禁卡 + 保安。 沙箱是那道门禁（物理上拦着你出不去），审批是门口那个保安的脾气——有的保安见谁都放（never），有的只拦陌生人（untrusted），有的是你想出门就喊一嗓子问一下（on-request）。门是死的，保安的松紧是你能调的。

官方给的三种常见审批策略：

注意：这里的 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 跑一个批量脚本，它在我半个主目录里翻文件，看得我手心冒汗——从那以后我再没在不该用的地方开过完全访问。

怎么切？在 CLI 会话里用 /permissions 打开权限选择器（桌面 App 和 IDE 里则看输入框旁边的权限入口）；菜单里可能出现「需要时问我」「自动批准」或你自己配好的权限档位。想把沙箱和审批拧到一个精确组合，就像后面实验那样写启动参数；想让它每次启动都用同一套，再去写配置文件——那是 Codex config.toml 配置详解 的活，这里先知道有这么个开关。

上面那张图说清了一件事：Codex 每要做一步，先看「在不在沙箱圈内」（沙箱说了算），出圈了再看「要不要问你」（审批说了算）。两道关卡，各管各的。

💡 一句话总结：沙箱管「能不能」、审批管「问不问」，两个旋钮分开拧；日常 workspace-write + on-request 这套组合，安全和省心兼顾。

AGENTS.md 项目规则配置

前三节讲的是「权限」。这一节换个话题：怎么让 Codex 记住你这个项目的规矩，省得每次都得重新交代一遍。

答案是一个叫 AGENTS.md 的文件。

类比：给新员工的入职手册。 新人来公司，你不会每天追在屁股后面念叨「咱们用 pnpm 不用 npm」「提交信息要写中文」——你给他一本手册，他自己看。AGENTS.md 就是给 Codex 的这本手册：放进项目里，它每次开工前先读，按里头的规矩办。

官方对它的定位是「durable project guidance」——跟着仓库走、在代理开始干活之前就生效的持久指引。一句话嘱咐：保持精简（Keep it small），别把它写成长篇大论。

里头通常写这些（官方给的例子）：

• 构建和测试命令（比如「测试用 pytest -q」）
• 代码审查的期望（比如「改完必须跑 lint」）
• 这个仓库特有的约定（比如目录怎么放、命名怎么取）

它不只两个层级，而是会从全局一路读到当前工作目录，离工作目录越近的越优先（这点和优先级判断很关键）：

同一层如果有 AGENTS.override.md，Codex 会优先读它；没有才读普通的 AGENTS.md。这就像入职手册旁边贴了张临时通知——通知还在，先按通知办；删掉以后，再回到长期规矩。

最妙的用法官方点了出来，我自己也最爱用——把它当反馈回路（feedback loop）：当 Codex 对你的代码库做了错误假设，你别光在对话里纠正（那是一次性的，下次它又忘），直接让它把这条修正写进 AGENTS.md，下回开新会话它自己就继承了。我给一个 Python 项目调了两周，AGENTS.md 从空白长到二十来行，全是它踩过、被我逮住、然后自己记下来的坑——现在新会话基本不犯重复错误了。

AGENTS.md 之于 Codex，约等于 CLAUDE.md 之于 Claude Code——同一个概念，换了个文件名。

💡 一句话总结：AGENTS.md 是 Codex 的项目入职手册——写下你项目的规矩，它每次开工先读；把它当反馈回路，犯一次错就记一条，越用越顺手。

Codex 记忆与 Chronicle 功能区别

最后这组概念，是 Codex 比较新、也容易让人误会的地方——它到底能不能记住你之前聊过的东西？

先把两个词分清楚：Memory 从之前的对话里攒经验，Chronicle 则把近期屏幕内容也变成记忆来源。两者都在帮你少重复解释，但真正必须执行的项目规矩，还是得落进 AGENTS.md。

Codex Memory 如何跨会话记住信息

记忆（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，开头先标清楚：

⚠️ 实验性，可能变化。 Chronicle 目前是「需主动开启的研究预览（opt-in research preview）」，只对符合条件的 ChatGPT Pro 用户开放，而且只在 macOS 的 ChatGPT 桌面 App 里使用。

Chronicle 是给记忆「喂屏幕」的。 普通记忆是从你和 Codex 的对话里学；Chronicle 更进一步，用你屏幕上的内容帮 Codex 理解你最近在忙啥——你正看着哪个文件、哪个 PR、哪个文档，它能顺着接上，省得你从头解释。

类比：一个能看你屏幕的搭档。 普通搭档只能听你说；Chronicle 这个搭档还能瞟一眼你的显示器，「哦你在看这个报错」，于是不用你复述。听着很爽，但代价也实在——官方明明白白警告了三条：吃配额很快、会增加提示注入（prompt injection）的风险、记忆是不加密地存在你本地的。换句话说，方便和风险都摆在台面上，自己掂量。我个人态度：尝鲜可以，敏感屏幕内容（密码、私信、客户数据）面前，记得用菜单栏的「Pause Chronicle」暂停它。

💡 一句话总结：记忆让 Codex 从「新人」变「老搭档」，但默认关着、还别拿它替代 AGENTS.md；Chronicle 是实验性的「看屏幕」增强，方便但风险也明摆着。

五个概念单独讲完了，再回头看开头那张总图就顺了：中间那个代理是主角，它被关在沙箱里干活；想出圈先过审批；AGENTS.md 在开工前喂规矩，Memory 和 Chronicle 则负责把经验带到下次。 五个概念，全围着中间这个代理转。

Codex 沙箱只读模式验证

光读概念记不住。跑个一分钟的小实验，亲眼看沙箱在 read-only 模式下怎么拦住一次写操作——这是这一篇最该有体感的地方。实验不依赖任何现成项目，新建个空文件夹就行。

这次不赌不同版本的菜单长什么样，直接把沙箱和审批写进启动参数。跑完你会看到同一个写文件请求，在只读和工作区可写两种模式下，待遇完全不一样。

1. 建个空目录。

   Mac / Linux 在终端运行：

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

   Windows PowerShell 可以运行：

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

   预期结果：你进入一个空目录，不会碰到手头正在干活的真实项目。

2. 用只读沙箱启动 Codex。

   codex --sandbox read-only --ask-for-approval on-request

   预期结果：Codex 可以查看当前目录，但编辑文件或运行命令需要先申请权限。还没装 Codex？没关系，先把这段混个眼熟，Codex 安装教程 会手把手带你装好再回来跑。

3. 让它尝试创建文件。

   帮我新建一个文件 hello.txt，里面写一行字 "hello codex"。

   预期结果：它不会默默把文件建好，而是停下来申请权限；如果当前权限配置直接拒绝越界动作，也会明确告诉你写入被拦。无论是哪种，重点都是——hello.txt 不能悄悄落地。

4. 拒绝这次写入，再从另一个终端检查目录。

   ls -la ~/codex-demo

   预期结果：目录里没有 hello.txt。看到这个结果，你就亲眼见到沙箱 + 审批联手干活了：沙箱先判定「这步要出圈」，审批再决定「要不要问」。

5. 改成工作区可写，再跑一遍同样的请求。

   退出当前会话，重新启动：

   codex --sandbox workspace-write --ask-for-approval on-request

   再发一次创建 hello.txt 的指令。预期结果：它能直接在当前目录里把文件建好，因为这次写入发生在沙箱圈内，不用再为这一小步敲门。

6. 用 /status 看清当前边界。

   /status

   预期结果：状态里会显示当前工作区等会话信息。以后再遇到「它怎么不肯改」，先来这里看一眼，往往比条件反射地开完全访问靠谱。

同一个建文件的请求，只读时被拦、可写时放行——这就是沙箱模式实打实的区别。比起读十遍「沙箱是安全边界」，亲眼看它在只读模式下停下来问你那一下，理解得快得多。

💡 一句话总结：跑一遍这个最小实验，你会亲眼看到——同一个写文件请求，read-only 拦下来问、workspace-write 直接放行，沙箱和审批就是这么联手的。

小结：

这一篇把 Codex 后面所有章节都要用到的核心概念，一次铺平了：

你现在应该能看懂：为什么 Codex 有时「不肯」改某个文件（不在沙箱圈内）、为什么它会突然停下来问你（要出圈、审批拦着）、以及怎么用 AGENTS.md 让它记住你的规矩、用 /permissions 当场调松紧。

最该带走的一句话：Codex 不是个许愿池，而是个戴着紧箍咒的能干搭档——你的活儿是给方向、画好它能动手的圈、跑偏时拉一把。把这几个概念吃透，后面学各个入口、配置、扩展，都是在这套地基上添砖加瓦。

常见问题

Codex 为什么能读文件，却不能修改文件？

多半不是它突然罢工，而是当前用了 read-only 沙箱，或者目标文件压根不在工作区里。先用 /status 看工作目录，再用 /permissions 看权限档位；别一着急就把 danger-full-access 搬出来，那相当于门锁卡了一下，你直接把墙拆了。

审批策略设为 never，是不是就等于完全访问？

不是。never 只表示 Codex 不会停下来向你申请审批，能不能读写、能不能联网仍由沙箱决定。如果沙箱不允许某个动作，它不会偷偷越过去，而是直接失败或换一条圈内能走的路。

项目规则应该写进 AGENTS.md，还是交给 Memory？

必须稳定执行、需要团队共享的规则写进 AGENTS.md，比如测试命令、目录约定和改完必须跑什么检查。Memory 更适合记你的偏好、历史经验和会话里学到的背景——一个是贴在墙上的制度，一个是老搭档脑子里的经验，别让后者代替前者。

Chronicle 看不到开关，是配置错了吗？

不一定。Chronicle 是实验性的研究预览，目前面向符合条件的 ChatGPT Pro 用户，并且只在 macOS 的 ChatGPT 桌面 App 中使用；还要先启用 Memories。入口会受账号、客户端版本和工作区条件影响，看不到时先别拿普通 Codex CLI 的权限配置折腾它。

下一篇 Codex 安装教程：概念懂了，该真刀真枪把 Codex 装到你机器上了。下一篇带你在 Mac / Windows / Linux 上装好 Codex、登录账号、跑通第一句话——尤其 Linux 用户，还记得本篇说的那个 bubblewrap 吗？装的时候你就知道它派什么用场了。