OpenAI-Codex-CLI-智能体编程实战指南-一-

OpenAI Codex CLI 智能体编程实战指南（一）

原文：Agentic Coding with OpenAI Codex CLI

译者：飞龙

协议：CC BY-NC-SA 4.0

贡献者

作者简介

Daniel Vaughan 是一位总部位于英国的技术领导者和软件架构师，专攻智能体 AI。他在企业、初创公司和学术界拥有近三十年的经验，职业生涯始终专注于工程质量和开发者生产力。他的工作现在集中在这样一个转变上：AI 不再是一个实验，而是成为组织构建软件的核心方式。

Daniel 是 HCLTech AI Labs 的前沿部署工程负责人，他领导着一个全球性实践，将工程师和编码智能体嵌入复杂的企业环境中，将生产级 AI 从原型推向上线系统。他从零开始建立了这一实践，运营精益区域小组，其中共享架构师、少量工程师以及一支通过 Codex、Claude Code、Cursor 和 GitHub Copilot 等工具工作的智能体团队，能够交付出相当于大型团队的产出。

在加入 HCLTech AI Labs 之前，Daniel 是 Mastercard 在伦敦的软件工程总监，在高度监管的金融服务环境中领导实时支付产品的云战略和架构。更早之前，他在剑桥的欧洲生物信息学研究所度过了八年，从软件工程师成长为工程领导者，致力于解决他现在用智能体工具解决的软件质量和开发者生产力问题。

他是《Google Cloud 云原生开发》（O'Reilly, 2024）和《Ext GWT 2.0: Beginner's Guide》（Packt, 2010）的作者，同时也是 Google 开发者专家和绿色软件倡导者。他在 blog.danielvaughan.com 上撰写关于智能体工程和 AI 辅助开发的文章。

本书是在 AI 编码智能体的协助下编写的，考虑到书的主题，作者认为这很合适。编辑判断、架构决策和表达的观点完全出于人类。

前言

这一切始于一列火车上

从 Audley End 到 Liverpool Street 的 07:02 班次需要五十八分钟，除非 Tottenham Hale 出了问题，否则能在 08:00 抵达伦敦。2025 年 11 月的一个周二，我打开笔记本电脑，有一个还算不错的移动数据连接，还有一个模糊的意图：终于要认真对待 Codex CLI 了。我几周前安装过它，运行了几个命令，耸耸肩，然后回去做我原本在做的事了，可能是玩 Gemini Nano Banana 玩得挺开心。那天早上我遇到了一个真实的问题：六个月前写的一个 Node 服务在预发布环境开始表现异常，我以来一直没看过它了。我甚至对这仓库的情况记忆犹新。

我将 Codex CLI 指向项目目录，描述了症状，然后看着它运行。

接下来发生的事情就是你正在读这本书的原因。它不仅仅是建议修复方案。它读取源文件，追踪执行路径，运行测试套件，发现了一个我没提到的第二个问题，为它编写了一个失败的测试，修复了这两个问题，并询问我是否应该打开一个拉取请求。当我们驶入 Tottenham Hale（那里确实出了问题）时，我已经有了一个干净的差异对比、一个关于根本原因的简短解释，还有一种对刚才所见之事的微妙不安感。

我从早期的 Copilot 时代就开始使用 AI 编码助手了。我经历过在浏览器标签页用 ChatGPT、侧边栏用 Claude、各种 Copilot 变体、Cursor、Windsurf，还有一堆我已经忘记名字的其他工具。它们都很有用，就像自动补全有用一样。但这次不一样。并非因为它更“聪明”，确切说不是，而是因为它在运行：读取上下文、采取行动、管理状态、从错误中恢复，而不是单纯地响应。这种区别听起来很微妙，但其实不然。

那就是这本书变得必要的时刻。

是什么改变了我的想法

改变我想法的不是任何单一的惊艳输出。而是理解了其架构。

大多数 AI 编码工具的核心，都是带有上下文窗口的复杂文本补全器。你给它们代码；它们给你更多代码。质量参差不齐，上下文窗口不断变大，集成越来越顺滑，但底层模式是被动的。你提示，它响应。你接受或拒绝。你再提示。

Codex CLI 建立在不同的前提上。它是一个智能体循环。你给它一个目标，它会规划、执行、观察结果、调整，并持续下去，直到完成或卡住。它拥有真正的工具使用能力：它可以读写文件、运行任意 Shell 命令、执行测试、调用外部 API。它可以生成子智能体并行处理独立的子任务。它在会话内跨步骤保持上下文。它知道何时该请求澄清，何时该自顾自地干下去。

这种架构很重要，因为它改变了工具的适用范围。自动补全擅长逐行编码。聊天擅长问答。智能体执行擅长任务——那些有始有终、需要读取多个文件、运行多个命令、在过程中做出多个决策的事情。重构一个模块。端到端地添加一个功能。诊断一个构建失败。这些曾是吞噬你整个下午的事情。这些正是 Codex CLI 专为之而生的。

关于 AI 编码工具的大量惊叹式评论——而且有很多，大多言过其实——都忽略了这一区别。人们对自动补全质量做基准测试，或衡量模型建议正确函数名的频率。这没问题，但衡量的是错东西。有趣的问题不在于模型能否写出排序算法。而在于该工具能否坐在你身边，融入你的实际工作流、你的代码库、你的测试、你的 CI 系统、你的约定，并凭借真正的自主性做出有用的工作。Codex CLI 对该问题的回答，是我见过最有趣的。

本书是我试图解释原因，并教你如何正确使用它的尝试。

适读人群

我写这本书是给中高级软件工程师看的，他们已经习惯了 AI 辅助开发，并且在想智能体工具是否会改变局面。如果你用 GitHub Copilot 用了一阵子，或者你已经在用像 Claude Code 这样的智能体工具，你了解这些工具擅长什么、不擅长什么，并且想从智能体方法中榨取更多价值：这本书就是为你写的。

你应该熟悉终端操作。Codex CLI 是一个命令行工具，本书将其视为命令行工具对待。没有 GUI，没有插件，没有侧边栏。一切都在你的 Shell 中发生。如果这听起来有吸引力而非惊悚，那你来对地方了。

你不需要深厚的机器学习或大语言模型专业知识。我会解释你有效使用 Codex CLI 所需了解的底层模型工作原理，但这不是一本机器学习教科书。我假设的是工程经验：阅读代码库的能力、推理系统行为的能力、在不确定性中调试的能力。这些技能可直接迁移。

本书不适合想了解 AI 全景的管理者，也不适合对软件开发前景好奇的非技术读者。市面上有适合那些受众的好书。本书不是其中之一。我为工程师而写，并力求用工程师觉得有用的具体、明确的方式表达。

还有一点：我是从每天使用该工具的实践者视角写作，跨越企业交付、研究和工程团队。我曾在生产代码库、新建项目、CI 流水线和本地开发中运行 Codex CLI。本书中的观点建立在该实践基础上，而非基准测试或演示。

你不会在本书中找到的内容

我想诚实地说明本书范围。过度承诺覆盖面的书对读者是一种损害。

这不是一本通用的提示工程入门书。 市面上有很多，其中一些很优秀。本书假设你能写出像样的提示，而是专注于适配 Codex CLI 代理模式的特定模式和习语。

这不是一本 LLM 教科书。 我不会解释注意力机制、Transformer 架构或当前前沿模型的训练方式。在底层模型至关重要的特定场景下，我会解释你需要知道的内容。但理解神经网络并非有效使用 Codex CLI 的前提。

这不是一本市场调研报告。 我不会花费篇幅对比 Codex CLI 与 Cursor、Devin、Aider、Claude Code 及领域内的其他每个工具。那种对比在本书付印前就会过时。我将解释代理方法与替代方案的区别，让你自行判断这对你已在使用的工具有何意义。

你将在这里找到的是：一位作者基于数月的日常使用，深度覆盖单一工具，并对什么有效、什么无效持有强烈观点。

本书的组织结构

全书分为六个部分。

第 1 部分：基础 将 Codex CLI 置于语境中，并确立代理始终读取的持久上下文。它是什么、源自何处、如何安装和提示、什么属于 AGENTS.md？如果你完全不熟悉该工具，从这里开始。如果你已使用一段时间，可略读第 1 部分，在相关章节需要时再回来查阅。

第 2 部分：护栏 涵盖引导和约束运行的可配置杠杆：审批模式、模型选择、上下文管理、MCP 集成和钩子系统。这是你最常作为参考返回的部分。我力求让各章节独立成章。

第 3 部分：规模化 解释如何超越默认设置。技能、子代理、多代理编排、成本管理和 CI/CD 集成。如果你有特定工作流或约束，这部分会变得有趣。

第 4 部分：生产 解决从个人使用转向团队使用时出现的问题。安全加固、企业配置、调试和测试策略。

第 5 部分：实践指南 是应用篇，包含使用 Codex CLI 进行代码审查、代码库迁移、基础设施即代码、前端工程、Python 团队和基于 Worktree 隔离的具体、详细演练。本部分每章都跟踪一个真实任务从开始到结束。

第 6 部分：大局观 从个别工作流中抽离，审视架构：基准测试、竞品工具、测试工程和代理工程小组的新兴角色。这些章节假设你已通读前几部分，准备好思考更宏大的图景。

关于版本时效性的说明

Codex CLI 每周发布，有时更频繁。你今天安装的工具可能与我撰写特定章节时使用的表现不同。这不是不信任本书的理由：架构、心智模型和核心工作流是稳定的。这确实意味着你应将特定标志和配置选项视为起点而非教条。codex --help 的输出永远比本书印刷内容更权威。

一个保持跟进的实用建议：阅读变更日志。Codex CLI 的变更日志异常优秀，团队对变更内容及原因保持透明。

如何使用本书

如果你是首次阅读，我建议从头读到尾，至少读完第 3 部分。本书层层递进：早期引入的概念在后续章节中直接使用而不再重述，第 1 和第 2 部分的心智模型会让第 3 和第 4 部分容易得多。

如果你作为参考书回顾，第 2、3、4 部分的每章都设计为独立成章。索引详尽，我大量交叉引用。你不必重读周边章节即可获取所需信息。

如果你带领团队阅读本书、举办研讨会或让工程师快速上手代理工具，第 5 部分专为此设计。每个实践指南均结构为动手练习。

好了，让我们开始吧。

第一部分：基础

第一章：什么是 Codex CLI？

在配置任何 Profile、编写 AGENTS.md 文件或运行首个任务之前，了解 Codex CLI 的来龙去脉及其解决的问题会有所帮助。本章追溯从最初的 OpenAI Codex 模型、到 GitHub Copilot 的自动补全时代、再到 2023 和 2024 年向代理的转变、以及造就今日 Codex CLI 的设计决策的脉络。该工具是一个终端优先、沙箱化、开源的编码代理，它读取你的仓库、运行你的测试、进行提交，并遵循纯 Markdown 文件中的项目专用指令。

读完本章，你将拥有本书其余部分赖以构建的心智模型。

学习目标

你将能够：

  1. 向同事或团队负责人解释自动补全、基于聊天和代理式 AI 编码辅助的区别

  2. 在当前工具全景图上定位 Codex CLI，理解其与 Claude Code、Cursor、GitHub Copilot、Cline 及云托管代理的区别

  3. 清楚阐述定义 Codex CLI 核心价值主张的四大能力：读取仓库、运行测试、进行提交和遵循 AGENTS.md

Codex 之前：简史

“Codex” 这个名字比 CLI 工具早四年。要理解 Codex CLI 是什么，你需要了解它之前发生了什么。

Codex 模型（2021）

2021 年 7 月，OpenAI 发布了一篇研究论文（arXiv:2107.03374），由 Mark Chen 等人撰写，描述了一系列在 GitHub 公开代码上微调的 GPT 语言模型。[1] 最大变体单独在 159 GB Python 代码上训练。论文表明，一个足够大的模型，在足够多代码上微调，仅凭文档字符串描述就能解决非平凡比例的竞技编程问题，无需工具、测试运行器或检索系统。

团队还推出了 HumanEval，这是一个包含 164 道手写编程问题的基准测试，每个问题均由函数签名和文档字符串定义。如果模型能在一次尝试中生成正确的实现，即视为通过。最初的 Codex 模型通过率为 28.8%。这个数字在今天看来只是个历史趣闻，但在 2021 年，它证明了将语言模型规模应用于代码能产生质变的新能力。^(⁴)

最初模型的两个特性塑造了后续的一切发展。首先，它是生成式的，根据提示逐个 token 生成代码，这意味着它能补全部分函数、在语言之间转换，并用自然语言解释自己的输出。其次，它围绕补全隐喻进行优化：你给它文档字符串，它返回实现。这种交互模式定义了 AI 辅助编程的第一个商业化时代。

GitHub Copilot 与自动补全范式 (2021 年 6 月)

2021 年 6 月 29 日，GitHub 推出了 GitHub Copilot 技术预览版，由 Codex 模型驱动。[⁵] 交互体验优雅：随着你输入，幽灵文本随之出现。按 Tab 接受；继续输入即忽略。模型拥有足够上下文——打开的文件、函数名、周围代码和文档字符串——能足够频繁地生成有用的补全，让人真切感受到帮助。

Copilot 的传播速度超过几乎所有此前的开发者工具。^(⁶) 自动补全范式——AI 看着你的肩膀帮你把话说完——已然来临。

这种范式内嵌的局限性，从内部并不明显。自动补全是被动且局部的：模型看到你输入的内容并预测接下来的内容。它不读取你的测试套件、不理解你的构建系统、也不在乎其建议能否通过你的 linter 检查。它只是补全代码行。对于样板代码和熟知的模式，这通常足够。但对于任何需要多文件推理、迭代测试反馈或架构约束满足的场景，自动补全触及到了硬性上限。

ChatGPT 的转变 (2022 年 11 月)

在专用 Codex API 模型于 2023 年 3 月弃用之前，一个更重大的事件重塑了开发者实践。ChatGPT 于 2022 年 11 月 30 日发布。^(⁷) 五天内用户破百万；两个月内破亿，成为当时有记录以来增长最快的消费级应用。

对开发者而言，ChatGPT 将交互模式从行补全变为对话。你描述问题、收到回复、追问、迭代。反馈回路比 Tab 补全慢，但处理复杂问题的能力显著增强。你可以粘贴堆栈跟踪、请求解释、要求修复、询问修复原理并索要变体，全在一个线程内完成。

ChatGPT 并非为编码工具而设计，但它揭示了自动补全范式掩盖的事实：模型具备多步推理、约束应用和任务分解能力。它只需要一个允许对话跨越多轮交互的界面。基于聊天的编码辅助时代由此开启，并将持续到下一次范式转移：代理。

自动补全的问题

自动补全范式存在结构性局限，无论模型如何改进都无法完全解决。理解这一点，就能明白为何随后出现的代理工具不仅仅是“更好的自动补全”，而是完全不同的事物。

自动补全在单一时刻作用于单一上下文窗口。模型看到你打开的代码，提出补全建议，然后停止。它无法运行你的测试、观察失败并修正建议。无法打开第二个文件以检查与别处定义的类型定义是否一致。无法读取你的 CI 日志以理解构建为何中断。

这不是模型能力问题，而是界面问题。一个足以推理多文件系统和迭代测试反馈的复杂模型，若界面只允许它在单一时刻看到单个文件并产出单次补全，便无法施展这些能力。

从自动补全转向聊天有所帮助，因为聊天界面允许多轮推理。但聊天仍需人工复制粘贴错误信息、获取相关文件内容、传递测试结果。人类在模型与开发环境间搭桥。这增加了摩擦，限制了模型在单次会话中能完成的工作量。

代理模式消除了这座桥。你不再传递信息，而是赋予模型直接访问环境的工具：读取此文件、运行此命令、写入此输出并提交此变更。模型随即能端到端完成多步任务：读取失败测试、定位实现、修复 Bug、再次运行测试、若通过则提交，全程无需人工在每步中转。

在此语境下，“代理”意味着什么？模型拥有代理权：在真实环境中采取行动的能力，而非仅建议文本供人类执行。代理工具在单次会话中读取文件、执行 Shell 命令、观察输出并决定下一步。人类设定目标；代理追踪目标。

“代理”不等于“完全自主无监管”。Codex CLI 支持多种审批模式，包括在任何写入或命令执行前需用户确认的交互模式。代理模式赋予模型访问环境的能力；并未将人类监督移出循环。

代理格局

你大概率已接触过多款 AI 编码工具：在编辑器里、会议演讲中、招聘广告里、同事工作流中。如今大多数专业开发者同时使用多款 AI 工具。^(⁸) 这非赢家通吃的市场，而是分品类的市场，理解品类对于理解 Codex CLI 的定位至关重要。

格局按代理驻留位置分为三类：编辑器内、终端内、云端。

类别 1：IDE 集成代理

这些工具在开发者最常驻足的地方相遇：代码编辑器内。IDE 代表集成开发环境，即内置运行、测试、调试工具的代码编辑器。Visual Studio Code (VS Code) 是当今专业开发者中最流行的 IDE。

GitHub Copilot 仍是部署最广、认知度最高、职场采用率最高的 AI 编码工具。^(⁹) Copilot 起步于自动补全（幽灵文本，Tab 接受），现已发展为更宽泛的平台：用于对话式辅助的 Copilot Chat、通过拉取请求进行异步任务完成的 Copilot Coding Agent，以及扩展生态。对企业而言，Copilot 与 GitHub 的集成——代码、拉取请求、CI 均驻留于此——赋予了其纯产品对比常低估的结构性优势。

