ECC for Codex CLI：模型选型、技能发现、MCP 配置合并与多智能体协同实践指南

本篇指南完整解析 ECC（Everything Claude Code）仓库中为 Codex CLI 设计的配套规范 .codex/AGENTS.md：从模型选型建议、.agents/skills/ 技能发现机制，到 config.toml 的 MCP 服务器自动合并策略与 multi_agent 多智能体角色编排，帮助你在 Codex 环境中正确配置、运行并扩展 ECC 的完整工作流。读完本文后，你将能够独立配置 ECC 的 Codex 基线、理解 scripts/sync-ecc-to-codex.sh 的合并语义，并复用仓库内置的 explorer/reviewer/docs-researcher 三种角色层。

文档定位：Codex 专用的补充指令层

.codex/AGENTS.md 的定位是根目录 AGENTS.md 的 Codex 专用补充（supplement），它不重复通用项目规则，只承载 Codex 特有的配置、技能发现、MCP 基线与能力边界说明。两者发生冲突时，按 docs/CODEX-NAVIGATION-GUIDE.md 的约定：对当前任务更具体的文件优先——Codex 特有行为归 .codex/AGENTS.md，通用贡献政策归 AGENTS.md 与 CONTRIBUTING.md。

文档要求在阅读完本补充文件后，继续阅读 docs/CODEX-NAVIGATION-GUIDE.md，以获取仓库导航、PR diff packet 形态与评审泳道（review lanes）的完整指导。该导航指南给出的推荐阅读顺序是：

1. AGENTS.md —— 跨 harness 的通用项目规则、agent 路由、测试预期与提交工作流；
2. .codex/AGENTS.md —— Codex 专用配置、MCP、技能发现与 hook 能力边界；
3. docs/COMMAND-AGENT-MAP.md —— 命令到 agent、skill 的路由关系；
4. docs/CODEX-NAVIGATION-GUIDE.md —— 仓库导航、diff packet 形态与 PR 评审泳道。

模型推荐：统一收敛到 GPT 5.5

文档给出的模型推荐表如下，所有任务类型均收敛到同一模型：

任务类型	推荐模型
常规编码、测试、格式化（Routine coding, tests, formatting）	GPT 5.5
复杂功能、架构（Complex features, architecture）	GPT 5.5
调试、重构（Debugging, refactoring）	GPT 5.5
安全评审（Security review）	GPT 5.5

这一推荐在仓库源码中有一致的落点。Codex 多智能体角色层统一使用 gpt-5.5 作为模型，并通过 model_reasoning_effort 区分任务深度，例如 explorer.toml 与 docs-researcher.toml 使用 medium，而 reviewer.toml 使用 high——即"同一模型、按任务调整推理强度"的策略。

需要注意的是，.codex/config.toml 顶部明确建议：保持 model 与 model_provider 不设置，让 Codex CLI 使用其当前内置默认值，只有在需要仓库级或全局模型覆盖时才取消注释并固定。因此实践路径是：角色层显式固定 gpt-5.5，而顶层运行时交给 Codex 默认，避免仓库配置锁死未来的模型默认值。

技能发现：从 .agents/skills/ 自动加载

文档规定 Codex 的技能发现路径为 .agents/skills/，每个技能目录包含两类资产：

• SKILL.md —— 详细指令与工作流；
• agents/openai.yaml —— Codex 接口元数据（interface metadata）。

这一点可在仓库中得到验证：find .agents/skills -path "*agents*" -name "*.yaml" 可命中大量形如 .agents/skills/deep-research/agents/openai.yaml 的元数据文件，且每个技能目录均包含 SKILL.md。以 security-review 技能 为例，其 SKILL.md 以 frontmatter 声明激活条件（涉及认证、用户输入、secrets、API 端点、支付等场景时启用），随后给出包含 FAIL/PASS 对照代码块的完整安全清单，可作为技能文档结构的典型样本。

文档列出的可用技能清单（auto-loaded）包括：

