Agent Teams 与 Channels

Agent Teams 和 Channels 都是“让 Claude Code 不只等你输入”的能力,但它们解决的问题不同:

能力	核心作用	适合
Agent Teams	多个 Claude Code session 组成团队,互相发消息、认领任务	复杂 review、并行假设、跨模块研究
Channels	MCP server 把外部事件推入正在运行的 session	CI 结果、监控告警、聊天消息、webhook
Permission relay	Channels 把工具审批发到远端,再把批准或拒绝传回本地	手机上批准命令、远程处理 ask

这些能力会增加并行 token、权限面和事件来源复杂度。接 Gushen888 时,还要确认网关是否完整转发 MCP、工具、缓存和 channel 相关字段。

Agent Teams 什么时候用

Agent Teams 适合需要多个独立 Claude instance 互相协调的工作。它不是 subagent 的简单别名。

官方当前把 Agent Teams 作为实验能力,默认关闭。启用方式:

~/.claude/settings.json

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

如果要让 teammate 用分屏显示,可以设置 teammateMode,或单次启动时传 claude --teammate-mode auto。分屏模式依赖 tmux 或 iTerm2 的 it2 CLI。只做普通协作时,默认 in-process 模式更稳。

对比项	Subagent	Agent Teams
上下文	独立上下文,结果回主会话	每个 teammate 独立上下文,互相通信
协调	主 agent 分配和汇总	共享任务列表,teammate 可认领任务
沟通	只回报给调用方	teammates 可直接互发消息
成本	相对低,结果摘要回主上下文	更高,每个 teammate 都是完整 Claude Code session
适合	单点调研、单文件 review、隔离上下文	大型审查、并行方案、长期协作

典型用法:

Spawn 3 teammates: one for security review, one for performance review, and one for test coverage. Have them report separately, then cross-check each other's findings.

Team lead、teammate 和 mailbox

官方把 Agent Teams 拆成几个角色:

组件	作用
Team lead	当前主会话,负责启动 teammates 和协调方向
Teammates	独立 Claude Code 实例,各自处理任务
Task list	共享任务列表,teammate 可 claim 和 complete
Mailbox	agent 之间发消息、提问、同步结论

使用时要给每个 teammate 明确角色、输入材料和验证口径。不要只说“帮我 review”,应该说明严重性标准、要跑的测试、哪些文件不可改。

权限和质量门

Agent Teams 的风险来自“多个 agent 同时有工具权限”。建议:

默认先让 teammate 做 research 和 review,不要一开始就允许所有人编辑。
写操作走 ask 或限定目录。
大任务用 worktree 隔离,避免多个 teammate 改同一文件。
用 Hooks 做质量门,例如测试失败不能完成任务。
让 team lead 等 teammate 完成后再汇总,不要提前结束。

Channels 是什么

Channels 让 MCP server 主动向 Claude Code session 推送事件。普通 MCP 是 Claude 需要时去调用工具,Channels 是外部系统有事时把消息送进会话。

事件来源	可以推什么
CI/CD	job 失败、测试日志、部署状态
ChatOps	Slack/Discord/Teams 消息
监控系统	告警、恢复、指标异常
Webhook	issue、PR、ticket、incident 变化

Claude 会把事件作为 <channel> 内容读到上下文中,然后按 instructions 判断要不要回复、要不要调用工具、要不要等待人工批准。

官方 channel 入口

Channel	前置条件	适合
Fakechat	Claude Code 已登录、Bun 可用	本地快速验证 channel 和 reply tool
Telegram	创建 bot、安装官方插件、pair sender	手机远程发送任务和接收回复
Discord	创建 bot、启用 Message Content Intent、邀请到 server	团队聊天桥接
iMessage	macOS、Full Disk Access、Messages/AppleScript 权限	Apple 设备间自用远程控制
自定义 webhook	MCP SDK、stdio server、本地 HTTP listener	CI、监控、部署、工单事件推入本地 session

官方预置 channel 通常通过插件安装,再用 --channels 启动:

claude --channels plugin:fakechat@claude-plugins-official

开发自己的 channel 时,研究预览期间需要开发 flag:

claude --dangerously-load-development-channels server:webhook

.mcp.json 中存在 server 不代表它能推送 channel 事件。server 还必须在启动参数中被列为 channel,并且没有被组织 policy 阻断。

Channel MCP server 需要什么

官方 reference 里,Channel server 通过 MCP capabilities 声明自己支持 channel。

