Codex

Codex 是 OpenAI 的软件开发 Agent 产品家族，可用于编写代码、理解陌生代码库、审查和修复问题，以及自动执行重构、测试、迁移和环境配置等工程任务。

2026 年 7 月，原 Codex App 并入新的 ChatGPT 桌面应用；桌面入口中并列 Chat、ChatGPT Work、Codex、Scheduled 和 Sites。Codex 仍是面向开发者与技术人员的编程 Agent，且用户可以把它设为默认视图；这一产品整合不改变本文对 CLI、IDE 与云端执行环境的区分。

“Codex”不是 Codex CLI 的简称，而是覆盖多种入口的产品总称：

产品形态	运行位置与用途
Codex App	macOS / Windows 桌面端，并行管理线程、worktree、自动化和 Git 操作
Codex CLI	在本地终端运行，可读取、修改和执行当前目录中的代码
Codex IDE extension	在 VS Code 等 IDE 中协作，也可把任务委派给 Codex Cloud
Codex web / Cloud	连接 GitHub 仓库，在云端执行任务并创建 Pull Request

下文涉及 harness、shell 沙箱、推理端点和本地配置的内容，主要描述开源的 Codex CLI；其他产品形态共享部分能力，但运行环境和权限边界并不完全相同。

Codex CLI 的核心 harness

Codex CLI 的关键价值不只是调用强模型，而是把模型放进一个可执行、可约束、可持续的 Agent Loop（智能体循环）中。其 harness 负责协调用户、模型和工具：

读取用户输入、项目指令和本地环境信息
根据模型、工具列表、权限配置和工作目录构造初始输入
通过 Responses API（响应 API）请求模型推理
消费 SSE 事件流，并把输出转成 UI 流式文本、reasoning item、tool call 或 assistant message
执行 shell、计划更新、Web search、MCP 工具等工具调用
管理上下文增长、Prompt Caching（提示缓存）和自动压缩

Codex 内置 Agent Worktree（Agent 工作树）支持——多个线程可同时操作同一个 repo，每个线程在自己的 worktree 里工作，互不干扰。

这体现了 Harness Engineering（驾驭工程）的核心判断：真实 Agent 产品的可靠性很大一部分来自围绕模型的执行基础设施。

Codex CLI 的输入结构

Codex 不是把用户输入原样作为 prompt 发给模型，而是构造一个结构化输入列表。初始请求通常包含：

模型或用户配置提供的 instructions
工具 schema，包括 Codex 内置 shell 工具、计划工具、Responses API 工具和用户通过 Model Context Protocol（模型上下文协议）接入的工具
适用于 Codex shell 工具的权限说明
用户配置中的 developer instructions
AGENTS.md、AGENTS.override.md、技能元数据等用户/项目指令
当前工作目录、shell 等本地环境上下文
最后追加用户本轮消息

OpenAI 的文章强调，沙箱说明只约束 Codex 提供的 shell 工具；MCP 服务器等外部工具需要自己实现护栏。

Codex CLI 的 AGENTS.md：持久项目指令

Codex 在执行任务前读取 AGENTS.md，用它保存构建命令、代码规范、验证步骤和审查要求等持久约定。指令链在每次运行开始时构建一次；TUI 中通常对应每次新会话。

从广义的 Agent Memory（Agent 记忆）看，AGENTS.md 确实是跨会话存活的外部记忆；但在 Codex 的产品术语中，它属于人维护的项目指令，与 Codex 自动生成的 Memories 是两套机制。必须稳定执行的团队约定应写进 AGENTS.md 或受版本控制的项目文档，不能只依赖 Memories。

加载分为两层：

全局层：在 CODEX_HOME（默认 ~/.codex）中优先读取 AGENTS.override.md，不存在时读取 AGENTS.md，只取第一个非空文件。
项目层：从项目根目录（通常是 Git 根目录）走到当前工作目录，在每一级目录中最多读取一个文件，优先级依次是 AGENTS.override.md、AGENTS.md、project_doc_fallback_filenames 配置的备用文件名。

