Channels:把外部事件推进活跃 session

原文:https://code.claude.com/docs/en/channels 官方定位:An MCP server that pushes events into your running Claude Code session. 状态:Research Preview · v2.1.80+ · 仅 Anthropic 第一方 auth(Bedrock / Vertex / Foundry 不支持) Team/Enterprise:默认关,管理员开

🔥 影响力卡片

维度	数据
引入版本	v2.1.80+(比 Agent View 早一个月)
官方支持 channel	Telegram + Discord + iMessage + fakechat(demo),本机 marketplace 都有
跟 MCP 的关系	Channel 就是 MCP server,但反过来 — server 推消息给 Claude,Claude 反应,用同一个 MCP transport
跟 push notification 的关系	Push notification(02-remote-control.md)是单向 Claude → 你;Channel 是双向你 → Claude → 你
实现细节	都用 Bun 跑(本地 stdio server),配置存 ~/.claude/channels/<name>/.env
跟 Remote Control 的对比	RC 是”你驾驶 session”;Channel 是”事件 push 进 session,Claude 自动反应”

🎯 为什么必读

1. 这是 Claude Code 唯一原生的”事件驱动”机制。

之前所有功能都是你主动给 Claude 输入:

• 你打字 → Claude 回
• 你 @claude mention → GHA 触发
• cron 到点 → Routines 跑

Channel 反过来:外部事件(CI 挂了 / 朋友发消息 / Sentry 报警)→ 主动 push 进你已经开着的 session → Claude 看到 → 反应。

2. 它特别适合”边工作边接消息”的工作模式

• 你在写代码,Telegram 收朋友消息 → Claude 帮你回(用上下文)
• CI 挂了,webhook 推消息 → Claude 在你正在 debug 的 session 里继续看
• 自己 iMessage 自己 → 手机当成 Claude 的远程输入终端

3. 跟 Remote Control 不重叠,而是互补

	Remote Control	Channels
谁发起	你(从手机 / 网页驾驶)	事件(MCP server push)
显示在哪	claude.ai/code(完整 UI)	你本地 terminal(事件以 tag 形式插入)
适合	你想接管在跑的 session	你想”接受信息”但不打断工作
例子	”我打字让 Claude 改这行"	"Sentry 推消息,Claude 自己 debug”

一句话总结

Channel = 一个本地 Bun MCP server,声明 claude/channel capability,可以把外部事件推进当前 Claude session;启动时 --channels plugin:<name>@<marketplace> 显式开启;支持双向(Claude 通过 reply 工具回话)。

💎 金句墙

★ “Events only arrive while the session is open, so for an always-on setup you run Claude in a background process or persistent terminal.” “事件只在 session 开着时到达,长期开启需要 background 或常驻 terminal。” —— 🟢 channel 跟 cloud routine 的关键差别 — 必须有活的 session 接收

★ “Being in .mcp.json isn’t enough to push messages: a server also has to be named in --channels.” “光在 .mcp.json 里不够,必须在 —channels 显式开启。” —— 🟢 双重 opt-in 安全模型 — 默认禁,每个 session 显式启用

★ “When Claude replies through a channel, you see the inbound message in your terminal but not the reply text. The terminal shows the tool call and a confirmation (like ‘sent’), and the actual reply appears on the other platform.” “Claude 通过 channel 回话时,terminal 只看到入站消息和’sent’确认,实际回复在另一头(Telegram/Discord/iMessage)显示。” —— 🟢 设计上避免 terminal 被 channel 喧宾夺主 — 你工作的 terminal 保持安静

📋 核心精读

1. 4 个官方 channel + 实际门槛

Channel	需要什么	难度
fakechat(demo)	啥都不要,localhost:8787	⭐
Telegram	BotFather 建个 bot + token	⭐⭐
Discord	Developer Portal 建 bot + enable Message Content Intent + invite 到 server	⭐⭐⭐
iMessage(macOS only)	Full Disk Access 给终端	⭐⭐(macOS 系统配置)

