如何挑选合适的Codex子代理：Awesome Codex Subagents核心开发13代理完整选型指南
项目地址: https://gitcode.com/gh_mirrors/aw/awesome-codex-subagents Awesome Codex Subagents 是一个开源的 Codex 子代理（Subagents）合集，收录了 13 大分类、171+ 个面向真实开发场景的专用 AI 子代理。其中 categories/01-core-development/ 目录下的核心开发类子代理共 13 个，覆盖从前端 UI、后端 API 到 GraphQL、WebSocket、微服务等日常开发场景。本文将带你快速完成 Codex 子代理的安装配置，并给出一份按"前端 → 后端 → 架构"维度的 13 个子代理选型指南，帮你把对的任务交给对的代理。
什么是 Codex 子代理？为什么需要它？
Codex 子代理是针对特定开发任务定制的专用 AI 助手，每个子代理通过一个 .toml 文件定义，包含角色设定、工作模式、质量检查清单和权限边界。它们有 4 个核心优势：
- 独立上下文：每个子代理拥有隔离的上下文空间，不会污染主对话
- 领域专精：精心编写的专业指令，让特定任务结果更准确
- 跨项目共享：一次配置，全团队复用，保证开发实践一致
- 显式委派：Codex 不会自动派生子代理，需要你在提示词中明确指定，控制权完全在你手里
💡 简单理解：主代理是"全能管家"，子代理是"分领域专家"。写前端交给前端专家，设计 API 交给 API 架构师，各司其职。
Codex 子代理一键安装步骤
安装非常简单，只需 4 步（依据 README.md）：
- 克隆仓库：
git clone https://gitcode.com/gh_mirrors/aw/awesome-codex-subagents - 把你需要的
.toml文件复制到代理目录：- 全局代理：
~/.codex/agents/（所有项目可用） - 项目级代理：
.codex/agents/（仅当前项目可用，优先级更高）
- 全局代理：
- 必要时重启或刷新 Codex 会话
- 在提示词中显式委派子代理（Codex 不会自动派生自定义子代理）
示例：把核心开发类的后端子代理装到全局目录：
mkdir -p ~/.codex/agents
cp categories/01-core-development/backend-developer.toml ~/.codex/agents/
| 类型 | 路径 | 可用范围 | 优先级 |
|---|---|---|---|
| 项目子代理 | .codex/agents/ | 仅当前项目 | 高 |
| 全局子代理 | ~/.codex/agents/ | 所有项目 | 低 |
⚠️ 命名冲突时，项目级子代理会覆盖全局子代理。
13个核心开发子代理选型清单
下表是 categories/01-core-development/README.md 中全部 13 个子代理的速查表：
| 子代理 | 适用场景 | 沙盒模式 |
|---|---|---|
| fullstack-developer | 单个功能横跨前后端，一人负责全链路 | 可写 |
| frontend-developer | 范围明确的前端实现或 UI 缺陷修复 | 可写 |
| backend-developer | 代码路径清晰后的后端实现或修复 | 可写 |
| mobile-developer | 移动端实现、生命周期与平台特有调试 | 可写 |
| electron-pro | Electron 主/渲染进程、打包、桌面集成 | 可写 |
| ui-fixer | UI 问题已复现，需要最小安全补丁 | 可写 |
| websocket-engineer | 实时连接、消息契约、重连与故障行为 | 可写 |
| design-bridge | 把 DESIGN.md 规范转成可实现的 UI 指令 | 可写 |
| api-designer | 实现前设计、演进或兼容性评审 API 契约 | 只读 |
| code-mapper | 改动前绘制代码路径与归属边界地图 | 只读 |
| graphql-architect | GraphQL Schema、Resolver 与联邦设计评审 | 只读 |
| microservices-architect | 服务边界与分布式系统契约评审 | 只读 |
| ui-designer | 开发前给出具体可落地的 UI 设计决策 | 只读 |
🔑 规律一目了然："设计/评审"类代理全部只读（先想清楚再动手），"实现/修复"类代理才拥有写入权限——这正是官方推荐的"先映射、再实现、后评审"工作流。
场景一：前端与 UI 工作 → 选谁？
- frontend-developer：核心前端开发主力。它会先梳理"路由 / 组件 / 状态 / 数据"边界，再做最小化 UI 改动，并强制验证加载、空态、错误态的一致性以及键盘焦点等可访问性行为（详见 frontend-developer.toml 的 Focus 清单）
- ui-fixer：UI bug 已复现时的"急诊医生"，目标是给出最小安全补丁，不做无关重构
- ui-designer：开发前的设计决策者，产出具体到"另一个代理可以直接实现"的 UI 方向
- design-bridge：当你手里有一份 DESIGN.md 设计规范时，由它翻译成忠于品牌、可实施的 UI 指令
选型建议：没有复现证据时先用只读代理定位，确认问题后再让 ui-fixer 动手；新功能优先 ui-designer → frontend-developer 的接力组合。
场景二：后端与 API 开发 → 选谁？
- backend-developer：后端主力。它的检查清单覆盖事务边界、幂等与重试、认证授权路径、向后兼容等生产级关注点，并要求验证"一条关键成功路径 + 一条高风险失败路径"（见 backend-developer.toml）
- api-designer：API 契约的"总设计师"，只读模式。聚焦资源建模、校验语义、版本化与弃用策略，强调"契约行为必须显式，而非依赖框架默认值"
- graphql-architect：如果你的 API 采用 GraphQL，Schema 演进、Resolver 架构、联邦设计都归它管
选型建议：REST 项目遵循 api-designer（定契约）→ backend-developer（写实现）的顺序；GraphQL 项目把第一步换成 graphql-architect。
场景三：跨栈与跨端任务 → 选谁？
- fullstack-developer：当一个有边界的完整功能横跨前后端时，由它单独负责"用户操作 → 后端效应 → UI 状态"整条链路，重点保证两层间的 API 契约对齐和错误行为一致性
- mobile-developer：跨平台移动端的实现与调试，关注应用生命周期、API 集成与设备级 UX 约束
- electron-pro：Electron 桌面应用专家，覆盖主进程 / 渲染进程 / preload 边界、打包与桌面运行时行为
- websocket-engineer：实时通信专家，专注 WebSocket 生命周期、消息契约和重连 / 故障恢复
选型建议：小功能单人闭环选 fullstack-developer；只要涉及长连接、推送、实时状态同步，就交给 websocket-engineer 而不是通用开发代理。
场景四：大型架构决策 → 选谁？
- code-mapper：任何改动前的"侦察兵"，绘制文件、入口点和状态流转的高置信度地图，划清归属边界
- microservices-architect：评审服务边界、跨服务契约与分布式系统架构决策
- ui-designer + design-bridge：设计体系层面的方向输出与规范落地
选型建议：接手陌生代码库，第一步永远是 code-mapper 只读侦察，拿着地图再派开发代理动手。
智能模型路由：每个子代理自动匹配最合适的模型
每个子代理的 .toml 中都有 model 字段，自动在质量与成本之间取平衡：
| 模型 | 适用任务 | 核心开发类示例 |
|---|---|---|
gpt-5.4（高推理） | 深度推理：架构评审、安全审计、复杂实现 | backend-developer、frontend-developer、fullstack-developer |
gpt-5.3-codex-spark（快速） | 快速扫描、综合整理等轻量任务 | code-mapper、ui-fixer |
也就是说，重决策任务（api-designer.toml 使用 gpt-5.4 + 高推理）和轻快任务（ui-fixer.toml 使用 spark + 中推理）会自动分配不同算力，无需你手动操心。
实战：显式委派子代理的提示词模板
记住一个关键原则：Codex 不会自动派生子代理，必须显式委派。官方 README.md 给出了几个可直接套用的工作流提示词：
PR 评审工作流（并行派发多个子代理）：
Review this branch with parallel subagents. Have reviewer look for correctness, security, and missing tests. Have docs_researcher verify the framework APIs this patch depends on. Wait for both and summarize the findings with file references.
Bug 排查工作流（先只读侦察，后写入修复）：
Investigate the broken settings flow. Have code_mapper trace the owning code paths, browser_debugger reproduce the bug in the browser, and frontend_developer propose the smallest fix after the failure is understood. Wait for the read-heavy agents first, then continue.
探索规划工作流（多代理分工输出行动清单）：
Use search_specialist to locate the code related to payment retries, knowledge_synthesizer to summarize the current design, and refactoring_specialist to propose a minimal refactor plan. Return a concrete action list.
💡 套用技巧：[子代理名] + [具体任务] + [期望产出形式]，一次提示词里可以派多个代理并行干活，并明确"先等谁、后动谁"。
子代理文件结构速览
每个子代理就是一个 Codex 原生的 .toml 文件，结构非常简洁（以 backend-developer.toml 为例）：
name = "backend-developer"
description = "Use when a task needs scoped backend implementation..."
model = "gpt-5.4"
model_reasoning_effort = "high"
sandbox_mode = "workspace-write"
developer_instructions = """
Own backend changes as production behavior...
"""
三个关键字段帮你快速读懂任何子代理：
description：什么场景下应该调用它（这就是选型的第一依据）model/model_reasoning_effort：用什么模型、多大推理力度sandbox_mode：read-only（只读评审）还是workspace-write（可写实现）
常见问题 FAQ
Q1：装了子代理之后，Codex 会自动使用它们吗？ 不会。必须在提示词中显式委派（如 "Have code_mapper trace the owning code paths"），这是为了保证你对任务分配的完全控制。
Q2：项目级和全局级子代理冲突怎么办？ 项目级（.codex/agents/）优先级更高，同名时会覆盖全局定义。
Q3：13 个核心开发代理装几个合适？ 新手建议从 3 个起步：fullstack-developer（全栈主力）+ code-mapper（改动前侦察）+ ui-fixer（快速修 UI bug），跑顺后再按需添加。
Q4：这些子代理安全吗？ 子代理以"原样"提供，官方不审计或保证其安全性与正确性，使用前请先审阅 .toml 内容。所有子代理均遵循 MIT License（见 LICENSE）。
总结：3 句话掌握选型心法
- 先侦察后动手：陌生代码先派
code-mapper只读测绘，再让开发代理实现 - 契约先行：API 项目用
api-designer/graphql-architect先定契约，再交给backend-developer落地 - 最小改动：修复类任务优先
ui-fixer这类"最小安全补丁"代理，避免无关重构
完整代理目录可在 README.md 中按 13 大分类浏览，社区贡献指南见 CONTRIBUTING.md。把对的任务交给对的子代理，你的 Codex 开发效率会完全不同！
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
