Claude Code vs OpenCode vs Codex CLI：Sub Agent 对比手册

适用对象：经管学科研究生与青年学者 更新日期：2026-04-23

如何使用本手册

• 初次阅读：先看第1章概述和第2章对照表，建立整体认知
• 课堂跟练：重点阅读第3章（Claude Code），这是课程主工具
• 使用其他工具：查阅第4章（OpenCode）或第5章（Codex CLI），再用第6章迁移指南快速上手
• 遇到具体问题：翻到第8章常见问题和附录术语表

术语表

1. 概述

1.1 三个工具简介

安装方式速览：

Claude Code 是 Anthropic 推出的命令行 AI 编程助手，深度绑定 Claude 模型生态，拥有最成熟的 Sub Agent 系统，支持自动委派、@-mention 调用、后台运行等丰富特性。

OpenCode 是社区驱动的开源替代方案，核心优势在于多模型支持（可以为不同 Agent 指定不同提供商的模型）和细粒度权限控制。它兼容 Claude Code 的 Skills 格式，迁移成本较低。

Codex CLI 是 OpenAI 推出的命令行工具，使用 TOML 格式配置，设计理念偏向显式控制——只在用户明确要求时才生成 Sub Agent，不会自动委派。擅长并行批量处理任务。

2. 快速对照表

2.1 Sub Agent 概念对应关系

以下表格帮助你在三个工具间"翻译"同一个概念：

2.2 配置与格式对比

2.3 运行时能力对比

2.4 内置代理对比

3. Claude Code 的 Agent 系统

3.1 配置文件位置和格式

Agent 文件是 带有 YAML frontmatter 的 Markdown 文件（.md），存放位置决定作用范围：

同名 Agent 按优先级高低覆盖。

Plugin 中 Agent 的限制：出于安全原因，Plugin 中的 Agent 不支持以下 frontmatter 字段：hooks、mcpServers、permissionMode。这些字段在加载 Plugin Agent 时会被忽略。如果需要使用这些功能，需将 Agent 文件复制到 .claude/agents/ 或 ~/.claude/agents/ 中。

3.2 核心字段说明

---
name: code-reviewer          # 必填，唯一标识符
description: "Expert code review specialist. Use proactively."  # 必填，Claude 据此判断何时委派
tools: Read, Grep, Glob, Bash  # 可选，工具白名单
disallowedTools: Write, Edit    # 可选，工具黑名单
model: inherit                  # 可选，sonnet/opus/haiku/inherit/完整模型ID
permissionMode: default         # 可选，default/acceptEdits/dontAsk/bypassPermissions/plan
maxTurns: 20                    # 可选，最大 agentic 轮数
skills:                         # 可选，预加载 Skill 列表
  - api-conventions
mcpServers:                     # 可选，MCP 服务器配置（支持内联定义或引用已配置名称）
  - playwright:
      type: stdio
      command: npx
      args: ["-y", "@playwright/mcp@latest"]
  - github                      # 引用已配置的服务器名称（简写）
hooks:                          # 可选，生命周期钩子
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate.sh"
memory: user                    # 可选，持久化记忆范围
background: false               # 可选，是否始终后台运行
effort: high                    # 可选，思考力度（仅 Opus 4.6）
isolation: worktree             # 可选，在临时 git worktree 中运行
---

（这里写系统提示词，即 Markdown 正文部分）

工具控制：tools（白名单）和 disallowedTools（黑名单）可组合使用。先应用黑名单移除工具，再从剩余池中解析白名单。可通过 tools: Agent(worker, researcher) 限制可生成的 Sub Agent 类型；完全省略 Agent 则该 Agent 不能生成任何 Sub Agent。

模型选择：

• 模型别名：sonnet、opus、haiku
• 完整模型 ID：如 claude-opus-4-6、claude-sonnet-4-6
• inherit：使用主对话相同的模型（默认值）
• 可通过环境变量 CLAUDE_CODE_SUBAGENT_MODEL 设置全局默认 Subagent 模型

3.3 创建和调用示例

创建方式一：交互式创建（推荐）

在 Claude Code 中输入 /agents，选择 "Create new agent"，按向导完成。

创建方式二：手动创建文件

创建 .claude/agents/code-reviewer.md：

---
name: code-reviewer
description: Expert code review specialist. Reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a senior code reviewer ensuring high standards of code quality and security.

When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

