Subagent 与自定义 agent 对比：Claude Code vs Codex vs Cursor vs Gemini CLI vs GitHub Copilot（2026）

自定义 subagent 是带 YAML frontmatter 的 Markdown 文件。正文会成为 subagent 的系统 prompt。只有 name 和 description 是必填的。

• 位置（按优先级）：managed 设置、--agents CLI flag（JSON，仅当前会话）、.claude/agents/（项目）、~/.claude/agents/（用户），然后是插件的 agents/ 目录。
• 可选字段包括 tools（allowlist）、disallowedTools（denylist，优先应用）、model、permissionMode、maxTurns、skills、mcpServers、hooks、memory、background、effort、isolation（worktree）和 color。
• 内置 subagent：Explore（只读搜索）、Plan（plan 模式下的只读调研）、general-purpose、claude、statusline-setup 和 claude-code-guide。
• 调用方式：根据 description 自动委派、自然语言、@ 提及（如 @agent-<name>），或使用 claude --agent <name> 让整个会话以该 agent 运行。
• 后台：后台 subagent 并发运行，Ctrl+B 可将正在运行的任务移到后台。默认上限为 20 个并发 subagent（CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS）。
• 模型：sonnet、opus、haiku、fable、完整模型 ID 或 inherit。CLAUDE_CODE_SUBAGENT_MODEL 设置默认值。

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

Codex 自定义 agent 是独立的 TOML 文件，每个文件一个 agent。Codex 通过 name 字段而不是文件名来识别 agent。

• 位置：~/.codex/agents/（个人）和 .codex/agents/（项目）。
• 必填字段：name、description、developer_instructions。可选：model、model_reasoning_effort、model_reasoning_summary、model_verbosity、features.* 键以及 skills 设置。
• 自定义 agent 无法覆盖 sandbox_mode、approval_policy、model_provider 或 mcp_servers，这些会从父级继承。
• 内置 agent：default、worker 和 explorer。与内置 agent 同名的自定义 agent 优先。
• 调用方式：直接请求，例如 "spawn two agents"，或在 prompt 中指名某个自定义 agent。项目或 skill 指令也可以请求委派。
• 并行：Codex 会生成多个 agent，等待所有结果后返回一个汇总的回复。你可以打开 subagent 线程，并让 Codex 引导、停止或关闭 subagent 线程。
• 全局 [agents] 设置包括 agents.enabled、agents.max_concurrent_threads_per_session、agents.default_subagent_model、agents.default_subagent_reasoning_effort 和 agents.interrupt_message。
• 工具限制：subagent 继承父级权限。要缩减能力，可将 features.shell_tool 等 feature 键设为 false。

Cursor subagent 是带 YAML frontmatter、后接 prompt 的 Markdown 文件。Cursor 也会读取 Claude Code 和 Codex 的 agent 文件夹。

• 项目位置：.cursor/agents/、.claude/agents/、.codex/agents/。用户位置：~/.cursor/agents/、~/.claude/agents/、~/.codex/agents/。
• 项目 agent 覆盖用户 agent。名称冲突时，.cursor/ 优先于 .claude/ 或 .codex/。
• 字段：name（默认为文件名）、description、model（默认 inherit）、readonly（默认 false）、is_background（默认 false）。
• 内置 subagent：explore（默认使用更快的模型）和 browser（通过 MCP 工具控制浏览器）。
• 调用方式：agent 根据 description 委派，或你在 prompt 中用 /name 调用（如 /verifier），或直接指名该 subagent。
• 并行与后台：同一条消息中的多个 Task 工具调用会同时运行。is_background: true 会立即返回。Subagent 可以在自己的 Git worktree 或云端虚拟机中运行。/in-cloud 将下一个任务作为云端 subagent 运行，/autopilot 将 pull request 交给云端 subagent。
• 模型：inherit 或模型 ID，可带方括号选项，如 claude-opus-5[effort=high]。
• 工具限制：subagent 继承父级的所有工具。readonly: true 是唯一有文档记载的限制字段。

