企业官网建设流程全解析

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

【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC

本篇指南完整解析 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

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

这一推荐在仓库源码中有一致的落点。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。

仓库内置的三个示例角色

三个角色层结构一致，均固定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"的依据：

导航指南也重申了一个易踩的坑：不要假设 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 工作流的前提。

【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC