想搞懂 Claude Code 这类 Coding Agent 到底是怎么工作的吗?这个开源仓库也许能帮你少走一些弯路。我基于 learn-claude-code v2 课程(感谢原作者)学习,并维护了 OpenAI SDK 版实现。如果对你有帮助,欢迎点一个 Star,大家一起学习、共同进步。

项目地址:https://github.com/peijiping/learn-claude-code-langchain

最近在学习 Claude Code(下称 CC)的 Agent Teams 功能时,发现一个很有意思的现象:命令列表里只有一个 /team-onboarding,却看不到启动团队的 /team 命令。顺着这个坑一路挖下去,把"子智能体(Agent)"和"团队智能体(Agent Teams)"两套机制的关系彻底理清了。这篇文章把整个思考过程整理出来。

结论先行:两种机制都能在同一会话按需启动

真实子智能体(Agent) 和 团队智能体(Agent Teams) 在同一个 CC 会话中,都可以随时按需启动,但它们是两个不同层次的东西。

维度	真实子智能体(s06 的内容)	团队智能体(s15 的内容)
启动方式	主会话任意时刻调用 Agent 工具	通过 /team 命令,由用户发起
生命周期	一次性,跑完销毁	常驻,通过文件收件箱持续协作
上下文	完全隔离,跑完回传结论	通过收件箱消息共享信息
层级	主线程的直接扩展	Lead + 多个队友,队友是完整会话
数量	主 Agent + 偶尔子 Agent	一个 Lead + 多个队友

两者完全可以共存:你可以现在派一个子代理查代码,下一步再起一个团队干活,互不干扰。

一、子智能体:会话内部的"临时工"

子智能体是主会话内部的能力:

• 主会话任意时刻都能用 Agent 工具派一个 Explore、general-purpose 或自定义 .claude/agents/*.md 代理,并支持并行启动。
• 它运行在当前会话内部,共享父上下文,跑完即销毁。
• 它是轻量、可随时回收的,本质上就是主 Agent 的一个工具调用。

一句话:子智能体 = 你在当前会话里"临时叫的帮手",不改变你的角色。

二、团队智能体:会话之上的"组队模式"

团队智能体则完全是另一回事:

• 它本质上是启动多个完整的 CC 会话协作,第一个会话自动成为 Lead(编排者)。
• 你从当前会话通过 /team 命令启动,不需要预先切到某个"团队模式",但启动后你的当前会话会变成团队 Lead。
• 每个队友有独立的 system prompt、独立的收件箱(~/.claude/teams/{team}/inboxes/),通过文件收件箱异步通信。
• 团队内还有权限冒泡机制:队友遇到需要审批的操作 → 发 permission_request 到 Lead → 用户审批 → 回传队友。

一句话:团队 = 你"带一队全功能会话",启动后你变成了 Lead。

三、核心问题:为什么团队不能像子智能体一样,由主智能体直接启动?

这是很多人(包括我)的第一反应:既然子智能体随时能调,团队为什么不也做成一个工具?答案不是"技术不能",而是产品设计的刻意分层。

1. 架构分层的必然:主 Agent 没有创建兄弟会话的权限

子智能体运行在当前会话内部;而团队要动的东西在会话之上:

• 启动多个完整的 CC 会话(真实 CC 用 tmux 窗格/独立进程)
• 创建团队注册表 ~/.claude/teams/{team}/config.json
• 跑权限轮询、idle 通知等常驻循环

主 Agent 运行在"某一个会话里面",天然没有创建兄弟会话的权限——那是 CLI/harness 层的特权。所以创建团队的入口只能在命令/UI,而不是 Agent 工具。这是架构分层的必然结果。

2. 角色转变需要用户显式同意

启动团队 = 你从"干活的人"变成"带队伍的人",整个会话的职责都变了。这不该由模型悄悄替你做决定。

3. 重度资源 + 用户可见,需要知情启动

团队在 UI 上会铺开多个带颜色的窗格,每个都是真会话在烧 token,还有权限审批要冒泡到你这里。这是一件你要盯着、要参与的事情,不是后台黑盒。用显式命令开始,等于让你清楚"现在开始起一堆进程了"。实验性功能 gate 住,正是防止模型随手起一群。

4. 失控成本差异巨大

子代理失控,杀线程即可;团队失控,是一堆会话和收件箱状态。入口越显式,越能保证用户有意识地使用。

一个容易混淆的点:创建团队 ≠ 招队友

值得注意的分层细节:

• 创建团队要用户通过 /team 命令发起(要你"签字注册公司")。
• 但团队成立后,Lead 是用工具直接 spawn 队友的——这正是 s15 教学代码里的 spawn_teammate(真 CC 是 spawnMultiAgent.ts 的 spawnTeammate()),"招人"是随时、直接、工具调用的。
• 而队友内部又可以用 Agent 工具叫子代理(临时工)。

层级	行为	入口
创建团队	注册公司	/team 命令(用户发起)
招队友	Lead 招聘员工	spawn_teammate 工具
叫子代理	临时工	Agent 工具

唯一的硬限制:队友不能再嵌套启动队友("teammates spawning other teammates" 被禁止),但子代理可以随便嵌套。

四、为什么我只看到了 /team-onboarding,而不是 /team?

这是让我最困惑的地方。查证之后发现,/team-onboarding 和 /team 是两码事:

1. /team-onboarding 是个"人"的上手指南工具

它根据你现有的 CC 配置和使用情况,自动生成一份"让新同事快速上手 Claude Code"的指南——即便你根本没建过团队,它也能生成。它同时以 skill 形式分发,所以人人都会在 / 命令列表里看到它。名字带 "team" 纯属误导,它管的是"团队里的人类队友",和启动 agent 团队毫无关系。

2. /team 看不到的原因:实验性功能被环境变量 gate 住了

CC 的 Agent Teams 是实验性功能,被环境变量 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS gate 住。不设置这个变量,/team 命令根本不会注册,命令列表里自然只剩无关的 /team-onboarding。

五、如何启用团队功能

1. 设置环境变量(二选一):
   • 终端:export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1,然后重启 CC
   • 或写入 ~/.claude/settings.json 的 env 字段,再重启
2. 运行 /team 打开团队视图
3. 完成功能内的 onboarding 向导(有个已知坑:GitHub issue #34190 报告过卡在 "Choose text style" 界面,需要手动点完才能继续)
4. 添加队友 / 分配任务,Lead 委派给 agent 队友

六、诚实标注:哪些是经过官方验证的,哪些是推断的

写文章要对读者负责。以下信息基于搜索结果 + 第三方指南综合整理,当时官方文档页面网络受限未能抓取全文:

• 可靠:子智能体完全按需可启动;团队是"多会话协作 + Lead 编排"的模型;/team-onboarding 是独立于团队启动的人类 onboarding 工具。
• 待验证:环境变量名 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 由 2 个独立来源佐证,但非官方原文;/team 是单数还是复数,也是从第三方 commit 推断的。
• 最可靠的验证方法:export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 && claude,重启后看 / 列表里是否出现 /team。如果没出现,可能是 CC 版本早于 2026 年 2 月的功能上线时间,更新即可。

结语

CC 的团队机制和你在学习仓库(s06 子代理 / s15 团队)里模拟的模型是相通的:

• 子智能体 = 临时工,会话内部工具,随时可调,不改变你的角色;
• 团队智能体 = 组队模式,会话之上的编排,用命令显式启动,让你成为 Lead;
• /team 不出现,不是 bug,是实验性功能的 gate 设计。

---