Codex 配置

🎯 学习目标

• 理解 Codex CLI / Codex Cloud 在 Agent 工具谱系中的位置
• 区分 AGENTS.md（持久规则） 与 .agents/skills/（可复用 Skill）
• 将 Codex 接入 CI 或本地脚本化工作流

引言

Codex（OpenAI 代码 Agent 产品线，含 CLI 与云端任务）强调 在真实仓库里执行：读代码、改 diff、跑命令。配置分两层：

层次	仓库路径	全局路径
AGENTS 规则	仓库根或子目录 AGENTS.md	~/.codex/AGENTS.md
Skills	.agents/skills/<name>/SKILL.md	~/.agents/skills/

产品名与 CLI 子命令随 OpenAI 迭代较快，本章给出 稳定可迁移 的配置模式，具体 flag 以 OpenAI Codex 文档 为准。

章节正文

第 1 步：安装与基本使用

典型本地流程：

# 安装 CLI（以官方文档为准）
npm i -g @openai/codex   # 或 brew install 等

# 在仓库根目录启动
cd your-repo
codex

首次运行完成 OAuth 或 API Key 配置；密钥只放环境变量，不进仓库。

第 2 步：AGENTS.md（持久规则）

AGENTS.md 描述 Codex 每次进仓库都要遵守 的约定（build 命令、review 风格、目录规范）。可从当前工作目录向上合并，越靠近的文件优先级越高：

# Agents

## 默认 Agent
- 先 npm run sync 再改 website 生成物
- 测试：npm run build

## 子角色

### doc-writer
- 只改 course/ 与 news/ 下 Markdown
- 不碰 .github/workflows

### ci-fixer
- 只读 CI 日志与配置文件，最小修复

Multi-Agent 在此文件声明 角色边界；单次任务 prompt 指定「以 ci-fixer 角色执行」。

第 3 步：.agents/skills/（Skill 包）

Codex 的 Skill 不是 放在 .codex/，而是 .agents/skills/（与 Cursor 的 .cursor/skills/ 对应）。Codex 从当前目录向上扫描到仓库根，可提交到 Git 供团队共用：

.agents/
└── skills/
    └── ai-info-research/
        ├── SKILL.md
        └── references/   # 可选：按需加载的参考文档

SKILL.md 示例：

---
name: ai-info-research
description: 检索、核验并摘要最新 AI 资讯，输出带来源链接的结论。适用于 AI资讯、最新AI动态等请求。
---

1. 先取系统日期，再联网检索核验
2. 写入 news/YYYY-MM/ai-news-YYYY-MM-DD.md
3. 每条资讯附官方来源链接

Skill 若依赖 MCP，可在 skill 目录下的 agents/openai.yaml 声明依赖，Codex 会自动安装与接线（见官方 Agent Skills 文档）。

第 4 步：其他项目上下文

除 AGENTS.md 外，建议保留：

文件	用途
README.md	人类与 Agent 的快速上手
CLAUDE.md / CONTRIBUTING.md	命令与贡献规范（Codex 常一并读取）
~/.codex/config.toml	全局默认 model、沙箱、禁用特定 skill 等

与 Cursor 的 .cursor/rules/ 内容对齐，减少 Agent 行为不一致；团队 Skill 可放在 .agents/skills/ 并在 Cursor 中 symlink 到 .cursor/skills/（或维护两份要点）。

第 5 步：Skills 与 Cursor 对照

工具	Skill 目录（仓库级）	规则 / 记忆
Codex	.agents/skills/	AGENTS.md
Cursor	.cursor/skills/	.cursor/rules/
Claude Code	插件 / 项目 skill 目录	CLAUDE.md

重复三次以上的流程 → 抽成 .agents/skills/<name>/SKILL.md，并在 AGENTS.md 里链接何时触发。

第 6 步：自动化与 CI

Codex 适合：

• PR 触发：小范围修复 lint / 类型错误
• 定时任务：依赖升级草案（需人工 review）
• 本地 pre-push：Agent 跑 build 并摘要错误

注意：

• CI 中 Agent 需要 只读 token 与 分支保护
• 输出必须是 PR，禁止直接推 main

第 7 步：与 Cursor / Claude Code 对比

维度	Codex	Cursor	Claude Code
界面	CLI / Cloud 为主	IDE 深度集成	终端
规则载体	AGENTS.md	.cursor/rules/	CLAUDE.md
Skill 载体	.agents/skills/	.cursor/skills/	项目 / 插件 skill
典型用户	脚本化 / OpenAI 栈	日常编码	仓库批处理

小结

• Codex 锚点：AGENTS.md（规则）+ .agents/skills/（流程）+ README/CLAUDE + 环境密钥 + CI 护栏
• Multi-Agent 用 AGENTS.md 角色 + 任务级 prompt 指定