Codex 的隐藏大脑：拆解 OpenAI 官方系统提示词架构与驾驭工程

你和高手之间，差的不是提示词#

你有没有发现一个奇怪的现象：同样用 Codex CLI，有些人一个小时能搞定一个完整功能，从计划到测试一气呵成；而你花了同样的时间，却在反复纠正它的方向，像是在跟一个固执的实习生拉扯。

差别不在模型，也不在你的 Prompt 写得有多花哨。

差别在于，高手们读过一份你可能从未翻阅过的文档：OpenAI Cookbook 里的 Codex 提示词指南。这份指南是 OpenAI 为所有使用 gpt-5.3-codex 或 GPT-5.4 构建自定义 Harness（驾驭系统）的开发者准备的参考手册。它详细记录了 Codex CLI 背后的系统提示词架构、工具定义规范和行为指令模式。

换句话说，这是一份让你理解 Codex「大脑构造」的解剖图。

什么是驾驭工程（Harness Engineering）？#

在深入提示词架构之前，先厘清一个概念。

过去两年，我们一直在谈「提示词工程」（Prompt Engineering），即如何写出更好的指令让 AI 产出更优的结果。但到了 2026 年，当 AI 编程工具从单次对话进化为持续运行的 Agent 时，单纯的提示词已经不够了。

驾驭工程是一门新兴学科，它关注的是如何为 AI Agent 构建一整套运行环境，包括系统提示词、工具接口、状态管理、权限控制和反馈循环。如果说提示词工程是「跟 AI 说话的艺术」，那驾驭工程就是「为 AI 搭建舞台的技术」。

Codex CLI 本身就是一个开源的驾驭系统参考实现。OpenAI 在 Cookbook 中明确表示，codex-cli 是「最佳参考实现」，但他们也为企业客户记录了更多超越开源版本的定制模式。

系统提示词的四大支柱#

Codex 的系统提示词不是一段随意写就的指令，而是由多个精心设计的模块组成。每个模块负责引导 Agent 行为的一个维度。

支柱一：自主行动指令#

系统提示词的核心是一条行动偏好指令：模型应该基于合理假设直接行动，而不是反复追问确认。

这条指令的威力在于，它从根本上改变了 Agent 的工作模式。没有它，gpt-5.3-codex 会在每一步都请求许可，把一个自主工作流降级为「你问我答」的低效对话。有了它，模型会主动收集上下文、制定计划、实施编码、运行测试、迭代修正，全程不需要你额外输入。

这也是为什么你在 Codex CLI 里感受到的「流畅感」并非偶然，而是精心设计的结果。

支柱二：工具优先级体系#

系统提示词建立了一套清晰的工具使用层级：优先使用专用工具，其次才考虑 Shell 命令。

具体来说，文件编辑必须优先使用 apply_patch 工具，而不是退回到 sed、awk 或 echo >> 这类脆弱的 Shell 操作。这个设计有两层考量：一是专用工具更可靠，不容易出现编码问题或意外覆盖；二是专用工具的操作更易于审计和回滚。

如果你在构建自己的 Harness，记住这条原则：给模型提供结构化的工具，而不是让它用通用工具拼凑解决方案。

支柱三：并行工具调用#

这是对性能影响最大的一条指令。系统提示词明确要求模型先思考所有需要的资源，然后通过 multi_tool_use.parallel 一次性批量调用。

对比一下两种模式：

串行模式（低效）： 读取文件 A → 读取文件 B → 读取文件 C，三次往返，三次等待。

并行模式（高效）： 一次性发出读取文件 A、B、C 的请求，单次往返，同时返回结果。

没有这条指令，模型会像一个谨慎的新手一样逐个读取文件，每次读取都消耗一轮 API 调用的 Token。在一个中等规模的项目里，这种串行行为可能让一次任务的 Token 消耗翻倍。

支柱四：计划行为规范#

系统提示词对「何时做计划」有明确的分层指导：简单任务跳过计划，直接执行；多步骤任务才启用 update_plan 工具。

更关键的是，每完成一个子任务，模型必须更新计划状态。任务结束时，所有计划项必须标记为「完成」「阻塞」或「取消」，不允许有悬而未决的「进行中」状态。

这个设计的妙处在于，它让 Harness 可以在 UI 中展示一个实时的、可靠的进度面板，而不用担心看到一堆永远显示「进行中」的僵尸任务。

两种人格模式：选对模式比写对提示词更重要#

Codex Harness 内置了两种人格模式，可以通过系统提示词注入：

友好模式（Friendly Mode）#

温暖、支持性的协作风格。模型会主动解释推理过程，频繁确认你的输入，用鼓励性的语言与你互动。适合以下场景：

新成员上手项目时的引导式编程
模糊或探索性任务，需要模型多问多解释
结对编程场景，你希望从模型的推理中学习

务实模式（Pragmatic Mode）#

直接、简洁的交付风格。没有「好问题！」或「明白了！」这类客套话，只给 actionable 的信息。适合：

CI/CD 流水线中的自动化任务（没人会读它的寒暄）
批量操作，追求吞吐量
资深开发者，只想要结果不要过程

选择建议：如果你在构建自动化流水线，用务实模式；如果是交互式开发，用友好模式。选错模式的代价比你想象的大，一个在流水线里喋喋不休的 Agent 会白白消耗大量 Token。

四个核心工具：Harness 的基石#

提示词指南记录了四个任何 Harness 都应该实现的核心工具：

apply_patch：文件编辑的首选方案#

