/ NLP, DEEPLEARNING

Codex 使用指南：从一次对话，到一套可复用的开发工作流

官网：Codex

注册：当注册的时候需要你填写电话（没有中国区电话）的时候，可以通过这个SMS短信来购买临时的虚拟电话号来接受短信完成注册。

刚开始使用 Codex 时，很多人会把所有要求都塞进当前对话：代码风格写在 Prompt 里，项目规则靠记忆补充，常用流程每次重新描述，外部数据源则临时寻找连接方式。

这样当然可以完成任务，但随着项目增多，配置会逐渐变得难以维护。更好的方式是先分清楚一件事：不同类型的要求，应该放在不同的配置层。

本文从这个问题出发，梳理 Codex 中最常用的四类配置：对话提示、AGENTS.md、config.toml 和 Skill，并进一步介绍 MCP 如何把外部工具和数据源接入工作流。读完之后，你应该能够回答三个问题：

  • 这条要求应该写在哪里？
  • 这个能力应该属于项目，还是属于个人环境？
  • 我应该使用规则、Skill，还是 MCP？

一. codex配置总览

1.1 整体配置地图

可以把 Codex 的配置理解成一张从“临时要求”到“长期能力”的地图：越靠近当前对话，影响范围越小、变化越快；越靠近用户全局环境，复用范围越大、稳定性要求也越高。

需求 推荐位置 作用范围 典型内容
当前任务的临时要求 当前对话 Prompt 当前任务 “请只修改这个文件”
团队规范和验证方式 仓库或目录下的 AGENTS.md 当前目录及其子目录 代码风格、测试命令、目录职责
Codex 的运行默认值 项目内或用户级 config.toml 项目级或用户级 模型、沙箱、审批、MCP 等配置
可复用的专业流程 .agents/skills/<name>/SKILL.md 或 $CODEX_HOME/skills/<name>/SKILL.md 项目级或用户级 代码审查、文档生成、数据处理流程
外部工具和数据源 config.toml 中的 [mcp_servers.<name>] 当前配置作用域 数据库、搜索服务、内部 API

Codex 配置层级示意

一个简单的判断原则是：

  1. 只在这一次任务中有效的要求，写在对话里。
  2. 只对某个项目或团队有效的约定，写进项目内的 AGENTS.md。
  3. 希望改变 Codex 运行方式的设置，写进 config.toml。
  4. 需要反复执行、具有明确步骤的工作流，沉淀为 Skill。
  5. 需要访问外部系统时，配置 MCP；MCP 的说明文字本身并不是连接配置。

1.2 运行环境配置

常见的配置作用域包括：

  • 项目级：项目/.codex/config.toml
  • 用户级：~/.codex/config.toml

项目级配置适合团队共享的项目设置，用户级配置适合个人默认值、插件和通用服务。涉及个人路径、凭据或本机差异的内容，应谨慎放入项目配置。

二. Rules配置

2.1 规则是什么

AGENTS.md 更像是项目交给 AI 助手的一份协作说明书。Codex 开始任务时，会在相关目录范围内查找并读取它。常见的规则来源包括：

  1. 全局规则：~/.codex/AGENTS.md
  2. 项目根目录：项目/AGENTS.md
  3. 更深层目录中的规则文件：只约束对应目录及其子目录

具体的读取和合并行为会受到运行环境与目录结构影响，因此最好把项目的关键约定放在项目根目录，并在实际任务中验证 Codex 是否正确读取。

2.2 规则怎么写

一份实用的 AGENTS.md 通常包含以下内容：

  • 仓库目录职责与代码组织方式
  • Python 命名、导入、异常处理和注释约定
  • Spark、UDF、地理计算和数据字段规范
  • 生产环境中的敏感信息保护规则
  • 本地脚本、文档和发布流程
  • 推荐的测试、格式化和检查命令
  • 代码完成后的验收标准

规则要尽量具体、可执行。例如，与其写“注意代码质量”，不如写成：

## 验证要求

- 修改 Python 文件后运行 `pytest tests/`。
- 修改 SQL 后检查字段名、分区字段和空值处理。
- 不得在代码中提交 Token、密码或内部服务地址。

规则文件的目标不是把所有背景知识都塞进去，而是让一个刚进入项目的协作者能够稳定地完成任务。对于需要多步执行的复杂流程，则更适合使用 Skill。

三. Skill配置

3.1 Skill 放在哪里

Skill 是一套可以反复调用的专业工作流。项目级 Skill 通常放在：

.agents/
└── skills/
    └── review-code/
        └── SKILL.md

创建项目级 Skill：

mkdir -p .agents/skills/review-code
touch .agents/skills/review-code/SKILL.md

如果一项能力只属于 Codex，可以放在用户级目录 ~/.codex/skills。如果希望其他 Agent 也能够使用，可以放在用户级目录 ~/.agents/skills。用户级 Skill 通常可以被多个项目复用。

