如果你刚开始使用 Codex，或者刚开始使用 coding agents，本指南会帮助你更快获得更好的结果。它涵盖了让 Codex 在 CLI、IDE extension 和 Codex app 中更有效的核心习惯，包括提示词、规划、验证、MCP、skills 和 automations。
当你把 Codex 当作一个可以持续配置和改进的队友，而不是一次性的助手时，它的效果最好。
一个有用的理解方式是：从正确的任务上下文开始，使用 AGENTS.md 存放持久化指导，配置 Codex 以匹配你的工作流，用 MCP 连接外部系统，把重复工作变成 skills，并将稳定的工作流自动化。
强力的首次使用：上下文和提示词
Section titled “强力的首次使用：上下文和提示词”即使你的提示词并不完美，Codex 也已经足够强大，可以提供价值。你通常可以在最少设置的情况下交给它一个困难问题，并仍然得到不错的结果。清晰的 prompting 并不是获得价值的必要条件，但它确实会让结果更可靠，尤其是在更大的代码库或更高风险的任务中。
如果你在大型或复杂仓库中工作，最大的突破点是给 Codex 正确的任务上下文，并清楚描述你想完成的结构。
一个好的默认提示词应包含四件事：
- 目标： 你想改变或构建什么？
- 上下文： 哪些文件、文件夹、文档、示例或错误与这个任务相关？你可以通过
@提及某些文件作为上下文。 - 约束： Codex 应该遵循哪些标准、架构、安全要求或约定？
- 完成标准： 在任务完成前，什么应该为真？例如测试通过、行为发生变化，或者 bug 不再复现。
这可以帮助 Codex 保持范围明确、减少假设，并产出更容易审查的工作。
根据任务难度选择 reasoning level，并测试哪种设置最适合你的工作流。不同用户和任务适合不同设置。
- Low 适合更快、范围明确的任务
- Medium 或 High 适合更复杂的变更或调试
- Extra High 适合长时间、agentic、推理密集型任务
对困难任务先做计划
Section titled “对困难任务先做计划”如果任务复杂、模糊，或者很难描述清楚，请先让 Codex 制定计划，再开始写代码。
有几种方法很有效：
使用 Plan mode： 对大多数用户来说，这是最简单也最有效的选择。Plan mode 可以让 Codex 收集上下文、提出澄清问题，并在实现前构建更强的计划。可以通过 /plan 或 Shift+Tab 切换。
让 Codex 先采访你： 如果你对想要的东西有一个粗略想法，但不确定如何准确描述，可以让 Codex 先向你提问。告诉它挑战你的假设，并在写代码之前把模糊想法变成具体方案。
使用 PLANS.md 模板： 对于更高级的工作流，你可以配置 Codex 遵循 PLANS.md 或执行计划模板，以处理更长时间运行或多步骤的工作。更多细节请参见 execution plans guide。
使用 AGENTS.md 让指导可复用
Section titled “使用 AGENTS.md 让指导可复用”一旦某个提示词模式有效，下一步就是停止手动重复它。这就是 AGENTS.md 的作用。
可以把 AGENTS.md 理解为面向 agents 的开放格式 README。它会自动加载到上下文中，是编码你和团队希望 Codex 在仓库中如何工作的最佳位置。
一个好的 AGENTS.md 会覆盖：
- 仓库布局和重要目录
- 如何运行项目
- 构建、测试和
lint命令 - 工程约定和
PR期望 - 约束和禁止事项
- 什么算完成，以及如何验证工作
CLI 中的 /init 斜杠命令是快速启动命令，可以在当前目录中搭建一个初始 AGENTS.md。这是一个很好的起点，但你应该编辑生成结果，让它匹配你团队实际构建、测试、审查和发布代码的方式。
你可以在不同层级创建 AGENTS.md 文件：位于 ~/.codex 的全局 AGENTS.md 用于个人默认规则；仓库级文件用于共享标准；子目录中的更具体文件用于局部规则。如果有一个更靠近当前目录的更具体文件，则该指导优先。
保持实用。一个简短、准确的 AGENTS.md 比一个充满模糊规则的长文件更有用。从基础内容开始，然后只在你发现重复错误之后添加新规则。
如果 AGENTS.md 开始变得过大，请保持主文件简洁，并引用任务专用的 markdown 文件，例如规划、代码审查或架构相关文件。
配置 Codex 以保持一致性
Section titled “配置 Codex 以保持一致性”配置是让 Codex 在不同会话和界面中表现更一致的主要方式之一。例如，你可以为模型选择、reasoning effort、sandbox mode、approval policy、profiles 和 MCP 设置默认值。
一个好的起始模式是：
- 将个人默认值放在
~/.codex/config.toml中：Codex app 中进入 Settings → Configuration → Open config.toml - 将仓库特定行为放在
.codex/config.toml中 - 仅在一次性场景中使用命令行覆盖项，如果你使用 CLI
config.toml 是定义持久化偏好的位置，例如 MCP servers、多代理设置和 feature flags。特定 profile 的覆盖项位于单独的 $CODEX_HOME/profile-name.config.toml 文件中。
Codex 自带操作级别的沙盒机制，并有两个你可以控制的关键旋钮。Approval mode 决定 Codex 什么时候请求你允许它运行命令；sandbox mode 决定 Codex 是否可以读取或写入目录，以及 agent 可以访问哪些文件。
如果你刚开始使用 coding agents，请从默认权限开始。默认情况下保持审批和沙盒严格，只有在需求明确之后，才为可信仓库或特定工作流放宽权限。
请注意，CLI、IDE 和 Codex app 共享相同的配置层。可以在 sample configuration 页面了解更多信息。
通过测试和审查提高可靠性
Section titled “通过测试和审查提高可靠性”不要只让 Codex 做变更就停止。需要时让它创建测试、运行相关检查、确认结果，并在你接受之前审查工作。
Codex 可以为你完成这个循环，但前提是它知道什么才算 “好”。这些指导可以来自提示词，也可以来自 AGENTS.md。
这可以包括：
- 为变更编写或更新测试
- 运行正确的测试套件
- 检查 lint、格式化或类型检查
- 确认最终行为符合请求
- 审查 diff，查找 bug、回归或高风险模式
这里一个有用的选项是斜杠命令 /review，它提供几种代码审查方式：
- 基于 base branch 做 PR 风格审查
- 审查未提交变更
- 审查某个 commit
- 使用自定义审查指令
如果你和团队有一个 code_review.md 文件，并且从 AGENTS.md 中引用它，Codex 在审查期间也可以遵循该指导。对于希望审查行为在不同仓库和贡献者之间保持一致的团队来说，这是一个强模式。
Codex 不应该只是生成代码。通过正确指令，它也可以帮助你 测试代码、检查代码和审查代码。
如果你使用 GitHub Cloud，可以设置 Codex 为你的 PR 运行 code reviews。在 OpenAI，Codex 会审查 100% 的 PR。你可以启用自动审查，也可以在 @Codex 时让它响应式审查。
使用 MCPs 获取外部上下文
Section titled “使用 MCPs 获取外部上下文”当 Codex 需要的上下文位于仓库之外时，请使用 MCPs。它可以让 Codex 连接到你已经使用的工具和系统，这样你就不需要不断把实时信息复制粘贴到提示词中。
Model Context Protocol，即 MCP，是一种开放标准，用于将 Codex 连接到外部工具和系统。
当出现以下情况时使用 MCP：
- 所需上下文位于仓库之外
- 数据频繁变化
- 你希望 Codex 使用工具，而不是依赖粘贴的指令
- 你需要跨用户或项目的可重复集成
Codex 支持 STDIO 和带 OAuth 的 Streamable HTTP servers。
在 Codex App 中，进入 Settings → MCP servers 可以查看自定义和推荐 servers。通常，Codex 可以帮助你安装所需 servers。你只需要提出请求。你也可以在 CLI 中使用 codex mcp add 命令，带上名称、URL 和其他细节来添加自定义 servers。
将可重复工作变成 skills
Section titled “将可重复工作变成 skills”一旦某个工作流变得可重复，就不要再依赖长提示词或重复来回沟通。使用 Skill 将指令打包到 SKILL.md 文件中，并附带上下文和 Codex 应该稳定应用的支持逻辑。Skills 可用于 CLI、IDE extension 和 Codex app。
让每个 skill 的范围只聚焦一项工作。从 2 到 3 个具体用例开始，定义清楚输入和输出，并编写 description，使它说明该 skill 做什么以及什么时候使用它。包括用户实际会说的触发短语。
不要一开始就试图覆盖所有边界情况。从一个有代表性的任务开始，让它运行良好，然后把该工作流变成 skill，再持续改进。只有当脚本或额外 assets 能提高可靠性时才添加它们。
一个好的经验法则是：如果你一直重复使用同一个提示词，或者一直纠正同一个工作流，它很可能应该变成一个 skill。
Skills 尤其适合以下重复性工作：
- 日志分诊
- 发布说明起草
- 按清单做 PR 审查
- 迁移规划
- 遥测或事故摘要
- 标准调试流程
$skill-creator skill 是搭建第一个 skill 版本的最佳起点。迭代期间先把第一个版本保持在本地。当它准备好广泛共享时，再将其打包为 plugin。skill 最重要的部分之一是 description。它应该说明该 skill 做什么以及什么时候使用它。
使用 automations 处理重复工作
Section titled “使用 automations 处理重复工作”一旦某个工作流稳定下来，你就可以安排 Codex 在后台为你定期运行它。在 Codex app 中，automations 可以让你为周期性任务选择项目、提示词、频率和执行环境。
一旦某个任务对你来说变得重复，你就可以在 Codex app 的 Automations 标签页中创建 automation。你可以选择它在哪个项目中运行、运行的提示词是什么，也可以调用 skills，以及运行频率。你还可以选择 automation 是在专用 git worktree 中运行，还是在你的本地环境中运行。了解更多关于 git worktrees 的信息。
好的候选任务包括：
- 总结最近 commits
- 扫描可能的 bug
- 起草发布说明
- 检查 CI failures
- 生成站会摘要
- 按计划运行可重复分析工作流
一个有用的规则是：skills 定义方法，automations 定义时间表。如果某个工作流仍然需要大量引导，先把它变成 skill。一旦它可预测，automation 就会成为放大器。
使用会话控制组织长时间运行的工作
Section titled “使用会话控制组织长时间运行的工作”Codex sessions 不只是聊天历史。它们是工作线程，会随着时间积累上下文、决策和操作，因此良好管理它们会显著影响质量。
Codex app UI 让线程管理最简单，因为你可以 pin threads 和创建 worktrees。如果你使用 CLI，这些 slash commands 尤其有用：
/experimental：切换实验性功能并添加到你的config.toml/resume：恢复已保存的对话/fork：在保留原始 transcript 的同时创建新线程/compact：当线程变长，并且你想要早期上下文的摘要版本时使用。请注意，Codex 也会自动为你压缩对话/agent：当你运行并行 agents，并想在活跃 agent 线程之间切换时使用/theme：选择语法高亮主题/apps：直接在 Codex 中使用 ChatGPT apps/status：检查当前会话状态
每个连贯的工作单元使用一个线程。如果工作仍然属于同一个问题，留在同一个线程通常更好，因为它会保留推理轨迹。只有当工作真正分支时才 fork。
刚开始使用 Codex 时，需要避免一些常见错误：
- 在提示词中塞入过多持久化规则，而不是把它们移到
AGENTS.md或 skill 中 - 没有让 agent 看见自己的工作，也就是没有提供如何最好运行构建和测试命令的细节
- 在多步骤和复杂任务中跳过规划
- 在理解工作流之前，就给 Codex 你的电脑的完整权限
- 没有使用 git worktrees，就在相同文件上运行实时线程
- 在工作流还没有手动可靠运行前，就把重复任务变成 automation
- 把 Codex 当成你必须一步一步盯着看的东西，而不是把它和你自己的工作并行使用
- 每个项目只使用一个线程，而不是每个任务使用一个线程。这会导致上下文膨胀，并随着时间推移让结果变差