先看一张总表

你想扩展什么	放哪里	怎么触发
项目规则、代码规范、工作流	AGENTS.md	进入该目录作用域后自动生效
全局默认模型、审批、沙盒、MCP 配置	~/.codex/config.toml	启动 codex 时自动加载
外部工具能力（数据库、Figma、文档、Issue 系统）	codex mcp add ... 或 ~/.codex/config.toml 的 [mcp_servers.*]	在对话中自然语言调用，或用 /mcp 管理
可复用工作流 / 领域知识 Skill	官方文档当前使用 .agents/skills/；你这台机器已安装的 OMX 技能位于 ~/.codex/skills/	自动匹配、$skill-name、/skills
专门角色的子 Agent	.codex/agents/*.toml 或 ~/.codex/agents/*.toml	让 Codex 按角色委派，或在界面里选择
一次性命令行覆盖	codex -c key=value ...	当前命令生效

1. 先把 CLI 本体用熟

当前版本里最常用的命令是这些：

# 交互式会话
codex

# 直接带 prompt 启动
codex "修复这次构建失败"

# 非交互执行
codex exec "为 src/auth.ts 补测试并运行"

# 非交互代码审查
codex review --uncommitted

# 管理 MCP 服务器
codex mcp list
codex mcp add docs --url https://example.com/mcp

# 在 Codex 提供的沙盒里跑命令
codex sandbox macos -- echo hello

# 打开桌面版
codex app .

几个高频参数：

# 指定模型
codex -m gpt-5.4 "解释这个仓库"

# 开启低摩擦自动执行
codex --full-auto "修复 lint 并提交"

# 切到工作目录
codex -C /path/to/repo "检查这个项目"

# 临时覆盖配置
codex -c model_reasoning_effort=\"high\" "定位 race condition"

你可以把 CLI 理解成“总入口”，真正决定长期体验的是下面几层。

2. AGENTS.md：放项目规则

如果你问“我能加什么”，优先加的通常不是 Skill，而是 AGENTS.md。

适合放什么

• 代码风格和提交规范
• 必跑命令，例如 pnpm build、pnpm test
• 哪些目录不能乱动
• 审查标准，例如“优先找回归风险，不要只给总结”
• 这个项目的特殊约束，例如“不允许新增依赖”

放哪里

• 仓库根目录：AGENTS.md
• 某个子模块目录：subdir/AGENTS.md
• 个人全局层：~/.codex/AGENTS.md

规则是越深的目录优先级越高。也就是说，根目录管全仓库，子目录可以覆盖自己那一片。

怎么用

不需要手动“启用”。只要 Codex 在这个目录或子目录里工作，它就会自动读。

一个实用例子：

# AGENTS.md

## Build
- 变更配置或导航后必须运行 `pnpm build`

## Style
- TypeScript 使用 4 空格缩进
- 复用现有工具函数，不要平行造轮子

## Safety
- 不要改动 `docs/.vuepress/dist/`
- 不要删用户已有内容，除非任务明确要求

如果你的目标是“让 Codex 在这个仓库里更像团队成员”，先写好 AGENTS.md。

3. ~/.codex/config.toml：放个人默认配置

这个文件更像“你的 Codex 偏好面板”。

适合放什么

• 默认模型
• 推理力度
• 审批策略
• 沙盒模式
• 通知命令
• MCP 服务器定义
• 特性开关

放哪里

• 全局：~/.codex/config.toml

怎么用

例如：

model = "gpt-5.4"
model_reasoning_effort = "high"

[features]
multi_agent = true

[projects."/Users/me/work/my-repo"]
trust_level = "trusted"

临时不想改全局文件时，直接用 CLI 覆盖：

codex -c model=\"gpt-5.4-mini\" "先快速扫一遍这个仓库"

经验判断：

• 项目共享规则放 AGENTS.md
• 你个人机器偏好放 ~/.codex/config.toml

不要反过来。

4. MCP：给 Codex 接工具和数据源

MCP 可以理解成“给 Codex 插 USB 口”。

适合接什么

• 文档站
• 数据库
• GitHub / GitLab
• Figma
• Notion
• 内部 API
• 日志和监控系统

放哪里

两种主流方式：

1. 直接命令添加

codex mcp add mydocs --url https://example.com/mcp
codex mcp add postgres -- env DATABASE_URL=... npx my-mcp-server

2. 写进 ~/.codex/config.toml

[mcp_servers.my_docs]
command = "npx"
args = ["-y", "@your/docs-mcp"]
enabled = true

怎么用

先看有没有接好：

codex mcp list

接好以后，通常不需要你手写工具调用，直接自然语言说：

• “去查一下设计稿里的按钮间距”
• “读取生产库里昨天新增用户数”
• “把这个 issue 的上下文拉进来”

Codex 会在可用工具中选择合适的 MCP 能力。

你这台机器当前已经有什么

我实测 codex mcp list，当前环境已经有：

• omx_code_intel
• omx_memory
• omx_state
• omx_trace

也就是说，这台机器已经装了一个偏“工程增强型”的 Codex 环境。

5. Skill：把经验沉淀成可复用工作流

这是很多人最容易混淆的一层。

Skill 适合放什么

• 固定排查流程
• 常用文档生成套路
• 团队内部规范
• 某个领域的背景知识
• 需要脚本 + 说明 + 参考资料一起打包的工作流

放哪里

这里要分两种口径：

OpenAI 官方 Codex 文档口径

• 项目级：.agents/skills/<skill-name>/SKILL.md
• 全局级：~/.agents/skills/<skill-name>/SKILL.md

你当前这台机器的 OMX 增强环境

• 已安装技能目录：~/.codex/skills/<skill-name>/SKILL.md

也就是说：

• 如果你想按官方 Codex 文档组织项目内 Skill，优先参考 .agents/skills
• 如果你想和你当前这台机器的增强环境保持一致，直接看 ~/.codex/skills

最小结构

my-skill/
└── SKILL.md

更完整一点：

my-skill/
├── SKILL.md
├── scripts/
├── references/
└── assets/

SKILL.md 至少要有：

---
name: my-skill
description: 什么时候应该使用这个 skill，它解决什么问题
---

# Workflow

告诉 Codex 这个技能该怎么执行。

怎么用

通常有三种方式：

• 自动匹配：当描述命中 skill 的用途时自动触发
• 显式调用：$my-skill
• 浏览技能：/skills

什么时候该写成 Skill

满足下面任意一条，就值得做成 Skill：

• 你已经重复讲了 3 次以上
• 这个流程步骤固定，顺序不能错
• 这个领域知识不在通用模型常识里
• 你希望团队里的人和 Agent 都按同一套流程做

6. 子 Agent：把任务拆给专门角色

Skill 是“流程模板”，子 Agent 是“角色模板”。

适合加什么角色

• reviewer：专看回归风险
• writer：专写文档
• debugger：专做根因分析
• security-reviewer：专扫安全问题
• designer：专做界面与交互建议

放哪里

• 项目级：.codex/agents/<name>.toml
• 全局级：~/.codex/agents/<name>.toml

怎么用

你可以直接在任务里说：

• “先让一个 reviewer 子 agent 看回归风险”
• “派一个 writer 子 agent 整理迁移文档”
• “开两个子 agent 并行，一个查前端，一个查后端”

一个最小示例

name = "api-reviewer"
description = "Review API changes for compatibility and contract risk"

[instructions]
developer = """
Focus on API compatibility, schema changes, error handling, and migration risk.
Report findings first, summary second.
"""

什么时候用子 Agent，而不是 Skill？

• Skill：你想复用“做事的方法”
• 子 Agent：你想复用“做事的人设/视角”

7. 这台机器现在已经是增强版 Codex 了

从当前环境看，你不是在一个“纯净原版” Codex 里，而是装了 oh-my-codex（OMX）。

我本机看到的事实有这些：

• ~/.codex/config.toml 已开启 multi_agent = true
• ~/.codex/agents/ 下已经有 architect、debugger、executor、verifier 等角色
• ~/.codex/skills/ 下已经有 plan、skill、code-review、web-clone、team 等技能
• 已接入 4 个 OMX MCP 服务器

所以对你来说，最省力的路径通常不是“从零发明一切”，而是：

1. 先写好仓库级 AGENTS.md
2. 再决定哪些东西要沉淀成 Skill
3. 最后再补专门子 Agent

8. 一个推荐的目录组织

如果你想把 OpenAI Codex 相关能力整理得长期可维护，可以按这个思路来：

repo/
├── AGENTS.md
├── .codex/
│   └── agents/
│       └── api-reviewer.toml
└── .agents/
    └── skills/
        └── release-check/
            └── SKILL.md

你自己的全局环境则放：

~/.codex/
├── AGENTS.md
├── config.toml
├── agents/
└── skills/

这个分法的好处是：

• 仓库共享的东西进版本控制
• 个人习惯保留在自己机器上
• 不会把团队规范和个人偏好混在一起

9. 如果你现在就想开始，先加这三样

优先级我建议这样排：

1. 先补 AGENTS.md 这是收益最高的一层，几乎所有任务都会吃到。

2. 再接 MCP 让 Codex 能看文档、查设计、读数据，能力会立刻上一个台阶。

3. 最后沉淀 Skill 把你高频重复的套路做成可复用工作流。

子 Agent 不用一上来就写很多。等你真的遇到“同一种审查视角、同一种委派角色”反复出现，再拆出来最合适。

参考链接

• OpenAI Codex 文档
• CLI Overview
• AGENTS.md
• MCP
• Skills
• Subagents
• Config

贡献者: Ra1n

上一页OpenAI Codex CLI 使用教程

下一页Codex 好用的插件和 Skill 推荐