flowchart LR
    G["CODEX_HOME\n全局指令"] --> R["项目根目录"]
    R --> S["中间子目录"]
    S --> C["当前工作目录"]
    C --> P["按顺序合并进 prompt"]

文件按全局、项目根目录、子目录到当前工作目录的顺序拼接。越靠近当前工作目录的规则出现得越晚，因此可以覆盖上层规则。空文件会被跳过；所有项目指令合计达到 project_doc_max_bytes 后停止添加，默认上限为 32 KiB。

这提供了目录层级作用域，但不等同于 Claude Code .claude/rules/*.md 的 paths frontmatter：Codex 不会按 glob 匹配当前处理的文件，也不会在会话中进入其他子目录时动态重建指令链。若 services/payments/ 需要专属规则，应在该目录放置 AGENTS.md 或 AGENTS.override.md，并以它作为当前工作目录启动 Codex。

可以在 ~/.codex/config.toml 中兼容其他项目文档名称并调整大小上限：

project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536

修改后需启动新会话。可用以下命令核对实际加载的指令及其顺序：

codex --cd services/payments --ask-for-approval never \
  "列出已加载的指令来源，并按优先级排序。"

AGENTS.md + PLANS.md：长任务执行规范

OpenAI Cookbook 的《Using PLANS.md for multi-hour problem solving》给出了一种更强的项目指令用法：在 AGENTS.md 中定义一个团队内部 shorthand，例如 ExecPlan，并规定当任务属于复杂功能或重大重构时，Codex 必须按照仓库里的 PLANS.md 从设计推进到实现。这里的 ExecPlan 不是行业通用概念，也不是 Codex 内置术语，而是这篇示例文章里人为定义的项目内约定。

这里的重点不是文件名本身，而是把“如何做长任务”从一次性 prompt 迁移到版本库中的持久协议。AGENTS.md 负责告诉 Codex 什么时候触发这种模式；PLANS.md 负责定义计划文档必须包含目的、上下文、步骤、验证、进度、意外发现、决策日志和复盘。具体任务的 ExecPlan 则成为可审查、可恢复、可接力的工作状态。

这与 Codex 的 Goals 机制互补：Goal 是当前线程中的完成契约，适合让 Codex 持续围绕一个目标推进；PLANS.md 驱动的任务计划是仓库文件里的执行规格，适合多小时任务、换手任务和需要事前审查的工程设计。两者都在对抗同一个问题：长任务不能只依赖模型当前上下文里一段容易遗失的计划。

25 小时长程任务实验

OpenAI 2026 年 2 月的《Run long horizon tasks with Codex》把 Codex 的能力边界放在时间跨度 上观察，而不是只看一次性代码生成。实验给 GPT-5.3-Codex 一个空仓库、完整权限和“从零构建设计工具”的任务，使用 Extra High reasoning，连续运行约 25 小时。文章明确说这不是生产发布，而是一次压力测试：看 Codex 能否长期遵循规格、保持任务焦点、持续验证并修复失败。

截图给出的会话统计比正文更具体：active runtime 为 25.4 小时，wall-clock session span 为 29.7 小时；token usage 约 12.7M，其中 input 10.7M、output 2.0M、cached input reused 267.8M；tool calls 为 2,106，其中 shell calls 1,391、patches 632；patch volume 约 26.0k 行；自动上下文压缩 13 次，单步峰值 270,352 tokens。这些数字说明 Codex 的长任务能力依赖 Prompt Caching（提示缓存）、Context Engineering（上下文工程）和外部验证循环共同工作，而不是靠一次超长 prompt。

这个实验的文件栈可以看作 Codex 版的 Long-running Agent Harness：

文件	角色
`Prompt.md`	固定规格、目标、非目标、硬约束、交付物和 “done when”
`Plan.md`	把任务拆成 milestone，每个 milestone 带验收标准和验证命令
`Implement.md`	作为 runbook，要求按计划推进、保持 diff 收敛、失败先修再继续
`Documentation.md`	记录当前状态、已做决策、运行方式、demo flow 和后续问题

实验中的设计工具最终实现了 canvas 编辑、实时协作、检查器、图层管理、对齐/吸附、历史快照、replay timeline、prototype mode、评论和 JSON / React + Tailwind 导出等高层能力。更关键的是验证策略：每个 milestone 后运行 lint、typecheck、test、build、export CLI、snapshot tests、replay tests 和 persistence tests；出现 lint 失败时，Codex 会读取相关文件、修改代码并重新验证。

对 Codex 的产品含义是：长程任务的可靠性来自“规格文件 + 里程碑 + 执行 runbook + 状态日志 + 机器验证”的组合。模型更强只是必要条件；让模型在几十小时里不漂移，仍然需要把目标、进度和证据写入仓库，而不是只放在对话上下文里。

Memories：自动维护的跨线程记忆

Codex Memories 可以从符合条件的历史线程中提取稳定偏好、重复工作流、技术栈、项目约定和已知陷阱，在后续线程中作为辅助上下文使用。它默认关闭，可在 Codex 设置中开启，或写入：

# ~/.codex/config.toml
[features]
memories = true

记忆生成在后台完成：Codex 会跳过仍活跃或过短的线程，等线程空闲后再提取；接近 rate limit 时也可能跳过生成，因此线程结束后不会立即出现新记忆。生成文件默认位于 ~/.codex/memories/，包含摘要、持久条目、近期输入和支撑证据。

Codex App 和 TUI 可用 /memories 控制当前线程是否使用已有记忆，以及是否允许该线程成为未来记忆的来源。线程级选择不改变全局设置。详细机制与边界见 Agent Memory（Agent 记忆）。

Subagents：显式并行委派

Codex 可以由主智能体启动多个专用子智能体，并行完成代码探索、专项审查、测试或文档核对，再把结论汇总回主线程。中间搜索、日志和大段工具输出留在子线程，主线程继续保存需求、约束和关键决策。

子智能体不会自动触发，用户必须明确要求委派或并行工作。Codex 内置 default、worker 和 explorer 三类角色，也允许在 .codex/agents/ 或 ~/.codex/agents/ 中用 TOML 定义自定义 Agent，为不同角色指定模型、推理力度、沙箱、MCP 和 Skill。子线程继承当前会话的沙箱和审批策略，自定义角色可以把权限进一步收紧为只读。

这一能力适合边界清楚、彼此独立的只读任务。多个 Agent 同时修改相同文件会增加合并冲突与协调成本，应划分文件所有权或配合独立 worktree。

Goals：线程级完成契约

Codex Goals 是 Codex 的线程级持久目标机制。用户用 /goal 声明一个可验证目标后，Codex 会围绕该目标在后续 turn 中继续工作，并根据测试、benchmark、文件 diff、命令输出、研究材料或最终产物等证据判断是否完成。

它解决的不是“怎样写更长的 prompt”，而是“怎样让目标在多轮工具调用、测试、修复和研究分支之间持续存在”。普通 prompt 更像“做下一件事”；Goal 更像一份完成契约：什么状态算完成、用什么证据验证、哪些约束不能破坏、什么时候应该承认阻塞。

强 Goal 通常包含六个要素：

要素	作用
Outcome	完成时应该为真的状态
Verification surface	用来证明完成的测试、benchmark、报告、产物、命令输出或来源材料
Constraints	迭代时不能破坏的约束
Boundaries	允许使用的文件、工具、数据和仓库范围
Iteration policy	每轮失败或未达标后如何选择下一步
Blocked stop condition	什么时候停止并报告无法继续，以及需要什么输入解锁

Goal 不是全局记忆，也不是项目指令；它属于当前线程。它记录目标、生命周期、预算和进度账本，可被用户暂停、恢复或清除。Codex 可以在证据支持时标记完成，但预算耗尽、路径不明或材料缺失时应报告进展与阻塞，而不是把“已经努力过”当作完成。

Goal 激活后的续跑是事件驱动的，而不是简单无限循环。只有在线程空闲、没有用户输入排队、没有其他工作 pending、Goal 仍 active 且预算未耗尽时，系统才会考虑继续。预算耗尽不是完成；它只意味着应该停止实质工作，汇报进展、阻塞和下一步。

flowchart LR
    G["Goal\n可验证目标"] --> W["Codex 工作\n读代码/改动/运行工具"]
    W --> E["证据\n测试/benchmark/文件/报告"]
    E --> A{"目标满足且约束未破坏?"}
    A -->|"否"| N["选择下一步实验"]
    N --> W
    A -->|"是"| C["标记完成"]
    A -->|"无法推进"| B["报告阻塞与解锁条件"]

这让 Codex 从“执行下一条 prompt”扩展为“围绕一个完成条件工作到证据支持为止”。适合性能优化、flaky test 调查、依赖迁移、benchmark 驱动调优和研究复现；不适合一行编辑、简单解释或没有明确验收面的开放请求。研究型 Goal 尤其需要预先定义证据标准，把已复现机制、近似支持、缺失材料导致的阻塞和剩余不确定性分开写，避免把近似支持写成精确复现。

Codex headless repair loops

OpenAI Cookbook 的 iterative repair loops 示例展示了 Codex CLI 在 headless mode 中被 Python notebook 调用：Review 阶段输出结构化 findings，Repair 阶段只修改复制出来的 notebook，Validation 阶段执行 notebook 并把失败证据写成下一轮 remaining delta。

这个例子说明 Codex 不只适合交互式聊天修代码，也可以作为更大 Harness Engineering（驾驭工程）的一环嵌进自动化流程。关键边界是：Codex 负责提出和应用候选修复，循环外部的验证逻辑负责决定是否继续。

Codex CLI 的推理端点

Codex CLI 的 Responses API endpoint 可配置：

ChatGPT 登录模式使用 ChatGPT 后端的 Codex responses 端点
API key 模式使用 OpenAI hosted model 的 /v1/responses
--oss 模式可连接本机 Ollama 或 LM Studio 暴露的本地 Responses API 兼容端点
也可接入 Azure 等云提供商托管的 Responses API

这种设计把 Codex harness 与具体模型/提供商解耦，符合 Harness Engineering（驾驭工程）中"模型-harness 对"的视角：同一个模型在不同 harness 下表现不同，同一个 harness 也可以接入不同模型后端。

Codex CLI 的上下文与性能策略

Codex 目前不依赖 previous_response_id 续接对话，而是倾向于发送完整的无状态请求。这使请求更容易支持 Zero Data Retention 配置，但也让输入 JSON 随对话增长。

为控制成本，Codex 尽量保持旧 prompt 是新 prompt 的精确前缀，从而利用Prompt Caching（提示缓存）。当上下文超过阈值时，Codex 会使用 Responses API 的 compact 机制，把历史输入替换为更小但保留关键状态的项目列表，其中可包含加密的 compaction item。

Codex 模型的提示与工具协议

OpenAI Cookbook 的 Codex Prompting Guide 从 API 集成视角说明：在 API 中，Codex-tuned 模型名为 gpt-5.3-codex；想获得接近 codex-cli 的表现，通常不能只替换模型名，还要让 prompt、工具 schema、并行工具调用、输出截断和 preamble 协议一起贴近 Codex 的训练分布。

指南建议以 Codex-Max starter prompt 为基础，重点保留自主性与持久执行、代码库探索、工具使用、前端质量、编辑约束和脏工作树保护等行为规则。它同时提醒，过多要求模型在 rollout 期间输出 upfront plan 或冗长状态消息，可能让长任务在真正完成前中断；状态更新应通过更明确的 preamble 机制表达。

对自定义 harness 来说，工具层是主要性能杠杆之一：

shell 工具应显式带 workdir，不要依赖 cd 隐式改变状态
文件修改优先提供 apply_patch 这类贴近 Codex 经验的补丁工具
计划工具用稳定状态枚举表达任务进展
多文件读取应通过并行工具调用批量完成
长工具输出应截断为保留开头和结尾的结构，而不是随意吞掉尾部结论

gpt-5.3-codex 还引入了 assistant 输出项上的 phase 元数据，用于区分 commentary/preamble 与 final answer。harness 在重建历史时必须保留这些 assistant item 及其 phase；丢失该信息会让模型无法正确区分工作中的状态更新和最终收尾。