由 Anysphere 开发的 Cursor 是主导级 IDE 集成代理之一。^(¹⁰) Anysphere 未选择构建扩展，而是 fork 了 VS Code 并将 AI 嵌入每个表面：通过 Composer 实现多文件编辑、通过 Background Agents 实现并行自主会话、通过深度代码库索引赋予模型比提示词注入更丰富的结构上下文。Cursor 面向愿留在编辑器内的开发者。其可视化差异、行内接受/拒绝工作流、熟悉的扩展生态，适合那些希望在变更落地前精确查看代理动作的人群。它非终端原生，亦非开源。

AI 编码工具全景

类别 1：IDE 智能体

Cline（最初名为 Claude-Dev）是一个开源的 VS Code 扩展，它赋予模型工具访问权限、文件读取、Shell 执行以及通过 Playwright 进行浏览器控制的能力，并允许其在编辑器内规划并执行多步骤任务。^(¹¹) 与 Cursor 不同，它运行在标准的 VS Code 中，而不是一个分支版本，因此你可以保留完整的扩展生态系统。Cline 与模型无关，并由贡献者社区积极维护。

类别 2：终端智能体

终端智能体运行在 Shell 中，即你输入命令并查看其输出的基于文本的界面。自图形界面出现之前，这就是开发人员与计算机交互的方式，它至今仍是专业软件开发的基石。

终端智能体可与 Unix 工具组合使用，自然地集成到 CI/CD 流水线（自动构建、测试和部署代码的系统）中，并能在任何拥有终端的环境中工作：SSH 会话、Docker 容器和无头服务器。Codex CLI 就属于这一类别。

Claude Code 由 Anthropic 于 2025 年 5 月发布，是 Codex CLI 最直接的竞争对手，也是你最有可能与其并列遇到的工具。^(¹²)

Claude Code 以终端为先、具备智能体特性，并使用一个名为 CLAUDE.md 的项目指令文件，其功能与 Codex CLI 的 AGENTS.md 类似。它运行在沙箱环境中，支持用于并行执行的子智能体和智能体团队，并与 Anthropic 的模型上下文协议 (MCP) 深度集成，MCP 是一种让 AI 工具连接外部服务和数据源的标准。Codex CLI 同样支持 MCP。这两个工具共享足够多的设计理念，以至于技能可以在它们之间迁移。关键差异在于：模型系列（Claude 对比 GPT）、子智能体架构（Claude 使用基于邮箱的智能体团队；Codex CLI 使用带有路径寻址的 TOML 定义子智能体）以及生态系统。

如果你所在的团队使用 Claude Code，或者你正在为工作流评估这两个工具，了解 Claude Code 的设计决策将加深你对 Codex CLI 的理解，反之亦然。第 26 章提供了详细对比。

Aider 由 Paul Gauthier 于 2023 年创建，是最早的开源终端智能体之一，并影响了后续工具的设计。^(¹³) 其核心创新是结构化编辑格式：Aider 不再让模型流式输出原始代码，而是提示模型生成可确定性应用的 diff 块。Aider 与模型无关（支持 500 多家 LLM 提供商）并保持活跃开发。对于有严格数据驻留要求且需要特定模型提供商的组织，Aider 将界面与模型解耦是一项真正的优势。

类别 3：云端与托管智能体

这些工具在云环境中异步运行，通常集成到拉取请求工作流中。

GitHub Copilot Coding Agent 直接连接到 GitHub Issues：你将 Issue 分配给 Copilot，智能体提出计划，在沙箱环境中生成实现，并打开一个草稿拉取请求供审查。^(¹⁴) 该流程是异步的：你委派任务、离开，回来时已有一份拉取请求。这代表了平台所有者的押注：智能体工具的正确位置，是集成在代码已被审查和合并的工作流中。

Devin 由 Cognition Labs 于 2024 年 3 月发布，被营销为“首个 AI 软件工程师”，是一个功能齐全的托管自主智能体，拥有浏览器、Shell 和编辑器访问权限，旨在无需人工干预即可在长时间会话中完成工程任务。^(¹⁵)

Google Jules 和 Codex Cloud Tasks（OpenAI 自身的云产品）代表了“即发即弃”式智能体执行的增长趋势：提交任务，智能体在隔离的云环境中工作，结果就绪时你进行审查。

它们的现状

下表记录了撰写时的全景概况。市场地位一栏参考了 JetBrains 开发者调查。^(¹⁶)

表 1-1：AI 编码工具全景

| 工具 | 类别 | 界面 | 市场地位 | 沙箱 | 开源 |

| --- | --- | --- | --- | --- | --- |

| GitHub Copilot | IDE 智能体 | VS Code / JetBrains 扩展 | 认知度与采用率最高 | 通过扩展 | 否 |

| Cursor | IDE 智能体 | VS Code 分支 | 采用率显著 | 通过编辑器 | 否 |

| Claude Code | 终端智能体 | 终端 / CLI + 桌面端 | 采用率显著 | 操作系统级 | 源码可得 |

| Cline | IDE 智能体 | VS Code 扩展 | 活跃的开源社区 | 通过工具权限 | 是 (Apache 2.0) |

| Copilot Coding Agent | 云端智能体 | GitHub Web + Actions | 原生融入 GitHub PR 流程 | Actions 沙箱 | 否 |

| Devin | 云端智能体 | 托管 Web VM | 开创了“AI 工程师”定位 | 托管 VM | 否 |

| Aider | 终端智能体 | 终端 / CLI | 开源小众、模型无关 | 通过 Shell | 是 (Apache 2.0) |

| Codex CLI | 终端智能体 | 终端 / CLI | 采用率增长中 | 内核级 | 是 (Apache 2.0) |

市场份额并不决定工具对你用例的质量优劣。工具的选择取决于你的模型偏好、编辑器、部署约束，以及是否需要终端组合能力。本书将帮助你基于对其中一个选项的深度熟悉来评估该决策。

定义 Codex CLI

2025 年 4 月 16 日，OpenAI 发布了 Codex CLI，这是一个由 Fouad Matin 和 Michael Bolin 构建的开源、Apache 2.0 许可的终端智能体。^(¹⁷) 以 AI 发布标准来看，此次发布相当低调。没有“AI 软件工程师”的框架宣传。README 将其描述为一个供希望在终端中工作的开发者使用的工具。

Andrej Karpathy 将 Codex CLI 定义为 Software 3.0 平台：上下文窗口是杠杆，AGENTS.md 是程序，而“ harness（约束与验证框架）”，即配置、约束和验证智能体的纪律，正是区分高效使用与混乱的关键。^(¹⁸) 这一框架构成了本书的核心论点。第 27 章将对此进行充分展开。

区分 Codex CLI 与其同类工具的设计决策均是深思熟虑的，理解它们是熟练使用该工具的先决条件。

终端优先

Codex CLI 运行在你的 Shell 中。它不是 VS Code 扩展，不是托管的 Web 服务，也不是主要的 GUI 应用程序（尽管存在一个用于管理并行会话的配套 macOS 应用）。

这一点很重要，因为终端工具可与 Unix 生态系统组合：管道、重定向、环境变量、Shell 脚本、Cron 任务和 CI 流水线。任何能运行 Shell 命令的东西都可以调用 Codex CLI，这是第 15 章中 CI 集成模式的基础。

无头且可脚本化

codex exec 命令以非交互方式运行智能体，接受参数或标准输入中的提示词，并在任务完成时退出。正是这个接口使得 Codex CLI 适用于自动化流水线。GitHub Actions 作业可以像调用 pytest 或 eslint 一样调用 codex exec，作为工作流中的一个步骤，并捕获结构化输出供下游处理。^(¹⁹)

内核层级沙箱

当我们说 Codex CLI 是“沙箱化”的，意味着操作系统在其运行时限制智能体能做什么。在 macOS 上，Codex CLI 使用 Apple Seatbelt 限制文件系统和网络访问。在 Linux 上，它使用 bubblewrap 和 seccomp。这些是内核级安全机制：限制由操作系统强制执行，而非由应用程序执行。智能体无法意外绕过它们，而提示词注入（隐藏在输入文本中的恶意指令）导致模型误以为拥有提升权限，仍会在内核级被阻止。^(²⁰)

你可以通过在 ~/.codex/config.toml 中定义的审批模式和沙盒配置文件，刻意扩大沙盒范围。但默认情况下是受限的，且该限制是真实存在的。

AGENTS.md 感知

Codex CLI 会从你的仓库根目录及子目录读取 AGENTS.md 文件，加载特定于项目的指令：运行哪个测试命令、偏好哪个工具链、遵循哪些约定、避开哪些陷阱。^²¹ 该格式现已成为 Linux 基金会旗下 Agentic AI Foundation 维护的开放标准。大多数主流 Agentic 工具均已采用。

第 4 章 深入介绍 AGENTS.md 的编写方法。

Apache 2.0 开源

Codex CLI 的源代码公开托管于 GitHub，并接受社区贡献。对于一个代表你执行 Shell 命令的工具而言，这种透明度是信任模型中极具意义的一环。

为什么终端很重要

将 Codex CLI 构建为终端工具，而非 IDE 插件或托管式 Web 应用，这是关于可组合性的宣言，而非对命令行的怀旧偏好。

与 Unix 工具的可组合性

Unix 工具可组合。一个程序的输出成为下一个程序的输入。过滤器、转换器和聚合器链接成管道。Shell 是程序间通过标准输入输出对话的协调层。

身处该环境的智能体，免费继承了这种可组合性。将 Codex CLI 输出管道传给 jq 以提取结构化结果。在 Shell 脚本中封装 codex exec 并通过 cron 定时夜 ly 运行。在 Makefile 目标中串联多个会话，依次完成构建、测试、修复和提交。传递环境变量以控制行为，无需修改任何配置文件。

这一切都不需要 Codex CLI 提供特殊支持。这仅仅是作为一个读取 stdin、写入 stdout 并返回有意义退出码的终端工具的必然结果。

无需繁文缛节的 CI/CD 集成

CI 流水线本质是 Shell 脚本。GitHub Actions 工作流是描述 Shell 命令的 YAML 文件。Jenkins 作业、CircleCI 流水线和 GitLab CI 配置归根结底都是：按顺序运行这些命令，设置这些环境变量，在该容器中执行。

原生终端工具的智能体，如同任何其他命令行工具一样自然集成。你不需要 GitHub App、OAuth 集成、Webhook 处理器或专用云环境。你只需在密钥存储中配置 API Key，并在工作流文件中调用 codex exec。

对于受监管环境或企业防火墙后的团队而言，新服务集成需要安全审查，这一点至关重要。一个使用与你其他 API 调用相同网络路径的 CLI 工具，比新的 SaaS 集成更容易获批。

codex exec 命令结合 --ask-for-approval never 和限制性沙盒模式（如 workspace-write 或 read-only），专为 CI 场景设计。第 15 章 详细演示了完整的 GitHub Actions 集成模式，包括如何为自动化上下文界定沙盒范围。

无需 GUI

开发环境各异。有的开发者用 VS Code，有的用 Neovim、Emacs 或 Helix。有的通过 SSH 在无法运行 GUI 的远程服务器工作。有的在容器化环境中，安装 Electron 应用不可行。

终端工具适用于所有这些场景。SSH 会话、Docker 容器、远程开发环境和无头 CI 运行器都有 Shell。存在于 Shell 中的智能体，便在 Shell 存在的任何地方可用。

使 Codex CLI 在交互会话中安全运行的沙箱机制在操作系统层面生效，这意味着它在 macOS (Seatbelt) 和 Linux (bubblewrap/seccomp) 上的行为有所不同。如果你在 macOS 上开发，却在 Linux 上部署 CI 自动化，请在依赖生产流水线前，在两个平台上测试你的沙盒配置文件。

核心主张

Codex CLI 的核心主张可以用一句话概括：你描述任务，智能体读取你的仓库、运行你的测试、创建提交，并在完成时告知你。

这四项能力将 Codex CLI 与自动补全时代、基于聊天的辅助工具，以及更简单的 Agentic 工具区分开来。

读取整个仓库

智能体不局限于你打开的单个文件。得益于大上下文窗口，大多数项目代码库可装入单个上下文。智能体可同时阅读某文件的类型定义、另一文件的实现模式、第三个文件的测试固件，并在决定如何实现你的需求时统筹推理。

这对重构最为关键，因为一个文件中的正确修改往往取决于分布在几十个其他文件中的使用模式。自动补全看不到这些模式。聊天需要你手动粘贴。Codex CLI 自行发现它们。

运行你的测试

智能体可调用你的测试套件，观察输出，并利用失败信息指导下一步动作。这个反馈循环——写代码、跑测试、观察失败、修正——正是资深开发者的工作方式。Codex CLI 自主参与该循环。

测试运行器在 AGENTS.md 中指定，或从仓库结构推断。智能体运行的正是你在终端中会运行的命令。输出被捕获、解析，并融入其下一动作。

创建提交

经你许可，智能体将工作提交至 Git。结果是带有有意义提交信息的、可审查的真实历史，而非编辑器中的未保存更改，也非需复制粘贴的差异。提交是真实的，历史是真实的，你可像审查其他变更一样用 git log 或 git diff 审查它。

你配置的审批策略和沙盒决定了智能体提交的自主程度。在 on-request 策略下，智能体在运行前提议命令和编辑供你批准。untrusted 策略更严格，几乎所有操作都升级确认。never 策略搭配 workspace-write 沙盒，适用于 CI 流水线和可信环境，让智能体无中断地端到端运行。

遵循 AGENTS.md

智能体读取并遵循 AGENTS.md 文件中的指令。这些不是提示；它们是智能体视为其运行上下文一部分的约束性指令。若 AGENTS.md 指定 uv 而非 pip，智能体用 uv。若指定 just test 而非 pytest，智能体运行 just test。若警告部署脚本中的已知陷阱，智能体会避开。

这是将你团队的制度性知识编码进智能体行为的方式。智能体不知你代码库的历史、团队的决策或组织的惯例，除非你将其写下来。AGENTS.md 正是你记录它们的地方。

AGENTS.md 的价值随具体程度而增。通用建议（“写整洁代码”）对智能体行为无可衡量影响。具体、非显而易见的工具指令（“用 uv run pytest 而非直接用 pytest，虚拟环境不会自动激活”）有显著、可靠的效果。第 4 章 介绍了 AGENTS.md 应包含什么、不应包含什么。

总结

  1. 从研究模型到自动补全。 原始 OpenAI Codex (2021) 证实了代码微调语言模型能从描述生成实现。GitHub Copilot (2021) 将自动补全带给开发者，却也定下了其天花板：被动、局部、无法运行测试或跨文件推理。

  2. 对话与 Agentic 转向。 ChatGPT (2022) 将交互模式转为对话。Agentic 转向 (2023–2024) 赋予模型工具访问权，实现多步自主任务完成。

3. Codex CLI 是一款智能体终端客户端

OpenAI 于 2025 年 4 月发布的开源、Apache 2.0 许可的终端智能体：无头模式、内核级沙箱、感知 AGENTS.md，旨在读取代码库、运行测试、提交变更并遵循项目特定指令。

4. 终端至关重要

终端工具与 Unix 组合、融入 CI/CD 流水线，且可在任何拥有 Shell 的环境中运行。

练习

练习 1-1：梳理你当前的工具栈

写下你目前正在使用或过去六个月内使用过的每一个 AI 编码工具。针对每个工具，确定其类别（IDE 智能体、终端智能体、云端智能体）、主要交互模式（自动补全、聊天、智能体模式）以及是否开源。使用表 1-1 作为模板，为你列表中的工具添加行。Codex CLI 相对于你已有的工具处于什么位置？如果你使用 Claude Code，请列出它与 Codex CLI 共有的三个设计决策以及三个分歧点。

练习 1-2：找出自动补全无法完成的任务

回想过去一个月你完成的最复杂的编码任务，那种需要阅读多个文件、迭代运行测试或在代码库中进行协调变更的任务。写一段话描述该任务。然后找出该任务中超出自动补全能力范围的步骤，并说明原因。此练习旨在建立直觉，理解智能体辅助在哪些方面能提供早期工具无法提供的价值。

练习 1-3：阅读 AGENTS.md 标准

在 第 4 章 编写你的第一个 AGENTS.md 文件之前，请阅读 agents.md 上的当前规范。注意哪些字段是必需的，哪些是可选的，以及表 1-1 中的哪些工具支持哪些字段。列出关于你当前项目的五件事，这些事仅从阅读源代码并不明显，但新团队成员或 AI 智能体为了良好协作必须知道。这些将成为你在 第 4 章 中 AGENTS.md 的种子内容。

练习 1-4：将 Codex CLI 映射到智能体循环

本章描述的四步智能体循环（读取、规划、行动、验证）是 Codex CLI 工作的基础。从你当前的项目待办事项中选择一项任务，手动完成需要 15 到 60 分钟。针对这四个步骤中的每一个，写一句话描述 Codex CLI 在你选定任务的该步骤会做什么。然后估算哪一步会消耗最多 Token（上下文），哪一步出错风险最大。此练习为你在 第 3 章 编写有效提示词做准备。

练习 1-5：研究沙箱模型

