02 · Codex 核心概念速览

封面图

先讲个典型的反面教材：刚接触 Codex 那会儿，张口就问它“帮我把这三个文件批量重命名”，它噼里啪啦改完一看——只动了当前项目目录里的，桌面上那两个纹丝没动。当时还纳闷：不是说能跑命令吗，怎么还挑食？后来翻文档才反应过来：那是沙箱在拦着，它默认只能在你指定的工作区里动手，出了这个圈得先问你。

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

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

看完这一篇，你会拿到：

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

01 袋里：它会自己动手，不只是回你话

先说结论：Codex 是 OpenAI 的“编程袋里”，能自己读代码、改文件、跑命令，而不只是给你回一段文字。官方原话就是 "OpenAI's coding agent that can read, edit, and run code"。

这里的“袋里”是关键词。第一次见得解释一句：袋里 = 能自己拆解任务、调工具、看结果、再决定下一步的 AI，不是一问一答的聊天框。

官方描述 Codex 干活的方式是这么一句：“袋里在一个循环里跑终端命令，它改代码、跑检查、尝试验证自己的工作”。

翻译成大白话，还是那三个动作——想 → 做 → 看：

• 想：读相关文件、看报错、搞清楚状况
• 做：改代码、建文件、跑命令
• 看：跑测试、看输出，不对就回头再来一轮

类比：一个肯自己跑腿的代购。普通聊天机器人像个只会查价格的客服——你问它“这件衣服多少钱”，它告诉你，完事。Codex 像个代购：你说“帮我买件均码的黑卫衣”，它自己去翻货、比价、下单、收到货还拆开检查尺码对不对，不对再退换。“自己跑完整个流程”才是袋里和聊天框的本质区别。

几个你真会遇到的场景：

• 你说“这个测试为啥挂了”，它自己跑测试 → 读报错 → 找到 bug → 改 → 再跑一遍确认，全程你就看着。
• 你扔给它一个没文档的老项目说“理一下结构”，它自己查看当前目录里有哪些文件、自己搜关键字、读一堆文件，最后给你画张图——你一个文件都没指定。
• 你说“把这个函数加上缓存”，它改完顺手把相关调用处也一起捋了，因为它能跨文件看全局。

02 沙箱：它动手的圈，画在哪

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

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

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

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

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

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

平台上各有各的实现，这点装的时候会碰到（细节留到 03 安装与登录讲）：

• macOS：用系统自带的 Seatbelt 框架，开箱即用，啥都不用配。
• Windows：直接在 Windows 原生环境运行，用原生 Windows 沙箱（分 elevated 和 unelevated 两种模式）；用 WSL2 则走 Linux 那套实现。
• Linux / WSL2：得先自己装一个叫 bubblewrap 的东西，沙箱才正常工作（这是官方明确要求的前置条件）。

03 审批：到了围栏边，谁来点头

沙箱画好了圈，那“出圈的时候找谁批”——这是另一码事，叫审批。

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

类比：门禁卡 vs 保安。沙箱是那道门禁（物理上拦着你出不去），审批是门口那个保安的脾气——有的保安见谁都放（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 里则是输入框旁边的权限选择器）。想让它每次启动都用同一套，再去写配置文件——那是 18 config.toml 配置详解的活，这里先知道有这么个开关。

下面这张图把沙箱和审批的关系理一遍：

Codex 审批策略的两层决策三种终态：圈内直接做 / 出圈看策略 / 问你看答案

这张图在干什么：它说清了一件事——Codex 每要做一步，先看“在不在沙箱圈内”（沙箱说了算），出圈了再看“要不要问你”（审批说了算）。两道关卡，各管各的。

04 AGENTS.md：给 Codex 的项目入职手册

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

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

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

官方对它的定位是“durable project guidance”——跟着仓库走、在袋里开始干活之前就生效的持久指引。一句话嘱咐：保持精简，别把它写成长篇大论。

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

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

