[AI Agent] Codex 计划模式

0 序

  • 接续: [AI Agent/应用] OpenAI Codex 概述 - 博客园/千千寰宇
  • 在 Codex 0.90.0 及以后的版本， Codex 支持内置的计划模式了。

之前 Codex CLI 在增加 Skills 支持的时候，顺手也带了一个 create-plan 的试验性 Skill，并且是需要手动安装才能使用的。
现在直接是内置了，并且使用体验上向 Claude Code 靠齐了，Shift+Tab 就能在 Plan 和 Code 模式之间自由切换。
Codex CLI 在实现这个功能的时候，借鉴了人类协作的理念，称其为（多Agent）【协作模式】。

  • 计划模式：在做复杂任务的时候，它会先跟你确认方案再动手，不会上来就乱改代码。

1 概述：Codex 计划模式

  • 在 AI Agent 从“单轮对话/即时生成”向“长链路自主协同”演进的过程中，Codex 的计划模式（Plan Mode / Long-running Tasks） 是一种非常经典且具备工程示范价值的模式设计。

1.1 概念定义与核心区别

Codex 的工作模式 x3

模式 说明 适用场景
标准模式(默认) 直接执行操作 日常开发、快速修改
计划模式 先规划后执行 复杂任务、架构设计
沙箱模式 受限执行环境 不受信任的代码、安全敏感场景

标准模式

  • 标准模式 : Codex 的默认工作模式。在该模式下，Codex 会直接执行你请求的操作。
  • 特点: 直接修改文件 / 自动执行命令 / 实时反馈结果
  • 使用方式:
# 默认即为标准模式
codex "重构这个模块"
  • 适用场景
简单的代码修改
文件创建和编辑
运行测试和构建
日常开发辅助

计划模式

  • 计划模式 : 计划模式/协作模式（Plan Mode）让 Codex 先制定执行计划，经用户确认后再执行操作。
  • 进入计划模式
# 方式1 在GUI交互模式中切换# 方式2 在命令行交互模式中切换
> /plan# ... 更多方式，略
  • 计划模式工作流:
用户请求 → Codex 分析 → 制定计划 → 用户确认 → 执行操作 → 结果反馈
  • 适用场景
多文件重构
架构设计决策
数据库迁移
新功能开发

沙箱模式

  • 沙箱模式 : 沙箱模式限制了 Codex 的操作能力，提供安全的执行环境。

  • 沙箱限制

能力 沙箱模式 信任模式
文件读取 ✅ 允许 ✅ 允许
文件写入 ⚠️ 需审批 ✅ 允许
命令执行 ⚠️ 受限 ✅ 允许
网络访问 ⚠️ 受限 ✅ 允许
  • 进入沙箱模式
    1. 最常用：允许 Codex 修改当前项目

workspace-write 的含义是：Codex 可以读取文件，并且可以修改当前工作目录（以及配置的可写目录）；超出范围的修改需要额外授权。

codex --sandbox workspace-write
或 codex -s workspace-write
    1. 只读沙箱

如果你希望 Codex 只能分析代码，不能修改文件：

codex --sandbox read-only

这适合代码审查、让 Codex 分析项目结构等场景。

  1. 如果你想“默认每次都进入沙箱”

可以在 ~/.codex/config.toml 中设置：

核心配置项：
sandbox_mode = "workspace-write"例如：
approval_policy = "on-request"
sandbox_mode = "workspace-write"另外，项目级别配置（在 config.toml 中）
[projects."/path/to/project"]
trust_level = "untrusted"

不过要注意，近期 Codex CLI 的 profile 配置存在过 sandbox 设置没有被正确应用的问题；
如果你发现实际启动后仍然显示 workspace-write 以外的模式，直接在命令行显式指定 -s workspace-write 更可靠。

    1. 怎么确认当前是不是沙箱模式？

启动 Codex 后，顶部通常会显示类似：

sandbox: workspace-write

你也可以直接运行：

codex --sandbox workspace-write

