跳到主内容
✍️ 公众号文章
研究者
AI 教师
学生
经/管/金融人

tools: # 已废弃,请使用 permission 代替

系统对比 Claude Code、OpenCode、Codex CLI 三大 AI 编程工具的子代理系统:概念对照、配置格式、调用方式、迁移路径与常见问题,并给出 Agent/Skill/Command 选型决策建议。

李学恒18 分钟阅读#claude-code#opencode#codex-cli#subagent#agent-migration

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

封面图

在构建AI Agent系统辅助科研和日常工作的流程中,Subagent(子代理)已经成为高效使用这些工具的核心能力。无论是自动化代码审查、论文润色修订,还是大规模文件整理,子代理都能将复杂任务拆解给专用 AI 助理独立完成,大大提升工作效率。

本长文根据 Claude Code、OpenCode 和 Codex CLI 的官方文档系统整理对比了它们的子代理功能,涵盖概念对照、配置方法、调用方式、迁移路径和常见问题,既可以通读建立完整认知,也可以在遇到具体问题时按需查阅

或者,直接把本文扔给你的 AI Agent

目录

1. 概述

1.1 三个工具简介

工具开发者定位开源模型支持配置格式
Claude CodeAnthropic官方 CLI 编程助手Claude 系列(别名 haiku/sonnet/opus、完整模型 ID 如 claude-opus-4-6inherit 继承)Markdown + YAML frontmatter
OpenCodeAnomaly(原 SST)开源 AI 编程助手,140K+ Stars是(开源)75+ 提供商(Claude、GPT、Gemini 等)Markdown + YAML 或 JSON/JSONC
Codex CLIOpenAI官方 CLI 编程助手是(Apache-2.0)GPT 系列(gpt-5.4、gpt-5.4-mini 等)TOML

安装方式速览:

工具安装命令
Claude Codenpm install -g @anthropic-ai/claude-code
OpenCodenpm install -g opencodebrew install opencode
Codex CLInpm i -g @openai/codexbrew install --cask codex

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

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

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

了解了三个工具的基本定位,接下来我们通过一系列对照表,快速建立概念对应关系。如果你已经熟悉某个工具,这些表格能帮你把已有知识"翻译"到其他工具上。

2. 快速对照表

2.1 子代理概念对应关系

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

