阅读使用经验和实践建议

如果你刚开始使用 Codex，或刚开始接触 coding agents，这篇 guide 可以帮助你更快获得稳定结果。

它覆盖 Codex 在 CLI、IDE extension 和 Codex app 中都适用的核心习惯：prompting、planning、validation、MCP、skills 和 automations。

使用 Codex 时，与其把它当成一次性 assistant，不如把它当成一个需要配置、需要持续改进的 teammate。

一个实用的思路是：

1. 从正确的 task context 开始。
2. 用 AGENTS.md 保存 durable guidance。
3. 把 Codex 配成贴合你的 workflow。
4. 用 MCP 连接 external systems。
5. 把重复工作沉淀为 skills。
6. 把稳定 workflows 自动化。

第一次使用：上下文和提示词

即使 prompt 不完美，Codex 也已经足够有用。你经常可以只给一个 hard problem 和很少 setup，就得到不错结果。

清晰的 prompting 不是获得价值的前提，但它会让结果更可靠，尤其是在大型 codebases 或 high-stakes tasks 中。

如果你在大型或复杂 repository 中工作，最大的 unlock 是给 Codex 正确 task context，并清楚描述你想完成的结构。

一个好的默认 prompt 包含四件事：

• Goal：你想 change 或 build 什么？
• Context：哪些 files、folders、docs、examples 或 errors 与任务相关？你可以用 @ mention 特定 files 作为 context。
• Constraints：Codex 应该遵循哪些 standards、architecture、safety requirements 或 conventions？
• Done when：任务完成前应该满足什么条件，例如 tests passing、behavior changed，或 bug 不再复现？

这样能帮助 Codex 保持 scope，减少 assumptions，并产出更容易 review 的 work。

reasoning level 应该根据 task 难度选择，并通过测试找到最适合你 workflow 的设置。不同 users 和 tasks 可能适合不同 settings。

• Low：更快，适合 well-scoped tasks。
• Medium 或 High：适合更复杂 changes 或 debugging。
• Extra High：适合 long、agentic、reasoning-heavy tasks。

为了更快提供 context，可以在 Codex app 中使用 speech dictation，直接口述你希望 Codex 做什么，而不是逐字输入。

难任务先规划

如果 task complex、ambiguous，或很难描述清楚，先让 Codex plan，再开始 coding。

几个做法很有效：

Use Plan mode：对多数 users 来说，这是最简单、最有效的选择。Plan mode 让 Codex 先 gather context、ask clarifying questions，并在 implementation 前形成更扎实的 plan。通过 /plan 或 Shift+Tab 切换。

Ask Codex to interview you：如果你只有粗略想法，还不确定怎么描述，可以先让 Codex 提问。让它 challenge your assumptions，并把模糊想法变成具体任务，再写代码。

Use a PLANS.md template：更 advanced 的 workflows 可以配置 Codex 遵循 PLANS.md 或 execution-plan template，用于 longer-running 或 multi-step work。更多信息见 execution plans guide。

用 AGENTS.md 复用项目规则

当某种 prompting pattern 已经有效，下一步就是不要再手动重复它。

这就是 AGENTS.md 的用途。

可以把 AGENTS.md 理解为 agents 的 open-format README。它会自动加载到 context 中，是记录你和团队希望 Codex 如何在 repository 中工作的最佳位置。

一个好的 AGENTS.md 通常覆盖：

• repo layout 和 important directories。
• 如何运行 project。
• build、test、lint commands。
• engineering conventions 和 PR expectations。
• constraints 和 do-not rules。
• done 的定义，以及如何 verify work。

CLI 里的 /init slash command 是快速 scaffold starter AGENTS.md 的命令，会在当前目录创建初始文件。

它是很好的起点，但你应该继续编辑，让它匹配团队真实的 build、test、review 和 ship code 方式。

你可以在不同层级创建 AGENTS.md：

• global AGENTS.md：个人 defaults，位于 ~/.codex。
• repo-level AGENTS.md：共享 standards。
• subdirectory-level AGENTS.md：更具体的 local rules。

如果当前目录附近存在更具体的 AGENTS.md，更近的 guidance 会优先。

保持 practical。短而准确的 AGENTS.md 比充满模糊规则的长文件更有用。

先从基础内容开始，只有当你发现 repeated mistakes 后，再添加新 rules。

如果 AGENTS.md 开始变得过大，保持 main file 简洁，并引用 task-specific markdown files，例如 planning、code review 或 architecture。