• tdd-workflow —— 测试驱动开发，80%+ 覆盖率目标；
• security-review —— 综合安全清单；
• coding-standards —— 通用编码标准；
• frontend-patterns —— React/Next.js 模式；
• frontend-slides —— 视口安全的 HTML 演示与 PPTX 转 Web；
• article-writing —— 基于笔记与语气样本的长文写作；
• content-engine —— 平台原生社交内容与二次分发；
• market-research —— 带来源归因的市场与竞品调研；
• investor-materials —— 融资 Deck、备忘录、模型与单页材料；
• investor-outreach —— 个性化投资人触达与跟进；
• backend-patterns —— API 设计、数据库、缓存；
• e2e-testing —— Playwright E2E 测试；
• eval-harness —— 评估驱动开发（Eval-driven development）；
• strategic-compact —— 上下文管理；
• api-design —— REST API 设计模式；
• verification-loop —— 构建、测试、lint、类型检查、安全检查；
• deep-research —— 基于 firecrawl 与 exa MCP 的多源调研；
• exa-search —— 通过 Exa MCP 进行 Web、代码与企业的神经搜索；
• claude-api —— Anthropic Claude API 模式与 SDK；
• x-api —— X/Twitter API 发帖、线程与分析；
• crosspost —— 多平台内容分发；
• fal-ai-media —— 通过 fal.ai 生成图像/视频/音频；
• dmux-workflows —— 基于 dmux 的多智能体编排。

结合仓库结构看，.agents/skills/ 下实际目录数量多于上述清单（还包含 benchmark-methodology、brand-voice、mcp-server-patterns 等），可以推断清单描述的是文档撰写时的核心集合，目录会随仓库演进持续扩充。docs/CODEX-NAVIGATION-GUIDE.md 的 Surface Map 对此有明确分工：skills/ 是规范技能源（canonical skill source，新增工作流知识应优先更新），.agents/skills/ 是面向 Codex 的技能副本（Codex-facing skill copies，供 Codex 原生技能加载使用），并且特别提醒：不要在不核对规范源 skills/ 与 agents/openai.yaml 元数据约定的情况下直接修改 .agents/skills/。

MCP 服务器基线：项目本地 .codex/config.toml

文档将项目本地的 .codex/config.toml 定义为 ECC 的默认 Codex 基线（default Codex baseline）。当前 ECC 基线启用六个服务器：GitHub、Context7、Exa、Memory、Playwright 和 Sequential Thinking；更重的扩展服务器应只在任务确实需要时才加入用户级 ~/.codex/config.toml。

基线配置的实际内容

查看 .codex/config.toml，基线服务器均为 npx 启动、startup_timeout_sec = 30：

• [mcp_servers.github] —— npx -y @modelcontextprotocol/server-github；
• [mcp_servers.context7] —— npx -y @upstash/context7-mcp@latest；
• [mcp_servers.exa] —— npx -y mcp-remote https://mcp.exa.ai/mcp；
• [mcp_servers.memory] —— npx -y @modelcontextprotocol/server-memory；
• [mcp_servers.playwright] —— npx -y @playwright/mcp@latest --extension；
• [mcp_servers.sequential-thinking] —— npx -y @modelcontextprotocol/server-sequential-thinking。

配置文件中还以注释形式预留了四个可选扩展：Supabase（supabase-mcp-server@latest --read-only）、firecrawl、fal-ai、cloudflare，按需在 ~/.codex/config.toml 中启用即可，与"基线保持精简、重扩展按需加载"的原则一致。

除 MCP 外，基线运行时设置包含：

• approval_policy = "on-request" —— 审批策略为按需请求；
• sandbox_mode = "workspace-write" —— 沙箱允许工作区写入；
• web_search = "live" —— 实时 Web 搜索；
• notify = [...] —— 任务完成后通过 terminal-notifier 推送系统通知；
• persistent_instructions —— 附加到每个提示词的持久指令（文档注明它是追加式的，与会替换 AGENTS.md 的 model_instructions_file 不同）；
• [features] multi_agent = true —— 显式开启多智能体开关；
• [profiles.strict]（read-only + cached 搜索）与 [profiles.yolo]（never 审批 + workspace-write）两个配置档，通过 codex -p <name> 切换。

Context7 的规范命名

文档特别强调一个易错点：ECC 的规范 Codex 段名是 [mcp_servers.context7]，而启动包名仍然是 @upstash/context7-mcp——归一化的只是 TOML 段名（为了与 codex mcp list 输出和参考配置保持一致），包名不做改动。.codex/config.toml 中该行附近也留有注释重申此约定。历史配置中的 [mcp_servers.context7-mcp] 旧条目在同步脚本更新时会被当作别名处理，避免新旧命名并存产生重复条目。