如果你的目的其实是 “让 Codex 像 Claude Code 那样，既能自动改项目，又不能碰项目目录以外的东西”，可以进一步咨询 Codex 或其官网，以给你一套最安全的 config.toml 配置，包括 sandbox + approval + 网络权限。

直接询问:

image

image

GUI 用户界面上查验/配置:

image

  • 退出沙箱模式
# 禁用沙箱
codex --no-sandbox# 或设置项目为受信任
[projects."/path/to/project"]
trust_level = "trusted"
  • 适用场景
  • 处理不受信任的代码
  • 安全审查
  • 第三方代码分析
  • 学习探索

什么是计划模式 / 长耗时任务？

  • 计划模式是 AI Agent 在处理高复杂度、多步骤或耗时较长的任务时，引入的一种“先规划（Planning）、后执行（Execution）、动态调整（Replanning）”的【显式运行机制】。

  • 不同于传统的“输入 Prompt \(\rightarrow\) 输出 Code/Result”的单次推理过程——计划模式将【大任务】拆解为一个状态机（State Machine）或有向无环图（DAG）。Agent 在执行每一步时，都会对照“【计划列表】”更新自身状态、评估中间结果，并在必要时触发长时间运行的后台任务或自动修复逻辑。

对比: 非计划模式（即时/反应式模式）

维度 非计划模式（Reactive Mode） 计划模式（Plan-Driven / Long-running Mode）
思考范式 ReAct / 单轮推理：边想边做，依赖单次上下文 Plan-and-Solve：先生成全局 Blueprint，再分步调度与验证
任务粒度 局部修改、函数级编写、单文件重构 跨模块重构、全栈 Feature 开发、大规模 Bug 修复
上下文管理 随着对话增加快速被满载，容易出现“【幻觉】”或【忘记目标】 【计划】作为“【外部记忆】（External Memory）”，【主干上下文】保持干净
执行中断 依赖【用户交互】，阻碍长周期代码编译/测试执行 支持【异步挂起】、【长耗时轮询】（Polling）、【断点续传】与【自主重试】
透明度 过程为【黑盒】，仅能看到流式输出的文本/代码片段 【过程显式化】，用户与 Agent 均对 Progress Bar / Plan Checklist 可视化

1.2 核心优势、主要短板与适用场景

核心优势

  1. 防漂移（Goal Drift Prevention）：在长代码修改链条中，Agent 容易“走一步看一步”走向【局部最优】、但最终偏离最初需求。计划模式通过维护一个静态/动态的 Checklist，强制 Agent 每次 Loop 都校验当前 Task 是否归属于【全局目标】。

  2. 长耗时任务脱机执行：对于需要运行长时间单元测试、项目编译或 Docker 构建的任务，Agent 能够解耦“推理状态”与“执行状态”，实现【非阻塞式】的后台轮询与异步通知。

  3. 更高的 Token 效率与上下文控制：将复杂的上下文压缩为“【计划状态】”，每一步只加载与该子任务相关的代码文件（Sub-context windowing），极大节省昂贵的大模型 Context 空间。

  4. 容错与回滚机制：若步骤 \(N\) 失败（如测试未通过），Agent 可以根据 Plan 回溯到步骤 \(N-1\) 重新分析，而不是在【错误的中间态】上继续叠加错误。

主要短板

  1. 前期延迟较高（Planning Overhead）：对于简单的代码修改，强制生成 Plan 会增加额外的 LLM 调用开销，导致响应变慢、Token 浪费。

  2. “计划僵化”风险：如果初始生成的 Plan 存在逻辑盲区，Agent 若过度依赖 Plan，可能陷入【无效的循环执行】（Plan Execution Loop），需要强大的【动态重规划】（Replanning）机制支撑。

  3. 系统复杂性剧增：工程上需要处理【状态持久化】、【并发控制】、【中断恢复】、【日志追踪】等【典型分布式的工程难题】。

