一个让人困惑的现象#

你和同事都在用 Codex，他那边运行顺畅，你的却频频报错。检查了半天，发现问题出在一个隐藏在项目根目录的 AGENTS.md 文件上。他写了，你没写。

Codex 的配置体系不像传统 IDE 那样"改个设置就完事"。它有一套分层合并机制，指令文件、工具连接、权限控制各自独立又互相影响。搞懂这套体系，Codex 才真正从"能用"变成"好用"。

Codex 的配置心智模型#

在深入细节之前，先建立一个整体框架。Codex 的配置可以归纳为四层：

层级职责对应文件
指令层告诉 Codex “怎么干活”AGENTS.md
工具层告诉 Codex “能用什么”MCP Server 配置
技能层告诉 Codex “怎么做特定任务”Skills 目录
偏好层告诉 Codex “用什么模型、什么权限”config.toml

这四层各司其职，但最终会被 Codex 合并成一个统一的执行上下文。理解它们的边界和交互方式，是高效使用 Codex 的前提。

三种界面，一套配置栈#

Codex 提供了三种使用方式：CLI（命令行）、VS Code 扩展、macOS 桌面应用。很多人以为它们是三个独立产品，其实它们底层读的是同一套配置文件。

CLI 是最灵活的入口。终端里的 Codex 速度快、支持完整的 MCP 和 Skills，适合脚本化和自动化场景。

VS Code 扩展 把 Codex 的能力嵌入编辑器侧边栏。它和 CLI 共享同一套配置，你在 CLI 里配好的 AGENTS.md、MCP、Skills，在 VS Code 里直接生效。

macOS 桌面应用 提供了独立的工作区界面。适合不想在终端或编辑器里切来切去的人，但目前只支持 macOS。

我的建议：日常开发用 CLI 或 VS Code 扩展就够了。桌面应用更适合需要"专注模式"的场景，把 AI 编程和日常编辑器工作分开。

AGENTS.md：给 Codex 写一份"项目说明书"#

AGENTS.md 是 Codex 的指令核心。它的作用是告诉 Codex：这个项目是什么，怎么构建，哪些地方不能碰。

合并机制：从根目录一路向下#

Codex 读取 AGENTS.md 的方式很特别。它从项目根目录开始，沿着目录树往下走到你当前所在的文件夹，把沿途找到的 AGENTS.md 文件依次拼接。

项目根/
  AGENTS.md              ← 第一层：项目概览
  src/
    AGENTS.md            ← 第二层：源码约定
    components/
      AGENTS.md          ← 第三层：组件规范

在 src/components/ 下工作时，Codex 会把三层内容合并。这意味着你可以在根目录写全局规则，在子目录写局部约束。

还有一个 AGENTS.override.md 机制。如果某个目录需要完全覆盖上级指令（而不是追加），用这个文件。

写什么，不写什么#

一份好的 AGENTS.md 应该控制在 10 条以内，每条都具体明确。

应该写的：

  • 项目是什么，面向谁
  • 关键命令（dev、build、test、lint）
  • 入口文件（Codex 应该先读哪几个文件）
  • 架构边界（主要目录的职责划分）
  • 硬性约束（比如"纯静态导出，不用 Server Actions"）
  • 非显而易见的约定（命名规则、import 顺序、生成代码的位置）
  • 禁止修改的区域（密钥、生产配置）
  • 验证方式（跑测试、类型检查、lint）

不应该写的：

  • 长篇大论的编程哲学。如果 AGENTS.md 比 README 还长，说明你写多了。
  • 代码风格规则。链接到 ESLint/Prettier 配置就行，别复制粘贴进来。
  • 敏感信息。永远不要把 API Key 写在 AGENTS.md 里。
  • 空洞的口号。“写干净的代码”、“保持简洁"这类话毫无指导意义。

快速生成#

在 Codex 里运行 /init，它会自动扫描项目结构并生成一份 AGENTS.md 草稿。生成之后，删掉多余的，保留真正有用的部分。

MCP：让 Codex 连接外部世界#

MCP（Model Context Protocol）是 Codex 连接外部工具的标准协议。你可以把它理解为 Codex 的"插件系统”。

为什么需要 MCP#

Codex 本身能读代码、改文件、跑命令。但它不能直接访问 GitHub Issues、查 Jira 工单、读 Confluence 文档。MCP 就是为了解决这个问题：让 Codex 能调用外部服务的 API，获取上下文信息。

配置方式#

MCP 的配置在 config.toml 里，有两种作用域：

  • 全局配置：~/.codex/config.toml，对所有项目生效
  • 项目配置：.codex/config.toml，只对当前项目生效

配置优先级从高到低：CLI 参数 > 项目配置 > 全局配置 > 默认值。

一个典型的 MCP 配置：