Gemini CLI agent 是带 YAML frontmatter 的 Markdown 文件。正文会成为 agent 的系统 prompt。Subagent 默认启用。

• 位置：.gemini/agents/*.md（项目）和 ~/.gemini/agents/*.md（用户）。
• 字段：name 和 description（必填）、kind（local 或 remote，默认 local）、tools、mcpServers、model（默认 inherit）、temperature（默认 1）、max_turns（默认 30）、timeout_mins（默认 10）。
• 内置 subagent：codebase_investigator、cli_help 和 generalist 默认开启。browser_agent 默认关闭，需要 Chrome 144 或更高版本。
• 调用方式：自动委派，或以 @ 加名称开头写 prompt，如 @codebase_investigator。每个 subagent 都以同名工具的形式暴露给主 agent。
• 模型：用 model 为每个 agent 设置，或在 settings.json 中通过 agents.overrides 覆盖。
• 工具限制：tools 列表支持通配符 *、mcp_* 和 mcp_server_*。Subagent 不能调用其他 subagent。policy.toml 规则可通过 subagent 属性针对某个 subagent。
• 在 settings.json 中设置 "experimental": { "enableAgents": false } 可关闭 subagent。使用 /agents 管理它们。

---
name: my-agent
description: When the main agent should call this subagent
tools:
  - mcp_*
model: inherit
max_turns: 30
---

System prompt for the subagent goes here.

Copilot 自定义 agent 即 agent profile：带 YAML frontmatter 的 Markdown 文件。正文存放 prompt，最多 30,000 个字符。去掉 .md 或 .agent.md 后的文件名即为 agent 的标识符。

• Copilot CLI 位置：.github/agents/（项目）和 ~/.copilot/agents/（用户），使用 .agent.md 扩展名。名称冲突时主目录中的版本优先。
• Cloud agent 位置：仓库中的 .github/agents/，或组织的 .github 或 .github-private 仓库中的 /agents/。企业 agent 位于 .github-private 仓库中。仓库 agent 覆盖组织 agent，组织 agent 覆盖企业 agent。
• 字段：description（必填）、name（可选的显示名称）、target（vscode 或 github-copilot）、tools、model、disable-model-invocation、user-invocable、mcp-servers、metadata。infer 已停用。
• 内置 CLI agent：explore、task、general-purpose、code-review、research（仅通过 /research）和 rubber-duck（在不同的模型上运行）。
• CLI 调用方式：交互模式下使用 /agent、在 prompt 中指名 agent、根据 description 推断，或 copilot --agent <name> --prompt "..."。
• 并行：agent 作为拥有独立上下文窗口的 subagent 运行，并在合适时并行运行。
• 工具限制：省略 tools 或使用 ["*"] 表示所有工具，列出 read、edit、search、execute、agent、web 和 todo 等别名，或使用 [] 禁用全部。MCP 工具使用 server/tool 或 server/*。

---
name: reviewer
description: Reviews pull requests for security issues
tools: ["read", "search"]
---

Review the changes and report security problems.

• 需要最精细的工具控制：Claude Code 同时提供 allowlist 和 denylist，还有按 agent 设置的权限模式、hooks 和 worktree 隔离。Copilot 也有支持别名和 MCP 命名空间的 tools 列表。
• 希望一个 agent 文件夹在多个工具中通用：Cursor 除了 .cursor/agents/，还会读取 .claude/agents/ 和 .codex/agents/。
• 希望并行 worker 返回一个合并的答案：Codex 文档说明了生成多个 agent 并返回一个汇总回复。
• 希望后台或云端运行：Claude Code（后台 subagent、Ctrl+B）和 Cursor（is_background、云端 subagent）有相关文档。Gemini CLI 的页面没有。
• 需要在 GitHub 上全组织共享 agent：Copilot 支持在 .github 或 .github-private 仓库中使用组织和企业 agent profile。
• 希望按 agent 调整采样：Gemini CLI 文档记载了 temperature、max_turns 和 timeout_mins 字段。