Review checklist:
- Code is clear and readable
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Good test coverage

Provide feedback organized by priority:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)

Include specific examples of how to fix issues.

创建方式三：CLI 临时定义

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer.",
    "prompt": "You are a senior code reviewer.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'

调用方式：

3.4 最佳实践

1. description 写清楚用途：这是 Claude 决定是否自动委派的关键依据。加入 "use proactively" 可鼓励主动委派。
2. 只读 Agent 限制工具：审阅类 Agent 只给 Read, Grep, Glob, Bash，不给 Write, Edit。
3. 不能嵌套：Sub Agent 不能再生成 Sub Agent，这是硬限制。
4. 善用 isolation: worktree：让 Agent 在临时 git worktree 中运行，避免影响主工作区。
5. 模型选择：探索类任务用 haiku（快速低成本），复杂任务用 inherit 或 opus。
6. 注意 Plugin Agent 限制：Plugin 中的 Agent 不支持 hooks、mcpServers、permissionMode 字段（详见 3.1 节）。

4. OpenCode 的 Agent 系统

4.1 配置文件位置和格式

OpenCode 支持两种配置格式：Markdown 文件和 JSON 配置。

Markdown 文件位置：

JSON 配置位置（opencode.json）：

4.2 核心字段说明

Markdown 格式：

文件名即为代理名（如 review.md 创建名为 review 的代理）。

---
description: "Reviews code for quality and best practices"  # 必填
mode: subagent              # 可选，primary/subagent/all（默认 all）
model: anthropic/claude-sonnet-4-20250514  # 可选，格式为 provider/model-id
temperature: 0.1            # 可选，0.0-1.0
top_p: 0.9                  # 可选，0.0-1.0
steps: 10                   # 可选，最大迭代步数
hidden: false               # 可选，从 @ 菜单隐藏
disable: false              # 可选，禁用该代理
color: "#FF5733"            # 可选，UI 显示颜色
permission:                 # 可选，细粒度权限（推荐使用）
  edit: deny
  bash:
    "*": ask
    "git diff *": allow
    "git log *": allow
  webfetch: deny
  task:
    "*": deny
    "research": allow
  skill:
    "*": allow
# tools:                    # 已废弃，请使用 permission 代替
---

（这里写系统提示词）

注意：tools 字段已废弃，建议使用 permission 代替。新配置请使用 permission 对象进行权限控制。

JSON 格式（在 opencode.json 的 agent 字段中）：

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "code-reviewer": {
      "description": "Reviews code for best practices and potential issues",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-20250514",
      "temperature": 0.1,
      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
      "permission": {
        "edit": "deny",
        "bash": {
          "*": "ask",
          "git diff *": "allow",
          "git log *": "allow"
        }
      }
    }
  }
}

prompt 字段支持引用外部文件：使用 {file:./prompts/review.txt} 语法可以从外部文件加载系统提示词，便于管理长提示词。

权限控制亮点：OpenCode 的 permission 系统支持 glob 模式匹配，可以对每种工具类型（edit、bash、webfetch、task、skill）设置 allow/ask/deny 三级权限，bash 命令还支持按命令模式单独配置（如 "git diff *": "allow" 表示允许所有以 git diff 开头的命令）。task 权限可精确控制主代理能调用哪些子代理。

4.3 创建和调用示例

创建方式一：交互式命令

opencode agent create

按向导选择保存位置、输入描述、选择工具权限。

创建方式二：手动创建 Markdown 文件

创建 .opencode/agents/research.md：

---
description: Deep research agent for exploring codebases and gathering information
mode: subagent
model: anthropic/claude-haiku-4-20250514
temperature: 0.2
steps: 20
permission:
  edit: deny
  bash:
    "*": ask
    "grep *": allow
    "find *": allow
    "git log *": allow
  webfetch: allow
---

You are a research specialist. Your job is to thoroughly investigate
questions about the codebase and external resources.

## Rules:
- Never modify files
- Always cite specific file paths and line numbers
- Provide comprehensive but concise answers
- Use web search when codebase info is insufficient

创建方式三：在 opencode.json 中配置

直接在 opencode.json 的 agent 字段中添加 JSON 配置（见上文 JSON 格式示例）。

调用方式：

子会话导航（TUI 中）：

• <Leader>+Down：进入子会话
• Right/Left：切换子会话
• Up：返回父会话

4.4 内置代理