[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env_vars = ["GITHUB_PERSONAL_ACCESS_TOKEN"]

也可以用 CLI 快速添加：

codex mcp add github -- npx -y @modelcontextprotocol/server-github

常见问题排查#

MCP 连不上是最常见的问题。排查思路：

  1. 工具没出现：检查配置是否写在了正确的 scope 里（全局 vs 项目），重启 Codex
  2. 认证失败：确认环境变量已导出，Token 没过期。用 echo $VARIABLE_NAME 验证
  3. 命令找不到：确认 npx（Node.js）或 uvx（uv）已安装
  4. 服务启动但工具报错：先在 Codex 外面手动运行命令，确认能正常工作

一个实用技巧：用 codex mcp list 查看当前生效的 MCP 配置，快速定位配置层级问题。

Skills：可复用的任务剧本#

如果某个工作流是可重复的、多步骤的、容易出错的，就应该封装成 Skill。

Skill 的结构#

每个 Skill 是一个文件夹，核心是一个 SKILL.md 文件：

.agents/skills/
  code-review/
    SKILL.md           # 技能定义（YAML frontmatter + 指令）
    examples/          # 可选的示例输入/输出

SKILL.md 的格式：

---
name: code review
description: Review code for bugs, style issues, and best practices
command: review
---
## What I do
- Review code diffs for bugs, logic errors, and security issues
- Check performance implications of changes
- Suggest specific fixes with line numbers

## When to use me
`/review` when you want a second pair of eyes on code changes.

Skill 存放位置#

  • 项目级：.agents/skills/ 目录，跟着仓库走，团队共享
  • 用户级：~/.codex/skills/ 目录，个人专属

团队协作用项目级，个人习惯和快捷方式放用户级。

实用 Skill 示例#

代码审查 Skill：定义审查的优先级（先找 Bug，再看性能，最后看风格），输出格式（按严重程度分级），以及具体的审查步骤。

文档更新 Skill：当代码变更涉及公共 API 时，自动识别需要更新的文档，生成迁移说明，但不会擅自删除已有文档。

测试生成 Skill：根据变更的代码自动生成对应的测试用例，遵循项目的测试框架和命名约定。

config.toml：细粒度偏好控制#

config.toml 是 Codex 的核心配置文件，控制模型选择、权限策略、通知方式等。

关键配置项#

# 模型选择
model = "gpt-5-codex"
model_reasoning_effort = "medium"

# 权限策略
approval_policy = "on-request"    # untrusted / on-request / never
sandbox_mode = "danger-full-access"  # read-only / workspace-write / danger-full-access

# Web 搜索（内置功能，不需要 MCP）
web_search = "cached"             # cached / live / disabled

# 任务完成通知
notify = "afplay /System/Library/Sounds/Submarine.aiff"  # macOS
# notify = "paplay /usr/share/sounds/freedesktop/stereo/complete.oga"  # Linux

权限控制#

Codex 默认在受信任的项目中使用宽松权限。如果你刚接触一个新项目，建议从严格模式开始：

approval_policy = "untrusted"
sandbox_mode = "read-only"

等你熟悉了项目的结构和约束，再逐步放宽。也可以在 Codex 里用 /permissions 命令实时切换。

Web 搜索#

这是 Codex 的内置功能，不需要额外配置 MCP。设为 cached 时使用缓存结果，live 时实时搜索，disabled 关闭。对于大多数开发场景，cached 就够了。

五个常见配置陷阱#

1. AGENTS.md 变成垃圾场

把所有东西都塞进 AGENTS.md，最后变成一份几百行的文档。Codex 处理长指令的效果会打折扣。解决方案：控制在 10 条以内，详细内容放进 Skills 或 docs/ 目录。

2. Token 泄露到 Git

在 config.toml 里写死 API Token，然后不小心提交到仓库。解决方案：用环境变量 env_vars = ["TOKEN_NAME"]，让 config.toml 本身不含敏感信息，可以安全提交。

3. MCP 连不上

最常见的原因是环境变量没导出，或者命令不在 PATH 里。解决方案：先在终端手动运行 MCP 命令，确认能正常工作，再配到 Codex 里。

4. 桌面应用不认配置

改了 config.toml 但桌面应用没反应。Codex 不一定会热加载配置。解决方案：重启应用，确认你改的是正确的配置层级（用户级 vs 项目级）。

5. 权限被意外放开

在不熟悉的项目里用了 danger-full-access，Codex 可能会做出超出预期的修改。解决方案：新项目默认用 read-only，逐步放开。

和 Claude Code、Gemini CLI 的对比#

如果你同时接触过这几个工具，这里有一些实际使用后的对比：

配置复杂度：Codex 的 AGENTS.md 比 Claude Code 的 CLAUDE.md 简单得多。没有复杂的记忆文件继承规则，所见即所得。Gemini CLI 的 GEMINI.md 介于两者之间。

多端一致性：Codex 的最大优势。CLI、VS Code、桌面应用共享同一套配置。Claude Code 主打终端体验，Gemini CLI 也以命令行为主。

工具生态：Codex 的 MCP 是第一公民，配置方式统一。Claude Code 的工具集成依赖子代理机制，Gemini CLI 有内置的 Google 搜索。

文档质量：Claude Code 的文档最完善。Codex 的文档还在追赶，遇到边缘情况可能需要看源码。

总结#

Codex 的配置体系可以浓缩为一个公式：

指令（AGENTS.md）+ 工具（MCP）+ 技能（Skills）+ 偏好（config.toml）= 完整的 AI 编程环境

关键是理解每一层的职责边界。AGENTS.md 管"怎么干活"，MCP 管"能用什么工具"，Skills 管"怎么做特定任务"，config.toml 管"用什么模型和权限"。

把这四层配好，Codex 就不只是一个能帮你写代码的工具，而是一个真正理解你项目上下文的编程伙伴。

参考来源：OpenAI Codex Setup: AGENTS.md, MCPs, Skills (Definitive Guide 2026)，Dmytro Chaban