Codex - Docs Note

本文最后更新于 2026年4月19日 晚上

前言

迄今为止的自己和原始人一样，还没用过Copilot以外的Agent。为了防止落后于时代，充值了一个ChatGPT Plus才不是因为充不起Claude Code，以使用最新最热的Codex。并且将在这篇笔记中记录一些自己阅读Codex官方文档学习到的使用Agent进行开发的workflow。

阅读参考：Codex | OpenAI Developers

一些概念

Threads 线程

线程是指单个会话：包括提示词以及后续的模型输出和工具调用。

当Codex在处理某个线程时，这个线程就是“运行中”；可以同时运行多个线程。

就最佳实践而言：比如让Thread A去写代码，开另一个Thread B去写测试，让这两个Thread修改的文件互不相同。

线程可以在本地或云端运行：

  • 本地线程在Sandbox中运行（这个概念之后解释）

  • 云端线程在隔离环境中运行，Codex所做的是：

    • 克隆代码仓库
    • checkout正在处理的分支

    云端线程在需要并行处理工作时非常有用。

所有的线程都存在~/.codex/threads/中：

~/.codex/threads/
 ├── thread_1/
 ├── thread_2/
 └── thread_3/

这个概念其实没那么好理解，我问了几次GPT，总结一下我得到的回答：

Thread
 ├── Turn 1：帮我实现登录功能
 │    ├── Item：用户消息
 │    ├── Item：Codex 回答
 │    ├── Item：运行 pytest
 │    └── Item：修改 login.py
 │
 ├── Turn 2：再补上测试
 │    ├── Item：用户消息
 │    ├── Item：修改 test_login.py
 │    └── Item：再次运行测试
 │
 └── Turn 3：顺便更新 README
      ├── Item：用户消息
      └── Item：修改 README.md

应当把thread理解为一条独立的任务线。

可以类比成GitHub单开一个PR，一个PR是一个新的branch，可以有很多的commit，最后merge到main上。

一个 Project 下面可以有多个 Threads；每个 Thread 是一段“持续的任务会话”（通常表现为一个聊天）

客制化

在Codex中，客制化通过这么几个机制来实现：

  • AGENTS.md：塑造行为模式
  • Memories：传递局部上下文
  • Skills：封装可重复流程
  • MCP：将Agent连接到本地空间之外的系统
  • Subagents

下面对这些部分进行简单介绍。

AGENTS.md

里面写入希望Codex在代码库中每次遵顼的规则，比如Build-and-Test、Review期望、特地Spec、目录说明等。

当Agent做出错误的事情的时候，在AGENTS.md中予以纠正，并要求Agent去update。

AGENTS.md有多个优先级加载：

  • ~/.codex/AGENTS.md
  • repo-root/AGENTS.md

离得越近的，优先级越高。

何时更新AGENTS.md

  • 重复犯同样的错误时，加规则
  • 添加指导，让其正确阅读文件
  • 使用自动化工具进行检查
  • In GitHub: In a pull request comment, tag @codex with a request (for example, @codex add this to AGENTS.md) to delegate the update to a cloud task. (其实就是会把PR review里面的内容加入AGENTS.md)

将AGENTS.md与hooks, linters, type-checkers搭配来防止错误。

分层设置

repo/
 ├── AGENTS.md                （全局项目规则）
 └── services/payments/
      └── AGENTS.override.md  （支付模块特殊规则）

Codex的加载规则：从全局 → 一路往下找 → 到当前目录为止。在哪个目录启动 codex，就加载到哪一层，不会继续往下找。

建议把override放在越接近实际工作目录越好。

Skills

  • 提供可重复workflow的可复用能力
  • 在运行时被Agent加载并可见

一个skill的组成，在一个my-skill/文件夹下：

  • SKILL.md
  • scripts/：可选
  • references/：可选
  • assets/：可选

一个SKILL.md的例子：

---
name: commit
description: Stage and commit changes in semantic groups. Use when the user wants to commit, organize commits, or clean up a branch before pushing.
---

