一文搞懂Codex的5大核心概念

来源：互联网 2026-07-14 06:17:12

Codex作为编程代理围绕代码库完成任务闭环，Agent执行从分析到验证的任务；Sandbox限定读写与操作边界；Approval控制高风险越界操作是否需要确认；AGENTS.md承载项目规则；Memory保存个人偏好，Chronicle增强当前上下文。边界清晰是自动化可靠的基础。

Codex 核心概念：Agent、Sandbox、Approval、AGENTS.md、Memory 与 Chronicle

一文搞懂Codex的5大核心概念

长期稳定更新的攒劲资源： >>>点此立即查看<<<

这篇文章主要写给刚开始接触 Codex 的开发者。咱们跳过安装流程，直接聊几个最容易让人困惑的核心概念：Codex 到底是什么、为什么总被权限拦住、什么时候需要你点一下确认、项目规则到底该写在哪，以及 Memory 和 Chronicle 分别在什么场景下救场。

1. 背景

不少开发者第一次用 Codex 时，大概率遇到过这些情况：

让它改个文件，它却说权限不够；
让它联网查点资料，它停下来等你批准；
让它处理项目外的文件，完全碰不了；
让它按团队习惯写代码，结果它没完全遵守项目约定。

这些看起来像是“不稳定”的表现，其实大多和 Codex 的底层机制有关——搞清楚下面这几个概念，问题基本就明朗了：

Agent：Codex 是能执行任务的编程袋里，不是只会聊天的机器人；
Sandbox：限制了 Codex 能读写哪些文件、能执行哪些操作；
Approval：决定高风险或越界操作是否需要你确认；
AGENTS.md：给 Codex 定义项目级规则的说明文件；
Memory：用来保存个人偏好和长期经验；
Chronicle：用来增强当前屏幕和任务上下文。

理解这些之后，再让 Codex 改代码、修测试、做项目分析，遇到问题就能快速定位根源。

2. Codex 为什么不是普通聊天机器人

普通聊天机器人主要负责“回答问题”。你问它一段代码怎么写，它给你一段代码；你问某个报错可能是什么原因，它给你几个排查方向。就这样。

但 Codex 的定位更接近一个编程袋里，也就是 Agent。

它的工作模式不是只回答，而是围绕一个目标完成闭环：

读取项目文件；
分析代码和报错；
修改相关文件；
执行命令或测试；
根据结果继续调整；
最后给出变更说明。

区别可以这样看：

类型	主要能力	典型交互
ChatGPT	回答、解释、生成片段	“这个函数怎么写？”
Codex	读代码、改文件、跑命令、验证结果	“这个测试挂了，帮我定位并修复。”

所以，Codex 的核心价值不只是“会生成代码”，而是能在代码库里完成从分析到验证的任务闭环。

3. Agent：从回答问题到执行任务

Agent 可以理解为“带目标执行能力的助手”。当你给 Codex 一个任务时，它通常经历这样的过程：

理解目标 -> 读取上下文 -> 执行动作 -> 查看结果 -> 继续修正

这和普通问答最大的区别就是：Codex 会动手。

举个例子，你输入：

修复当前项目里失败的单元测试。

一个典型的 Agent 流程可能是：

先查看测试失败输出；
找到相关测试文件；
阅读被测代码；
修改最小必要代码；
重新运行测试；
如果仍失败，继续分析；
最后说明修改了什么。

这也是为什么 Codex 需要权限控制——它不仅能给建议，还可能真正修改文件、执行命令。如果没有边界，风险会比普通聊天机器人高得多。

4. Sandbox：限制 Codex 的操作边界

Sandbox 可以理解为 Codex 的操作围栏。它决定了 Codex 能访问哪里、能不能写文件、能不能执行某些命令。

常见的沙箱模式大致如下：

沙箱模式	含义	适合场景
`read-only`	只能读取，不能写入	分析陌生项目、做代码审查
`workspace-write`	可以修改当前工作区内文件	日常开发、修复 bug、补测试
`danger-full-access`	权限非常大，基本不受工作区限制	临时可信环境，不建议常态使用

如果 Codex 无法修改文件，先别急着判断它“没执行”。更合理的排查顺序是：

当前是不是 read-only；
要修改的文件是否在工作区内；
命令是否需要访问工作区外资源；
是否需要联网或访问系统级路径。

对大多数日常开发任务来说，workspace-write 是比较合适的默认选择。