字段	用途
`capabilities.experimental["claude/channel"]`	注册通知监听能力
`capabilities.experimental["claude/channel/permission"]`	可选,允许接收工具审批 relay
`capabilities.tools`	双向 channel 需要 reply tool
`instructions`	告诉 Claude event 怎么解释、何时回复、用哪个 tool 回复

通知 payload 通常包含:

字段	用途
`content`	事件正文
`meta`	路由属性,例如 `chat_id`、`sender`、`severity`

meta key 只能使用标识符字符。带连字符或特殊字符的 key 可能被丢弃,所以建议统一用 snake_case。

Webhook channel 架构

步骤	说明
声明能力	MCP server 在 `capabilities.experimental["claude/channel"]` 声明 channel
连接 Claude Code	server 通过 stdio transport 被 Claude Code 子进程启动
接收事件	本地 HTTP listener、chat bot 或 platform polling 收到外部事件
推送通知	server 发 `notifications/claude/channel`,把 `content` 和 `meta` 注入 session
可选回复	双向 channel 暴露 reply tool,Claude 调用 tool 发回 chat 或 webhook
可选审批	声明 `claude/channel/permission`,把工具审批 relay 到可信 sender

通知没有端到端 ack。mcp.notification() 只说明写入 transport,不代表 Claude 已经处理。如果需要确认,让 Claude 调用 reply tool 回传状态。

最小事件形态:

<channel source="webhook" severity="high" run_id="1234">
build failed on main: https://ci.example.com/run/1234
</channel>

Permission relay

Permission relay 可以把本地工具审批转发到远端 channel。你在手机或聊天工具里看到一个审批请求,回复批准或拒绝后,Claude Code 再继续。

字段	说明
`request_id`	本次审批的短 ID,必须原样带回
`tool_name`	例如 `Bash`、`Write`、`Edit`
`description`	Claude 对工具调用的说明
`input_preview`	工具参数预览,通常会截断

安全重点是 sender gating:只有可信发送者能触发消息或批准权限。不要让公开 webhook 直接拥有批准生产命令的能力。

企业控制

Channels 处于研究预览或快速演进阶段时,组织更应该集中控制。

设置	建议
`channelsEnabled`	明确开关,不要靠默认值猜
`allowedChannelPlugins`	只允许经过审查的 channel plugin
Managed settings	对团队统一下发,避免个人乱配
MCP allowlist	限制可接入的 server 和工具
Hooks	对高风险 Bash、Write、MCP 写操作做二次拦截

缓存和成本影响

动作	5m / 1h 缓存解释
创建 Agent Team	每个 teammate 是独立 Claude Code session,各自建缓存
teammate 互发消息	消息进入对应 teammate 历史,后续可在该 session 内缓存
Channel 事件推入	事件作为新消息追加,短间隔可刷新 TTL
CI 告警间隔超过 5 分钟	API/provider 默认 5m TTL 可能冷启动
permission relay	审批本身通常不调用模型,批准后的工具结果会进上下文

如果事件很频繁,要控制 channel 内容长度。把长日志放链接或 artifact,让 Claude 按需抓取,不要每次把完整日志推入会话。

Gushen888 边界

问题	判断
Agent Team 是否走 Gushen888	取决于 teammate 启动环境是否继承 `ANTHROPIC_BASE_URL` 和 token
Channel 消息是否进模型请求	进入 session 后通常会成为后续上下文
网关是否支持	需要完整转发 MCP、tool search、usage、cache 字段
云端 web session	不自动继承本地 Gushen888 配置
第三方 chat/CI	自己的数据保留和权限模型要单独审查

Agent Teams 与 Channels

Agent Teams 什么时候用

Team lead、teammate 和 mailbox

权限和质量门

Channels 是什么

官方 channel 入口

Channel MCP server 需要什么

Webhook channel 架构

Permission relay

企业控制

缓存和成本影响

Gushen888 边界

官方参考

相关页面

Agent Teams 与 Channels ​

Agent Teams 什么时候用 ​

Team lead、teammate 和 mailbox ​

权限和质量门 ​

Channels 是什么 ​

官方 channel 入口 ​

Channel MCP server 需要什么 ​

Webhook channel 架构 ​

Permission relay ​

企业控制 ​

缓存和成本影响 ​

Gushen888 边界 ​

官方参考 ​

相关页面 ​

Agent Teams 与 Channels

Agent Teams 什么时候用

Team lead、teammate 和 mailbox

权限和质量门

Channels 是什么

官方 channel 入口

Channel MCP server 需要什么

Webhook channel 架构

Permission relay

企业控制

缓存和成本影响

Gushen888 边界

官方参考

相关页面