全部依赖 Bun:bun --version 确认有装。

2. 安装 + 启动模板(以 Telegram 为例)

# A. 装 plugin
/plugin install telegram@claude-plugins-official

# 如果 marketplace 找不到:
/plugin marketplace update claude-plugins-official
# 或第一次加:
/plugin marketplace add anthropics/claude-plugins-official

# B. 配置 bot token
/reload-plugins
/telegram:configure <bot-token>
# 写到 ~/.claude/channels/telegram/.env

# C. 退出 Claude Code,带 --channels 重启
claude --channels plugin:telegram@claude-plugins-official

# D. 在 Telegram 给 bot 发任意消息 → bot 回 pairing code
/telegram:access pair <code>

# E. 锁定 — 只允许你账号
/telegram:access policy allowlist

完。从此 Telegram 消息 = Claude 输入。

3. fakechat — 0 配置体验(强烈推荐先试这个)

/plugin install fakechat@claude-plugins-official
# 退出 claude
claude --channels plugin:fakechat@claude-plugins-official
# 浏览器开 http://localhost:8787
# 在 web UI 打字 → Claude 收到 <channel source="fakechat"> 事件 → 回 reply tool

5 分钟搞清 channel 长什么样。不连真实 Telegram / Discord 也能跑。

4. 双向工作流(关键设计)

[Telegram message: "hey, what's in src/api/?"]
       │
       │  bot polling / push
       │
       ▼
[Claude Code session in your terminal]
       │
       │  receives as <channel source="telegram"> event
       │  Claude reads, looks at src/api/
       │
       │  calls telegram:reply tool with answer
       ▼
[Reply appears in Telegram]
       │
       │  你 terminal 只看到 "tool call: reply, sent"
       │  实际答案文字在 Telegram 那边

你 terminal 不被 channel 内容污染

5. 比 Remote Control 更适合的 4 个场景

场景	为什么 channel 比 RC 更合适
CI / 监控告警 push	是 event 不是会话,RC 太重
朋友发短信 / iMessage,你想 Claude 帮回	Channel 直接接 iMessage 数据库
Discord channel 里有人 @ 你机器人	Channel 持续 polling,RC 必须主动连
想要 Claude 同时处理 5 个外部输入源	加 5 个 channel,RC 同一时间一个

6. --dangerously-skip-permissions 配合 channel — 真无人值守

claude --channels plugin:telegram@claude-plugins-official \
       --dangerously-skip-permissions

意思:你出门 / 睡觉时,channel 收到消息 → Claude 完全自动反应,不弹权限对话框。

⚠️ 风险:Claude 可能跑 rm -rf、改 .git/、push 等都不弹确认。只在你信任 channel 来源 + 信任 Claude 自主权时用。

替代方案:启用 permission relay capability(channel 自己声明),把权限对话框 转发给 channel,你在 Telegram 上 approve/deny。

7. 5 个真实坑

坑	解
Bot 不回 pairing code	检查 --channels 是否在启动时传了;退出 Claude 重启
iMessage 第一次 authorization denied	macOS Privacy 设置加 Full Disk Access
Telegram bot 卡死	限速 — Telegram bot API 有 30 message/sec 限制,channel 服务器会自动 retry
Enterprise 用户看不到	channelsEnabled 没开,找 admin
启动时 marketplace plugin “not found”	/plugin marketplace update claude-plugins-official

8. 企业控制(2 个 managed setting)

// managed-settings.json
{
  "channelsEnabled": true,
  "allowedChannelPlugins": [
    { "marketplace": "claude-plugins-official", "plugin": "telegram" },
    { "marketplace": "claude-plugins-official", "plugin": "discord" },
    { "marketplace": "acme-corp-plugins", "plugin": "internal-alerts" }
  ]
}