当 Codex 第二次犯同样错误时，让它做一次 retrospective，然后更新 AGENTS.md。这样 guidance 会基于真实 friction，而不是抽象规则。

用配置保持行为一致

configuration 是让 Codex 在不同 sessions 和 surfaces 中表现更一致的主要方式之一。

例如，你可以设置 model choice、reasoning effort、sandbox mode、approval policy、profiles 和 MCP setup 的 defaults。

一个好的起步模式是：

• personal defaults 放在 ~/.codex/config.toml。在 Codex app 中可通过 Settings -> Configuration -> Open config.toml 打开。
• repo-specific behavior 放在 .codex/config.toml。
• command-line overrides 只用于 one-off situations，如果你使用 CLI。

config.toml 用来定义 durable preferences，例如 MCP servers、profiles、multi-agent setup 和 feature flags。

你可以直接编辑它，也可以让 Codex 帮你更新它。

Codex 自带 operating level sandboxing，并提供两个关键 knobs：

• approval mode：决定 Codex 什么时候需要询问 permission 才能运行 command。
• sandbox mode：决定 Codex 能否在目录中 read 或 write，以及 agent 能 access 哪些 files。

如果你刚开始使用 coding agents，先使用 default permissions。

approval 和 sandboxing 默认保持收紧；只有当需求明确后，再对 trusted repos 或 specific workflows 放宽。

注意，CLI、IDE 和 Codex app 共享相同 configuration layers。更多信息见 sample configuration。

尽早按你的真实环境配置 Codex。很多 quality issues 本质上是 setup issues，例如 working directory 错误、missing write access、model defaults 错误，或 tools/connectors 缺失。

用测试和审查提升可靠性

不要只让 Codex 做 change 就停下。

需要时，让它创建 tests、运行相关 checks、确认 result，并在你接受前 review 这次工作。

Codex 可以替你完成这个 loop，但前提是它知道什么算 “good”。这类 guidance 可以来自 prompt，也可以来自 AGENTS.md。

它可以包括：

• 为 change 写入或更新 tests。
• 运行正确 test suites。
• 检查 lint、formatting 或 type checks。
• 确认 final behavior 匹配 request。
• review diff，查 bugs、regressions 或 risky patterns。

在 Codex app 中打开 diff panel，可以直接本地 review changes。点击具体 row 可以给 feedback，这些 feedback 会作为 context 进入下一轮 Codex turn。

这里有一个有用的 slash command：/review。它提供几种 review code 的方式：

• 基于 base branch 做 PR-style review。
• review uncommitted changes。
• review 某个 commit。
• 使用 custom review instructions。

如果你和团队有 code_review.md file，并在 AGENTS.md 中引用它，Codex 在 review 时也可以遵循这份 guidance。

这对于希望 review behavior 在 repositories 和 contributors 之间保持一致的团队，是很强的模式。

Codex 不应该只 generate code。给对 instructions 后，它也可以帮助 test it, check it, and review it。

如果你使用 GitHub Cloud，可以设置 Codex 为 PRs 运行 code reviews。在 OpenAI，Codex 会 review 100% 的 PRs。你可以开启 automatic reviews，也可以在需要时通过 @Codex 触发 review。

用 MCP 接入外部上下文

当 Codex 需要的 context 在 repo 外部时，使用 MCP。

MCP 让 Codex 连接到你已经在用的 tools 和 systems，不需要你不断把 live information copy/paste 到 prompts。

Model Context Protocol，简称 MCP，是把 Codex 连接到 external tools 和 systems 的 open standard。

这些情况适合用 MCP：

• 需要的 context 在 repo 外部。
• data 变化频繁。
• 你希望 Codex 使用 tool，而不是依赖粘贴说明。
• 你需要跨 users 或 projects 复用 integration。

Codex 支持 STDIO 和 Streamable HTTP servers，并支持 OAuth。

在 Codex App 中，进入 Settings -> MCP servers，可以查看 custom 和 recommended servers。

很多时候，Codex 可以帮你安装所需 servers。你只需要提出请求。

你也可以在 CLI 中使用 codex mcp add command，按 name、URL 和其他 details 添加 custom servers。

只在 tools 真正解锁 workflow 时添加它们。不要一开始就把所有常用工具都接进来。

先从一两个能明确减少手动循环的 tools 开始，然后再扩展。

把重复工作沉淀成 Skills

当 workflow 变得 repeatable，就不要继续依赖 long prompts 或重复来回沟通。