概念Claude CodeOpenCodeCodex CLI
项目指令文件CLAUDE.mdAGENTS.md(兼容 CLAUDE.mdAGENTS.md
全局配置~/.claude/settings.json~/.config/opencode/opencode.json~/.codex/config.toml
Agent 定义文件.claude/agents/*.md.opencode/agents/*.md.codex/agents/*.toml
主代理主对话(隐式)Primary Agent(Build、Plan)default agent
子代理SubagentSubagentSubagent
内置探索代理Explore(Haiku)Exploreexplorer
内置通用代理General-purposeGeneralworker
Skills 系统.claude/skills/.opencode/skills/(兼容 .claude/skills/Skills 配置(skills.config
子代理调用工具Agent / Task 工具Task 工具显式提示词指令

2.2 配置与格式对比

维度Claude CodeOpenCodeCodex CLI
配置文件格式Markdown + YAML frontmatterMarkdown + YAML 或 JSON/JSONCTOML
项目级 Agent 目录.claude/agents/.opencode/agents/.codex/agents/
全局 Agent 目录~/.claude/agents/~/.config/opencode/agents/~/.codex/agents/
核心必填字段name, descriptiondescriptionname, description, developer_instructions
系统提示词位置Markdown body(正文)Markdown body 或 JSON prompt 字段developer_instructions 字段
模型指定model: sonnet/opus/haiku/inheritmodel: provider/model-idmodel: gpt-5.4
权限控制tools / disallowedTools 白黑名单permission 对象(支持 glob 模式)sandbox_mode(read-only 等)
MCP 服务器Agent 级别配置支持(详见各工具文档)Agent 级别配置
Plugin 系统完整 Plugin 体系支持不适用

2.3 运行时能力对比

维度Claude CodeOpenCodeCodex CLI
自动委派支持(根据 description 自动判断)支持(Task 工具自动调用)不支持(仅显式调用)
@-mention 调用@"agent-name (agent)"@agent_name不支持(用自然语言指名)
交互式创建/agents 命令opencode agent create不支持(手动创建)
后台运行支持(background: true 或 Ctrl+B)支持(独立子会话)支持(并行线程)
嵌套限制不能嵌套(硬限制)文档未提及嵌套限制max_depth 可配置(默认 1)
最大并发无显式限制无显式限制max_threads(默认 6)
CSV 批量处理不支持不支持spawn_agents_on_csv(实验性)

2.4 内置代理对比

功能Claude CodeOpenCodeCodex CLI
通用编码General-purpose(继承模型)Build(Primary,全工具)default
只读探索Explore(Haiku)Exploreexplorer
规划分析Plan(只读)Plan(Primary,禁止编辑)无专用(手动配置)
执行实现General-purposeGeneral(Subagent)worker
自动压缩内置(无需配置)Compaction(隐藏系统代理)内置(无需配置)

对照表提供了全局视角。下面我们深入每个工具的 Agent 系统,从配置文件位置、核心字段、创建方式到最佳实践逐一展开。先从本课程的主工具——Claude Code 开始。

3. Claude Code 的 Agent 系统

3.1 配置文件位置和格式

Agent 文件是 带有 YAML frontmatter 的 Markdown 文件.md),存放位置决定作用范围:

位置范围优先级
--agents CLI 参数当前会话最高
.claude/agents/当前项目
~/.claude/agents/所有项目
Plugin 的 agents/ 目录Plugin 启用范围最低

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

Plugin 中 Agent 的限制:出于安全原因,Plugin 中的 Agent 不支持以下 frontmatter 字段:hooksmcpServerspermissionMode。这些字段在加载 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) 限制可生成的子代理类型;完全省略 Agent 则该 Agent 不能生成任何子代理。

模型选择

  • 模型别名sonnetopushaiku
  • 完整模型 ID:如 claude-opus-4-6claude-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"
  }
}'

调用方式:

方式语法说明
自动委派(无需操作)Claude 根据 description 自动判断
自然语言Use the code-reviewer subagent to review my changes显式请求
@-mention@"code-reviewer (agent)" look at the auth changes确保指定 Agent 运行
整个会话claude --agent code-reviewerAgent 提示词替代默认系统提示词
后台运行background: true 或 Ctrl+B并发执行,不阻塞主对话
恢复已完成Continue that code review and now analyze the auth logic通过 SendMessage 工具恢复之前的子代理,保留完整对话历史

3.4 最佳实践

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

Claude Code 的 Agent 系统最为成熟,但它的局限也很明显——只能用 Claude 系列的模型。如果你需要混用多种模型,或者偏好开源工具,OpenCode 提供了一个非常接近的替代方案,而且迁移成本很低

4. OpenCode 的 Agent 系统

4.1 配置文件位置和格式

OpenCode 支持两种配置格式:Markdown 文件JSON 配置

Markdown 文件位置:

范围路径
全局~/.config/opencode/agents/*.md
项目.opencode/agents/*.md

JSON 配置位置(opencode.json):

层级位置说明
全局~/.config/opencode/opencode.json用户偏好
项目项目根目录 opencode.json项目特定
环境变量OPENCODE_CONFIG 指定路径自定义覆盖

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.jsonagent 字段中):

{
  "$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.jsonagent 字段中添加 JSON 配置(见上文 JSON 格式示例)。

调用方式:

方式语法说明
自动调用(无需操作)主代理通过 Task 工具根据 description 自动判断
@ 提及@review check the changes in src/手动指定子代理
Tab 切换按 Tab 键在主代理之间切换(仅 Primary Agent)
CLI 指定opencode run --agent plan "..."命令行指定代理
命令绑定"command": {"review": {"agent": "plan"}}将斜杠命令绑定到特定代理执行;设置 "subtask": true 可让命令在子代理中执行

子会话导航(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 而非 toolstools 字段已废弃,新配置请使用 permission 进行权限控制。

OpenCode 的灵活性和多模型支持令人印象深刻。接下来看 OpenAI 自家的 Codex CLI——它的设计哲学与前两者截然不同:强调显式控制,不做自动委派,适合喜欢精细掌控的用户。

5. Codex CLI 的 Agent 系统

5.1 配置文件位置和格式

Codex CLI 使用 TOML 格式定义 Agent。

Agent 文件位置:

范围路径
全局~/.codex/agents/*.toml
项目.codex/agents/*.toml

全局 Agent 设置(在 config.toml 中):

位置说明
~/.codex/config.toml全局配置
.codex/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 超时

模型选择策略:

模型推荐用途
gpt-5.4大多数代理的起点,强编码+推理+工具使用
gpt-5.4-mini快速轻量任务:探索、大文件审查、并行 worker
gpt-5.3-codex-spark近乎即时的纯文本迭代(ChatGPT Pro 专享)

推理努力程度(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 不会自动委派 子代理。你需要在提示词中显式指名使用:

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.

管理运行中的代理:

操作方式
查看/切换代理线程/agent 斜杠命令
处理审批请求o 打开非活跃线程的审批请求
CSV 批量处理spawn_agents_on_csv 工具(见下文)

5.4 最佳实践

  1. 显式调用:Codex 不会自动生成子代理,记得在提示词中明确指名要使用的 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)相同,自定义版本优先。

以上三章分别介绍了每个工具的 Agent 系统。但对于已经用上 Claude Code 的读者来说,最实际的问题是:我现有的配置怎么迁移过去?下面通过七个常见场景,逐一演示从 Claude Code 迁移到 OpenCode 和 Codex CLI 的具体做法。

6. 从 Claude Code 迁移指南

下面以一门 AI 编程课程中实际使用的 manuscript-reviewer(论文审稿 Agent)为例,展示完整的迁移过程。这是经管类研究中常见的需求——用 AI 代理生成结构化的审稿报告。先看原始的 Claude Code 配置,再分别演示迁移到 OpenCode 和 Codex CLI 的步骤。

原始 Claude Code 配置

文件.claude/agents/manuscript-reviewer.md

name: "manuscript-reviewer"
description: "Use this agent when the user asks for a peer review,
  referee report, or manuscript evaluation of an academic paper..."
model: opus
memory: project

You are an elite academic peer reviewer with deep expertise across
economics, finance, management, and related social sciences...

## Report Structure
### 1. Summary and Evaluation(总体评价)
### 2. Major Comments(重大问题)
### 3. Minor Comments(次要问题)

(完整系统提示词约 2000 字)

核心特征model: opus(用最强模型)、长 description(含触发示例)、无工具限制(默认全部可用)、memory: project(持久化记忆)。

6.1 迁移到 OpenCode

改动较小,格式相似。 主要调整:

Claude Code 写法OpenCode 对应写法
name: "manuscript-reviewer"去掉(文件名 manuscript-reviewer.md 即代理名)
model: opusmodel: anthropic/claude-opus-4-6(写完整 ID)
memory: projectOpenCode 无此字段,去掉
description 中的触发示例保留,OpenCode 同样依据 description 自动委派
(无)新增 mode: subagent

迁移后文件.opencode/agents/manuscript-reviewer.md

description: "Use this agent when the user asks for a peer review,
  referee report, or manuscript evaluation of an academic paper.
  Examples: '请帮我审一下这篇论文草稿', 'Give me a referee report
  on this working paper'"
mode: subagent
model: anthropic/claude-opus-4-6
permission:
  edit: deny
  bash:
    "*": ask
    "cat *": allow

You are an elite academic peer reviewer with deep expertise across
economics, finance, management, and related social sciences...

(系统提示词照搬,去掉 Claude Code 特有的 memory 相关段落)

迁移要点

  • description 可以精简,去掉 <example> XML 标签(OpenCode 不解析)
  • 审稿 Agent 不需要写文件,用 permission 限制 edit: deny
  • memory 字段无对应,需删除系统提示词末尾的 memory 指令段

Skills 无需迁移:OpenCode 自动扫描 .claude/skills/ 目录。

OpenCode 的迁移相当顺畅——毕竟它和 Claude Code 同属 Markdown + YAML 阵营。但如果你的目标是 Codex CLI,情况就完全不同了:Codex 使用 TOML 格式,且不支持自动委派,迁移思路需要做较大调整。

6.2 迁移到 Codex CLI

改动较大,格式完全不同。 YAML frontmatter + Markdown 正文 → 全部改为 TOML 字段。

Claude Code 写法Codex CLI 对应写法
name: "manuscript-reviewer"name = "manuscript-reviewer"
description: "Use this agent..."description = "..."
Markdown 正文(系统提示词)developer_instructions = """..."""
model: opusmodel = "gpt-5.4"(换模型系列)
memory: project无对应,去掉
自动委派(靠 description)不支持,必须显式指名

迁移后文件.codex/agents/manuscript-reviewer.toml

name = "manuscript-reviewer"
description = "Academic manuscript peer reviewer. Generates structured referee reports with Summary/Major/Minor comments."
model = "gpt-5.4"
model_reasoning_effort = "high"
sandbox_mode = "read-only"
developer_instructions = """
You are an elite academic peer reviewer with deep expertise across
economics, finance, management, and related social sciences.

## Report Structure
### 1. Summary and Evaluation(总体评价)
- Summary of research question, methodology, and findings
- Overall assessment and recommendation

### 2. Major Comments(重大问题)
- Numbered list (Major 1, Major 2, ...)
- Substantive issues that MUST be addressed
- Each comment: state problem → explain WHY → suggest remedies

### 3. Minor Comments(次要问题)
- Numbered list (Minor 1, Minor 2, ...)
- Smaller improvements with page/line references

## Review Principles
1. Be specific: reference sections, pages, equations, tables
2. Be constructive: suggest a path forward
3. Be fair: acknowledge strengths before weaknesses
4. Language: match the manuscript language
"""

迁移要点

  1. description 要精简:Codex 不自动委派,长 description 意义不大,保留核心功能描述即可
  2. 调用方式改变:不能靠自动委派,需要显式写 Have manuscript-reviewer review this paper
  3. 模型切换opusgpt-5.4,配合 model_reasoning_effort = "high" 保证审稿质量
  4. 系统提示词塞进 TOML:正文全部移入 developer_instructions,用 """ 多行字符串
  5. memory 功能无对应:去掉所有 memory 相关指令

迁移问题解决之后,还有一个更根本的选择:在 AI 编程工具中,什么时候该用 Skill,什么时候该用子代理,什么时候该用 Command?这三者功能有重叠,但适用场景差异很大。下面这张对照表和决策树可以帮你快速判断。

7. Agent vs Skill vs Command 选择指南

维度SkillAgent(子代理)Command
独立上下文否(在主对话中运行)是(独立窗口)
自动触发否(仅手动 / 调用)
Token 消耗低(按需加载)高(独立窗口)
适合场景可复用流程、知识模板、行为指南需要隔离的复杂任务、并行工作简单快捷方式

决策树:

  • "我想让 AI 记住某个流程/规范" --> Skill
  • "我想把一个复杂任务委派出去独立完成" --> 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:子代理的 token 消耗大吗?

所有三个工具中,子代理都运行在独立的上下文窗口中,这意味着每个子代理都会消耗独立的 token

  • 单个子代理调用:约为不使用子代理时的 2 倍 token 消耗(因为主对话和子对话各占一个上下文窗口)
  • 多个子代理协作:Claude Code 文档指出,多个子代理场景下总 token 消耗约为单会话的 4-7 倍

费用估算示例:假设一次子代理调用涉及约 10K input tokens + 2K output tokens,以 Claude Sonnet 为例(3/Minput,3/M input, 15/M output),单次调用费用约 0.03+0.03 + 0.03 = 0.06。如果并行3个子代理,费用约0.06。如果并行 3 个子代理,费用约 0.20。

因此建议:

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

Q3:子代理能嵌套调用吗?

工具嵌套支持
Claude Code不能嵌套(硬限制)
OpenCode文档未提及嵌套限制
Codex CLI通过 max_depth 控制,默认为 1(仅直接子代理)

Q4:Agent 和 Skill 有什么区别?我应该用哪个?

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

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

Q5:OpenCode 能直接用 Claude Code 的配置文件吗?

部分兼容:

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

Q6:Codex CLI 为什么不支持自动委派?

这是设计思路不同。Codex CLI 把控制权交给用户——你不主动点名,它就不生成子代理。好处是 token 花多少心里有数,不会突然冒出一堆子代理。代价是你得清楚每个 Agent 能做什么,主动点名让它干活。

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

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

Q8:Claude Code 的 Agent Teams 是什么?和子代理有什么区别?

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

维度子代理Agent Teams
通信方式不能相互通信,结果返回主对话独立会话间可共享发现
并行方式在主会话内并行跨独立会话协调
Token 消耗约 4-7x约 15x
适用场景Worker 间无需通信需要共享发现、挑战假设

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

三个工具都在快速迭代中,本文信息截至 2026 年 4 月。建议在遇到具体问题时,同时查阅各工具的最新官方文档。

附录:术语表

术语解释
CLICommand Line Interface,命令行界面。在终端中通过文字命令与程序交互的方式
TUITerminal User Interface,终端用户界面。在终端中提供类图形界面的交互体验
YAML一种常用的配置文件格式,使用缩进表示层级,易于人类阅读
TOMLTom's Obvious Minimal Language,另一种配置文件格式,使用 [section]key = value 语法
JSON / JSONCJavaScript Object Notation,数据交换格式。JSONC 是带注释的 JSON
FrontmatterMarkdown 文件开头被 --- 包围的元数据块,通常使用 YAML 格式
MCPModel Context Protocol,模型上下文协议。让 AI 模型访问外部工具和数据源的标准协议
Context Window模型的上下文窗口。模型单次对话能处理的最大文本量,子代理拥有独立的上下文窗口
Token模型处理文本的基本单位。大约 1 个汉字 = 1-2 个 token,1 个英文单词 = 1-4 个 token
Glob 模式通配符匹配模式。* 匹配任意字符,如 git diff * 匹配所有以 git diff 开头的命令
Plugin插件。将 Skill、Agent、Command 打包分发的机制

信息来源说明

本手册信息来源如下,截至 2026-04-23:

Claude Code:

OpenCode:

Codex CLI:

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

related