OpenCode 内置以下代理（按功能分组）：

主代理（Primary）：

• Build：默认主代理，启用所有工具，用于完整的开发工作
• Plan：受限代理，专用于规划和分析，默认禁止文件编辑

子代理（Subagent）：

• General：通用子代理，拥有完整工具权限，可执行多步任务
• Explore：快速只读代理，用于探索代码库

隐藏系统代理（自动运行，不可选择）：

• Compaction：自动压缩长上下文
• Title / Summary：自动生成会话标题和摘要

4.5 最佳实践

1. 用 mode 字段区分职责：Primary Agent 用于直接交互，Subagent 用于被委派任务。
2. 活用 task 权限：通过 permission.task 精确控制主代理能调用哪些子代理，防止不必要的 token 消耗。
3. 每个代理可用不同模型：研究任务用便宜的 Haiku，审阅任务用 Sonnet，规划任务甚至可以用 GPT-5。
4. 用 steps 控制成本：设置合理的最大迭代步数，避免子代理无限循环。
5. 兼容 Claude Code Skills：OpenCode 会自动扫描 .claude/skills/ 目录，已有的 Claude Code Skills 无需迁移。
6. 使用 permission 而非 tools：tools 字段已废弃，新配置请使用 permission 进行权限控制。

5. Codex CLI 的 Agent 系统

5.1 配置文件位置和格式

Codex CLI 使用 TOML 格式定义 Agent。

Agent 文件位置：

全局 Agent 设置（在 config.toml 中）：

AGENTS.md 发现层级：

Codex 按以下顺序查找项目指令文件：

1. ~/.codex/AGENTS.override.md（个人临时覆盖）
2. ~/.codex/AGENTS.md（个人全局指令）
3. 项目根目录到当前目录逐级查找 AGENTS.md

5.2 核心字段说明

# .codex/agents/reviewer.toml

name = "reviewer"                    # 必填，代理标识
description = "PR reviewer focused on correctness, security, and missing tests."  # 必填
developer_instructions = """         # 必填，核心行为指令（相当于系统提示词）
Review code like an owner.
Prioritize correctness, security, behavior regressions, and missing test coverage.
Lead with concrete findings, include reproduction steps when possible,
and avoid style-only comments unless they hide a real bug.
"""
model = "gpt-5.4"                    # 可选，指定模型
model_reasoning_effort = "high"      # 可选，low/medium/high
sandbox_mode = "read-only"           # 可选，权限控制
nickname_candidates = ["Athena", "Ada"]  # 可选，显示昵称池

# 可选：MCP 服务器配置
[mcp_servers.chrome_devtools]
url = "http://localhost:3000/mcp"
startup_timeout_sec = 20

# 可选：Skills 配置
[[skills.config]]
path = "/path/to/SKILL.md"
enabled = true

全局 [agents] 设置：

# config.toml
[agents]
max_threads = 6                  # 最大并发代理线程数
max_depth = 1                    # 代理嵌套深度（默认 1，仅直接子代理）
job_max_runtime_seconds = 1800   # CSV 批量任务的 worker 超时

模型选择策略：

推理努力程度（model_reasoning_effort）：high 用于复杂逻辑追踪和安全审查，medium 为大多数代理的平衡默认值，low 用于简单任务、速度优先。

Hooks 支持：Codex 支持代理生命周期钩子（如 AfterAgent），可在代理完成后触发自定义操作。

5.3 创建和调用示例

创建方式：手动创建 TOML 文件

Codex CLI 不提供交互式创建命令，需要手动在 ~/.codex/agents/ 或 .codex/agents/ 下创建 .toml 文件。

创建 .codex/agents/pr-explorer.toml：

name = "pr_explorer"
description = "Read-only codebase explorer for gathering evidence before changes are proposed."
model = "gpt-5.3-codex-spark"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
developer_instructions = """
Stay in exploration mode.
Trace the real execution path, cite files and symbols, and avoid proposing fixes
unless the parent agent asks for them.
Prefer fast search and targeted file reads over broad scans.
"""

也可以在 config.toml 中通过 [agents.<name>] 引用外部配置文件：

[agents.reviewer]
description = "Find correctness, security, and test risks in code."
config_file = "./agents/reviewer.toml"
nickname_candidates = ["Athena", "Ada"]

调用方式：

Codex CLI 不会自动委派 Sub Agent。你需要在提示词中显式指名使用：