适用场景

  • 大型工程重构：如“将某个服务从 Python 2 迁移到 Python 3”或“替换核心 API 接口”。

  • 全自动 Bug 修复与回归测试：跑完自动化测试集（耗时 10-30 分钟）\(\rightarrow\) 提取 Error \(\rightarrow\) 修复 \(\rightarrow\) 重新跑测试。

  • 从零构建复杂 Feature：涉及 API 设计、DB Schema 迁移、后端逻辑实现、前端 UI 对接等多层协作。

1.3 使用与配置指南

  • 在标准的类 Codex 交互环境（如 OpenAI Codex CLI、Cursor/Claude Code 或自定义 Agent 工具链）中，典型的操作逻辑如下：

软件版本要求

  • 升级到 Codex 0.90.0 以上

之前 Codex CLI 在增加 Skills 支持的时候，顺手也带了一个 create-plan 的试验性 Skill，并且是需要手动安装才能使用的。
现在直接是内置了，并且使用体验上向 Claude Code 靠齐了，Shift+Tab 就能在 Plan 和 Code 模式之间自由切换。

激活计划模式

可以通过显式指令或配置开关开启：

  • 用户界面/GUI :

如果你使用的是 Codex 的图形界面（如 ChatGPT 中的 Codex），界面上通常会有模式切换的控件或指示器，可以直观看到当前模式和切换。

image

  • 指令方式：在 Prompt 中包含类似 /plan 标记或显式触发词：

/plan "将现有系统的 Redis 客户端从 Jedis 替换为 Lettuce，并补全单元测试"
此时再查看工作模式，即已切换到 plan 模式

/status╭─────────────────────────────────────────────────────────────────────────────────────────╮
│  >_ OpenAI Codex (v0.147.0)                                                             │
│                                                                                         │
│ Visit https://chatgpt.com/codex/settings/usage for up-to-date                           │
│ information on rate limits and credits                                                  │
│                                                                                         │
│  Model:                deepseek-ai/DeepSeek-V4-Flash (reasoning medium, summaries auto) │
│  Model provider:       siliconflow - http://127.0.0.1:15721/v1                          │
│  Directory:            H:\Local\study-codex\projects\research-ai-agent-projects         │
│  Permissions:          Workspace (Ask for approval)                                     │
│  Agents.md:            C:\Users\xxxx\.codex\AGENTS.md                                 │
│  Account:              API key configured (run codex login to use ChatGPT)              │
│  Collaboration mode:   Plan                                                             │
│  Session:              019fefa0-6c5a-77a1-8681-452322085275                             │
│                                                                                         │
│  Token usage:          9.54K total  (9.34K input + 194 output)                          │
│  Context window:       99% left (13.3K used / 122K)                                     │
│  Limits:               not available for this account                                   │
╰─────────────────────────────────────────────────────────────────────────────────────────╯

退出与干预

  • 主动中断/退出：
  • 输入 /exit 退出 codex 当前交互模式，再重新进入。
  • 人机协同干预（Human-in-the-loop）：
  • Agent 在完成 Plan 的每一个 Key Milestone 时可以触发暂停，等待用户审核通过（Approve）或提出修正意见（Feedback）后再继续下一步。

查看与追踪状态

  • Plan Checklist 查看：输入 /status 或输入 "查看计划内容" 查看当前的 Task List（Pending / In Progress / Completed / Failed）。

  • 后台长任务日志：输入 /logs [task_id] 查看长时间运行后台任务（如编译构建）的实时 stdout/stderr。

4. 对 AI Agent 项目工程的借鉴意义

如果你正在构建自己的 AI Agent 框架/产品，Codex 的计划模式提供了极为关键的架构设计启示：

① 显式分离 Plan 生成与 Plan 执行（Architecture Separation）

在工程实现上，建议拆分为两个模块：

  • Planner（规划器）：使用推理能力更强的模型（如 Claude 3.5 Sonnet / O1/O3），负责生成结构化的任务 JSON/YAML 计划。
  • Executor（执行器）：使用高吞吐、低成本或定制化的模型，严格按照 Planner 拆解的单步 Task 调用 Tool 执行。