config.toml 的自动合并机制

scripts/sync-ecc-to-codex.sh 是基于 Node TOML 解析器的同步脚本，负责把 ECC 资产（AGENTS.md 补充、角色层、导航指南、PR 模板、MCP 服务器等）合并进本地 Codex 配置。文档描述其合并语义如下：

• 默认只增不改（Add-only） —— 缺失的 ECC 服务器被追加，已存在的服务器从不被修改或删除；
• 7 个受管服务器 —— Supabase、Playwright、Context7、Exa、GitHub、Memory、Sequential Thinking；
• 规范命名 —— ECC 以 [mcp_servers.context7] 管理 Context7，遗留的 [mcp_servers.context7-mcp] 条目在更新时按别名处理；
• 感知包管理器 —— 使用项目配置的包管理器（npm/pnpm/yarn/bun），而不是硬编码 pnpm；
• 漂移告警（Drift warnings） —— 若已存在服务器配置与 ECC 推荐值不一致，脚本输出警告但不擅自修改；
• --update-mcp —— 显式把所有 ECC 受管服务器替换为最新推荐配置，能安全地移除 [mcp_servers.supabase.env] 这类子表；
• 用户配置始终保留 —— ECC 受管段之外的自定义服务器、参数、环境变量与凭据绝不被触碰。

从脚本源码看，入口支持 --dry-run（预览不落地）与 --update-mcp（触发全量替换模式）两个参数，且通过 CODEX_HOME 环境变量可重定向目标目录（默认为 ~/.codex）。脚本头注释还说明它会先备份 ~/.codex 的 config 与 AGENTS.md，采用基于标记（marker-based）的 AGENTS.md 合并以保留用户已有内容，并附带安装全局 git 安全钩子（pre-commit / pre-push）与同步后回归检查。

外部动作边界（External Action Boundaries）

文档对联网工具划定了明确的安全边界，核心原则是：联网工具默认视为只读。

• 允许在用户请求范围内自由检索、检查与起草（search, inspect, and draft）；
• 以下动作必须先取得用户显式批准：发帖（posting）、发布（publishing）、推送（pushing）、合并（merging）、开通付费任务（paid jobs）、派发远程 agent、修改第三方资源、变更凭据；
• 当批准意图模糊时，产出本地计划或草稿工件（local plan or draft artifact），而不是执行外部动作；
• 除非用户明确要求进行范围化的修改，否则保留用户配置与私有状态。

这一原则与 .codex/config.toml 中 approval_policy = "on-request"、评审/探索角色的 sandbox_mode = "read-only" 形成呼应：指令层、审批策略与沙箱三层共同约束 agent 的外部副作用。

多智能体支持：multi_agent 与角色层

文档说明 Codex 的多智能体工作流位于实验性 features.multi_agent 开关之后，并给出四步落地方式：

1. 在 .codex/config.toml 中以 [features] multi_agent = true 启用；
2. 用 [agents.<name>] 定义项目本地角色；
3. 每个角色指向 .codex/agents/ 下的一个 TOML 层；
4. 在 Codex CLI 内用 /agent 检查与调度子 agent。

仓库内置的三个示例角色

角色	文件	用途
Explorer	explorer.toml	只读的证据收集
Reviewer	reviewer.toml	正确性/安全评审
Docs researcher	docs-researcher.toml	API 与 release note 验证

三个角色层结构一致，均固定 model = "gpt-5.5" 与 sandbox_mode = "read-only"，差异体现在推理强度与指令上：

• explorer（model_reasoning_effort = "medium"）：指令要求"停留在探索模式，追踪真实执行路径、引用文件与符号，除非父 agent 要求否则不提出修复方案，优先定点搜索与文件读取而非大范围扫描"；
• reviewer（model_reasoning_effort = "high"）：指令要求"像 owner 一样评审，优先关注正确性、安全、行为回归与缺失测试，先给出具体发现，避免纯风格性意见除非其中隐藏真实 bug"；
• docs-researcher（model_reasoning_effort = "medium"）：指令要求"变更前用一手文档验证 API、框架行为与 release note 声明，逐条引用支撑结论的文档或文件路径，不虚构未记录的行为"。

