tools: # 已废弃,请使用 permission 代替
系统对比 Claude Code、OpenCode、Codex CLI 三大 AI 编程工具的子代理系统:概念对照、配置格式、调用方式、迁移路径与常见问题,并给出 Agent/Skill/Command 选型决策建议。
目录展开 ↓
- 目录
- 1. 概述
- 1.1 三个工具简介
- 2. 快速对照表
- 2.1 子代理概念对应关系
- 2.2 配置与格式对比
- 2.3 运行时能力对比
- 2.4 内置代理对比
- 3. Claude Code 的 Agent 系统
- 3.1 配置文件位置和格式
- 3.2 核心字段说明
- 3.3 创建和调用示例
- 3.4 最佳实践
- 4. OpenCode 的 Agent 系统
- 4.1 配置文件位置和格式
- 4.2 核心字段说明
- 4.3 创建和调用示例
- 4.4 内置代理
- 4.5 最佳实践
- 5. Codex CLI 的 Agent 系统
- 5.1 配置文件位置和格式
- 5.2 核心字段说明
- 5.3 创建和调用示例
- 5.4 最佳实践
- 6. 从 Claude Code 迁移指南
- 原始 Claude Code 配置
- 6.1 迁移到 OpenCode
- 6.2 迁移到 Codex CLI
- 7. Agent vs Skill vs Command 选择指南
- 8. 常见问题
- Q1:我应该选哪个工具?
- Q2:子代理的 token 消耗大吗?
- Q3:子代理能嵌套调用吗?
- Q4:Agent 和 Skill 有什么区别?我应该用哪个?
- Q5:OpenCode 能直接用 Claude Code 的配置文件吗?
- Q6:Codex CLI 为什么不支持自动委派?
- Q7:课堂演示中,老师用 Claude Code 的 @-mention 调用 Agent,我在 OpenCode/Codex 中怎么做?
- Q8:Claude Code 的 Agent Teams 是什么?和子代理有什么区别?
- 附录:术语表
- 信息来源说明
适用对象:经管学科研究生与青年学者 更新日期:2026-04-26