根据你的平台，查阅 macOS Seatbelt 或 Linux bubblewrap 的文档并阅读技术概览。写两段话解释：（1）默认情况下沙箱阻止 Codex CLI 执行哪些类别的操作；（2）哪一类任务中，默认沙箱会过于严格，导致 Codex CLI 无法完成任务。此练习为 第 5 章 中的审批模式讨论做铺垫。

第二章：Codex CLI 入门

第 1 章 解释了 Codex CLI 是什么以及智能体模式为何重要。本章回答实际问题：如何安装、认证并运行真正的第一次会话？最后，你将拥有一个可用的安装环境，并有信心跟进后续所有内容。

学习目标

你将能够：

  1. 安装 Codex CLI 并验证安装

  2. 完成适合你情况的认证流程

  3. 运行真正的第一次会话并理解你看到的内容

首次会话的样子

在安装步骤之前，先看看你安装的是什么。以下是在一个真实代码库上的真实首次会话：一个包含失败测试和待查找 Bug 的微型项目。你暂时还无法运行它，那在后几页，但先读一遍能让你知道输出开始滚动时该期待什么、该忽略什么。

任务只有一句话，输入提示词中：

Find the bug in main.js and fix it. Run the tests before and after to confirm the fix.

Codex CLI 不会直接回答。它开始观察，并边走边叙述：

> Reading main.js, package.json, test/main.test.js
> Running npm test
  O calculateCartTotal multiplies each item price by its quantity (1 failing)

第一步是获取证据，而非猜测。智能体在做任何更改前先读取相关文件并运行测试套件，因此它是从同一个你会从中开始的失败测试起步。然后它大声提出假设：

> The cart total adds item.price but ignores item.quantity entirely. Bringing
  quantity into the sum: total + item.price + item.quantity.

这是一个合理的初步判断，但它是错的，这才是值得关注的部分。智能体进行编辑，重运行测试，测试套件告诉它错了：

> Editing calculateCartTotal: total + item.price  ->  total + item.price + item.quantity
> Running npm test
  O calculateCartTotal multiplies each item price by its quantity (1 failing)

对话式工具会把第一次编辑交给你就停下了。Codex CLI 运行了测试，看到了红色（失败），并继续前进。它再次读取失败信息，这次测试名称告诉它遗漏了什么：

> Still failing: got 10.5, expected 12.5. The test name says "multiplies": the
  quantity should multiply the price, not add to it. Changing the + to *.

它将加法改为乘法，并重运行直到测试套件全绿：

> Editing calculateCartTotal: + item.quantity  ->  * item.quantity
> Running npm test
  P 2 passing

然后它停下并总结所做之事：一个忽略数量的购物车总计，一次错误的猜测（加而非乘）被撤回，两个测试均通过。整个过程耗时 20 到 40 秒，每次工具调用都在会话日志中实时可见。

你刚才目睹的是 第 1 章 中的智能体循环：规划、执行、观察、调整。错路并非演示中的缺陷，它就是演示。一个能自己运行测试的智能体，首次尝试错了也没关系，因为捕捉错误的是测试运行，而非你的代码审查。

快速入门不会告诉你的事

官方快速入门只展示克隆和运行。它没告诉你：上述可见的推理过程才是重点，而非噪音。文档遗漏了三点：

  • 第一次编辑往往是探针，而非修复。 智能体被允许犯错，因为它会验证。把每个中间编辑都当成最终答案看会让你抓狂。看测试结果，别盯着按键。

  • 它在改动任何东西前先运行测试。 如果你的项目没有测试，或者测试慢、易变，智能体就失去了赖以生存的反馈，其第一次猜测极有可能成为最后一次猜测。快速的测试命令是你代码库中杠杆率最高的单一因素。

  • 结尾的总结才是交付物，而非滚动日志。 滚动的工具调用是实时追踪，不是报告。运行时瞥一眼；仔细阅读最终总结和差异。

更大的图景：四个界面，同一个智能体

Codex CLI 是共享同一智能体的四个界面之一：CLI、桌面应用、IDE 扩展和云端[2]。配置、技能和记忆可在四者间迁移。CLI 是基础界面：开源、本地优先，也是本书的重点。

先决条件

Codex CLI 需要 Node.js 22 或更高版本[3]。在 macOS 和 Linux 上，请使用 nvm 或 fnm 管理 Node 版本：

fnm install 22 && fnm use 22
node --version # v22.x.x 或更高版本

Codex CLI 可在 macOS、Windows（原生支持 AppContainer 沙箱，或通过 WSL2）和 Linux 上运行。撰写本文时，原生 Windows 支持属于实验性但已可用；WSL2 仍推荐用于生产环境，因为它运行的内核级沙箱与原生 Linux 安装相同。WSL1 无法创建沙箱所需的用户命名空间，因此不受支持。

需要 macOS 13 Ventura 或更高版本；同时支持 Apple Silicon 和 Intel 芯片。在 Linux 上，沙箱基于 bubblewrap (bwrap) 构建。您无需自行安装：Codex 自带一份并自动使用，仅当您的 PATH 中存在更新版本的系统 bwrap 时才会优先使用后者。

安装

npm（推荐）

npm install -g @openai/codex
codex --version

如果遇到权限错误，请将 npm 配置为使用主目录下的文件夹：npm config set prefix ~/.npm-global，并将 ~/.npm-global/bin 添加到您的 PATH 中。

Codex CLI 提供了内置的更新命令：

codex update # 通过安装时使用的包管理器进行自我更新

update 子命令会检测您的安装方式（npm、Homebrew 或二进制文件）并触发相应的更新机制。如需手动升级：

npm install -g @openai/codex@latest # npm 手动升级

Homebrew（macOS 和 Linux）

brew install --cask codex

Homebrew cask 直接安装预构建的二进制文件，因此不需要 Node.js。Homebrew 通过标准的 brew upgrade 机制处理更新。

直接下载二进制文件

预构建的二进制文件可在 GitHub 发布页面获取，适用于 npm 和 Homebrew 均不适用的环境。下载适用于您平台的压缩包，解压，将二进制文件重命名为 codex 并将其放置在您的 PATH 中：

tar xzf codex-aarch64-apple-darwin.tar.gz
mv codex-aarch64-apple-darwin /usr/local/bin/codex
chmod +x /usr/local/bin/codex

验证安装

确认一切正常工作：

codex --version

要确认可用的命令和标志，请运行：

codex --help

这将列出每个子命令和标志，并确认 CLI 响应正常。

Shell 补全

Tab 补全使标志和子命令更易于发现。Codex CLI 为 bash、zsh 和 fish（以及 PowerShell 和 Elvish）生成补全脚本。为您使用的 Shell 生成补全文件：

##### bash
mkdir -p ~/.local/share/bash-completion/completions
codex completion bash > ~/.local/share/bash-completion/completions/codex
##### zsh
mkdir -p ~/.zsh/completions
codex completion zsh > ~/.zsh/completions/_codex
##### fish
codex completion fish > ~/.config/fish/completions/codex.fish

Bash 和 fish 会自动从这些目录加载文件。Zsh 需要额外一步：在 ~/.zshrc 中 compinit 之前将补全目录添加到 fpath：

fpath=(~/.zsh/completions $fpath)
autoload -Uz compinit
compinit

认证

根据您访问 OpenAI 的方式，共有三种途径。

路径 1：ChatGPT 订阅（设备码流程）

codex login

CLI 会打印一个简短的代码并打开一个 URL。登录，输入代码，Codex 会将凭证令牌存储在 ~/.codex/auth.json 中（仅所有者可读写）。

路径 2：API 密钥

export OPENAI_API_KEY="sk-..."

将其添加到您的 Shell 配置文件以使其持久生效。使用 API 密钥时，您将按 Token 计费；建议在学习典型会话成本时，从较低的使用上限开始。

路径 3：企业配置

直接编辑 ~/.codex/config.toml：

api_base_url = https://your-org.openai.azure.com/...
api_key_source = "azure_ad"

对于管理员强制执行的设置，请使用 requirements.toml。对于命令行的一次性覆盖，请使用 -c / --config 标志并采用点号表示法（例如 codex -c api_base_url=https://... exec "your task"）。

第 8 章 详细介绍了企业部署。

首次会话

您已经看过演示；现在亲自尝试一下。克隆快速入门仓库并启动 Codex CLI：

git clone https://github.com/danielvaughan/codex-quickstart-example
cd codex-quickstart-example
codex

输入演练中使用的相同任务：

Find the bug in main.js and fix it. Run the tests before and after to confirm the fix.

预期会出现演练会话所示的情况：读取文件、运行测试、进行一次或多次编辑、可能出现智能体回退的错误尝试，最终测试套件全部通过。结果是文件系统上真实的差异，并由通过的测试确认，而不是需要您手动应用的建议。

如果智能体在读取文件或运行命令前暂停以请求许可，这是审批模式在起作用，而非故障。第 5 章 解释了各种模式及如何更改默认设置。

第一周常见的三个错误

几乎每个人在第一周都会犯同一类少数错误。这些错误都不严重，现在跳过它们比吃一堑长一智要快得多。

  1. 像聊天一样对待它，且任务描述不足。 “清理一下认证代码”没有给智能体提供任何验证标准，因此它会自行定义“清理”的标准并为此运行数分钟。解决方法是设定完成标准：指明文件、期望的更改、以及必须通过的测试。第 3 章 专门讲述这一点。

  2. 打断第一个您不同意的编辑。 正如演练所示，第一次编辑往往是探测性的。智能体刚做出您不会做的举动就将其叫停，会移除使其有用的“测试-纠正”循环。让它完成一轮，再阅读差异。

  3. 在没有测试和 AGENTS.md 的情况下运行。 没有测试，智能体无法判断是否成功；没有 AGENTS.md，它不知道运行哪个测试命令、遵循哪些约定，只能两者都猜。本章后面所述的最小化 AGENTS.md 只需十分钟，便能在第一次真实会话中收回成本。

codex 与 codex exec 的区别

codex（不带参数）启动交互式 REPL：一个带有对话历史的持久会话。用于交互式工作：探索、多步骤任务和学习。

codex exec 非交互式运行并在完成时退出。用于脚本任务、CI/CD 流水线和定义明确的自动化：

codex exec "update all TypeScript interfaces in src/types/ to add the new userId field"
codex exec --json "analyse test coverage and report modules under 80 per cent"

一个实用的启发式判断：如果您会将其输入终端，请使用 REPL。如果您会将其写入 Makefile，请使用 codex exec。

配置文件位置

Codex CLI 从多个来源解析配置；后加载的条目会覆盖先加载的。

~/.codex/config.toml：用户级默认值（模型、审批模式、沙箱设置）：

model = "gpt-5.5"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

Codex 启动时读取的环境变量：

| 变量 | 用途 |

| --- | --- |

| CODEX_HOME | Codex 状态根目录：配置、认证、日志、会话和技能 |

| CODEX_API_KEY | 单次非交互式 codex exec 运行的 API 密钥 |

| CODEX_ACCESS_TOKEN | 用于可信自动化的 ChatGPT 或 Codex 访问令牌 |

| CODEX_CA_CERTIFICATE | 具有企业 TLS 中间人拦截环境的 PEM CA 证书包 |

| RUST_LOG | CLI 和应用服务器的日志过滤和详细程度 |

解析顺序（后者优先）：内置默认值、~/.codex/config.toml、项目 .codex/config.toml、命令行标志。

一分钟了解 AGENTS.md

AGENTS.md 是位于您仓库根目录的普通 Markdown 文件，Codex CLI 在每次会话开始时会自动读取。您可在其中记录智能体无法从源代码推断的项目特定知识：测试命令、包管理器、遵循的约定、不应修改的文件。

一个最小化的 AGENTS.md 如下所示：

项目：支付服务

构建与测试

  • 安装：npm install

  • 测试：npm test

约定

  • 全程使用 async/await；不使用 .then() 链

  • 金额以整数（分）表示，绝不使用浮点数

请勿修改

  • src/legacy/ — 已弃用，只读

  • 任何匹配 *.generated.ts 的文件

文件可组合：~/.codex/AGENTS.md 设置个人默认值，仓库根目录设置项目默认值，子目录可覆盖两者。路径越深，指令越具体。

AGENTS.md 在全书中被反复引用。第 4 章 专门介绍它：应包含什么、不应包含什么，以及如何在项目演进过程中保持其实用性。

现状

你现在已拥有一个可用的 Codex CLI 安装、一个已认证的会话、一次在真实仓库上的首次运行，并对配置和项目上下文的位置有了了解。这是基础。本书后续的所有内容都建立在此基础之上。

下一个投入产出比极高的技能是提示词工程。Codex CLI 对具体性的奖励程度是对话式工具无法比拟的，因为模糊的提示词不会产生模糊的答案；它会产生一次可能持续数分钟、并可能触及你意想不到的文件的运行。第 3 章 介绍了高效提示词的四要素、在运行中引导会话的斜杠命令，以及在常见任务中行之有效的模式。请在下一次非简单会话前阅读该章。

摘要

  1. CLI 是 Codex 四大界面之一。 CLI、桌面应用、IDE 扩展和云端共享同一智能层、配置和记忆。

  2. 系统要求。 Codex CLI 需要 Node.js 22 或更高版本，可在 macOS、Windows（原生或 WSL2）和 Linux 上运行。

  3. 安装并验证。 使用 npm install -g @openai/codex、brew install --cask codex 或直接下载二进制文件。运行 codex --version 进行确认。

  4. Shell 补全加速日常使用。 在开始编写提示词前，为 bash、zsh 或 fish 设置好补全。

  5. 三种认证路径。 订阅制使用设备码流程，API 访问使用 OPENAI_API_KEY，托管部署使用企业配置。

  6. 交互式 REPL 与脚本化执行。 codex 是日常工作的交互式 REPL；codex exec 是用于脚本和 CI/CD 的无头模式。

  7. 配置分层解析。 三个层级，具有明确的解析顺序；更近的设置覆盖更远的设置。

  8. AGENTS.md 是项目约定文件。 一个 Codex 在会话开始时自动读取的 Markdown 文件。用于项目约定、测试命令和禁区文件。第 4 章 深入介绍。

练习

练习 2-1。 安装 Codex CLI，运行 codex --help，并找出三个你之前不知道的标志。为每个标志写一句话，解释何时使用它。

练习 2-2。 使用“AGENTS.md 一分钟上手”部分的最小示例，在当前项目中创建一个包含测试命令、一条编码约定和一个禁区目录的最小 AGENTS.md。运行一次会话，观察指令是否生效。第 4 章 介绍完整模式。

练习 2-3。 在一个有界任务上运行 codex exec（“查找所有 TODO 注释并生成列出它们的 TODOS.md”）。然后以交互方式运行同一任务。对比交互式会话向你展示了什么而 codex exec 没有展示。

第三章：高效提示 Codex CLI

第 1 章 和 第 2 章 介绍了入门与设置：Codex CLI 是什么、它如何定位、如何安装。本章开始讲述决定本书其余部分是否物超所值的两项技能。第一项是提示词工程，本章介绍：非提示词工程理论，而是适用于能读取代码库、执行命令、一次运行数分钟的智能体编码工具的具体模式。第二项是 AGENTS.md，见 第 4 章。为 Codex CLI 编写提示词，不像填写搜索框，更像在把办公室钥匙交给承包商前对其进行简报。

学习目标

你将能够：

  1. 编写包含目标、上下文、约束和完成标准的提示词

  2. 设置可跨会话持久传递上下文的 AGENTS.md 文件

  3. 识别导致浪费运行的提示词反模式，并应用相应修复

  4. 使用 Codex CLI 生成和维护项目文档

为何 Codex CLI 提示词与众不同

单个提示词可触发一系列工具调用——读取文件、运行测试、编写代码——运行数分钟后才返回供审查的内容。当模糊指令显现为问题时，Codex CLI 可能已触及十几个文件。³⁰

这改变了清晰度的经济学。在对话式 AI 中，模糊可恢复：你可以廉价迭代。在智能体 AI 中，模糊代价高昂。Codex CLI 还可能自信地做出技术上合理但对你的项目错误的选择，因为你从未告诉它此处“正确”是什么样子。

高效的 Codex CLI 提示词在于在执行开始前消除歧义。

模糊运行的代价

### 提示词 A
改进订单处理代码。
### 提示词 B
重构 src/orders/process.ts，将嵌套回调链替换为 async/await。不要更改公共函数签名。每次文件更改后运行 npm test，仅当所有测试通过时才继续。

提示词 A 让 Codex CLI 自行决定“改进”意味着什么、触及哪些文件以及何时停止。提示词 B 明确指定了这三点。差别在于：数分钟的算力浪费和数十个不想要的文件更改。

高效提示词的构成

以下四要素可靠地出现在产生良好结果的提示词中：

目标：用一个具体句子描述“完成”是什么样子。使用结果导向动词：“添加”、“修复”、“迁移”、“替换”。

上下文：语言版本、框架及一个类比代码片段：“遵循 src/api/users.ts 中的模式”。

约束：Codex CLI 不应做什么。不引入新依赖。不修改数据库模式。不触碰 src/legacy/ 中的文件。

完成标准：一个具体的、可运行的检查：“GET /api/posts?page=2&limit=20 返回正确的 JSON，且 npm test 以代码 0 退出”。

目标：为 /api/posts 端点添加分页。
上下文：Express.js 应用，通过 pg-pool 使用 PostgreSQL，遵循 src/api/users.ts 中现有的模式（基于游标的分页）。
约束：不修改数据库模式。不添加新 npm 包。不更改 /api/users 端点。
完成标准：GET /api/posts?cursor=<id>&limit=20 返回正确的页面和 next_cursor 字段。现有测试仍通过。运行 npm test。