使用 Skill，把 instructions、context 和 Codex 应该稳定应用的 supporting logic 打包进 SKILL.md。

Skills 可跨 CLI、IDE extension 和 Codex app 使用。

每个 skill 都要聚焦一个 job。先从 2 到 3 个具体 use cases 开始，定义清楚 inputs 和 outputs，并写好 description：说明这个 skill 做什么，以及什么时候使用。

description 中要包含 users 实际会说的 trigger phrases。

不要一开始就覆盖所有 edge cases。先选一个 representative task，把它跑顺，再把 workflow 做成 skill，并持续改进。

scripts 或 extra assets 只有在提升 reliability 时才加入。

一个经验规则：如果你总在复用同一个 prompt，或反复纠正同一个 workflow，它大概率应该变成 skill。

Skills 特别适合 recurring jobs，例如：

• Log triage。
• Release note drafting。
• PR review against a checklist。
• Migration planning。
• Telemetry 或 incident summaries。
• Standard debugging flows。

$skill-creator skill 是 scaffold 第一个 skill version 的最佳起点。

第一版先保持 local，方便 iteration。准备好 broadly share 时，再打包成 plugin。

skill 最重要的部分之一是 description。它应该说明 skill 做什么，以及什么时候使用。

Personal skills 存在 $HOME/.agents/skills；shared team skills 可以 check into repository 内的 .agents/skills。

这对 onboarding new teammates 尤其有帮助。

用自动化处理重复任务

当 workflow 稳定后，可以 schedule Codex 在 background 中为你运行。

在 Codex app 中，automations 可以为 recurring task 选择 project、prompt、cadence 和 execution environment。

当某个 task 对你来说变成 repetitive，就可以在 Codex app 的 Automations tab 创建 automation。

你可以选择它在哪个 project 中运行、运行什么 prompt，也可以 invoke skills，并设置运行 cadence。

你还可以选择 automation 运行在 dedicated git worktree，还是 local environment。更多信息见 git worktrees。

适合 automation 的任务包括：

• Summarizing recent commits。
• Scanning for likely bugs。
• Drafting release notes。
• Checking CI failures。
• Producing standup summaries。
• Running repeatable analysis workflows on a schedule。

一个有用规则是：skills define the method，automations define the schedule。

如果 workflow 仍需要很多 steering，先把它变成 skill。等它可预测后，automation 就会成为 force multiplier。

automations 不只用于 execution，也适合 reflection 和 maintenance。

定期 review recent sessions，summarize repeated friction，并随着时间改进 prompts、instructions 或 workflow setup。

用会话控制组织长任务

Codex sessions 不只是 chat history。

它们是会随时间累积 context、decisions 和 actions 的 working threads，因此 session 管理会直接影响质量。

Codex app UI 最方便管理 threads，因为可以 pin threads 和创建 worktrees。

如果你使用 CLI，下面这些 slash commands 很有用：

• /experimental：toggle experimental features，并添加到 config.toml。
• /resume：resume saved conversation。
• /fork：保留 original transcript，同时创建 new thread。
• /compact：thread 变长时，把早期 context 总结成 summarized version。Codex 也会自动 compact conversations。
• /agent：运行 parallel agents 时，在 active agent thread 之间切换。
• /theme：选择 syntax highlighting theme。
• /apps：直接在 Codex 中使用 ChatGPT apps。
• /status：检查 current session state。

每个 coherent unit of work 使用一个 thread。

如果 work 仍属于同一个 problem，留在同一个 thread 通常更好，因为它能保留 reasoning trail。

只有当工作真正分叉时再 fork。

使用 Codex 的 subagent workflows，把 bounded work 从 main thread 中卸载出去。

让 main agent 专注 core problem，把 exploration、tests 或 triage 这类任务交给 subagents。

常见错误

刚开始使用 Codex 时，常见错误包括：

• 把 durable rules 堆进 prompt，而不是移到 AGENTS.md 或 skill。
• 没有告诉 agent 如何运行 build 和 test commands，导致 agent 看不到自己的工作结果。
• multi-step 和 complex tasks 跳过 planning。
• 在还没理解 workflow 前，就给 Codex full permission 访问你的电脑。
• 不使用 git worktrees，却让多个 live threads 操作同一批 files。
• recurring task 还没手动跑稳定，就提前做成 automation。
• 把 Codex 当成必须逐步盯着看的工具，而不是和你自己的工作并行使用。
• 一个 project 只用一个 thread，而不是一个 task 一个 thread。这会导致 context 膨胀，长期结果变差。