• channelsEnabled: false → 整组织一切 channel 全关
• allowedChannelPlugins → 只允许列出的 plugin 注册为 channel
• 不设 allowedChannelPlugins → Anthropic 维护的默认 allowlist 生效

Pro/Max 个人用户完全跳过这两个检查。

9. 跟 4 个邻居功能的全景对比

工具	谁发起?	跑哪?	适合
Channels	外部 event push	本机活跃 session	持续监听 + 即时反应
Claude Code on the web	你点	Anthropic 云	一次性任务,不需本机
Slack 集成	@Claude mention	Anthropic 云(spawn web session)	团队聊天里
Remote Control	你从手机/网页驾驶	本机 CLI/VSCode	边活动边操控
普通 MCP server	Claude 主动查	本机	Claude 需要数据时调
Scheduled tasks	定时器	本机 / 桌面 / 云	周期性轮询

Channel 是唯一”外部 push 进活跃 session”的机制。

10. 自建 channel(高级)

如果官方 4 个不够,可以自建 — 见 /en/channels-reference。要点:

• 是个 MCP server(stdio / http)
• 声明 claude/channel capability
• 实现 reply tool 让 Claude 回话
• 可选实现 relay-permission-prompts capability
• --dangerously-load-development-channels 用于本地测试(不需要进 Anthropic 默认 allowlist)

适合场景:你公司内部 IM / 自家 webhook 接收器 / Telegram 之外的 messaging。

🟢 译者总评

1. Channel 是 “Claude 主动接外部世界” 的最后一块拼图

之前 Claude Code 接外部世界的方式:

• 你打字(被动)
• 你定时(/loop、cron)
• 你 @claude 在 GitHub / Slack
• Routines API 端点
• MCP server(Claude 主动查)

全部要么是”你触发”,要么是”Claude 主动拉”。Channel 终于实现了”外部主动推进 Claude session”。

2. 对独立开发者最值钱的用法:iMessage 自己

最便宜上手:

• 装 iMessage channel(macOS,免 bot 注册)
• 你出门时, terminal 不关
• 用手机给自己发 iMessage:“check the deploy”
• Claude 反应,把答案回 iMessage 给你看

= 把手机变成 Claude 的远程键盘。比 Remote Control + Claude 手机 app 还轻量(不用打开 app)。

3. 但要警觉的安全模型

Channel + --dangerously-skip-permissions 是组合杀招:外部一条消息,Claude 自己跑命令。如果 channel 被 hack(bot token 泄漏 / Discord 服务器有恶意用户),等于把 shell 暴露。

防护:

• ✅ allowlist policy(只允许你自己账号)
• ✅ 不用 --dangerously-skip-permissions,用 permission relay
• ✅ iMessage 比 Telegram / Discord 更安全(无 token 泄漏面)

4. 实操建议

如果你想体验,先按这个顺序:

1. fakechat — 0 风险体验流程(5 分钟)
2. iMessage — macOS 用户的最佳选择,自己跟自己聊
3. Telegram bot — 有团队 / 想发出去
4. 自建 channel — 等熟悉了再玩

🔗 延伸阅读

• 同系列:02-remote-control.md(RC vs channel 对比)、07-mcp-ecosystem.md(channel 本质是 MCP server)、06-hooks.md(配合 channel 做事件链)
• 官方:/en/channels-reference — 自建 channel 完整规范
• 官方 plugin 源代码:
  • https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins/telegram
  • https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins/discord
  • https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins/imessage

🔗 调研来源(可校验)

• 主原文:https://code.claude.com/docs/en/channels
• 本机已带 channel plugin:fakechat、telegram、discord、imessage(本机 marketplace catalog ~/.claude/plugins/marketplaces/claude-plugins-official/external_plugins/)
• 引入版本 v2.1.80+:文档明确
• enterprise control:channelsEnabled + allowedChannelPlugins 在 managed settings