提示词中的一个具体示例胜过一段抽象解释。

四要素提示词也隐含了范围。最佳切入点是同事能在一个下午完成、具有明确前后状态的任务。更小的任务浪费结构化提示的开销；更大的任务应拆解为里程碑或交给规划模式（本章后述）。

推理力度

Codex CLI 允许你调整模型在行动前思考的深度。model_reasoning_effort 设置以延迟和 Token 成本换取推理深度。更高力度并非总是更好：对于单行重命名，high 仅消耗 Token；对于跨模块重构，low 产出的浅层变更会遗漏架构隐患。

表 3-1. 推理力度级别

| 级别 | 配置值 | 最佳适用场景 |

| --- | --- | --- |

| minimal | model_reasoning_effort = "minimal" | 大规模运行的微小转换：格式化工具、批量重命名、CI 中的文件模板生成 |

| Low | model_reasoning_effort = "low" | 快速编辑、重命名操作 |

推理工作量配置

| 值 | 配置 | 适用场景 |

|---|---|---|

| medium | model_reasoning_effort = "medium" (默认) | 大多数交互式编码任务 |

| high | model_reasoning_effort = "high" | 复杂算法、跨模块重构 |

| xhigh | model_reasoning_effort = "xhigh" | 架构决策、安全审查 |

在 ~/.codex/config.toml 中设置推理工作量，按配置文件区分，或在会话中通过 /model 命令修改：

#### ~/.codex/config.toml — 用户级默认配置
model_reasoning_effort = "medium"
#### ~/.codex/refactor.config.toml — 一个提高难度工作工作量的配置文件
model_reasoning_effort = "high"

使用 codex --profile refactor 激活该配置文件。

规划模式

对于模糊或多步骤的任务，请先调用规划模式。按 Shift+Tab 切换模式，或输入 /plan。

/plan Propose a migration strategy for moving our auth from sessions to JWT

规划模式将 Codex CLI 置于上下文收集状态：它会读取代码库，识别歧义，并在更改任何文件之前生成结构化计划。

| 场景 | 使用方式 |

|---|---|

| 单文件、明确定义的变更 | 直接执行 |

| 跨模块变更 (3+ 模块) | 规划模式 |

| 需求模糊 | 规划模式 |

| 紧凑的调试循环 | 直接执行 |

规划模式的“无写入”约束在提示词层面强制执行，而非通过运行时沙箱。对于高风险工作，请使用临时分支。

用于多小时任务的 PLANS.md

对于跨越数小时或多个会话的任务，创建一个持久化的 PLANS.md 并在 AGENTS.md 中引用：

#### ExecPlan: <功能名称>
##### 目的 / 全局视角
##### 进度
- [ ] 步骤 1 --- 描述 (开始于: 2026-03-27T09:14Z)
- [x] 步骤 2 --- 描述 (完成于: 2026-03-27T09:32Z)
##### 决策日志
| 日期 | 决策 | 理由 |
##### 具体步骤
##### 验收与验证

关键属性是 自包含性：ExecPlan 必须使智能体能够在无外部上下文的情况下端到端地实现该功能。

这种规范可以形式化为 PLANS.md 技术：在编写任何代码之前，在 PLANS.md 文件中编写基于里程碑的计划。详见 第 4 章。

检查点模式

使用中间验证步骤构建长提示词：

将遗留认证模块迁移到新的认证服务。
每步完成后：(1) 所有测试通过，(2) 无 TypeScript 错误，(3) 变更已提交。

步骤：
1. 将令牌验证逻辑提取到 src/auth/validate.ts
2. 更新中间件以使用新模块
3. 删除 src/auth/legacy.js
4. 更新代码库中所有的导入

迭代提示与会话中纠偏

如果 Codex CLI 走偏了，请立即中断。按 Esc 停止当前步骤（REPL 底部的状态指示器显示 esc to interrupt 表示步骤正在运行）。然后输入纠正指令。会话中纠偏遵循与初始提示词相同的结构：“停止。撤销对 src/db/schema.ts 的更改，改为在 src/db/migrations/ 中处理迁移。”

当累积历史挤占近期决策时使用 /compact。使用 /fork 从同一起点探索两种方法。当会话因提示词有两种有效解释而产生错误结果时，停止并重写提示词，而非在纠偏上迭代。第 7 章 深入介绍了 /compact 和 /fork，包括上下文窗口如何填充、压缩保留与丢弃的内容，以及何时在冒险操作前进行分叉。

常见任务的提示词模式

Bug 修复

包含观察到的行为、预期行为和复现步骤：

Bug: 结账页面因卡片过期抛出未处理的 Promise 拒绝。
观察到: 服务器日志中出现 "CardError: card_expired"。用户看到 500 页面。
预期: 用户看到 "Your card has expired. Please update your payment method."
复现: 运行 __tests__/checkout/payment.test.ts "handles expired card" 用例。
修复位置: src/checkout/payment.ts。包含回归测试。
不要修改 src/payments/stripe.ts。

重构

明确要求保留行为：

重构 src/notifications/sender.ts：将 .then()/.catch() 替换为 async/await。
公共 API 必须不变。每个函数修改后运行 npm test。不要修改其他文件。

可并行化工作

明确告知 Codex CLI 任务相互独立：

并行为这三个模块编写单元测试：
- src/auth/validate.ts
- src/payments/process.ts
- src/notifications/sender.ts
使用 __tests__/helpers.ts 中的辅助函数和 __tests__/auth/token.test.ts 中的模式。

文档生成

Codex CLI 不仅是代码编写工具，也是高效的文档生成器。其读取整个代码库并推理代码结构的能力，使其适合生成和维护项目文档。

代码文档

Codex CLI 可以为整个代码库生成符合语言规范的文档注释：

为 src/api/ 中所有导出的函数添加 JSDoc 注释。
遵循 src/api/users.ts 中的现有风格。
包含 @param、@returns 和 @throws 标签。
不要修改任何实现代码。

对于 Python 项目，相同模式适用于 docstrings：

为 src/services/ 中所有公共函数添加 Google 风格的 docstrings。
包含 Args、Returns 和 Raises 部分。
遵循 src/services/auth.py 中的模式。

关键在于指定文档风格（JSDoc、Google 风格、NumPy 风格、rustdoc）并指向现有示例。没有风格参考时，Codex CLI 生成的文档虽正确但不一致。

架构决策记录 (ADR)

架构决策记录 (ADR) 记录重大技术决策背后的推理。Codex CLI 可以根据代码上下文和简短提示起草 ADR：

为从 Express 迁移到 Fastify 的决策编写 ADR。
阅读 src/api/ 中的现有 Express 路由和 src/api-v2/ 中的新 Fastify 路由。包含背景、决策、后果及考虑的替代方案。保存至 docs/adr/0012-fastify-migration.md。
遵循 docs/adr/0001-template.md 中的格式。

README 与引导文档

对于新项目或文档滞后的项目，Codex CLI 可以通过读取仓库结构、依赖和配置来生成引导文档：

为该项目生成 README.md。阅读 package.json、src/ 目录结构和现有的 AGENTS.md。包含：
- 项目概述（一段话）
- 先决条件和安装步骤
- 开发工作流（构建、测试、Lint）
- 项目结构概览
- 贡献指南
不包含徽章或盾牌。

将文档时效性作为 CI 任务

文档腐烂——即文档描述的代码已不复存在——是常见问题。Codex CLI 可检测此问题：

codex exec --sandbox read-only \
 "对比 docs/api.md 中记录的公共 API 与 src/index.ts 中的实际导出。列出文档中记录但已不存在的函数，以及存在但未记录的函数。" \
 -o /tmp/doc-audit.md

将其作为定期 CI 检查运行，在文档漂移累积前发现它。

将持久化上下文移出提示词

AGENTS.md

AGENTS.md 在每个会话开始时自动读取。将约定、约束、构建命令和禁修改文件放在此处：

### 项目: 支付服务
#### 构建与测试
npm run build && npm test
##### 约定
- 全程使用 async/await；禁止 .then() 链
- 错误消息使用句首大写，无尾随句号
- 所有货币金额以整数（分）存储，而非浮点数
#### 禁止修改
- src/legacy/chargebee.ts (已弃用；只读)
- 任何匹配 *.generated.ts 的文件

文件构成：~/.codex/AGENTS.md 设置个人默认值，仓库根目录设置项目默认值，子目录会覆盖两者。³² /init 斜杠命令会在会话中引导生成一个初始文件：这是一种轻松上手的方式，但很少能产生最佳结果。自动生成的文件往往过度描述显而易见的内容，而对真正改变智能体行为的项目特定决策描述不足。请将输出视为待修剪的草稿，而非待提交的文件。第 4 章 全面介绍了 AGENTS.md 的模式与陷阱。

通过配置文件使用自定义指令

AGENTS.md 适用于项目中的每个会话。配置文件仅在你请求时才会应用。当你在不同模式下工作时，这种区别很重要：同一个仓库早上可能是修复 Bug 的目标，下午可能变成架构评审的对象，发布前又可能成为安全审计的靶子。每种模式都需要不同的推理姿态、不同的输出风格和不同的常设指令。如果没有配置文件，你就必须在每次提示词中重新建立这种姿态。

在各自的每配置文件文件 ~/.codex/<name>.config.toml 中定义一个命名配置文件，其中 model_instructions_file 指向你的自定义指令：

#### ~/.codex/bugfix.config.toml
model_instructions_file = "~/.codex/prompts/bugfix.md"
model_reasoning_effort = "high"

使用 codex --profile bugfix 激活。指令文件可能包含：

你是一名一丝不苟的调试员。用一句话阐述根本原因。
包含回归测试。不做投机性更改。

输出控制：塑造智能体的沟通方式

提示工程不仅关乎你对模型说什么；还包括配置模型说什么回复。config.toml 中的多个键控制着冗长度、推理可见性和 Token 管理。这些邻近提示词的控制项在不改变任务指令本身的情况下，塑造了智能体的沟通风格。

冗长度

model_verbosity 键接受三个值：

model_verbosity = "low" # 以代码为主，最少文本
model_verbosity = "medium" # 平衡（默认）
model_verbosity = "high" # 详细演示、架构评论

在仅关注代码输出的自动化流水线中使用 low。在你希望模型用文本解释其推理过程的架构探索会话中使用 high。

冗长度也是成本的直接杠杆。输出 Token 的计费费率高于输入 Token，而文本解释的体量可能远超其伴随的代码。在每天运行数百次的 CI 任务上设置 low 冗长度，可将模型的评论压缩到产生结果所需的最小程度，使成本主要由输入提示词决定，而非运行时的叙述。在长会话中还有次级效应：每一轮助手对话都会成为对话历史的一部分，并在下一轮重放，因此冗长的早期轮次会复合成每次后续调用中更大的前缀。在文本是交付物的地方保持高冗长度；在不是交付物的地方降低它。

推理摘要

model_reasoning_summary 键控制模型的内部推理链是否在输出中被总结。结合 hide_agent_reasoning（完全抑制推理）和 show_raw_agent_reasoning（显示未经编辑的推理链），这三个键让你能将推理可见性从完全隐藏、总结到原始三个层级进行调节。

Token 预算感知

两个键影响智能体管理自身上下文的激进程度：tool_output_token_limit 限制单个工具结果消耗的 Token 数，model_auto_compact_token_limit 设置触发自动压缩的阈值。设置较低的 tool_output_token_limit 可防止单次大文件读取占用不成比例的上下文窗口份额，这在提示跨多文件工作时尤为相关。

常见工作流的配置文件

##### ~/.codex/ci.config.toml — 简练的自动化
model_verbosity = "low"
hide_agent_reasoning = true
model_reasoning_effort = "low"
tool_output_token_limit = 8000

##### ~/.codex/explore.config.toml — 详细的探索
model_verbosity = "high"
show_raw_agent_reasoning = true
model_reasoning_effort = "high"

##### ~/.codex/budget.config.toml — 成本敏感的长会话
model_verbosity = "medium"
model_reasoning_effort = "medium"
model_auto_compact_token_limit = 80000
tool_output_token_limit = 12000

使用 codex --profile ci 激活。这些配置文件可与模型选择配置文件组合，因此你可以将 ci 输出配置文件与快速模型结合，以实现最大的成本效益。

元提示：利用智能体改进自身指令

元提示使用一次 LLM 调用来改进后续调用所使用的提示词。³³ 在 Codex CLI 中，这意味着让智能体分析自身的失败，并针对三个跨会话持久化的指令界面提出具体的编辑建议：AGENTS.md、技能（SKILL.md）和 config.toml。³⁴

这不是一个自我修改的智能体循环。人类仍处于审批路径中。Codex CLI 提出建议；你审查并提交。这种区别很重要：研究表明，未经人工筛选的自我生成指令改进无法产生可衡量的收益，而人工筛选的改进能显著提高通过率。³⁵

模式 1：会后复盘

最简单的元提示模式运行在一个出现偏差的会话结束时：

你刚完成了一个任务，但犯了两个错误：
1. 你运行了 `npm test` 而不是 `pnpm test`
2. 你在一个纯 ESM 项目中创建了一个 CommonJS 模块
请审查当前的 AGENTS.md 并提出一个最小差异补丁，
以防止这两个错误在未来的会话中再次发生。
以围栏式 apply_patch 块的形式输出差异。

模式 2：通过 codex exec 进行批量分析

对于在许多仓库中运行 Codex CLI 的团队：

codex exec "读取 AGENTS.md 和 ~/.codex/sessions/ 中最近 5 次会话的记录。\
找出我覆盖你初始方法的三个最常见修正模式。针对每个模式，\
提出一个具体的 AGENTS.md 补充内容来消除该修正。\
输出为单个 Markdown 文件。" \
 --sandbox read-only \
 -o /tmp/metaprompt-report.md

模式 3：技能细化

技能使用渐进式披露：Codex CLI 最初只能看到名称和描述，仅在激活时才加载完整指令：

我在 ~/.agents/skills/api-scaffold/SKILL.md 处有一个技能。
当我要求创建新的 REST 端点时它应该激活，
但当我在调试现有端点时不应激活。
请审查当前的名称、描述和触发词。
提出更新后的前置元数据以提高激活精确度。
包含三个匹配示例和三个不匹配示例，
供我作为手动测试用例使用。

应避免的反模式

元提示可能会生成冗长、过度具体的规则，导致 AGENTS.md 膨胀超过 32 KiB 限制。每条规则都应通过一个简单测试：这是防止反复出现的失败，还是一次性失误？一次性修正应放在提示词中，而非配置文件中。

官方工作流配方：八大规范模式

OpenAI 的开发者文档包含一个专门的工作流页面，将跨软件开发生命周期使用 Codex CLI 的八大规范模式编纂成册。³⁶ 每个配方共享一个通用骨架，该骨架将本章开头的四要素提示词结构形式化：目标、上下文、约束 和 完成条件。³⁷

表 3-2. 八大官方工作流配方

| # | 配方 | 沙箱模式 | 关键技术 |

| --- | --- | --- | --- |

| 1 | 解释代码库 | read-only | @ 文件模糊搜索 + /plan 模式 |

| 2 | 修复 Bug | workspace-write | 粘贴错误输出，定义通过标准 |

| 3 | 编写测试 | workspace-write | 参考实现 + 现有测试规范 |

| 4 | 从截图生成原型 | workspace-write | -i 图像输入 + 高推理力度 |

| 5 | 将重构委托给云端 | workspace-write | 本地 /plan 然后云端提交 |

| 6 | 本地代码审查 | read-only | /review 斜杠命令 |

| 7 | 审查 GitHub PR | read-only | PR 评论中的 @codex 或 codex exec |

| 8 | 更新文档 | workspace-write | 交叉引用代码 + 文档，PostToolUse linter 钩子 |

配置文件消除了在不同工作流之间切换时的摩擦：

##### ~/.codex/explore.config.toml
sandbox_mode = "read-only"
model_reasoning_effort = "high"

#### ~/.codex/fix.config.toml
sandbox_mode = "workspace-write"
approval_policy = "on-request"

#### ~/.codex/review.config.toml
sandbox_mode = "read-only"
approval_policy = "never"

总结

  1. 智能体提示要求预先明确。 模糊的提示会发动一次持续数分钟、可能触及众多文件的运行；而对话式提示可以容忍歧义，这是智能体提示做不到的。

  2. 优秀提示的四要素。 目标、上下文、约束条件和可运行的完成标准。

  3. 持久化上下文存放在 AGENTS.md 中。 适用于每个提示的规则应放在文件中，而非在每次调用中重复。

  4. 规划模式与检查点。 规划模式在代码变更前生成可审查的策略；检查点将长任务构建为可验证的增量步骤。

  5. 重构框架优于持续纠错。 当会话偏离轨道时，停下来重新构建框架通常比强行纠错更划算。

  6. 元提示需要人工策划。 让模型改进自身的指令文件，经人工审查后的效果优于自动提交。

  7. 基于配方的提示与配置文件。 OpenAI 的八个官方工作流配方将基于“目标-上下文-约束-完成条件”结构的可复用模式固化下来。命名配置文件无需重新配置即可在配方类别间切换。

  8. 文档生成。 Codex CLI 可以将生成和维护代码注释、ADR、README 及新鲜度审计作为 CI 任务。

练习

练习 3-1：编写一个四要素提示。 选取一个最近完成的任务，使用目标、上下文、约束条件和完成标准编写一个 Codex CLI 提示。