它能放在两个层级，离工作目录越近的越优先：

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

05 记忆与 Chronicle：它能不能“记住”你

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

先把两个词分清楚：

记忆：让 Codex 把早先会话里学到的有用信息带到后面的工作里——比如你的技术栈、项目惯例、踩过的坑，省得每开一个会话都重新交代。

类比：一个跟久了的老搭档。新来的助理你得反复教“我们用 TypeScript、不写分号”；跟你三年的老搭档，你一个眼神他就懂——因为他记着你的习惯。记忆就是把 Codex 从“新来的”往“老搭档”上带。

但有几个关键的事实你必须知道，不然又会觉得它“时灵时不灵”：

• 默认是关的（off by default）。不主动开，它不会记任何东西。
• 开的方式：在 Codex App 设置里打开，或在 ~/.codex/config.toml 的 [features] 段里写 memories = true。
• 有地区限制。官方明说：发布时欧洲经济区、英国、瑞士暂不可用。
• 不是实时更新的。它会等一个会话“闲置足够久”、确认你不是还在干活，才在后台悄悄总结成记忆——所以你刚结束会话，记忆可能还没写进去。
• 存在本地：默认放在 ~/.codex/memories/ 下，是一堆生成的 markdown 文件。
• 能逐会话控制：在 App 和 CLI 里用 /memories 决定“当前这个会话要不要用已有记忆、要不要拿来生成新记忆”。

官方还补了句要紧的：真正必须每次都生效的团队规矩，老老实实写进 AGENTS.md，别指望记忆——记忆是“锦上添花的本地回忆层”，不是规则的唯一来源。这话深有体会：记忆这东西是概率性的，靠它兜底重要规矩，迟早翻车。

再说 Chronicle，开头先标清楚：

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

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

五个概念单独讲完了，在进入动手环节之前，用一张图把它们串起来看一眼——单独理解每个概念容易，但它们怎么协作才是关键：

五个核心概念怎么搭在一起

这张图在干什么：中间那个“袋里”是主角，它被关在“沙箱”这个圈里干活；想出圈到外部世界（你整台机器、网络），得先过“审批”这道关卡；左边的 AGENTS.md 在它开工前把项目规矩喂进去；下边的“记忆 / Chronicle”则跨会话帮它攒经验、下次复用——五个概念全是围着中间这个袋里转的。

06 动手：亲眼看沙箱拦你那一下

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

第一步：建个空目录，进去启动 Codex。

在终端里跑（Mac / Linux；Windows 用 PowerShell，把 mkdir -p 换成 mkdir）：

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

第二步：切到只读模式。

在 Codex 会话里输入斜杠命令，把权限调到只读：

/permissions

然后在弹出的选项里选只读那一档（Read Only / read-only）。预期看到：界面提示当前进入只读模式，类似——

Permissions updated: read-only

第三步：让它干一件“要写文件”的事，看它被拦。

丢这么一句给它：

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

预期看到：它不会默默把文件建好，而是停下来请求你的批准——因为“写文件”这一步突破了 read-only 的边界，按审批策略它必须先问你。大意是：

我需要创建文件 hello.txt，这超出了当前只读模式的权限，是否允许？(y/n)

看到这个“停下来问”的瞬间，你就亲眼见到沙箱 + 审批联手干活了：沙箱判定“这步要出圈”，审批接着弹出来找你点头。这正是第 02、03 节讲的两道关卡，在屏幕上活生生跑了一遍。

第四步：对比一下放开后的样子。

回 /permissions 切到工作区可写（workspace-write），再让它建一次 hello.txt。这回预期它直接建好、不再问你——因为在工作区里写文件本就在沙箱圈内，无需审批。

已创建 hello.txt

跑完用 /status 看一眼当前会话的模型、审批策略这些信息，心里就更有数了：

/status

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

07 小结

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

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

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

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