# Claude Code Agent Teams 与 Channels

> Claude Code Agent Teams、Channels、channel reference、权限 relay、团队协作和事件推送的使用边界、缓存成本与 Passion8 注意事项。

URL: https://docs.passion8.cc/docs/claude-code/agent-teams-channels
Language: zh-CN
Publisher: Passion8

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

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




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




## Agent Teams 什么时候用

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

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

```json title="~/.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、隔离上下文 | 大型审查、并行方案、长期协作 |

典型用法:

```text
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 同时有工具权限”。建议:

1. 默认先让 teammate 做 research 和 review,不要一开始就允许所有人编辑。
2. 写操作走 ask 或限定目录。
3. 大任务用 worktree 隔离,避免多个 teammate 改同一文件。
4. 用 Hooks 做质量门,例如测试失败不能完成任务。
5. 让 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` 启动:

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

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

```bash
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 回传状态。

最小事件形态:

```text
<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 按需抓取,不要每次把完整日志推入会话。

## Passion8 边界

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

## 官方参考

- [Agent teams](https://code.claude.com/docs/en/agent-teams.md)
- [Channels](https://code.claude.com/docs/en/channels.md)
- [Channels reference](https://code.claude.com/docs/en/channels-reference.md)
- [Run agents in parallel](https://code.claude.com/docs/en/agents.md)
- [Agent View](https://code.claude.com/docs/en/agent-view.md)
- [Dynamic workflows](https://code.claude.com/docs/en/workflows.md)

## 相关页面



- [多代理、后台与 Workflows](https://docs.passion8.cc/docs/claude-code/parallel-agents): Subagent、Background session、Agent View、/batch、/fork、/goal 和 workflow。
- [MCP 工具接入](https://docs.passion8.cc/docs/claude-code/mcp): MCP transport、OAuth、tool search、权限和网关注意事项。
- [权限与模式](https://docs.passion8.cc/docs/claude-code/permissions): allow/ask/deny、权限模式和 managed policy。
- [组织推广与沟通套件](https://docs.passion8.cc/docs/claude-code/adoption-communications): 把 channel 和 remote approval 放进推广 FAQ 和安全口径。