练习 3-2：审查并扩展你的 AGENTS.md。 添加三条未记录在案的团队约定及具体示例。运行一个会话并观察默认行为是否发生变化。

练习 3-3：在跨领域变更上使用规划模式。 对涉及五个或更多文件的变更运行 /plan。在批准执行前审查计划。

练习 3-4：标记可并行化的工作。 编写一个显式标记独立子任务的提示。对比其与顺序执行等效方案的会话时长。

练习 3-5：生成文档。 运行 Codex CLI 为未文档化的模块添加文档注释。然后运行一次新鲜度审计，将文档与实际 API 表层进行对比。记录审计发现的任何差异。

第四章：AGENTS.md：模式与陷阱

在 第 3 章 中，你学习了如何编写提示来引导 Codex CLI 完成单个任务：清晰地界定目标，提供正确的上下文，限定范围。这项技能很重要，但提示是易失的。每个新会话都从空白开始，如果你的团队发现 Codex CLI 提交前需要运行 make test，或者绝不能触碰 src/generated/ 下的生成文件，就得有人每次都记得说一遍。将这乘以十名工程师每天运行数十个 Codex CLI 会话，Codex CLI 默认行为与项目实际需求之间的鸿沟就会成为每天的摩擦来源。

AGENTS.md 弥合了这一鸿沟。它是一个你提交到代码仓库、或存放在主目录作为个人默认值的 Markdown 文件，Codex CLI 在每次会话开始时会自动读取它。不妨将其视为 AI 协作者的成文宪法：无论你要求什么任务，都适用的固定规则、项目约定和硬性限制。第 3 章 关注单个提示的艺术，而本章关注的是让每个提示都变得更好、且无需重复的基础设施。

学习目标

你将能够：

  1. 使用本章提供的初始模板从头编写一个完整的 AGENTS.md

  2. 使用分层 AGENTS.md 文件构建单体仓库，使每个服务或包都能获得精准所需的指令

  3. 诊断规则为何不生效并追踪活跃的指令链

  4. 在不破坏依赖行为的前提下精简臃肿的 AGENTS.md

  5. 以与生产代码相同的版本控制纪律对待指令文件

  6. 在更广泛的 .md 文件生态系统（AGENTS.md、DESIGN.md、SKILL.md、SOUL.md）中定位 AGENTS.md，以实现全面的智能体配置

AGENTS.md 是什么以及 Codex CLI 如何读取它

AGENTS.md 是一个纯 Markdown 文件。Codex CLI 不对其施加任何模式要求；任何合法的 Markdown 皆可。其特殊之处在于 Codex CLI 何时 以及 如何 读取它：在你的提示之前，自动地，在每次运行时。^(³⁸)

发现链

Codex CLI 通过从最宽泛的作用域向最狭窄的作用域遍历文件系统，拼接沿途发现的每一个 AGENTS.md 来构建其指令集。完整的解析顺序如下：

1. ~/.codex/AGENTS.override.md <- 最高优先级的全局覆盖
   或 ~/.codex/AGENTS.md <- 标准全局默认值
2. <git-root>/AGENTS.override.md <- 仓库覆盖（优于仓库 AGENTS.md）
   或 <git-root>/AGENTS.md <- 标准仓库规则
3. <intermediate-dirs>/AGENTS.override.md <- 根目录与当前目录之间每个中间目录
   或 <intermediate-dirs>/AGENTS.md
4. <cwd>/AGENTS.override.md <- 调用 Codex CLI 的目录
   或 <cwd>/AGENTS.md

拼接顺序意味着：当内容冲突时，距离更近的文件优先于距离更远的文件。你主目录下的 AGENTS.md 设定个人默认值；仓库根目录下的 AGENTS.md 设定团队默认值；子目录下的 AGENTS.md 设定特定服务的规则。每一层都可以在上层基础上增加、收紧或覆盖任何内容。

https://github.com/OpenDocCN/freelearn-dl-zh/tree/master/docs/agentic-coding-with-openai-codex-cli/img/B40007_04_01.jpg

图 4.1 - AGENTS.md 发现链

AGENTS.md 发现链的自顶向下流程图。Codex CLI 从最宽泛的作用域遍历到最狭窄：~/.codex 下的全局文件，然后是 Git 根目录下的仓库根文件，接着是任意中间目录文件，最后是当前目录文件。每一层级中 .override.md 变体优于普通 .md 变体。四个层级拼接成单一指令集，距离更近的文件在冲突时获胜。

有几个操作细节从一开始就值得了解：

  1. Codex CLI 每次运行都会重新构建此链；编辑文件后无需清理缓存。

  2. 空文件会被静默跳过；它们不会重置或中断链条。

  3. 所有加载文件的总大小受 project_doc_max_bytes 设置上限限制，默认为 32 KiB。超出该限制的文件会被静默截断。^(³⁹)

  4. 同一层级的 .override.md 变体优于普通 .md 变体。

Codex CLI 解析的是 Git 根目录，而非当前工作目录，作为 步骤 2 的起点。如果你从 services/payments/ 内部调用 Codex CLI，发现链从仓库根目录开始，然后向下穿过中间目录到达你的当前位置。这意味着仓库根规则始终适用，即使身处深层子目录。

文件长什么样

没有强制的结构要求。实践表明，效果最好的文件会被划分为少数几个重点章节，用通俗易懂的祈使语气编写，以便 Codex CLI 能够毫无歧义地遵循。以下是一个 TypeScript Web 服务的最小示例：

### 项目：结账服务
#### 概述
用于结账流程的 Node.js REST API。使用 TypeScript 编写，使用 Vitest 测试，通过 GitHub Actions 部署到 AWS Lambda。
#### 命令
- 构建：`npm run build`
- 测试：`npm test` （运行 Vitest；提交前必须通过）
- 代码检查：`npm run lint`
- 类型检查：`npm run typecheck`
##### 提交约定
- 使用约定式提交：`feat:`、`fix:`、`chore:` 等。
- 限定受影响的模块：`feat(cart): add coupon validation`
- 绝不直接提交到 `main` —— 始终通过 PR
#### 风格
- 已启用 TypeScript 严格模式；切勿使用 `any` 或 `// @ts-ignore`
- 导入在每组内按字母顺序排序（ESLint 强制执行此项）
- 所有异步函数显式返回 `Promise<T>`
#### 约束
- 切勿修改 `src/generated/` 下的文件 —— 它们是根据 OpenAPI 自动生成的
- 未在 PR 描述中列出的情况下，切勿安装新依赖
- 所有新端点必须在 `tests/integration/` 中包含集成测试

请将“命令”部分保持在文件顶部。Codex CLI 在决定如何验证自己的工作时会反复引用该部分。它找到测试命令的速度越快，就越不大可能自行编造一个。

分层思维：宪章、专家、技能

扁平的 AGENTS.md 非常适合中小型项目。一旦代码库超过约 20,000 行，你可能会发现单个文件变得难以驾驭。三层知识架构直接映射到 Codex CLI 现有的基元。^40

| 层级 | 角色 | Codex CLI 映射 | 加载时机 |

| --- | --- | --- | --- |

| T1：宪章 | 不可协商的规则、路由表 | AGENTS.md | 每次会话 |

| T2：专家 | 领域特定的专业知识 | 每个领域区域专用 AGENTS.md | 按任务类型 |

| T3：知识库 | 参考规范、API 文档 | MCP 服务器 | 按需查询 |

宪章（第 1 层）就是你已经熟悉的 AGENTS.md。它保持精简，不超过 500 行，仅包含每个会话都需要的内容：编码标准、架构边界、禁止模式，以及（至关重要的是）告诉代理何时委托给专家的路由规则。第 1 层文件内的路由表使委托变得显式：

#### 专家路由
| 如果任务涉及 | 首先阅读 |
|---|---|
| 支付流程、Stripe、退款 | `services/payments/AGENTS.md` |
| 认证、会话、JWT | `services/auth/AGENTS.md` |
| 数据库迁移 | `infra/db/AGENTS.md` |
| 其他任何情况 | （无专家；继续使用此文件） |

第 2 层存放如果内联包含会导致宪章膨胀的深度领域知识。专家文件是相关子目录中的一个 AGENTS.md：

#### services/payments/AGENTS.md
##### 范围
属于 PCI-DSS 范围。此处所有代码每年接受审计。
##### 硬性规则
- 切勿记录完整 PAN 或 CVV；仅保留后四位掩码。
- 所有金额以最小单位（分）计算；切勿使用浮点数。
- 新端点必须在 `tests/pci/` 下添加固定数据。
### 工具
- 使用 `pnpm run test:pci`（而非 `pnpm test`）；PCI 套件需要沙箱网络。

第 3 层将很少需要的参考资料推至 MCP 服务器后端，保持上下文窗口精简。第 8 章 将全面介绍 MCP。

第一天不需要具备所有三个层级。大多数项目仅靠第 1 层就能愉快地运行。

核心章节：提交、测试、风格

大多数高效的 AGENTS.md 文件都汇聚于同一组章节。这反映了仅从源代码中难以让语言模型推断出的信息类别。

命令

这是最重要的章节。列出 Codex CLI 可能需要运行以验证其工作的每一条命令：

#### 命令
- 安装依赖：`npm ci`
- 构建：`npm run build`
- 单元测试：`npm test`
- 集成测试：`npm run test:integration` （需要 Docker；CI 中若不可用则跳过）
- 代码检查：`npm run lint -- --fix`
- 类型检查：`npm run typecheck`
- 本地开发服务器：`npm run dev` （端口 3000）

要明确说明先决条件。集成测试行中的“需要 Docker”告诉 Codex CLI 不要在 Docker 不可用的环境中运行该命令。

提交约定

如果你的项目遵循提交信息格式（如约定式提交^41），请在此声明。否则，你将得到通用的提交信息：

##### 提交约定
- 格式：`<type>(<scope>): <description>`
- 类型：feat、fix、docs、style、refactor、test、chore
- Scope 为必填；使用模块或包名称
- 描述使用祈使语气、小写、无尾随句点

约束与禁区

这是你防止 Codex CLI 做出初衷良好但具有破坏性更改的地方：

#### 约束
- 切勿修改：`src/generated/`、`schema/migrations/`、`package-lock.json`
- 未经批准切勿安装包
- 切勿更改环境变量名 —— 它们在部署配置中被引用

“切勿”这种措辞是刻意的。否定性指令对硬性限制更可靠。

AGENTS.md 不是安全边界。代理可以在提示词中被指示忽略它。对于你真正必须保护的文件，请使用文件系统权限或仓库分支保护规则。AGENTS.md 是指导，而非强制执行。

供应链注入风险。 因为 AGENTS.md 文件以最大信任加载并跨会话持久化，它们成为供应链攻击的诱人目标。任何在依赖解析期间执行任意代码的构建系统均存在漏洞：Go init()、Python setup.py、Node.js postinstall、Rust build.rs。^42

防御模式： 使用锁文件固定依赖。将 AGENTS.md 加入代码审查清单，并以审查 CI 配置同等严谨的态度对待其变更。考虑使用 PreToolUse 钩子，在会话开始时验证 AGENTS.md 内容是否与已知良好的哈希值匹配。第 16 章 深入介绍了供应链风险和验证钩子。

单体仓库与多服务仓库的 AGENTS.md

推荐结构

my-monorepo/
+-- AGENTS.md <- 3-4 KiB：仓库布局、全局 CI 命令、共享约定
+-- services/
| +-- api/
| | +-- AGENTS.md <- 2 KiB：Node/TypeScript 规则、API 特定模式
| +-- payments/
| | +-- AGENTS.override.md <- 2 KiB：覆盖父级宽容度的 PCI 规则
| +-- frontend/
| +-- AGENTS.md <- 2 KiB：React 约定、Vitest 设置、CSS Modules
+-- infra/
 +-- AGENTS.md <- 2 KiB：Terraform 模式、切勿触碰状态文件

当 Codex CLI 在 services/api/ 中工作时，它会加载仓库根目录加上 services/api/AGENTS.md：约 5 到 6 KiB 聚焦、相关的指令。它看不到 Terraform 规则或支付 PCI 约束。

AGENTS.md 长度限制

Codex CLI 对所有加载的 AGENTS.md 文件的总大小有上限。配置键 project_doc_max_bytes 控制此上限；默认值为 32 KiB。超出上限的部分会被静默截断，终端或日志中无任何警告。^43 前面展示的分层结构是主要防御手段：通过分发指令，每次调用仅加载相关子集。

静默截断意味着大型 AGENTS.md 底部附近的规则可能永远不会被读取。请将最重要的约束放在文件顶部，而非底部。

用于 CI/CD 流水线的覆盖文件

在自动化流水线中，生成一个临时的覆盖文件：

cat > .codex/AGENTS.override.md << 'EOF'
#### CI Mode
- Never ask clarifying questions---make your best judgment and proceed
- Always run the full test suite before completing any task
- If tests fail, explain the failure and stop; do not attempt a fix
- Do not make commits; only propose changes as diffs
EOF
codex exec "$TASK" --sandbox workspace-write
rm .codex/AGENTS.override.md

AGENTS.md 并非 Codex CLI 独有。该规范已捐赠给 Linux 基金会旗下的 Agentic AI Foundation (AAIF)。超过 30 款 Agent 产品原生读取 AGENTS.md，包括 GitHub Copilot、Cursor、Gemini CLI、Jules、Windsurf、Amp、Devin、Aider、JetBrains Junie、Zed、Warp 和 Factory。社区推荐遵循 80/20 法则：将 80% 的指令写入 AGENTS.md，仅针对真正需要特定工具功能的部分维护专用文件。

常见错误

诊断：规则为何不生效

你写了约束，但 Codex CLI 却忽略了它。在认定是 Bug 之前，请先检查指令链：

codex --ask-for-approval never \
 "List the AGENTS.md files you loaded this session, in order, with their full paths."

表 4-1. AGENTS.md 常见诊断场景

| 症状 | 可能的原因 |

| --- | --- |

| 覆盖规则不生效 | 文件名错误：应使用 AGENTS.override.md，而非 AGENTS-override.md |

| 编辑后旧规则仍然生效 | 更近的 AGENTS.override.md 仍在覆盖你更新后的 AGENTS.md |

| 文件被静默忽略 | 文件为空，或合并链已达到 project_doc_max_bytes 限制 |

| 规则在错误目录生效 | Codex CLI 从 Git 根目录解析；请从目标目录运行 |

| 约束生效不一致 | 规则被埋没在截断点之下 |

文件为何会无限膨胀

AGENTS.md 文件一开始并不大。它们最初只有三四行。问题在于增长曲线。每当 Agent 做错事，本能反应就是添加一条指令。每次添加单看都合情合理。但合在一起却造出了另一个问题。

苏黎世联邦理工学院 (ETH Zurich) SRI 实验室的研究发现，LLM 生成的上下文文件与完全没有上下文文件相比，会使任务成功率降低 3%，同时将推理成本增加 20% 以上。人工编写的文件仅使成功率提高 4%，但成本最高增加 19%。真正能带来正面结果的内容，具体指非标准工具指令和不可推断的团队决策，而非架构概览或框架约定。

切勿在未经过彻底的逐行人工审查的情况下，提交 /init 或任何其他自动生成命令的输出。生成的文件听起来准确，但在你精简冗余内容之前，它们会主动损害 Agent 性能。

精简清单

一次性通读你的 AGENTS.md，应用以下检查：

是否关于仓库结构、架构或布局？ 删除。Agent 通过阅读仓库来导航。

是否为通用最佳实践？ 删除。这些已内化于模型中。

是否描述框架约定？ 删除。模型知晓这些。

是否与 README 内容重叠？ 删除。你在为重复内容买单。

能否移至嵌套的 AGENTS.md？ 如果仅与特定子目录相关，请下沉至该目录。

能否移至 Skill 文件？ 如果仅在特定工作流期间相关，则应放入按需加载的 Skill 文件中。

收录测试：添加内容前的四项检验

仅当指令同时通过以下四项检验时，才值得收录：

  1. 有失败案例支撑。 你在可复现的模式中见过 Agent 在无此指令时失败。

  2. 不可推断。 该信息无法通过直接阅读代码库发现。

  3. 始终相关。 该指令适用于该目录下的大多数任务。

  4. 可触发。 你能描述一个具体场景，其中遵循该指令会产生可度量的不同结果。

文件映射模式

研究表明，导航是编码 Agent 的主要失效模式，占所有 Agent 失效的 27% 至 52%。文件映射直接解决此问题：

#### File Map
##### Core Application
- `src/api/routes/` --- HTTP 路由处理器；每个文件映射一个 API 资源
- `src/api/middleware/` --- Express 中间件（认证、限流、错误处理）
- `src/services/` --- 业务逻辑；无直接数据库访问；由路由处理器调用
- `src/models/` --- Sequelize 模型定义；每表一个文件
##### Generated (DO NOT MODIFY)
- `src/generated/` --- OpenAPI 代码生成输出；构建时重新生成
- `prisma/client/` --- Prisma 客户端；从 Schema 重新生成
##### Tests
- `tests/unit/` --- 镜像 `src/` 结构；使用 `npm test` 运行
- `tests/integration/` --- 依赖 Docker；使用 `npm run test:integration` 运行

文件映射将探索问题转化为查找问题，减少消耗 Token 的目录读取操作。

生产模式：openai/codex 案例研究