② 引入“状态持久化”与“断点续传”（State Management）

长耗时任务随时可能因为网络波动、API 限流或程序崩溃中断。Agent 工程设计必须具备：

  • 将 Plan 状态（如当前执行到 Step 3/8）落盘到 SQLite/Redis/PostgreSQL。
  • Checkpoints 机制：每个步骤完成后保存代码快照（如 Git commit 或 Memory Snapshot），失败时快速回滚。

③ 工具调用的“异步化”与“事件驱动”（Async Tool Calling）

对于耗时较长的 Tool（如运行 CI/CD Pipeline、下载大数据集、执行深度重构脚本）：

  • 不要使用同步阻塞（Synchronous Block）等待结果返回。
  • 应该使用事件驱动/轮询机制：Tool 立即返回 task_id，Agent 将自身状态挂起（Suspend），定时器或 Webhook 触发后拉取结果并唤醒 Agent 恢复执行。

④ 建立健全的动态重规划逻辑（Dynamic Replanning Loop）

真正可用的 Agent 必须具备“自愈”能力。当 Tool 返回错误时，工程上应当捕获这个 Error，触发 Replanning Agent：

\[\text{Current State} + \text{Failed Step Reason} + \text{Remaining Plan} \longrightarrow \text{Updated Plan} \]

重新更新 Plan 后继续下发给 Executor，从而形成闭环。

G 最佳实践

CASE 全局级 PLAN.md 模板 from OpenAI/Codex 官网

  • 参考文献
  • 使用 PLANS.md 解决高耗时的问题 - OpenAI/Aaron Friel(亚伦·弗里尔) 2025.10.7 【推荐】

Step1 配置 全局级 Agent.md

  • 全局级 Agent.md 文件中添加 ExecPlan 的提示词

AGENTS.md 是一种用于引导编码代理（如 Codex）的简单格式。我们描述了一个用户可以作为简写使用的术语，以及当使用计划文档的简单规则。在这里，我们将其称为“ExecPlan”。请注意，这是一个方便定义的术语，Codex 将会在此进行专门的训练。这种简写可以在提示 Codex 时使用，以将其导向特定的计划定义。 from https://developers.openai.ac.cn/cookbook/articles/codex_exec_plans

  • 对应菜单: 设置-个性化-自定义指令
  • 对应路径: C:\Users\用户\.codex\AGENT.md
...# ExecPlans
- 在编写复杂功能或进行重大重构时，应从设计到实现使用 ExecPlan（如 .agent/PLANS.md 中所述）。...

When writing complex features or significant refactors, use an ExecPlan (as described in .agent/PLANS.md) from design to implementation.

Step2 配置全局级的 PLAN.md

  • 本文档中的提示经过前面的设计，旨在为用户提供大量的反馈，并引导模型精确执行计划所指定的内容。用户可能会发现，根据自己的需求定制该文件，或添加/删除必要的章节，使他们受益浅。
  • 全局级: C:\Users\用户\.codex\PLAN.md（默认是不会创建的，可手动创建之） / ...