在构建AI Agent系统辅助科研和日常工作的流程中,Subagent(子代理)已经成为高效使用这些工具的核心能力。无论是自动化代码审查、论文润色修订,还是大规模文件整理,子代理都能将复杂任务拆解给专用 AI 助理独立完成,大大提升工作效率。
本长文根据 Claude Code、OpenCode 和 Codex CLI 的官方文档系统整理对比了它们的子代理功能,涵盖概念对照、配置方法、调用方式、迁移路径和常见问题,既可以通读建立完整认知,也可以在遇到具体问题时按需查阅。
或者,直接把本文扔给你的 AI Agent。
目录
- 1. 概述
- 2. 快速对照表
- 3. Claude Code 的 Agent 系统
- 4. OpenCode 的 Agent 系统
- 5. Codex CLI 的 Agent 系统
- 6. 从 Claude Code 迁移指南
- 7. Agent vs Skill vs Command 选择指南
- 8. 常见问题
- 附录:术语表
- 信息来源说明
1. 概述
1.1 三个工具简介
| 工具 | 开发者 | 定位 | 开源 | 模型支持 | 配置格式 |
|---|---|---|---|---|---|
| Claude Code | Anthropic | 官方 CLI 编程助手 | 否 | Claude 系列(别名 haiku/sonnet/opus、完整模型 ID 如 claude-opus-4-6、inherit 继承) | Markdown + YAML frontmatter |
| OpenCode | Anomaly(原 SST) | 开源 AI 编程助手,140K+ Stars | 是(开源) | 75+ 提供商(Claude、GPT、Gemini 等) | Markdown + YAML 或 JSON/JSONC |
| Codex CLI | OpenAI | 官方 CLI 编程助手 | 是(Apache-2.0) | GPT 系列(gpt-5.4、gpt-5.4-mini 等) | TOML |
安装方式速览:
| 工具 | 安装命令 |
|---|---|
| Claude Code | npm install -g @anthropic-ai/claude-code |
| OpenCode | npm install -g opencode 或 brew install opencode |
| Codex CLI | npm i -g @openai/codex 或 brew install --cask codex |
Claude Code 是 Anthropic 推出的命令行 AI 编程助手,深度绑定 Claude 模型生态,拥有最成熟的子代理系统,支持自动委派、@-mention 调用、后台运行等丰富特性。
OpenCode 是社区驱动的开源替代方案,核心优势在于多模型支持(可以为不同 Agent 指定不同提供商的模型)和细粒度权限控制。它兼容 Claude Code 的 Skills 格式,迁移成本较低。
Codex CLI 是 OpenAI 推出的命令行工具,使用 TOML 格式配置,设计理念偏向显式控制——只在用户明确要求时才生成子代理,不会自动委派。擅长并行批量处理任务。
了解了三个工具的基本定位,接下来我们通过一系列对照表,快速建立概念对应关系。如果你已经熟悉某个工具,这些表格能帮你把已有知识"翻译"到其他工具上。
2. 快速对照表
2.1 子代理概念对应关系
以下表格帮助你在三个工具间"翻译"同一个概念:
| 概念 | Claude Code | OpenCode | Codex CLI |
|---|---|---|---|
| 项目指令文件 | CLAUDE.md | AGENTS.md(兼容 CLAUDE.md) | AGENTS.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 |
| 子代理 | Subagent | Subagent | Subagent |
| 内置探索代理 | Explore(Haiku) | Explore | explorer |
| 内置通用代理 | General-purpose | General | worker |
| Skills 系统 | .claude/skills/ | .opencode/skills/(兼容 .claude/skills/) | Skills 配置(skills.config) |
| 子代理调用工具 | Agent / Task 工具 | Task 工具 | 显式提示词指令 |
2.2 配置与格式对比
| 维度 | Claude Code | OpenCode | Codex CLI |
|---|---|---|---|
| 配置文件格式 | Markdown + YAML frontmatter | Markdown + YAML 或 JSON/JSONC | TOML |
| 项目级 Agent 目录 | .claude/agents/ | .opencode/agents/ | .codex/agents/ |
| 全局 Agent 目录 | ~/.claude/agents/ | ~/.config/opencode/agents/ | ~/.codex/agents/ |
| 核心必填字段 | name, description | description | name, description, developer_instructions |
| 系统提示词位置 | Markdown body(正文) | Markdown body 或 JSON prompt 字段 | developer_instructions 字段 |
| 模型指定 | model: sonnet/opus/haiku/inherit | model: provider/model-id | model: gpt-5.4 等 |
| 权限控制 | tools / disallowedTools 白黑名单 | permission 对象(支持 glob 模式) | sandbox_mode(read-only 等) |
| MCP 服务器 | Agent 级别配置 | 支持(详见各工具文档) | Agent 级别配置 |
| Plugin 系统 | 完整 Plugin 体系 | 支持 | 不适用 |
2.3 运行时能力对比
| 维度 | Claude Code | OpenCode | Codex 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 Code | OpenCode | Codex CLI |
|---|---|---|---|
| 通用编码 | General-purpose(继承模型) | Build(Primary,全工具) | default |
| 只读探索 | Explore(Haiku) | Explore | explorer |
| 规划分析 | Plan(只读) | Plan(Primary,禁止编辑) | 无专用(手动配置) |
| 执行实现 | General-purpose | General(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 字段: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) 限制可生成的子代理类型;完全省略 Agent 则该 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"
}
}'
调用方式:
| 方式 | 语法 | 说明 |
|---|---|---|
| 自动委派 | (无需操作) | Claude 根据 description 自动判断 |
| 自然语言 | Use the code-reviewer subagent to review my changes | 显式请求 |
| @-mention | @"code-reviewer (agent)" look at the auth changes | 确保指定 Agent 运行 |
| 整个会话 | claude --agent code-reviewer | Agent 提示词替代默认系统提示词 |
| 后台运行 | background: true 或 Ctrl+B | 并发执行,不阻塞主对话 |
| 恢复已完成 | Continue that code review and now analyze the auth logic | 通过 SendMessage 工具恢复之前的子代理,保留完整对话历史 |
3.4 最佳实践
- description 写清楚用途:这是 Claude 决定是否自动委派的关键依据。加入 "use proactively" 可鼓励主动委派。
- 只读 Agent 限制工具:审阅类 Agent 只给
Read, Grep, Glob, Bash,不给Write, Edit。 - 不能嵌套:子代理不能再生成子代理,这是硬限制。
- 善用
isolation: worktree:让 Agent 在临时 git worktree 中运行,避免影响主工作区。 - 模型选择:探索类任务用
haiku(快速低成本),复杂任务用inherit或opus。 - 注意 Plugin Agent 限制:Plugin 中的 Agent 不支持
hooks、mcpServers、permissionMode字段(详见 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.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 格式示例)。
调用方式:
| 方式 | 语法 | 说明 |
|---|---|---|
| 自动调用 | (无需操作) | 主代理通过 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 最佳实践
- 用
mode字段区分职责:Primary Agent 用于直接交互,Subagent 用于被委派任务。 - 活用
task权限:通过permission.task精确控制主代理能调用哪些子代理,防止不必要的 token 消耗。 - 每个代理可用不同模型:研究任务用便宜的 Haiku,审阅任务用 Sonnet,规划任务甚至可以用 GPT-5。
- 用
steps控制成本:设置合理的最大迭代步数,避免子代理无限循环。 - 兼容 Claude Code Skills:OpenCode 会自动扫描
.claude/skills/目录,已有的 Claude Code Skills 无需迁移。 - 使用
permission而非tools:tools字段已废弃,新配置请使用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 按以下顺序查找项目指令文件:
~/.codex/AGENTS.override.md(个人临时覆盖)~/.codex/AGENTS.md(个人全局指令)- 项目根目录到当前目录逐级查找
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 最佳实践
- 显式调用:Codex 不会自动生成子代理,记得在提示词中明确指名要使用的 Agent。
- 控制嵌套深度:
max_depth默认为 1,避免递归扇出导致 token 爆炸。 - 模型选择策略:
gpt-5.4用于复杂推理,gpt-5.4-mini用于快速探索和并行 worker,gpt-5.3-codex-spark用于即时文本迭代。 sandbox_mode控制安全:只读 Agent 设为read-only,实现类 Agent 用workspace-write。- 自定义 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: opus | model: anthropic/claude-opus-4-6(写完整 ID) |
memory: project | OpenCode 无此字段,去掉 |
| 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: opus | model = "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
"""
迁移要点:
- description 要精简:Codex 不自动委派,长 description 意义不大,保留核心功能描述即可
- 调用方式改变:不能靠自动委派,需要显式写
Have manuscript-reviewer review this paper - 模型切换:
opus→gpt-5.4,配合model_reasoning_effort = "high"保证审稿质量 - 系统提示词塞进 TOML:正文全部移入
developer_instructions,用"""多行字符串 - memory 功能无对应:去掉所有 memory 相关指令
迁移问题解决之后,还有一个更根本的选择:在 AI 编程工具中,什么时候该用 Skill,什么时候该用子代理,什么时候该用 Command?这三者功能有重叠,但适用场景差异很大。下面这张对照表和决策树可以帮你快速判断。
7. Agent vs Skill vs Command 选择指南
| 维度 | Skill | Agent(子代理) | 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 为例(15/M output),单次调用费用约 0.03 = 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 字段有差异),需要手动调整
mode、permission等字段
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 月。建议在遇到具体问题时,同时查阅各工具的最新官方文档。
附录:术语表
| 术语 | 解释 |
|---|---|
| CLI | Command Line Interface,命令行界面。在终端中通过文字命令与程序交互的方式 |
| TUI | Terminal User Interface,终端用户界面。在终端中提供类图形界面的交互体验 |
| YAML | 一种常用的配置文件格式,使用缩进表示层级,易于人类阅读 |
| TOML | Tom's Obvious Minimal Language,另一种配置文件格式,使用 [section] 和 key = value 语法 |
| JSON / JSONC | JavaScript Object Notation,数据交换格式。JSONC 是带注释的 JSON |
| Frontmatter | Markdown 文件开头被 --- 包围的元数据块,通常使用 YAML 格式 |
| MCP | Model 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:
- 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/
三个工具均处于快速迭代中,配置字段和功能可能随版本更新变化。建议遇到问题时查阅各工具的最新官方文档。