openai/codex 仓库（为 Codex CLI 提供支持的 Rust 工作区）自带 AGENTS.md 文件。六大模式可迁移至任何项目：

  1. 编码反直觉约定。 精确的异步 Trait 签名、命名分离（协议字段用 camelCase 但配置用 snake_case）。

  2. 用具体命令把关质量。 UI 变更后运行 just test -p codex-tui，Cargo.toml 变更后运行 just bazel-lock-update。

  3. 设定模块大小上限。 模块不超过 500 行（不含测试），超过 800 行的文件标记为需拆分。

  4. 划定禁区。 禁止修改沙箱隔离代码。

  5. 抵制重力井式增长。 将新代码引导远离单体中央 crate。

  6. 以表格形式编码 API 约定。 表格 Token 效率高且无歧义。

超越 AGENTS.md：延伸模式

AGENTS.md 之所以有效，是因为它是 Agent 会自动读取的纯 Markdown 文件。该公式可推广。团队开始使用同形不同名的文件处理相关事务：不同的文件名，将持久上下文钉入 Agent 会拾取的 Markdown 中这一核心理念相同。生态系统是非正式的（无委员会裁定何者算数），但实践中已稳定出一小组文件。

表 4-2. 常与 AGENTS.md 搭配使用的文件

| 文件 | 用途 | 范围 | 生命周期 |

| --- | --- | --- | --- |

| AGENTS.md | 常驻规则与约定 | 命令、约束、禁区文件 | 项目生命周期 |

| PLANS.md | 执行路线图 | 当前计划的里程碑 | 数天至数周 |

| SKILL.md | 程序性知识 | Agent 可执行的特定任务 | 跨项目复用 |

| DESIGN.md | 视觉 / UX 约定 | Token、组件、交互模式 | 项目生命周期 |

| SOUL.md | Agent 人设 | 语气、口吻、拒绝风格 | 每 Agent / 每角色 |

| WORKFLOW.md | 多 Agent 编排 | 子 Agent 如何移交工作 | 每工作流 |

最成熟的延伸是 PLANS.md。第 3 章 引入了该模式；此处阐述其背后的原则。OpenAI Codex 产品负责人 Alex Embiricos 建议：在编写任何代码前，先生成基于里程碑的计划至 PLANS.md。一次执行一个里程碑，提示 Codex CLI 在每步前读取 PLANS.md，并在进入下一步前用发现更新它。AGENTS.md 编码适用于每个会话的常驻规则；PLANS.md 编码当前计划的执行路线图。二者合一，赋予 Agent 项目的“宪法”与“行军令”。

最小化 PLANS.md 示例：

PLANS.md — 认证迁移

目标

将认证方式从会话 Cookie 迁移到 JWT，实现零停机。

里程碑

决策日志
  • 2026-05-02: v1 版本拒绝使用刷新令牌 —— 会增加我们目前不需要的令牌轮换工作。

SKILL.md 是次具体的文件。Codex CLI 自身的技能格式是一个带有 YAML 前置元数据的 Markdown 文件，按需发现而非每个会话都加载：

---
name: docstring-pass
description: 当 Python 文件的公共函数缺少 Google 风格文档字符串时使用。如果文档字符串已存在则跳过。
---
为每个公共函数（无前导下划线）添加包含 Args、Returns 和 Raises 部分的 Google 风格文档字符串。遵循 `src/services/auth.py` 中的模式。请勿更改实现代码。

第 10 章 全面介绍了技能。

DESIGN.md 标准化程度较低，但当项目拥有代理需遵守的设计系统时很有用：

#### DESIGN.md

##### 调色板（`src/ui/tokens.css` 中的令牌）

- 主色：`#0F62FE`
- 表面亮色：`#FFFFFF`；深色：`#161616`

##### 间距

4px 基准。使用 `--space-1` … `--space-8`；切勿硬编码像素值。

##### 组件

按钮遵循 `src/ui/Button.tsx` 中的变体模式。新按钮必须扩展现有变体，而非引入新形状。

SOUL.md 和 WORKFLOW.md 较少见，惯例仍在形成中。当你有反复出现的需求时使用它们：SOUL.md 用于具有独特语气的代理角色（例如代码审查代理绝不应使用模棱两可的语言），WORKFLOW.md 用于多个子代理按定义顺序交接工作的编排。第 27 章 在完整工具链中实战演练了 WORKFLOW.md。

惯例仍属非正式，但 SOUL.md 通常包含四个部分：角色、语气、拒绝风格和边界。以下是为安全痴迷型审查代理（前文提到的代码审查角色）具体化的一个例子：

#### SOUL.md — 安全审查代理

##### 角色

作为一名偏执的应用安全工程师审查代码。寻找入侵路径；不要表扬正常工作的部分。将每个变更集视为敌对输入，直到被证明安全。

##### 语气

直接且具体。无模棱两可之词（“这可能……”），无夹心饼干式表扬。按顺序陈述漏洞、影响、修复方案 —— 附带文件和行号。若不确定，直说而非掩饰。

##### 拒绝风格

只要存在未分类的发现就不予签署；绝不为讨好而批准。若被要求跳过检查，点明被要求接受的风险，并在继续前要求明确确认。

##### 边界

- 优先标记密钥泄露、注入、认证缺口和不安全反序列化。
- 仅编写演示发现所需的最小证明代码，绝不编写武器化利用代码。
- 严守范围：仅限人设与姿态。绝不削弱项目的批准策略或沙箱设置以简化任务。

SOUL.md 应塑造语气与判断，而非偷偷塞入指令：加载这些文件的工具越来越多地会扫描提示词注入模式，因此该示例中的最后一条边界发挥了实质作用：它防止人设悄悄放宽 第 6 章 明确建立的信任模型。

所有情况的模式一致：Markdown 作为代理自主读取的配置面。大多数团队仅需 AGENTS.md。仅当同一测试适用时才引入第二个文件：有失败支撑、不可推断、在其作用域内始终相关。

你现在的位置

第 1 部分 到此结束。你可以安装 Codex CLI、运行会话、编写值得其运行数分钟的提示词，并将持久上下文放入 AGENTS.md。这是信任模型的软性一面：代理会读取并遵循的指令。

指令只是建议。它们塑造 Codex CLI 倾向于做什么；无法阻止其做你未预期之事。信任模型的硬性一面是批准策略和沙箱模式：决定代理被允许采取哪些操作、以及操作系统将阻止哪些操作（即使代理尝试）的配置旋钮。这正是 第 6 章 的内容，也是第 2 部分的开始。

摘要

  1. AGENTS.md 让 Codex CLI 成为可靠的协作者。 没有它，代理虽有能力但健忘。Codex CLI 通过拼接从 ~/.codex/ 到仓库根目录再到当前工作目录的 AGENTS.md 文件来解析指令链，冲突时以更近的文件为准。

  2. 四大核心板块。 命令、提交约定、代码风格和约束。

  3. 大小限制是静默的。 project_doc_max_bytes（默认 32 KiB）会在无警告下截断，因此请将关键规则置前。

  4. 单仓分层。 子目录 AGENTS.md 文件让每个服务仅接收相关指令。

  5. 拥有广泛支持的开放标准。 AGENTS.md 在 Linux 基金会治理下，获得 30 余款代理产品支持。

  6. LLM 生成的上下文损害性能。 苏黎世联邦理工学院研究发现，仅非标准工具指令和不可推断的团队决策能带来正向结果。

  7. 添加任何指令前的四项测试。 有失败支撑、不可推断、始终相关、可触发。

  8. 像对待代码一样对待 AGENTS.md。 在拉取请求中评审变更，编写有意义的提交信息，并安排季度清理周期。

练习

  1. 为你参与的项目编写一份 AGENTS.md。重点关注命令板块。

  2. 对你的新 AGENTS.md 运行三问题验证测试。答案与你所写是否一致？

  3. 选取一个单体仓库，勾勒分层 AGENTS.md 结构。哪些规则属于仓库根目录，哪些属于服务层级？

  4. 清理行动。 对现有 AGENTS.md 应用清理清单。将每条指令分类为：架构类（移除）、通用最佳实践（移除）、框架约定（移除），或不可推断的团队决策（保留）。

  5. 移除实验。 移除一条你认为有用的指令。运行五个代表性任务。代理行为是否改变？

第二部分：护栏

第五章：批准模式与信任边界

第 4 章 介绍了 AGENTS.md：塑造 Codex CLI 行为的软约束。指令仅是建议，建议无法阻止代理做你未预期之事。

本章讲述硬约束。两个设置决定 Codex CLI 被允许尝试什么、以及操作系统即便代理尝试也会允许什么：批准策略和沙箱模式。二者共同构成一个可调信任模型，范围从只读检查到全自动执行。知晓哪种组合适配任务、哪种组合不安全，是驾驭代理的核心操作技能。

学习目标

你将能够：

  1. 根据任务类型和信任级别选择合适的批准模式

  2. 在 config.toml 中配置文件系统范围、网络允许列表和细粒度批准类别

  3. 应用批准模式阶梯，随信心增长逐步扩大 Codex CLI 的自主权

信任模型：Codex CLI 能触及什么

Codex CLI 采取的每个行动都落入两类之一：观察世界的动作（读取文件、列出目录、获取文档）和改变世界的动作（写入文件、运行 Shell 命令、发起网络请求）。信任模型回答：哪些变更操作需要你显式签署，哪些操作应由操作系统无条件阻止？

Codex CLI 将其拆分为两个独立控制：

审批与沙箱：核心概念

  1. --ask-for-approval（短标志 -a）控制程序边界：Codex CLI 必须在何时暂停并请求人工确认后方可继续。

  2. --sandbox（短标志 -s）控制技术边界：操作系统允许什么，独立于审批是否被请求或授予。

这种分离是关键洞见。你可以拥有无审批提示的沙箱、无沙箱的审批提示、两者兼有，或两者皆无。表 5-1 列出了常见配置映射。

表 5-1. 常见审批与沙箱组合

| 用例 | --ask-for-approval | --sandbox |

| --- | --- | --- |

| 审计陌生代码库 | untrusted | read-only |

| 交互式本地开发 | on-request | workspace-write |

| CI/CD 流水线 | never | workspace-write |

| 临时容器，无限制 | never | danger-full-access |

三种审批模式

--ask-for-approval 标志接受三个值。可将其视为信任阶梯。

Untrusted：最高谨慎

-a untrusted 是最严格的设置。已知安全的读操作自动运行；每个状态变更步骤（文件写入、命令执行、网络请求）在 Codex CLI 继续之前都需要显式批准。当你探索陌生代码库并希望在任何事情发生前确切查看 Codex CLI 的提议时，这是正确模式。

考虑典型场景：你克隆了一个从未见过的遗留单体仓库，想让 Codex CLI 勾勒迁移计划。在你完整审查提议前，不想有任何文件被触动。codex -a untrusted -s read-only "analyze the authentication module and draft a refactoring plan" 提供该保证。

On-request：实用默认值

-a on-request 是交互式会话的默认值。Codex CLI 在沙箱边界内自由运行，仅在需要超出边界时暂停：写入工作树外的目录，或在网络未启用时访问网络。对大多数交互式开发，这是务实的最佳平衡点。

Never：全自动流水线

-a never 完全禁用审批提示。除非你也禁用了沙箱，否则沙箱仍处于激活状态。在沙箱边界内，没有任何东西会暂停等待人工输入。这适用于没有人工可响应的 CI/CD 流水线。

在具有网络访问权限的生产目录中使用 never 是真正危险的配置。如果你的工作目录包含部署脚本、基础设施清单或凭据，且你启用了网络访问，一次误导性的运行就能对真实系统做出真实更改。

never 适用与不适用的场景

适用场景：

  1. 无网络访问的格式化和代码检查通过，范围限定在源码树

  2. 具有隔离测试的模块测试生成

  3. 从源码注释生成文档

  4. 数据库迁移生成（非应用），无实时凭据

不适用场景：

  1. 可能需要安装依赖的任何任务（网络 + 无审批 = 宽广攻击面）

  2. 触及控制部署目标的配置文件的重构通过

  3. 包含 .env 文件、API 密钥或机密的任何目录中的会话

在运行全自动会话前，用相同提示快速跑一遍 -a untrusted -s read-only 并审查 Codex CLI 说它会做什么。这种干运行只需两分钟，已让许多工程师避免了不愉快的惊喜。

行业跳过审查的压力

AI 编码代理生成代码的速度比人类编写或审查快数倍，由此产生结构性问题：提示代理的开发者无法再有意义地审查产出。一些组织没有将此视为加强审查的信号，而是开始将拉取请求视为拖慢 AI 生成输出的瓶颈。

行业目前的应对是堆叠更多代理：代理生成的代码由代理审查者审查，由代理测试者测试。正如一位前 GitHub 高级工程师所言：“不完美系统堆叠在不完美系统上不会收敛于完美。” 对无机密模块的格式化通过，自动审批无妨。但当任务涉及医疗系统、金融平台或数百万人依赖的基础设施时，审批步骤不是瓶颈：它是最后一道防线。

沙箱：文件系统与网络限制

--sandbox 标志控制操作系统允许什么，独立于 Codex CLI 或你想要什么。三个值定义递增的权限级别。

  • -s read-only 允许无文件写入，且无命令执行除非显式批准。代理可读取其有文件系统访问权的任何内容，但不能更改任何东西。

  • -s workspace-write 允许在当前工作目录及默认的 /tmp 和 $TMPDIR 内进行读写。出站网络访问关闭。这是交互式开发的推荐基线。

  • -s danger-full-access 移除所有文件系统和网络限制。它适用于容器本身提供隔离的环境，如作业后销毁的一次性 CI 运行器。

在 config.toml 中配置沙箱

approval_policy = "on-request"
sandbox_mode    = "workspace-write"

当 sandbox_mode 为 workspace-write 时，可调整范围：

[sandbox_workspace_write]
writable_roots = ["/home/dan/shared-fixtures"]

writable_roots 将写入权限扩展到当前工作目录之外。单次调用的等效参数是 --add-dir <path>。

网络访问与网页搜索

network_access 是二元开关：开或关。此层无逐域名允许列表。要么允许沙箱进程的所有出站请求，要么全不允许。关闭是 workspace-write 的默认值，大多数交互式会话可保持在此。仅为需要的运行开启：

[sandbox_workspace_write]
network_access = true

网页搜索是独立控制，有自己的设置。它允许代理在运行期间查阅开放网络信息：错误消息、库文档、特定版本语法、近期公告。如“查找最新 React 发布说明中的破坏性变更并更新迁移计划”这类提示，仅当 web_search 启用时才有效；否则代理仅限于其训练数据和已读取的本地文件。

web_search = "cached"   # "cached" | "live" | "disabled"

cached 设置（默认）使用预索引搜索索引，降低提示注入风险。live 设置启用实时搜索但增加攻击面。对大多数工作流，cached 是正确选择。

workspace-write 模式下网络访问默认关闭是常见困惑来源。如果你的代理任务包含安装包、获取 API 模式或克隆仓库，必须显式设置 network_access = true 或接受运行时的升级提示。

组合快捷标志

现在两个杠杆都有了名称，常见组合更易陈述。对本地开发，显式组合 -a on-request -s workspace-write 是大多数会话所用。对于需要关闭两种控制的强化流水线，单个组合标志即可：

### 低摩擦本地开发
codex -a on-request -s workspace-write
### 硬化容器内的 CI/CD 流水线：无审批，无沙箱
codex --dangerously-bypass-approvals-and-sandbox   # 别名：--yolo

--yolo 完全绕过两种控制。仅当执行环境本身提供隔离时适用：流水线运行后销毁的一次性容器。在开发者工作站运行 --yolo 非预期用例。

内核级沙盒

Sandbox_mode 设置是一种可移植的抽象，但强制执行机制因平台而异。

macOS: Seatbelt

在 macOS 上，Codex CLI 会在运行时生成 沙盒配置文件语言 (SBPL) 脚本并将其传递给 sandbox-exec，这是 Apple 的内核级沙盒工具。由于强制执行发生在内核系统调用级别，因此用户空间中运行的任何东西（包括 Codex CLI 本身）都无法绕过它。

Linux: bubblewrap 和 seccomp

Linux 沙盒是一个两阶段过程。外层阶段使用 bwrap（bubblewrap）对文件系统进行命名空间隔离：系统路径以只读方式绑定挂载，而写入访问权限被限制在配置的根目录内。内层阶段应用 PR_SET_NO_NEW_PRIVS 和 seccomp 系统调用过滤器，防止权限提升或超出精选允许列表的系统调用。

对于大多数威胁模型，Linux 沙盒比 macOS 沙盒有意义地更强。命名空间隔离、文件系统访问控制和系统调用过滤的组合提供了纵深防御。对于强化的自动化流水线，配置得当的 Linux 容器是更成熟的选择。

Windows: 受限令牌和 ACL

Windows 沙盒使用专用的低权限用户账户和 Win32 安全原语。存在两种子模式：elevated（首选，使用具有文件系统 ACL 和防火墙规则的专用沙盒账户，需要一次性管理员设置）和 unelevated（备选，使用来自当前用户的受限令牌）。对于托管的企业部署，强烈推荐 elevated。

命名配置文件