3.2 一个简单的skill编写例子

一个最小可用的 Skill 至少包含一个 SKILL.md。推荐使用 YAML 头部声明名称和用途，再写清楚执行流程：

---
name: review-code
description: Review code changes and report actionable findings.
---

# Review workflow

1. Read the relevant diff and nearby code.
2. Check tests and error handling.
3. Report findings with file and line references.
4. State remaining test gaps.

Skill 配置与调用示意

3.3 codex如何调用 Skill

最直接的方式是在对话里点名：

请使用 review-code skill 检查当前代码。

如果希望 Codex 在满足某种场景时自动考虑使用 Skill，需要在 description 中写清楚触发条件。例如：

description: 在需要检查代码变更、测试覆盖和错误处理时使用此技能。

这里有一个值得区分的边界：

  • AGENTS.md 适合描述“这个项目始终遵守什么规则”。
  • Skill 适合描述“完成某类任务时，要按什么步骤执行”。

前者是项目约束，后者是工作流程。两者可以配合，但不应该互相替代。

四. MCP配置

4.1 用 MCP 连接外部工具

Skill 主要告诉 Codex“如何完成一件事”，MCP 则让 Codex“能够访问什么工具或数据”。例如，数据库、搜索服务、内部 API 或其他外部系统，都可以通过 MCP 接入。

MCP 的两类连接方式

在 config.toml 中，MCP Server 常见的连接方式有两种：

  • stdio： Codex 在本机启动一个 MCP Server 进程。
  • URL / HTTP： Codex 连接一个远程 MCP endpoint，认证方式取决于服务本身。

MCP 配置示意

4.2 一个本地 MCP Server 示例

下面是一个完整的接入本地mcp服务的例子，直接让AI帮你生成：

image-20260904161049651

项目级配置可以放在项目内的 .codex/config.toml，用户级配置可以放在 ~/.codex/config.toml。下面是一个通过本地 Python 进程启动 MCP Server 的示例：

[mcp_servers.training_sqlite]
command = "~/training_sqlite_mcp/.venv/bin/python"
args = ["~/training_sqlite_mcp/server.py"]
startup_timeout_sec = 20

当 Codex 启动并读取到这段配置后，就会尝试启动名为 training_sqlite 的本地 MCP 服务。配置完成后，建议检查三件事：

  1. command 指向的程序是否存在并且可执行。
  2. args 中的脚本路径是否正确。
  3. Server 启动日志和工具列表是否符合预期。

某些 MCP 客户端也会使用独立的客户端配置文件，例如 ~/.mcporter/mcporter.json。这类文件属于对应客户端的配置，不应和 Codex 的 config.toml 混为一谈。使用哪种文件，取决于实际启动 MCP 的客户端和集成方式。

五. 总结

5.1 能力组合

一个成熟的 Codex 项目，通常不是只选其中一种配置，而是让它们各司其职：

当前对话 Prompt
    负责本次任务的目标和临时限制

AGENTS.md
    负责项目长期规则和验收标准

Skill
    负责可重复的专业执行流程

config.toml
    负责运行参数和外部服务连接

MCP
    提供数据库、搜索、API 等外部能力

例如，一个数据处理项目可以这样组织：

  • 用 AGENTS.md 规定 Spark 代码风格、分区字段命名和测试命令。
  • 用 review-data-pipeline Skill 固化“读取代码、检查字段、验证数据质量、输出风险”的流程。
  • 用 config.toml 配置项目使用的 MCP Server。
  • 用 MCP 查询测试数据或读取外部元数据。
  • 在当前对话中补充本次任务的日期范围、输出位置和特殊约束。

这样一来，规则、流程、运行环境和任务上下文彼此独立，后续维护也更容易定位。

5.2 常见误区

  • 把所有内容都写进 Prompt：短期看最省事，长期却会导致重复劳动，也容易让不同任务之间的要求互相冲突。稳定规则应该下沉到 AGENTS.md 或 Skill。

  • 把规则写成 Skill：“所有 Python 文件都要运行测试”是项目规则，适合写进 AGENTS.md；“如何进行一次完整的代码审查”才是工作流，适合写进 Skill。

  • 把 MCP 说明当成 MCP 配置：一段介绍 MCP 的文字不会自动创建连接。真正的连接需要配置 Server、启动命令或远程 endpoint，并且要验证服务是否成功启动。

5.3 一份实用的落地顺序

如果你正在从零整理自己的 Codex 环境，可以按下面的顺序开始：

  1. 先在当前对话中验证需求和工作方式。
  2. 把项目中稳定、必须遵守的约定整理到 AGENTS.md。
  3. 把重复出现的多步骤任务整理为 Skill。
  4. 再通过项目级或用户级 config.toml 固定运行环境。
  5. 最后接入真正需要访问的 MCP Server，并单独验证启动和调用。