# 执行计划（ExecPlans）本文档描述了执行计划（“ExecPlan”）的要求，即编码人员可依据的设计文档，用于实现一个功能或系统变更。请将读者视为该仓库的完全新手：他们仅拥有当前的工作树以及您提供的单个 ExecPlan 文件。没有对以往计划的记忆，也没有外部上下文。## 如何使用 ExecPlans 和 PLANS.md
- 编写【可执行规范】（ExecPlan）时，请严格按照 `PLANS.md` 的要求操作。如果未在您的【上下文】中找到相关内容，请重新阅读整个 PLANS.md 文件以【刷新记忆】。在阅读（并反复阅读）【源材料】时务必细致入微，以确保生成【准确的规范】。【创建规范】时，应从骨架开始，并在【研究过程中】逐步完善内容。- 在实现【可执行规范】（ExecPlan）时，不要向用户询问“下一步”，而是直接进入【下一个里程碑】。请保持所有部分的更新，在每个【停顿点】添加或拆分条目，明确记录已取得的进展和下一步工作。独立解决任何模糊之处，并频繁提交代码。在讨论可执行规范（ExecPlan）时，应将决策记录在规范的日志中以供后人查阅；任何对规范的修改原因都必须明确无误。ExecPlan 是【动态文档】，始终应能够仅从 ExecPlan 重新开始，而无需其他工作。- 在研究具有【挑战性需求】或存在【重大未知因素】的设计时，应使用【里程碑】来实现【概念验证】、“玩具实现”等，以验证用户的方案是否可行。通过查找或获取库的源代码，深入研究，并包含原型以指导更完整的实现。## 要求
- 不可协商的要求：
>> - 每个 ExecPlan 必须完全自包含。自包含意味着其当前形式已包含新手成功所需的所有知识和指令。
>> - 每个 ExecPlan 都是动态文档。贡献者需随着进展、新发现以及设计决策的最终确定而不断修订该文档。每次修订都必须保持完全自包含。
>> - 每个 ExecPlan 必须让完全的初学者能够无需事先了解本仓库，就能从头到尾实现该功能。
>> - 每个 ExecPlan 必须产生可验证的、实际运行的功能行为，而不仅仅是为“符合定义”而修改代码。
>> - 每个 ExecPlan 必须用通俗语言定义所有技术术语，或避免使用这些术语。- 目的和意图应放在首位。首先用几句话解释这项工作对用户而言为何重要：这一变更后用户能做什么，而之前无法做到；以及如何观察其效果。然后引导读者逐步完成具体操作步骤，包括需要编辑的内容、运行的命令以及应观察到的结果。- 执行你计划的代理程序可以列出文件、读取文件、搜索、运行项目并执行测试。它并不了解任何先前的上下文，也无法从之前的里程碑中推断你的意图。请明确列出你所依赖的任何假设。不要引用外部博客或文档；如果需要知识支持，请用自己的话将相关内容嵌入计划本身。如果一个 ExecPlan 建立在先前的 ExecPlan 上，且该文件已被提交，则通过引用方式纳入；若未提交，则必须包含该计划中的全部相关上下文。## 格式化
- 格式和信封应简单且严格。每个 ExecPlan 必须是一个单独的代码块，用 `md` 标记，并以三个反引号开头和结尾。不要在内部嵌套额外的三重反引号代码块；当需要显示命令、日志、差异或代码时，应将其作为该单一代码块内的缩进块呈现。为提高可读性，应使用缩进而非在 ExecPlan 内部使用代码块，以免提前关闭 ExecPlan 的代码块。每个标题后应添加两个换行符，使用 #、## 等符号，并正确处理有序和无序列表的语法。- 当将 ExecPlan 写入 Markdown（.md）文件，且文件内容仅包含单个 ExecPlan 时，应省略三重反引号。- 请使用纯文句写作，优先使用句子而非列表。除非简洁性会模糊含义，否则应避免使用清单、表格和长列表。仅在“进度”部分允许使用清单，且该部分必须使用清单。叙述性部分必须以纯文句为主。## 规则
- 自包含性和清晰的语言至关重要。如果引入了非普通英语的术语（如“daemon”、“middleware”、“RPC gateway”、“filter graph”），应立即定义该术语，并提醒读者它在本仓库中的具体体现方式（例如，通过命名出现该术语的文件或命令）。不要说“如先前所定义”或“根据架构文档”。即使重复说明，也应在此处提供必要的解释。- 避免常见的故障模式。不要依赖未定义的技术术语。不要将“某功能的字母”描述得过于狭窄。

Y 推荐文献

  • 使用 PLANS.md 解决高耗时的问题 - OpenAI/Aaron Friel(亚伦·弗里尔) 2025.10.7 【推荐】
  • [AI Agent/应用] OpenAI Codex 概述 - 博客园/千千寰宇
  • 工作模式 - laihaibo.github 【推荐】

X 参考文献