Codex CLI 暴露了两个相关但不同的配置文件命名空间。了解两者的区别可避免此领域最常见的配置错误。

  1. 命名配置文件 将会话级设置（模型、审批策略、沙盒模式、MCP 服务器）打包在单个配置文件 ~/.codex/<name>.config.toml 中，通过 --profile <name>（别名 -p）按调用激活。传递 --profile <name> 会先加载 ~/.codex/config.toml，然后叠加 ~/.codex/<name>.config.toml。

  2. [permissions.<name>] 定义文件系统和网络规则集，并通过 default_permissions 键激活。内置的 :read-only / :workspace / :danger-full-access 预设位于此命名空间中，将在以下小节中介绍。

配置文件将模型、审批策略和沙盒模式打包成可复用的配置集：

##### ~/.codex/strict.config.toml
model = "gpt-5.5"
model_reasoning_effort = "high"
approval_policy = "untrusted"
sandbox_mode = "read-only"

#### ~/.codex/auto.config.toml
approval_policy = "never"
sandbox_mode = "workspace-write"

codex --profile strict "audit this PR for security issues"
codex -p auto "fix all lint warnings"

每个配置文件位于各自的 <name>.config.toml 文件中；--profile 不会从 config.toml 读取 [profiles.<name>] 表。配置文件值会覆盖用户级配置，但会被显式的 CLI 标志覆盖。

TUI 权限选择器

交互式 TUI 暴露了一个简化的选择器，用于在会话中途更改权限。它显示的标签不是新模式；它们是将权限配置文件与两个现有配置键结合的表现层预设：approval_policy（本章前面已介绍）和 approvals_reviewer（选择由谁回答审批提示）。

approvals_reviewer 接受两个值：

  1. user（默认）将每个审批提示路由给你。

  2. auto_review 将提示首先路由给代理；代理决定该操作是否足够冒险而转发给你。

三个选择器条目映射到底层设置如下。

表 5-2. TUI 权限选择器映射

| TUI 标签 | 权限配置文件 | approval_policy | approvals_reviewer |

| --- | --- | --- | --- |

| Ask for approval | :workspace | on-request | user |

| Approve for me | :workspace | on-request | auto_review |

| Full Access | full access (sandbox disabled) | never | n/a |

“Ask for approval” 和 “Approve for me” 共享相同的沙盒和相同的 approval_policy。唯一的区别是审查者：“Approve for me” 将首轮审查交给代理本身，这也是其描述为“仅针对检测到的潜在不安全操作提问”的原因。如果你想要选择器当前的默认行为写入 config.toml，等效配置为：

default_permissions = ":workspace"
approvals_reviewer = "auto_review"

选择器会根据上下文隐藏某些预设。例如，workspace-write 会话将不会显示“Read Only”条目，即使底层预设列表中存在此项。当你需要选择器隐藏的设置时，请使用 config.toml 或 -c 覆盖。

内置配置文件

Codex CLI 随附三个内置配置文件，以冒号为前缀：

  • :read-only：无写入，无命令执行。适用于审查和探索。

  • :workspace：在项目工作区内读写，允许命令，默认禁用网络。受保护路径（.git/、.agents/、.codex/）保持只读。这是推荐的默认值。

  • :danger-full-access：移除所有限制。不推荐用于生产环境。

内置配置文件通过 ~/.codex/config.toml 中的 default_permissions 键激活，不是通过 --profile 标志（后者会将用户定义的单个配置文件 ~/.codex/<name>.config.toml 叠加到你的配置上）：

default_permissions = ":workspace"

要为单次运行覆盖默认值，请使用通用的 -c 配置覆盖在命令行传递该键：

codex -c default_permissions=':read-only' "audit this PR for security issues"

显式的 -a 和 -s 标志仍会覆盖配置文件，因此无需编辑配置即可进行一次性的 -a never -s danger-full-access 运行。

配置文件继承

配置文件通过配置层组合支持继承。平台团队在系统层定义限制性基线；项目团队通过仅添加其服务所需内容来扩展它：

#### /etc/codex/config.toml (system layer)
[permissions.secure-base]
description = "Restrictive baseline for hosted runners"
[permissions.secure-base.filesystem]
":workspace_roots"."." = "write"
":workspace_roots"."**/*.env" = "deny"
[permissions.secure-base.network]
enabled = true
[permissions.secure-base.network.domains]
"api.openai.com" = "allow"
"registry.npmjs.org" = "allow"

#### .codex/config.toml (project layer)
[permissions.payments]
extends = "secure-base"
[permissions.payments.network.domains]
"api.stripe.com" = "allow"

payments 配置文件继承 secure-base 的每一条规则，并在其之上仅添加 Stripe 域名。extends 键是组合分层权限集的文档化方式：扩展系统层基线的项目层配置文件将接收基线的所有规则，无需重述。基线中声明为 deny 的规则不能被扩展配置文件重新启用，因此高信任层可以为其下的所有内容锁定 .env 访问权限。

细粒度审批类别

对于想要按类别控制而非统一 never 的流水线：

[approval_policy.granular]
sandbox_approval    = true
rules               = true
mcp_elicitations    = false
request_permissions = false
skill_approval      = true

每个键切换该类别是否可以暂停运行以等待审批。使用此设置，技能和规则仍可提示，而 MCP 引导和权限请求将在不阻塞流水线的情况下处理。

权限阶梯

权限阶梯随着你对 Codex CLI 的理解和信心增长，授予其更多自主权。从将代理拴在紧绳子上开始，观察它在你的代码库中的行为，随着你积累证据表明其行为符合预期，一次放松一级绳索。

权限阶梯

  1. 第 1 阶段：审计模式。 untrusted + read-only。将实际任务交给 Codex CLI，但仅允许其观察和提出建议。审查每一个建议的操作。目标是理解：在代理能够做出任何更改之前，先建立其擅长什么、哪里会出错的心智模型。

  2. 第 2 阶段：监督写入。 untrusted + workspace-write。信任代理写入文件，但运行命令前仍需批准。审查建议的写入操作，批准看起来正确的，拒绝或修改其余的。留意你例行批准的操作类别；这些就是可以晋升到下一阶梯的操作。

  3. 第 3 阶段：按需批准。 on-request + workspace-write。信任代理自行处理常规操作。只有当它需要跨越边界时（例如写入工作树之外或访问网络），你才会被打断。大多数团队在交互式工作中都停留在此阶段。

  4. 第 4 阶段：选择性自动化。 never + workspace-write（或 CI/CD 流水线内的作用域配置文件 ~/.codex/<name>.config.toml）。信任度已足够高，以至于每次运行都无需人工在环；流水线定义和周围的容器成为监督层。

当证据支持时晋升一阶，当出现意外情况时退回一阶。经验丰富的用户一旦了解代理在特定仓库中的行为，可能会跳过某些阶梯；高风险环境可能会无限期停留在早期阶梯。每个阶段的原则都是一样的：每个阶梯都是一种你可以在承诺使用前进行测试和验证的配置。

https://github.com/OpenDocCN/freelearn-dl-zh/tree/master/docs/agentic-coding-with-openai-codex-cli/img/B40007_05_01.png

图 5.1 - 权限阶梯

一个四阶段阶梯，展示信任如何从最底层增长到最顶层：

  • 第 1 阶段 审计模式 (untrusted + read-only)

  • 第 2 阶段 监督写入 (untrusted + workspace-write)

  • 第 3 阶段 按需批准 (on-request + workspace-write)

  • 第 4 阶段 选择性自动化 (never + workspace-write)

向上箭头标注为“信任增长”，向下箭头表明当出现意外情况时可以退回一阶。

每个命令独立批准

批准范围绝不超出你所确认的单个命令。在多步骤运行中，每个命令都独立受控：批准 npm install 不会批准同一 Shell 代码块中随后的 rm -rf node_modules。如果代理需要再次提权，你会看到另一个提示。

目前的定论

批准策略和沙箱模式决定了代理被允许尝试什么。它们没有说明由哪个模型来尝试，也不涉及该模型在行动前思考多么努力。第 6 章将转向模型选择和推理努力：这两个设置决定了你刚刚设定的边界内每一步的质量、延迟和成本。

总结

  1. 两个独立的杠杆。 批准策略（代理何时询问）和沙箱模式（操作系统允许什么）。

  2. 三种批准模式构成阶梯。 untrusted（所有操作均需询问），on-request（边界处询问），never（无提示）。

  3. 三种沙箱模式定义技术边界。 read-only、workspace-write、danger-full-access。

  4. 内核级强制执行。 macOS 上的 Seatbelt，Linux 上的 bwrap+seccomp，Windows 上的受限令牌；无法从用户空间绕过。

  5. 命名权限配置文件。 将设置捆绑成可复用、可继承的配置，采用“拒绝优先”的冲突解决机制。

  6. 渐进式信任。 从限制性开始，随信心增长而放宽；权限阶梯就是这条进阶路径。

  7. 纵深防御。 两层必须同时同意才能执行任何操作，为你提供了两个独立的安全推理维度。

练习

练习 5-1。 在你的 config.toml 中创建三个命名权限配置文件：一个用于只读代码审查，一个用于交互式开发，一个用于 CI/CD。在所有三个配置下运行同一任务，观察代理行为如何变化。

练习 5-2。 使用 -a untrusted -s read-only 运行任务作为干运行，然后使用 -a on-request -s workspace-write 运行同一任务。对比 Codex CLI 提出的操作与实际执行的操作。找出一个如果没有先看到干运行结果你会拒绝的操作。

练习 5-3。 配置一个细粒度批准策略，自动批准沙箱操作但要求批准 MCP 引导。运行一个使用 MCP 服务器的任务，观察批准流程与全局 never 策略有何不同。

第六章：模型选择与推理努力

第 5 章涵盖了批准模式：决定 Codex CLI 被允许做什么的杠杆。一旦你设定了边界，还有两个设置决定代理在边界内工作得有多好、每次运行成本多少：由哪个模型执行任务，以及该模型在回答前思考多么努力。

模型选择设定了能力的上限。推理努力决定了模型在任何给定请求上距离该上限有多近。两者任一设置错误都会浪费额度：在琐碎查找上使用昂贵的旗舰模型属于过度设计，而在困难的架构问题上使用轻量级模型会产出浅薄的工作，日后反而让你付出更大代价。

学习目标

你将能够：

  1. 在 config.toml 中配置持久化的模型和努力默认值，并在每次调用时覆盖它

  2. 构建命名配置文件，通过单个标志在日常驱动、深度调查和节省额度配置之间切换

  3. 使用快速推理控制在活动会话期间改变推理深度

  4. 设计多模型工作流，将推理预算分配到回报最大的地方

模型角色，而非模型名称

OpenAI 按自己的节奏发布新模型并弃用旧模型。具体名称（撰写时为 gpt-5.5、gpt-5.4-mini、gpt-5.3-codex-spark）变化速度快于任何印刷页面的追踪速度。本章不将建议锚定在你阅读时可能已不存在的名称上，而是使用基于角色的类别，它们映射到当前相应角色所指向的任何模型。

表 6-1. 模型角色及其特征

| 角色 | 特征 | 典型用途 |

| --- | --- | --- |

| 旗舰 | 最大上下文、最高能力、最高成本 | 研究、复杂推理、最高基准性能 |

| 通用 | 能力与成本的良好平衡、可通过 API 密钥访问 | 日常驱动、CI/CD、编排、通用开发 |

| 快速/迷你 | 较小上下文、最低成本、最高吞吐量 | 子代理工作、批处理、额度敏感型会话 |

| 编码专家 | 为代码生成优化、高吞吐量 | 大容量终端编码、安全审计、长时程会话 |

请查看 developers.openai.com/codex/models 了解角色到模型名称的当前映射。codex --help 输出也会列出可用模型。

使用 --model（短标志 -m）、config.toml 中的 model 键，或交互式会话中的 /model 命令来设置活动模型：

codex -m gpt-5.5 "refactor the authentication module"
##### ~/.codex/config.toml
model = "gpt-5.5"

能力与成本并非完全相关

快速/迷你模型并非通用模型的“弱化版”；它是针对不同工作优化的不同模型。对于有界子任务、文件级分析和探索，它能以极低成本提供适当的质量。将其视为“更便宜但更差”忽略了其设计意图。

推理努力

推理努力控制模型在响应前思考的深度。共有五个级别可用；第 3 章在提示词设计背景下介绍过它们，同一张表在此同样适用：

| 级别 | 行为 | 适用场景 |

| --- | --- | --- |

| Minimal | 无思维链 | 简单转换：格式化、批量重命名、CI 模板生成 |

| Low | 最小思维链，响应快速 | 快速编辑、重命名操作、查找 |

| Medium | 平衡推理深度（默认） | 通用开发、中等复杂度任务 |

| high | 扩展推理，速度较慢但更彻底 | 架构决策、复杂调试、安全审计 |

| Xhigh | 最大推理预算 | 高风险架构决策、安全评审、困难根因分析 |

在 config.toml 中、每次调用时或会话期间设置推理力度：

model_reasoning_effort = "medium"
codex -c model_reasoning_effort=high "design the database schema for the new billing module"

快速推理控制

在交互式会话期间，无需重启即可调整推理力度：

  1. Alt+, 降低推理力度（例如，从 medium 降为 low）

  2. Alt+. 提高推理力度（例如，从 medium 升为 high）

当会话从探索阶段（低力度）转向复杂实现决策（高力度）再转回时，这很有用。更改在下一次模型调用时生效。

命名配置文件

配置文件将模型、推理力度和其他会话设置捆绑为可复用的配置。正如第 5 章所述，每个配置文件位于各自的文件中，即 ~/.codex/<name>.config.toml，其设置作为顶层键；--profile <name> 先加载 ~/.codex/config.toml，然后在其之上覆盖匹配的配置文件：

##### ~/.codex/config.toml
model = "gpt-5.5"
model_reasoning_effort = "medium"
#### ~/.codex/deep.config.toml
model = "gpt-5.5"
model_reasoning_effort = "high"
approval_policy = "untrusted"
sandbox_mode = "read-only"
#### ~/.codex/quick.config.toml
model = "gpt-5.4-mini"
model_reasoning_effort = "low"
#### ~/.codex/ci.config.toml
model = "gpt-5.5"
model_reasoning_effort = "medium"
approval_policy = "never"
sandbox_mode = "workspace-write"
codex --profile deep "audit this module for security vulnerabilities"
codex -p quick "fix all lint warnings"
codex -p ci "run the migration and verify tests pass"

配置文件值会覆盖用户级配置，但会被显式 CLI 标志覆盖。优先级为：CLI 标志 > 配置文件 > 项目配置 > 用户配置 > 默认值。

模型路由决策框架

既然有多种模型可用，为每项任务选择合适的模型就是一流的工程决策。从顶部开始遍历图 6.1中的决策树，在第一个“是”处停下；如果每个问题答案都是“否”，则通用模型为默认值。

https://github.com/OpenDocCN/freelearn-dl-zh/tree/master/docs/agentic-coding-with-openai-codex-cli/img/B40007_06_01.jpg

图 6.1 - 模型路由决策树

决策树包含四个自上而下堆叠的是/否菱形判断框。第一个询问是否涉及复杂推理或需要最大能力，“是”则路由至旗舰模型。第二个询问是否涉及工具使用或通用开发，“是”则路由至通用模型。第三个询问是否为子代理或批量工作，“是”则路由至快速/迷你模型。第四个询问是否为高容量编码流水线，“是”则路由至编码专用模型。连续四个“否”答案将回落至通用模型作为默认值。

错误路由的代价

在一个由十名开发者组成的团队中，每人每天运行五个会话，将所有任务路由至旗舰模型与将常规工作发送至快速模型之间的差价，每月高达数千美元。模型路由并非过早优化；它是大规模场景下的成本管理。

一个实用的启发式方法：如果资深开发者手动完成任务需时不足五分钟，快速/迷你模型足矣。如果任务需要阅读并推理多个文件或做出架构决策，请使用通用或旗舰模型。

多模型工作流

最高性价比的模式是针对工作的不同阶段使用不同模型：

编排者-工作者模式

使用通用模型作为编排者（规划、分解、集成），使用快速模型作为工作者（有界子任务、文件级编辑）：

# 示例：每个子代理通过 agents.<name>.config_file 指向自己的 Codex 配置，
# 该配置携带各自的模型 + 力度设置。
# 第 11 章涵盖完整的子代理配置机制。
[agents.planner]
config_file = "~/.codex/subagents/planner.toml"   # contains model = "gpt-5.5", model_reasoning_effort = "high"
[agents.worker]
config_file = "~/.codex/subagents/worker.toml"    # contains model = "gpt-5.4-mini", model_reasoning_effort = "medium"

编排者推理整体方案并生成工作者执行实现。每个工作者在有界范围内操作，快速模型在此表现出色。编排者整合结果并做出下一个战略决策。

会话阶段路由

在单个交互式会话中，推理力度（以及可选的模型本身）应与当前阶段匹配：

  1. 探索 (low 力度，快速模型)：读取文件、理解结构、提问

  2. 规划 (high 力度，旗舰模型)：设计方案、识别风险

  3. 实现 (medium 力度，通用模型)：编写代码、运行测试

  4. 评审 (high 力度，通用模型)：验证正确性、检查边缘情况

使用快速推理控制（Alt+, / Alt+.）和 /model 在阶段间切换。

https://github.com/OpenDocCN/freelearn-dl-zh/tree/master/docs/agentic-coding-with-openai-codex-cli/img/B40007_06_02.jpg

图 6.2 - 会话阶段路由