Review this branch against main. Have pr_explorer map the affected code paths,
reviewer find real risks, and docs_researcher verify the framework APIs
that the patch relies on.

通用并行指令：

Spawn one subagent for security risks, one for test gaps, and one for
maintainability. Wait for all three, then summarize the findings.

管理运行中的代理：

5.4 最佳实践

1. 显式调用：Codex 不会自动生成 Sub Agent，记得在提示词中明确指名要使用的 Agent。
2. 控制嵌套深度：max_depth 默认为 1，避免递归扇出导致 token 爆炸。
3. 模型选择策略：gpt-5.4 用于复杂推理，gpt-5.4-mini 用于快速探索和并行 worker，gpt-5.3-codex-spark 用于即时文本迭代。
4. sandbox_mode 控制安全：只读 Agent 设为 read-only，实现类 Agent 用 workspace-write。
5. 自定义 Agent 可覆盖内置：如果 name 与内置代理（如 explorer）相同，自定义版本优先。

6. 从 Claude Code 迁移指南

6.1 场景一：我想创建一个只读的代码审阅 Agent

Claude Code：

---
name: reviewer
description: Reviews code for quality and security issues
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a senior code reviewer. Focus on security, performance, and maintainability.
Provide feedback organized by priority.

OpenCode：

---
description: Reviews code for quality and security issues
mode: subagent
model: anthropic/claude-sonnet-4-20250514
permission:
  edit: deny
  bash:
    "*": ask
    "git diff *": allow
    "git log *": allow
    "grep *": allow
---

You are a senior code reviewer. Focus on security, performance, and maintainability.
Provide feedback organized by priority.

Codex CLI：

# .codex/agents/reviewer.toml
name = "reviewer"
description = "Reviews code for quality and security issues"
model = "gpt-5.4"
model_reasoning_effort = "high"
sandbox_mode = "read-only"
developer_instructions = """
You are a senior code reviewer. Focus on security, performance, and maintainability.
Provide feedback organized by priority.
"""

6.2 场景二：我想让 Agent 自动被调用

6.3 场景三：我想手动指定使用某个 Agent

6.4 场景四：我想让 Agent 使用不同的模型

Claude Code：

model: haiku  # 或 sonnet, opus, inherit, 完整模型 ID

仅支持 Claude 系列模型。

OpenCode：

model: anthropic/claude-haiku-4-20250514
# 或
model: openai/gpt-5
# 或
model: google/gemini-2.0-flash

支持 75+ 提供商，每个 Agent 可用不同提供商的模型。

Codex CLI：

model = "gpt-5.4"
model_reasoning_effort = "high"  # 额外支持推理努力程度

仅支持 GPT 系列模型。

6.5 场景五：我想控制 Agent 的权限

Claude Code 使用工具白名单/黑名单：

tools: Read, Grep, Glob, Bash        # 白名单
disallowedTools: Write, Edit          # 黑名单

OpenCode 使用细粒度 permission 对象（更精细）：

permission:
  edit: deny
  bash:
    "*": ask
    "git diff *": allow
    "grep *": allow
  webfetch: deny
  task:
    "*": deny
    "research": allow

Codex CLI 使用 sandbox_mode（更粗粒度）：

sandbox_mode = "read-only"      # 或 "workspace-write"

6.6 场景六：我想让多个 Agent 并行工作

Claude Code：

Run the code-reviewer and the security-auditor in the background simultaneously.

或为 Agent 设置 background: true。

OpenCode：

主代理自动通过 Task 工具并行调用多个子代理。子代理在独立子会话中运行。

Codex CLI：

Spawn one subagent for security risks, one for test gaps, and one for
maintainability. Wait for all three, then summarize.

配置 max_threads 控制最大并发数（默认 6）。

6.7 场景七：我的 Claude Code Skills 能在其他工具中用吗？

7. Agent vs Skill vs Command 选择指南

决策树：

• "我想让 AI 记住某个流程/规范" --> Skill
• "我想把一个复杂任务委派出去独立完成" --> Agent (Sub Agent)
• "我经常用某个 Agent，想要快捷方式" --> Command（调用 Agent）
• "我想把以上打包分享给团队" --> Plugin（捆绑 Skill + Agent + Command）

注：Claude Code 中，Command 功能已大部分合并到 Skills 中，Skills 是更灵活的上位替代。

8. 常见问题

