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_researc...

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 点就行了）