.codex/config.toml 中的 [agents] 段进一步设定了编排约束：max_threads = 6（最多 6 个并发线程）与 max_depth = 1（角色嵌套深度为 1，即只有一层子 agent，不递归派生）。每个角色以 description + config_file 两个字段注册，例如 [agents.explorer] 的 config_file = "agents/explorer.toml"。这种"有界 sidecar 工作"（bounded sidecar work）的使用方式也与 docs/CODEX-NAVIGATION-GUIDE.md 一致：本地立即处理阻塞性任务，把可并行的独立证据收集或评审任务委派给角色层。

与 Claude Code 的关键差异

文档给出的能力对照表如下，是判断"哪些 Claude Code 习惯可以直接迁移到 Codex"的依据：

特性	Claude Code	Codex CLI
Hooks	8+ 种事件类型	经过评审的原生子集，在 /hooks 中显式信任
上下文文件	CLAUDE.md + AGENTS.md	仅 AGENTS.md
技能	通过插件加载	原生插件技能与仓库 .agents/skills/
命令	/slash 命令	基于指令（instruction-based）
多智能体	Subagent Task 工具	通过 /agent 与 [agents.<name>] 角色实现
安全	Hook profiles + 沙箱	受信任 hook 子集 + 指令 + 沙箱
MCP	完整支持	通过 config.toml 与 codex mcp add 支持

导航指南也重申了一个易踩的坑：不要假设 Codex 与 Claude Code 的 hook 等价（hooks/ 目录面向 Claude Code 工作流），Codex 的约束机制建立在指令、沙箱设置与可选 MCP 配置之上。

更窄 hook 下的安全实践

Codex 支持的 hook 是 Claude Code 的原生子集，且需要在 /hooks 中显式信任。文档建议把已评审的 hook 视为指令与沙箱之外的又一层防护，并给出五条纪律：

1. 始终在系统边界处校验输入（Always validate inputs at system boundaries）；
2. 永不硬编码 secrets —— 使用环境变量；
3. 提交前运行 npm audit / pip audit；
4. 每次 push 前检查 git diff；
5. 在配置中使用 sandbox_mode = "workspace-write"。

其中第 5 条在 .codex/config.toml 中已有落实：顶层默认 workspace-write，需要更强隔离时切换到 [profiles.strict]（sandbox_mode = "read-only" + web_search = "cached"），而三个多智能体角色层则全部收敛到 read-only，形成"默认可写、评审/探索只读、strict 档全只读"的分层沙箱策略。

验证与延伸路径

对本文涉及的 Codex 面，仓库提供了可直接运行的本地校验命令（摘自 docs/CODEX-NAVIGATION-GUIDE.md 的 Fast Commands 一节）：

node tests/docs/codex-navigation-map.test.js
node tests/ci/codex-skill-surface.test.js
npm run command-registry:check
npm run catalog:check
node tests/run-all.js

其中 tests/ci/codex-skill-surface.test.js 专门守护 .agents/skills/ 的技能面一致性。

如需进一步深入，可沿以下路径阅读：

• .codex/AGENTS.md —— 本文的原始补充文档；
• .codex/config.toml —— MCP 基线、profiles 与 agent 注册的完整参考配置；
• .codex/agents/ —— 三个内置角色 TOML 层；
• docs/CODEX-NAVIGATION-GUIDE.md —— 仓库导航、任务路由与 PR diff packet 模板；
• scripts/sync-ecc-to-codex.sh —— 同步与 config.toml 合并的完整实现；
• .agents/skills/ 与 skills/ —— Codex 技能副本与规范技能源。

小结

.codex/AGENTS.md 用一份精炼的补充文档把 ECC 的能力模型映射到了 Codex CLI 的真实机制上：模型选型统一收敛到 GPT 5.5 并以推理强度区分任务深度；技能通过 .agents/skills/ 的 SKILL.md + agents/openai.yaml 双资产结构被发现；MCP 基线由项目本地 .codex/config.toml 锚定六个默认服务器，重扩展下沉到用户级配置，并由同步脚本以"只增不改、用户配置永不被触碰"的语义自动合并；多智能体则通过 features.multi_agent、[agents.<name>] 注册与 /agent 调度组成可并行的 explorer/reviewer/docs-researcher 角色层。理解这套"指令 + 配置 + 角色 + 沙箱"的四层结构，是正确使用与扩展 ECC Codex 工作流的前提。