Appearance
GPT-5.1-Codex-Max 提示词完全指南（通俗版）
什么是 GPT-5.1-Codex-Max
GPT-5.1-Codex-Max 是 OpenAI 推出的最强代码生成模型，专为"智能编码代理"场景设计。简单来说，它不只是一个回答问题的 AI，而是能够像资深工程师一样自主完成整个开发任务——从理解需求、探索代码库、编写代码到测试验证，一气呵成。
核心优势
超强自主性：给它一个任务，它会主动收集信息、制定计划并执行，不需要你每一步都催促
高效工具使用：内置优化的文件编辑、命令执行等工具，比传统方式快得多
长上下文处理：通过"压缩"技术，可以处理超长对话和复杂项目
更智能的并行操作：能同时执行多个操作，大幅提升效率
如何迁移到 Codex-Max
如果你已经在使用旧版 Codex 或其他 AI 编码工具，迁移到 Codex-Max 需要两个关键步骤：
步骤 1：更新你的提示词
OpenAI 提供了一套经过优化的标准提示词模板，建议以此为基础进行定制。
重点关注以下部分：
自主性和持久性：让模型知道它应该主动完成任务
代码库探索：如何高效查找和阅读文件
工具使用规范：优先使用专用工具，而非直接执行 shell 命令
前端开发规范：避免生成"AI 味"太重的千篇一律界面
重要提醒：删除所有要求模型"先说明计划"或"汇报进度"的指令。Codex-Max 会自动通过推理摘要告知进度，额外的计划说明反而可能让它提前停止工作。
步骤 2：更新你的工具集
工具配置是发挥 Codex-Max 性能的关键。务必采用 OpenAI 推荐的 apply_patch 实现和其他最佳实践。
核心提示词解析
以下是标准提示词的关键部分，我们用通俗语言解释每一块的作用。
自主性和持久性
plaintext
你是一位自主的资深工程师：用户给出方向后，主动收集上下文、制定计划、实施、测试和完善，
无需在每一步等待额外提示。
坚持到底：在当前回合内尽可能完整地处理任务——不要停留在分析或部分修复；
将更改贯穿实施、验证，并清楚说明结果，除非用户明确暂停或重定向你。白话翻译：告诉模型"你是老司机，接到活儿就自己干完，别干一半就停下来问我下一步怎么办"。这样能大幅减少来回对话次数。
代码实现原则
plaintext
作为一名挑剔的工程师：优化正确性、清晰度和可靠性，而非速度；
避免冒险的捷径、投机性更改和只是为了让代码运行的草率方案；
解决根本原因或核心需求，而不仅仅是症状或狭窄的一部分。关键点：
严格错误处理：不要用宽泛的
try/catch吞掉错误保持类型安全：避免
as any这种偷懒做法代码复用：先搜索有没有现成的辅助函数，别重复造轮子
批量编辑：一次性完成相关修改，别改一行提交一次
文件探索和并行读取
这是 Codex-Max 的一大亮点——批量并行读取文件。
plaintext
思考优先：在任何工具调用之前，决定你需要的所有文件/资源。
批量处理：如果需要多个文件（即使来自不同位置），一起读取它们。
使用 multi_tool_use.parallel 来并行化工具调用。实际效果：传统 AI 可能逐个文件读取，每次等待你确认；Codex-Max 会一次性并行读取 10 个文件，速度快 10 倍！
工作流程：
分析任务，列出需要的所有文件
发起一个并行批次读取所有文件
分析结果
如果需要更多文件（基于前面的结果），重复步骤 1-3
计划工具使用规范
plaintext
对于简单任务（大约最简单的 25%），跳过使用计划工具。
不要制定单步计划。
完成计划中的子任务后，更新计划。
除非被要求制定计划，否则永远不要仅以计划结束互动。核心思想：计划是用来指导自己的，不是用来"交差"的。复杂任务才需要计划，简单任务直接干。
前端任务特别要求
这部分非常有意思——专门防止生成"AI 套话"风格的界面：
plaintext
做前端设计任务时，避免陷入"AI 俗套"或安全、平庸的布局。
力求界面感觉有意图、大胆且有点令人惊喜。
- 排版：使用富有表现力、有目的的字体，避免默认字体栈（Inter、Roboto、Arial）
- 颜色和外观：选择明确的视觉方向；定义 CSS 变量；避免紫色加白色的默认配色。无紫色偏见或暗色模式偏见
- 动效：使用少量有意义的动画，而非通用的微动效
- 背景：不要依赖平面单色背景；使用渐变、形状或微妙的图案来营造氛围警告：如果你是在现有设计系统中工作，则应保持原有风格，不要"创新"。
呈现工作和最终消息
plaintext
你生成的是纯文本，稍后将由 CLI 进行样式处理。
- 默认：非常简洁；友好的编码队友语气
- 格式：使用自然语言和高级标题
- 对于代码更改：先快速解释更改，然后详细说明上下文，包括在哪里以及为什么做出更改关键规则：
不要倾倒你写的大文件；仅引用路径
不要说"保存/复制此文件"——用户在同一台机器上
文件引用用内联代码格式，例如
src/app.ts:42
Compaction 压缩功能详解
这是 Codex-Max 的"黑科技"——让 AI 能处理超长对话而不会"失忆"。
什么是 Compaction
想象你和 AI 对话了 100 轮，上下文窗口快满了。传统做法是删除旧对话或让 AI 变笨。Compaction 的做法是：把前面的对话"压缩"成更紧凑的形式，保留关键信息，但占用更少的 token。
工作原理
使用 Responses API 正常发送输入（包括工具调用、用户输入、助手消息）
当上下文窗口变大时，调用
/compact端点生成压缩后的上下文该端点返回一个
encrypted_content项在后续请求中传入这个压缩项，模型就能"记住"之前的状态
注意事项
发送到
/compact的上下文窗口必须在模型的上下文窗口限制内返回的加密内容可以在未来请求中使用
模型能用更少的 token 保留关键的先前状态
工具使用最佳实践
apply_patch：高效文件编辑
这是 Codex-Max 的核心工具，用于编辑文件。OpenAI 强烈建议使用他们的精确实现。
为什么重要：模型经过专门训练来生成这种 diff 格式，使用标准实现能获得最佳效果。
两种实现方式：
Responses API 内置工具（推荐）：直接在 API 中定义
{"type": "apply_patch"}自定义语法工具：使用上下文无关文法（CFG）定义
示例输出：
plaintext
*** Begin Patch
*** Update File: /app/page.tsx
@@
<div>
<p>Page component not implemented</p>
<button onclick="{()" ==""> console.log("clicked")}>Click me</button>
+ <button onclick="{()" ==""> console.log("cancel clicked")}>Cancel</button>
</div>
);
}
*** End Patchshell_command：执行命令
推荐的 shell 工具定义要点：
command 参数用字符串，不是命令列表（性能更好）
始终设置 workdir，避免使用
cd支持权限提升：通过
with_escalated_permissions参数需要说明理由：如果需要提升权限，必须提供
justification
update_plan：维护任务计划
json
{
"explanation": "开始实现取消按钮功能",
"plan": [
{ "step": "添加取消按钮到页面", "status": "completed" },
{ "step": "实现点击事件处理", "status": "in_progress" },
{ "step": "添加单元测试", "status": "pending" }
]
}最佳实践：
简单任务不需要计划（约 25% 的最简单任务）
不要创建单步计划
完成子任务后及时更新状态
最多只能有一个
in_progress步骤
自定义工具建议
如果你想添加自己的工具（如语义搜索、MCP 协议工具等），需要注意：
命名规范
语义明确：用
semantic_search而不是模糊的search参数清晰：
query比text更能表达语义搜索的意图
输出格式
让工具的输出看起来与模型习惯的格式不同。例如：
Ripgrep 的搜索结果应该与语义搜索结果有明显区别
这样能避免模型"混淆"不同工具的用途
提示词指导
在系统提示中明确说明：
何时使用这个工具
为什么使用（相比其他工具的优势）
如何使用（参数含义、预期输出）
提供好的和坏的使用示例
替代终端工具
如果你希望模型使用专用工具而非直接调用终端命令，OpenAI 的建议是：
python
GIT_TOOL = {
"type": "function",
"name": "git",
"description": "在仓库根目录执行 git 命令。行为类似在终端中运行 git",
"parameters": {
"type": "object",
"properties": {
"command": {
"type": "string",
"description": "要执行的 git 命令"
}
}
}
}然后在提示词中添加：
plaintext
严格避免在存在专用工具时使用原始 cmd/terminal。
优先使用专门工具：git（所有 git 操作）、list_dir、apply_patch。
只有在没有列出的工具可以执行操作时才使用 cmd/run_terminal_cmd。并行工具调用技巧
启用并行工具调用后，在 Responses API 请求中设置 parallel_tool_calls: true，并在系统指令中添加：
plaintext
## 探索和读取文件
- **先思考**：在任何工具调用之前，决定你需要的所有文件/资源
- **批量处理所有内容**：如果需要多个文件（即使来自不同位置），一起读取它们
- **使用 multi_tool_use.parallel**：使用它来并行化工具调用，且仅使用它
- **只有在确实无法在不看到结果的情况下知道下一个文件时，才进行顺序调用**
额外注意事项：
- 始终最大化并行性。除非逻辑上不可避免，否则永远不要逐个读取文件
- 这涉及所有读取/列表/搜索操作，包括但不限于 cat、rg、sed、ls、git show、nl、wc 等
- 不要尝试使用脚本或 multi_tool_use.parallel 以外的任何方式来并行化工具调用顺序
OpenAI 发现，按以下顺序排列并行工具调用项和响应更符合模型训练分布，效果更好：
所有工具调用请求按逻辑分组
对应的工具响应紧随其后
保持调用和响应的配对清晰
响应截断建议
为了保持与模型训练分布一致，建议按以下方式截断工具调用响应：
保留错误消息的完整性
对超长输出进行智能截断（保留开头和结尾）
明确标注已截断的内容
推理摘要（不可提示）
Codex 模型系列使用"推理摘要"在工作时向用户传达更新。这可以是单行标题（更新 Codex-CLI 中的临时文本），也可以是标题加简短正文。
重要：这是由单独的模型完成的，因此不可通过提示词控制。OpenAI 建议不要在提示词中添加任何关于中间计划或用户消息的指令。
Codex-Max 改进了这些摘要，使其更具沟通性，提供关于正在发生的事情及原因的更多关键信息。
上下文文件自动注入
Codex-cli 自动枚举这些文件并将它们注入到对话中；模型经过训练以严格遵守这些指令。
工作原理：
从
~/.codex加上从仓库根目录到当前工作目录的每个目录中拉取文件按顺序合并，后面的目录覆盖前面的目录
每个合并的块作为独立的用户角色消息显示给模型
实践建议总结
新手入门
从官方模板开始：使用 OpenAI 的标准提示词模板，不要自己从零开始写
克隆参考实现：下载 codex-cli 仓库，研究实际代码
小步迭代：先让基础功能跑起来，再逐步定制
性能优化
用对工具：apply_patch、shell_command、update_plan 使用官方实现
开启并行：设置
parallel_tool_calls: true，大幅提升速度合理压缩：长对话场景使用 Compaction 避免上下文溢出
常见陷阱
过度指导：不要在提示词中要求模型"先说计划再执行"，这会降低自主性
工具冲突：明确指示何时用专用工具，何时用 shell，避免混乱
忽略并行：文件读取一定要批量并行，否则速度慢 10 倍
质量保证
运行评估：针对答案正确性、完整性、工具使用正确性建立评测集
提高自主性：评测时开启"非交互模式"，测试完全自主能力
保持更新：关注 OpenAI 的 cookbook 和更新日志，及时采纳最佳实践
进阶话题
Windows PowerShell 支持
如果使用 Windows PowerShell，需要更新 shell_command 工具描述以适配 PowerShell 语法。
长生命周期 PTY
对于需要流式输出、REPL 或交互式会话的场景，使用 exec_command 启动长期存活的 PTY，并用 write_stdin 向现有会话发送额外的按键输入。
图像查看
使用基础的 view_image 函数让模型能够查看图像，这在前端开发和 UI 调试中特别有用。
总结
GPT-5.1-Codex-Max 代表了 AI 编码辅助的新高度——从"对话助手"升级为"自主工程师"。要充分发挥其能力，关键在于：
信任自主性：给它任务，让它自己干完
工具先行：使用官方推荐的工具实现
批量思维：能并行就并行，别一个一个来
持续优化：建立评测，迭代改进
遵循本指南的最佳实践，你的 AI 编码代理将成为真正得力的开发伙伴。