状态机展示会话如何在各阶段间流转，每个阶段绑定一种推理力度和一个模型。探索阶段在快速模型上使用低力度，规划阶段在旗舰模型上使用高力度，实现阶段在通用模型上使用中等力度，评审阶段在通用模型上使用高力度。探索通向规划，规划通向实现，实现通向评审；评审可回路至实现、返回探索或结束会话。

云端与本地模型提供商

Codex CLI 不局限于 OpenAI 的模型系列。config.toml 中的 [model_providers] 配置支持映射到 Responses API 契约的自定义提供商。

云端提供商

| 云平台 | 提供商机制 | 用例 |

| --- | --- | --- |

| Azure | Azure OpenAI 模型提供商 | 拥有 Azure 承诺的企业团队 |

| AWS | Amazon Bedrock 原生提供商 | AWS 优先组织 |

| GCP | 自定义模型提供商 (Vertex AI) | Google Cloud 环境 |

配置云端提供商：

model_provider = "azure-openai"
[model_providers.azure-openai]
name = "Azure OpenAI"
base_url = "https://your-org.openai.azure.com"
env_key = "AZURE_OPENAI_API_KEY"
wire_api = "responses"

本地模型提供商

本地推理服务器（Ollama、vLLM、llama.cpp）可使用相同配置模式作为模型后端。本地模型最适合有界的、机械性任务，在这些任务中延迟和成本优势超过了能力差距：

[model_providers.local]
name = "Local Ollama"
base_url = "http://localhost:11434"
wire_api = "responses"

对于 Ollama 或 LM Studio，--oss 标志是内置快捷方式：它让 Codex 将运行路由至本地开源后端，无需你定义 [model_providers.*] 块。Codex 仍需知道使用哪个后端，因此请在 config.toml 中设置一次 oss_provider：

oss_provider = "ollama"   # or "lmstudio"

此后，codex --oss "..." 通过 Ollama 路由。要为单次运行选择不同的本地后端，请使用 --local-provider lmstudio（或 ollama）。

对于更受控的本地配置，请继续使用 [model_providers.*]。当模型 slug 不在 Codex 的内置目录中时，请添加 model_catalog_json 文件，以便 Codex 知道如何呈现和处理该模型：

##### ~/.codex/local.config.toml
model = "qwen3:32b"
model_provider = "local"
model_context_window = 131072
model_catalog_json = "~/.codex/models/local-models.json"

model_context_window 应与本地服务器中配置的上下文相匹配。如果设置过高，Codex 可能会发送比后端所能接受的更多上下文。如果设置过低，Codex 会比必要时机更早进行压缩。Ollama 默认以 40K 窗口提供 qwen3:32b；将其提升至模型 128K 的最大值（131072 tokens）需要在 Ollama Modelfile 中扩展上下文，并拥有足够的 VRAM 作为支撑。

目录 JSON 文件使用与内置目录相同的模式。最小条目需要一个与部署模型名称匹配的 slug、一个人类可读的 display_name、一个简短的 description、以 token 为单位的 context_window，以及 Codex 应提供的推理力度级别：

{
  "models": [
    {
      "slug": "qwen3:32b",
      "display_name": "Qwen3 32B",
      "description": "Local Qwen3 32B served via Ollama",
      "context_window": 131072,
      "supported_reasoning_levels": ["medium"],
      "default_reasoning_level": "medium"
    }
  ]
}

有三个字段值得更仔细地关注。slug 必须与上游提供商期望的名称匹配：qwen3:32b 是 ollama pull 和 ollama run 接受的确切名称，因此 Codex 会原样透传。context_window 应为您的本地部署实际提供的窗口大小（以 token 为单位）。supported_reasoning_levels 是选择器中 Codex 提供的列表。Qwen3 仅有二元选项。

这与基于配置文件的切换不同。使用配置文件时，人工或脚本会在运行开始前选择备用提供商：

codex --profile azure "continue the refactor"

而网关故障转移时，选择发生在请求路径内部。Codex 配置保持稳定：

model_provider = "gateway"
model = "gpt-5.5"

这种稳定性在 CI/CD 和长时间交互会话中非常有用，因为调用者无需知道当前哪个上游是健康的。它还能集中管理策略。团队可以调整路由权重、禁用降级的提供商或添加备用账户，而无需更改每个开发者的 config.toml。

请勿将自动故障转移视为神奇的连续性保障。如果流式传输已开始，随后在响应中途失败，网关可能无法安全地重放该轮次。对非幂等的工具生成请求针对不同模型进行重试，也可能产生不同的计划或不同的工具调用。对于高风险工作，请倾向于在生成开始前进行故障转移，并在网关无法保证干净重试时使其闭合失败。

上游必须足够兼容，以便同一提示词能正常工作。请在故障转移池中保持以下各项对齐：

  1. 模型能力和上下文窗口

  2. Responses API 兼容性和流式行为

  3. 工具调用和结构化输出支持

  4. 安全性和数据保留要求

  5. 认证、配额和账单归属

  6. 解释每个请求由哪个提供商处理所需的日志字段

有意识地测试故障转移。在暂存网关中，强制主提供商返回 429 或超时，并确认 Codex 从备用提供商收到正常响应。同时检查日志：您应该能够重构原始请求、失败的上游、备用上游和最终状态。

https://github.com/OpenDocCN/freelearn-dl-zh/tree/master/docs/agentic-coding-with-openai-codex-cli/img/B40007_06_03.jpg

图 6.3 - 会话阶段路由

架构图。用户会话进入 Codex CLI，后者应用内置重试和指数退避。随后配置文件选择器路由至四条上游路径之一：OpenAI 直连（OpenAI 配额池）、Azure OpenAI（按 Azure 订阅划分配额）、Amazon Bedrock（按 AWS 账户划分配额），或 AI 网关（如 LiteLLM 或 Bifrost）。网关路径增加了跨所有三个上游提供商的虚线自动故障转移边。

监控模型弃用

OpenAI 会定期弃用旧模型。两种认证路径对弃用的处理方式不同：

  1. ChatGPT 认证用户在弃用生效后立即失去对已弃用模型的访问权限；Codex 模型页面会列出受影响的名称，并告知用户更新至当前默认模型。

  2. API 密钥用户通常能保留更长时间的访问权限。Codex 模型页面注明“某些对 ChatGPT 登录已弃用的模型在 API 中可能仍可用”，因此锁定在现已被 ChatGPT 弃用模型上的流水线，可能会继续工作，直到 OpenAI 也从 API 中退役该模型。

这两种结果都不是可靠的保护。ChatGPT 路径在弃用生效的那一刻即中断；API 路径仅仅是延缓了中断。请定期审核您的配置：

grep -rn --include='*.toml' 'model = ' ~/.codex .codex

在 CI/CD 流水线中显式锁定模型，并按计划刻意更新它们，而不是依赖回退行为。

这对您意味着什么

批准策略、沙箱模式、模型与推理深度

批准策略、沙箱模式、模型和推理深度决定了代理可以做什么、由谁来运行以及思考多深。这些设置都不会改变代理能记住多少内容。长会话会撞上另一堵墙：上下文窗口。第 7 章将介绍上下文如何填充、为何呈二次方而非线性增长，以及你可以利用哪些手段在不丢失线索的情况下维持长会话存活。

概要

  1. 使用模型类别而非名称。 旗舰、通用、快速和专用类别能经受住模型名称的更迭；死记每隔几个月就变一次的名称则无济于事。

  2. 推理深度是独立杠杆。 低、中、高三档控制思考深度，独立于模型选择。Alt+, 和 Alt+. 可在会话中途调整。

  3. 命名配置文件捆绑选择。 将模型、推理深度和权限打包成可切换的配置。

  4. 编排器-工作者路由。 将规划发送给旗舰或通用模型，将有边界的子任务发送给快速模型。

  5. 超越 OpenAI。 云服务商（Azure、Bedrock、Vertex AI）和本地推理（Ollama、vLLM）将模型选择范围扩展到了 OpenAI 系列之外。

  6. 多提供商弹性。 配置文件、网关和独立的速率限制池可防止会话被 429 错误终结。

  7. 定期审计。 检查配置中是否有已弃用的模型引用。

练习

练习 6-1. 创建三个命名配置文件：daily（通用模型，中等推理深度）、deep（旗舰模型，高推理深度，只读沙箱）和 quick（快速模型，低推理深度）。在所有三个配置下运行同一重构任务，并对比输出质量、Token 用量和实际耗时。

练习 6-2. 配置一个多模型子代理工作流，编排器使用通用模型，工作者使用快速模型。运行一个需要多文件编辑的任务，观察各角色的 Token 消耗。

练习 6-3. 搭建一个本地模型提供商（Ollama 或类似工具）并定义 local 配置文件。在本地和云端配置文件上分别运行有边界的任务（列出 TODO、格式化文件）。找出本地模型输出质量变得不再足够的任务复杂度临界点。

第七章：上下文窗口管理

第 6 章涵盖了模型选择和推理深度：决定 Codex CLI 在每一步表现优劣的杠杆。这些设置都不会改变另一个约束每个会话的约束：上下文窗口。它是指令、历史、工具结果和代码共享的固定大小内存。每一次文件读取、每一次工具调用和每一条错误消息都会蚕食剩余空间，窗口一满，你就会丢失信息或会话陷入停滞。

本章介绍上下文如何填充、如何降低填充速率，以及子代理委托如何重置计时器。

学习目标

你将能够：

  1. 在会话开始前，估算可用于工具结果和文件内容的 Token 预算

  2. 应用滚动摘要和针对性文件包含，维持长会话存活

  3. 使用 codex resume 和 codex fork 管理会话连续性，且不丢失上下文

  4. 使用规划模式的全新上下文工作流，将规划与实现分离，避免复杂任务耗尽上下文

  5. 使用 project_doc_max_bytes 配置键限制或禁用项目文档加载

  6. 解释双阶段内存管道如何跨会话提取并巩固持久化知识

  7. 描述机密清理、基于差分的遗忘和感知使用的选择如何保持持久化内存的安全与相关性

  8. 应用结构化提示模式，最大化提示缓存命中，将输入 Token 成本降低 70% 至 80%

  9. 评估 MCP 内存服务器，获取比内置内存存活更久的跨会话上下文

二次增长问题

每次 Codex CLI 向模型发送一轮对话时，整个对话历史都会随之发送：你的提示、代理之前的回复、每一条工具调用记录、每一次文件读取、每一段 Shell 输出。每一轮的提示都比上一轮大刚好一轮的大小，会话累计发送的 Token 与轮数呈大致二次方增长：

第 1 轮： 提示 ~2k Token；累计 ~2k
第 5 轮： 提示 ~15k Token；累计 ~40k
第 20 轮：提示 ~80k Token；累计 ~800k
第 50 轮：提示 ~250k Token；累计数百万

会话长度翻倍，累计 Token 大约翻四倍。长会话的成本高得不成比例，上下文压力是加速增长而非线性增长。实际上，自动压缩（本章后文介绍）会将单轮提示控制在模型的上下文窗口限制内，因此上述数字描述的是 Codex 正在积极对抗的趋势，而非稳态。

当会话变慢或变贵时，直觉会去检查当前提示，但真因往往是此前每一轮积累的重量。大量文件编辑（许多 apply_patch 调用）的会话，比轻量只读探索的会话耗尽上下文的速度快得多。

三种内置缓解措施瞄准二次增长问题：

  1. /compact：将当前对话摘要为更短的表征，在保持任务连续性的同时腾出上下文空间

  2. 子代理委托：生成子代理会开启一个全新的上下文窗口；编排器会话保持精简，而工作者独立累积上下文

  3. codex fork --last：在冒险或昂贵阶段前，从一个干净的中间状态分支会话

据此构架：一个会话，一个聚焦任务，在阶段边界刻意重置上下文。

线程恢复与分支：在不重启的情况下保留上下文

Codex CLI 会话是一条线程：一系列存储为带 UUID 的 JSONL 文件的轮次。当上下文压力变得尖锐或会话被中断时，除了从头开始，你还有两个选择。

恢复 重新打开现有线程，从 JSONL 记录重建状态：

codex resume # 打开交互式会话选择器
codex resume --last # 重新打开最近的会话
codex resume <SESSION_ID> # 按 UUID 恢复特定会话

当会话被中断（运行中 Ctrl+C）、超时或需次日继续时使用恢复。代理从最后一轮接手，无需你重述上下文。

分支 从现有线程创建新线程，保持原线程原封不动：

codex fork --last        # 分支最近的会话
codex fork <SESSION_ID>  # 分支特定会话

在活动会话中，/fork 斜杠命令效果相同：它将当前对话克隆到新线程，且不离开 TUI。

在尝试高风险操作前使用分支（若出错可返回分支前状态）、同时探索两种备选方案时、或将任务移交专家而不想丢失父会话上下文时。

resume 和 fork 的会话选择器均支持 ↑↓ 导航、Enter 选择、m 切换按创建时间或最后更新时间排序。

codex fork 在 TUI 中打开分支会话，无 --json 或 --output-schema 模式。CI 程序化用途请用 codex exec resume：它接受会话 ID 和提示，同时支持 --json（标准输出 JSONL 事件）和 --output-schema <FILE> 结构化输出。

什么消耗上下文（什么不消耗）

高效的上下文管理

高效的上下文管理始于了解 Token 的去向。会话的上下文窗口由两大类消费者填充：静态前缀（启动时加载一次：系统提示词、项目文档、工具模式、钩子注入的上下文、持久化记忆）和运行时累积（随每轮对话构建：对话历史、文件读取、Shell 输出、子代理调用）。

表 7-1 列出了每类的主要来源及其典型 Token 成本，后续文字将把这些数字转化为测量工作流。

表 7-1. 上下文消费者及其典型 Token 成本

| 消费者 | 近似 Token 成本 | 备注 |

| --- | --- | --- |

| 系统提示词 | 2,000–4,000 | 由 Codex CLI 默认设置；部分可自定义（参见“自定义系统提示词”） |

| AGENTS.md (项目根目录) | 1,000–3,000 | 会话开始时加载一次 |

| 技能 (每个启用的 SKILL.md) | 每技能 500–4,000 | 通过 skills.config 配置；启用多个技能会迅速累加 |

| 生成的记忆 (memory_summary.md) | 高达 ~5,000 | 启动时注入；可用 /memories 切换 |

| MCP 服务器工具模式 | 每服务器 500–35,000 | 约每工具 150 个 Token；大型服务器（GitHub 风格）占主导 |

| 应用 / 连接器模式 | 每启用的连接器 3,000–35,000 | 通常是最大的单一静态消费者；可用 include_apps_instructions = false 抑制 |

| 钩子注入的上下文 | 每钩子 0–5,000 | SessionStart 钩子可写入 additionalContext |

| 活动的 /plan 或 /goal 状态 | 200–2,000 | 跨轮次持久化，直到清除 |

| 对话历史 (用户 + 助手轮次) | 每次交互 500–2,000 | 持续累积 |

| 文件读取 (工具结果) | ~250 个 Token / KB | 与文件大小成正比 |

| Shell 命令输出 | 每次调用 100–5,000+ | 无上限；编译器输出可能很大 |

| 子代理调用记录 | 200–600 | 仅调用记录；结果摘要各异 |

| 错误消息和堆栈跟踪 | 200–2,000+ | 冗长的运行时 (JVM, .NET) 可能很大 |

| 内联图片或截图 | 1,000–4,000 | 取决于分辨率和编码 |

不消耗上下文的内容同样重要。未读取的文件零成本。目录列表仅消耗列表文本的 Token，而非文件内容。子代理会话在其独立的上下文窗口中运行；只有委托调用记录和返回的摘要出现在父会话中。这种不对称性是委托即上下文管理的基础。

表 7-1 中的 Token 计数基于 GPT 系列的分词器估算。不同提供商使用不同的分词器；请将该表视为规划指南，而非计费单据。

当你需要真实的逐组件细分时，codex debug prompt-input "hello" 会以 JSON 形式打印模型可见提示词的每个组件：系统和开发者消息、工具定义、聚合的 AGENTS.md 内容、钩子注入的上下文等。通过一个小型 Python 脚本对 JSON 进行管道传输，对每个组件分别进行分词并打印每条记录的计数及总计。GPT-5 系列使用 o200k_base 编码，因此请直接针对该编码处理，而非通过模型名称：

codex debug prompt-input "hello" | python3 -c '
import sys, json, tiktoken
enc = tiktoken.get_encoding("o200k_base")
total = 0
for i, item in enumerate(json.load(sys.stdin)):
    role = item.get("role", "?")
    text = "".join(c.get("text", "") for c in item.get("content", []))
    n = len(enc.encode(text))
    total += n
    print(f"{i:>3}  {role:<12}  {n:>6} tokens")
print(f"--- total: {total} tokens")
'

在加载默认配置且无 MCP 服务器的工作区上的典型输出：

  0  developer       9667 tokens
  1  user             944 tokens
  2  user               1 tokens
--- total: 10612 tokens

每行显示一个提示词条目的位置、角色和 Token 成本，随后是会话总计。这种极不均衡的分布正是重点：几乎所有的静态前缀都集中在单个开发者条目中，该条目组装了系统提示词、项目文档、技能和权限说明。当你需要腾出空间时，该条目就是攻克目标。在裸工作区运行此命令，然后在启用或禁用单个配置选项后再次运行，能清晰地显示哪个选项产生了前缀的哪一部分切片。

  1. 3 ↩︎

  2. 22 ↩︎

  3. 23 ↩︎

posted @ 2026-09-23 20:35  绝不原创的飞龙  阅读(47)  评论(0)    收藏  举报