Q1：我应该选哪个工具？

这取决于你的需求：

• 只用 Claude 模型、追求最成熟的 Agent 生态 --> Claude Code
• 想用多种模型（如 Claude + GPT 混合使用）、喜欢开源 --> OpenCode
• 主要使用 GPT 模型、需要批量处理能力 --> Codex CLI

对于本课程学员，三个工具的 Agent 概念是相通的，核心差异在配置格式和调用方式上。

Q2：Sub Agent 的 token 消耗大吗？

所有三个工具中，Sub Agent 都运行在独立的上下文窗口中，这意味着每个 Sub Agent 都会消耗独立的 token。

• 单个 Sub Agent 调用：约为不使用 Sub Agent 时的 2 倍 token 消耗（因为主对话和子对话各占一个上下文窗口）
• 多个 Sub Agent 协作：Claude Code 文档指出，多 Sub Agent 场景下总 token 消耗约为单会话的 4-7 倍

费用估算示例：假设一次 Sub Agent 调用涉及约 10K input tokens + 2K output tokens，以 Claude Sonnet 为例（$3/M input,$15/M output），单次调用费用约 $0.03 +$0.03 = $0.06。如果并行 3 个 Sub Agent，费用约$0.20。

因此建议：

• 只在确实需要上下文隔离时使用 Sub Agent
• 简单的可复用流程用 Skill 更节省 token
• 探索类任务用轻量模型（如 Haiku、gpt-5.4-mini）

Q3：Sub Agent 能嵌套调用吗？

Q4：Agent 和 Skill 有什么区别？我应该用哪个？

详见第7章的完整对比和决策树。简单判断：

• "我想让 AI 记住某个流程/规范" --> Skill
• "我想把一个复杂任务委派出去独立完成" --> Agent

Q5：OpenCode 能直接用 Claude Code 的配置文件吗？

部分兼容：

• Skills：完全兼容，OpenCode 自动扫描 .claude/skills/ 目录
• CLAUDE.md：OpenCode 兼容读取 CLAUDE.md 作为项目指令
• Agent 文件：格式类似但不完全相同（frontmatter 字段有差异），需要手动调整 mode、permission 等字段

Q6：Codex CLI 为什么不支持自动委派？

这是设计理念的差异。Codex CLI 的哲学是"用户显式控制"——只有用户明确要求时才生成 Sub Agent。这样做的好处是 token 消耗可预测，不会出现意外的 Agent 扇出。缺点是需要用户对 Agent 能力有清晰认知并主动指名调用。

Q7：课堂演示中，老师用 Claude Code 的 @-mention 调用 Agent，我在 OpenCode/Codex 中怎么做？

• OpenCode：同样支持 @agent_name 语法，使用方式几乎一致
• Codex CLI：不支持 @ 语法，改用自然语言指名，如 "Have reviewer check the changes"。效果相同，只是写法不同

Q8：Claude Code 的 Agent Teams 是什么？和 Sub Agent 有什么区别？

Agent Teams 是 Claude Code 于 2026 年 2 月推出的更高级的多代理协作机制：

实践建议：大多数任务使用 Sub Agent 即可。Agent Teams 适合需要多个 Agent 之间相互交流信息的复杂场景（如一个 Agent 的发现需要另一个 Agent 验证），但 token 消耗显著更高。

信息来源说明

本手册信息来源如下，截至 2026-04-23：

Claude Code：

• Claude Code 官方文档 — Create custom subagents: https://code.claude.com/docs/en/sub-agents
• Claude Code 官方文档 — Plugins reference: https://code.claude.com/docs/en/plugins-reference
• Simon Willison 关于 Sub-agents 的笔记: https://simonwillison.net/2025/Oct/11/sub-agents/

OpenCode：

• OpenCode 官方文档: https://opencode.ai/docs
• OpenCode GitHub 仓库: https://github.com/anomalyco/opencode

Codex CLI：

• Codex 官方 Subagent 配置指南: https://developers.openai.com/codex/subagents
• Codex 配置参考: https://developers.openai.com/codex/config-reference
• Codex GitHub 仓库: https://github.com/openai/codex
• Simon Willison 关于 Codex Subagents 的评述: https://simonwillison.net/2026/Mar/16/codex-subagents/

三个工具均处于快速迭代中，配置字段和功能可能随版本更新变化。建议遇到问题时查阅各工具的最新官方文档。