5. Approval：控制高风险操作是否需要确认

Sandbox 和 Approval 容易混在一起，但它们解决的是两个不同的问题。

Sandbox：这件事能不能做；
Approval：做之前要不要问用户。

举个例子，当前环境是只读模式，Codex 想创建一个文件：

Sandbox 先判断：写文件超出了只读模式；
Approval 再判断：是否允许请求用户授权；
如果需要确认，Codex 会停下来说明原因；
用户确认后，Codex 才能继续。

比较稳妥的日常组合是：

workspace-write + on-request

这个组合的含义是：

工作区内的普通读写可以正常进行；
涉及联网、工作区外路径、高风险命令时，先请求确认；
既不会每一步都打断，也不会完全放开权限。

不建议在不熟悉的项目里直接使用高权限模式，尤其是项目中包含 .env、密钥、生产配置、客户数据时。

6. AGENTS.md：项目级规则应该写在这里

AGENTS.md 可以理解为给 Codex 的项目入职手册。

项目里的很多约定不适合每次都在对话里重复，比如：

使用什么包管理工具；
修改代码后运行什么测试；
新增模块放在哪个目录；
命名规范是什么；
哪些文件不能修改。

这些内容适合沉淀到 AGENTS.md。

一个简单的示例：

# Project Instructions
## Build and Test
- After changing Kotlin code, run the related module tests.
- Do not modify `.env`, signing files, or CI configuration unless explicitly requested.
## Structure
- New Android screens should be placed under the matching feature module.
- ViewModel classes must end with `ViewModel`.

AGENTS.md 不需要写得很长，重点是具体、可执行、可验证。

推荐写入：

内容	示例
构建命令	修改后运行 `./gradlew test`
测试命令	运行对应模块单测
目录约定	新页面放在对应 feature 模块
禁止事项	不修改 `.env`、签名文件、CI 配置
验证要求	改完说明验证命令和结果

不推荐写入：

大段背景介绍；
与项目无关的个人偏好；
模糊规则，例如“代码要优雅”；
密钥、token、账号密码。

如果 Codex 经常犯同一个项目级错误，不要只在对话里纠正一次，更应该把规则补进 AGENTS.md。

7. Memory 与 Chronicle：长期记忆和当前上下文

Memory 和 Chronicle 都和上下文有关，但适用范围不同。

可以这样区分：

概念	作用	适合保存什么	不适合保存什么
`Memory`	长期记忆	个人技术栈、偏好、常用习惯	项目强约束、敏感信息
`AGENTS.md`	项目规则	构建命令、测试要求、目录规范	私人偏好、密钥
`Chronicle`	当前上下文增强	当前屏幕、当前任务、近期操作	敏感页面、密钥窗口

关键规则应该放在 AGENTS.md，而不是只依赖 Memory。

原因很简单：

AGENTS.md 跟项目走；
Memory 更像个人习惯的补充；
项目协作中，规则应该明确、可见、可审查。

Chronicle 能增强 Codex 对当前工作状态的理解，但也意味着它可能接触更多屏幕上下文。处理包含密钥、客户数据、内部文档的场景时，需要谨慎开启。

8. 最小实验：观察沙箱如何拦截写文件

下面用一个最小实验来看看 Sandbox 和 Approval 到底怎么工作的。

创建一个空目录并启动 Codex：

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

Windows PowerShell 也可以：

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

进入 Codex 后，切换到只读或最严格权限模式：

/permissions

然后输入：

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

如果当前是只读模式，创建文件会被拦截——因为这是写操作。这时候你应该能看到 Codex 说明它需要更高权限，或者请求你确认。

再切换到工作区可写模式，让它重新创建文件。只要文件位于当前工作区内，这次应该能正常完成。

这个实验可以帮你直观看到：

Sandbox 如何限制写文件；
Approval 如何在越界操作前介入；
同一个任务在不同权限模式下行为完全不同。

9. 实际使用建议

用 Codex 的时候，可以按下面这个顺序检查：

检查项	说明
明确任务目标	不要只说“优化一下”，说明要修什么、验什么
确认沙箱模式	日常开发优先使用 `workspace-write`
确认审批策略	高风险操作建议保留确认
写好 `AGENTS.md`	项目规则不要只靠临时口头说明
保护敏感信息	`.env`、密钥、token 不进提示、不进代码
要求验证结果	让 Codex 说明运行了哪些测试，结果是什么