1. Do not run `git add .`. Stage files in logical groups by purpose.
2. Group into separate commits: feat → test → docs → refactor → chore.
3. Write concise commit messages that match the change scope.
4. Keep each commit focused and reviewable.

和AGENTS.md一样，skills也分全局的和特定项目的：

Layer Global Repo
Skills $HOME/.codex/skills .codex/skills in repo

Codex是如何渐进式使用skills的？

  • 首先读metadata (name, description) for discovery
  • 仅当选中skills时加载SKILL.md
  • 仅在需要时读取scripts或references

skills可以被显式，或被智能体自己隐式调用。

  • 可以使用$skill-name来显式调用一个skill
  • 隐式调用十分依赖于description

创建一个skill

调用$skill-creator，之后跟着Agent的指导走。

MCP

Model Context Protocol

将Agent连接到外部工具的标准能力。

Use MCP when Codex needs capabilities that live outside the local repo, such as issue trackers, design tools, browsers, or shared documentation systems.

Skills + MCP together

二者搭配使用效率很高：skills定义操作流程，而MCP将skils与外部工具连接起来。(A skill defines the workflow and names the MCP tools to use)

Sandbox

简单来说：一个限制Codex访问权限的工具。

在不同的操作系统上，实现的原理不同，但是核心理念保持一致。

比如最常见的Permissions：

  • Default permissions
  • Full access

就是Sandbox的一个体现。

在CLI中使用/permissions在会话期间切换模式

至于具体的Sandbox的设置，是存储在config.toml中的。里面可以设置具体的键值对，来控制Sandbox内的权限。

common sandbox modes:

  • read-only
  • workspace-write：默认的模式
  • danger-full-access：完全放权

常用的approval policies:

  • untrusted：在运行不在trusted集合的命令之前进行询问
  • on-request：默认沙盒内运行，只有需要超出边界时询问
  • never：不管任何审批策略

如果您需要 Codex 在多个目录中工作，可写根目录允许您扩展其可修改的位置，而无需完全移除沙盒。如果您需要更宽或更窄的信任边界，请调整默认沙盒模式和审批策略，而不是依赖一次性例外。

Subagents

  • subagent workflow: 一种让Codex并行运行多个Agent并整合结果的workflow
  • subagent: 由Codex启动并处理特定任务的Agent
  • Agent thread: CLI thread for an agent, use /agent来进行检查和切换

Subagent workflows的优势：简单来说，主会话的上下文窗口非常宝贵，如果把一些脏活累活比如跑测试的嘈杂的中间结果充斥于主会话，那么可靠性是会降低的。(context pollution and context rot)
因而，使用subagent workflow将杂活移除主会话，让subagents负责测试、日志分析等工作，最后subagents会返回其工作的摘要。

custom agents

Codex内置了以下agents：

  • default
  • worker：专注于实现与修复
  • explorer：侧重于读取代码库

需要自定义，可以在/.codex/agents下添加独立的toml文件。

引用Example: PR review 将这个工作分给三个自定义agent： pr_explorer reviewer docs_research...

Example: PR review

将这个工作分给三个自定义agent：

  • pr_explorer
  • reviewer
  • docs_researcher

.codex/agents/pr-explorer.toml:

name = "pr_explorer"
description = "Read-only codebase explorer for gathering evidence before changes are proposed."
model = "gpt-5.3-codex-spark"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
developer_instructions = """
Stay in exploration mode.
Trace the real execution path, cite files and symbols, and avoid proposing fixes unless the parent agent asks for them.
Prefer fast search and targeted file reads over broad scans.
"""

.codex/agents/reviewer.toml:

name = "reviewer"
description = "PR reviewer focused on correctness, security, and missing tests."
model = "gpt-5.4"
model_reasoning_effort = "high"
sandbox_mode = "read-only"
developer_instructions = """
Review code like an owner.
Prioritize correctness, security, behavior regressions, and missing test coverage.
Lead with concrete findings, include reproduction steps when possible, and avoid style-only comments unless they hide a real bug.
"""

.codex/agents/docs-researcher.toml:

name = "docs_researcher"
description = "Documentation specialist that uses the docs MCP server to verify APIs and framework behavior."
model = "gpt-5.4-mini"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
developer_instructions = """
Use the docs MCP server to confirm APIs, options, and version-specific behavior.
Return concise answers with links or exact references when available.
Do not make code changes.
"""

[mcp_servers.openaiDeveloperDocs]
url = "https://developers.openai.com/mcp"

第三个subagent显式调用 MCP 来读文档。

如何使用

Codex不自动生成subagent，只在明确要求时启用。

一个优秀的prompt示例：

Review this branch with parallel subagents. Spawn one subagent for security risks, one for test gaps, and one for maintainability. Wait for all three, then summarize the findings by category with file references.

对于不同的agent可以指派使用不同的基模以及不同的推理深度。

Models

在config.toml中指定：

model = "gpt-5.4"

在Codex CLI中，使用/model来切换模型。

Codex App的使用

与 IDE 扩展同步

如果你在编辑器中安装了 Codex IDE 扩展，当你的 Codex 应用和 IDE 扩展处于同一项目时，它们会自动同步。

同步后，你会在 Codex 应用的编写器中看到一个 IDE 上下文选项。启用“自动上下文”后，Codex 应用会追踪你正在查看的文件，这样你就可以间接引用它们（例如，“这个文件是关于什么的？”）。你还可以在 IDE 扩展中看到 Codex 应用中运行的线程，反之亦然。

Automation

具体而言，就是让Codex“自动按规则、按时间、在后台反复执行任务。

每次执行自动化，可以Local执行，也可以新建一个worktree。

Worktree

只适用于使用Git管理的项目，底层基于git-worktree。

相当于是给代码库创建了一个副本，每个工作树都有代码库中所有文件的独立副本，但是共享相同的.git文件夹。

Terms:

  • Local checkout: 自己创建的代码仓库
  • Worktree
  • Handoff: 在本地和工作树之间交接的操作流程，这里的Git操作由Codex处理。

使用

可以新建worktree然后在里面工作，也可以把worktree里面工作的thread handoff给local。

所有的worktree统一管理在一个位置。由于worktree很占磁盘空间，Codex会自动清理最近的15个以外的。不过，特别设置的不会被清理。

Local environments

默认存在项目根目录的.codex文件夹内。

Codex CLI

感觉Codex App还可以，暂时不看了。

Configuration

配置文件

~/.codex/config.toml，里面一堆API，这个记了也没什么意思。

Configuration Reference – Codex | OpenAI Developers

Plugins

一个插件可以包含：

  • Skills
  • Apps - 比如连接到GitHub, GMail
  • MCP

在Codex App里面直接安装即可。

使用方式：用@调用并描述，或者使用自然语言说明。

最佳实践

这里大多是作为一些优秀用法的汇总。

上下文与Prompt

prompt原则：在prompt中包含这四个要素：

  • 目标
  • 上下文，使用@提及
  • 约束条件
  • 完成条件，比如需要满足哪些要求，才视作完成任务。

Plan first

  • 使用plan mode：/plan，然后询问Codex，「让Codex进行访谈」
  • 使用PLANS.md模板：具体而言，实践模式是先在AGENTS.md里面注明好关于计划的部分在@PLAN.md里面。

利用好AGENTS.md

一份优秀的AGENTS.md包含：

  • repo layout and important directories
  • How to run the project
  • Build, test, and lint commands
  • Engineering conventions and PR expectations
  • Constraints and do-not rules
  • What done means and how to verify work

如果 AGENTS.md 文件变得过于庞大，则保持主文件简洁，并引用针对特定任务的 Markdown 文件来处理规划、代码审查或架构等事项。

code review

通过AGENTS.md来告诉Codex，什么是“好”的代码，以此进行review。

可以写code_review.md文件，然后通过AGENTS.md引用之。

/review：后面给prompt，具体告诉如何审查。

控制长会话

对于CLI：

  • /fork：创建新线程，同时保留原始对话记录
  • /compact：压缩上下文
  • /agent：当并行运行agents时，想在不同线程之间切换时使用（App内直接GUI点就行了）