这是 Codex 的核心文件编辑工具，使用 V4A diff 格式。Responses API 提供了一等公民支持，只需在 tools 参数中传入 {"type": "apply_patch"}。

它支持三种操作：

操作	用途
`create_file`	创建新文件，包含完整内容
`update_file`	通过 V4A diff 修改现有文件
`delete_file`	删除文件

Harness 需要解析这些操作，应用到文件系统，然后返回 apply_patch_call_output 事件，附带 completed 或 failed 状态。

shell_command：终端操作的通用接口#

用于执行终端命令。指南建议使用字符串类型的 command 参数（而非列表），必须指定 workdir，可选 timeout_ms。Windows 环境有独立的 PowerShell 变体。

update_plan：任务进度管理#

标准的 TODO 管理工具，支持 pending、in_progress、completed 三种状态。模型用它维护一个可见的计划面板。

view_image：视觉上下文#

允许模型查看图片附件，包括截图、图表或设计稿，在实现过程中作为参考。

phase 参数：长会话的隐形守护者#

这是 gpt-5.3-codex 引入的一个关键参数，解决了长会话中的一个棘手问题：模型不知道何时该停止。

phase 参数有三个值：

null（默认）：正常响应
commentary：进度消息，模型知道后面还有更多工作
final_answer：结束消息，模型可以收尾了

工作流程是这样的：Harness 发送请求（phase=null），模型返回工具调用和进度消息（phase=commentary），Harness 执行工具并返回结果，模型继续工作，直到所有任务完成，返回最终总结（phase=final_answer）。

一个关键实现细节：在重建对话历史时，必须保留 phase 元数据。如果剥离了 phase 值，模型会失去对多步骤工作流进度的感知，导致它在中途就「以为任务完成了」。这是自定义 Harness 中最常见的 Bug。

响应截断：10K Token 的黄金法则#

指南建议将工具输出限制在 10,000 Token。当输出超出限制时，使用「前后各半」策略：

包含前 50% 的 Token 预算
插入截断标记（如 …3,482 tokens truncated…）
包含后 50% 的 Token 预算

为什么是这种格式？因为模型就是在这种截断格式的数据上训练的。发送未经截断的 50K Token 输出，会让模型的推理质量下降。保持「in-distribution」是驾驭工程中一个反复出现的主题。

元提示词：让 Agent 自己改进自己的指令#

当模型出现持续性的失败模式时，比如在第一次工具调用前想太久、状态更新不自然、或者开场白措辞尴尬，指南推荐一种叫元提示词（Metaprompting）的方法：

在一个有问题的轮次结束后，让模型审查自己的指令
针对具体问题请求改进建议
生成多个变体，寻找共同元素
将建议精简为一条通用改进规则

这种方法特别适合企业级 Harness，因为系统提示词往往随着不断累积的自定义内容变得臃长。模型本身就能识别哪些指令是冲突的或冗余的。

AGENTS.md 的分层注入机制#

从模型的视角看，AGENTS.md 文件是按层级自动发现和注入的：

全局层（~/.codex/） → 项目层（仓库根目录） → 目录层（当前工作目录）

每一层的文件作为一个独立的 user 角色消息插入对话，后面的层级覆盖前面的。对于自定义 Harness，你应该复现这个分层注入模式：先全局指令，再项目级，最后目录级。模型期望这种顺序，并用它来解决冲突的指令。

前端任务的特殊指导#

提示词指南中有一个常被忽略的部分：针对 UI 工作的设计指令。它要求模型避免「安全、平庸的布局」，追求有意图的、大胆的设计，包括表现力强的排版、有意义的动画和氛围感的背景。

唯一的例外是已有设计系统，此时模型应该遵循既定模式。

如果你没有在 Harness 中加入这条指令，gpt-5.3-codex 会默认生成 Bootstrap 风格的千篇一律的界面。

指南没有覆盖的部分#

提示词指南刻意忽略了几个 Harness 构建者需要自行解决的问题：

沙箱安全：指南假设你的 Harness 自己处理文件系统和网络隔离
审批工作流：除了基本的 needsApproval，审批 UX 完全由 Harness 定义
多 Agent 编排：指南只覆盖单 Agent 模式
成本管理：没有 Token 预算或模型路由的指导

对于这些领域，可以参考 Codex CLI 的源码和 App Server 架构文档。

实战建议：从这里开始#

如果你打算构建自己的 Codex Harness，这是经过验证的起步路径：

第一步，从官方系统提示词开始定制，不要从零写起。OpenAI 的默认模板已经包含了经过大规模验证的行为模式。

第二步，从第一天就启用并行工具调用。性能差异是数量级的。

第三步，自动化流水线用务实模式，交互式开发用友好模式。

第四步，实现 10K Token 的响应截断，严格按照指南的「前后各半」格式。

第五步，在对话历史中保留 phase 元数据。这是最常见的自定义 Harness Bug。

第六步，用元提示词迭代改进你的系统提示词，而不是手动编辑。

写在最后#

2026 年的 AI 编程工具竞争，表面上是模型能力的比拼，底层却是驾驭工程的较量。OpenAI 的 Codex 提示词指南揭示了一个事实：同一个模型，在不同的 Harness 下可以表现出天壤之别。

那些让 Codex 「跑得飞快」的开发者，并不是 Prompt 写得比你好。他们只是在第一天花 30 分钟写好了 AGENTS.md，配置了正确的工具接口，选对了人格模式，然后就不再纠结提示词了。

模型会越来越好，CLI 会不断增加新功能，团队会贡献更多 Skill。但这个工作循环的形态不会变。这才是区分「真正产出」和「不停调参」的关键。

参考来源：