Claude Code SDK #36：Channels 全解——--channels × Telegram/Discord/iMessage，把外部事件推进本地会话 (2026)

有一种 Claude Code 用法，容易被误解成「手机遥控终端」：你在 Telegram 里发一句「线上告警炸了，看一下」，Claude 就开始读日志、改代码、回你结果。

这里真正关键的不是手机，而是事件方向。Remote Control 是人去接管本地会话；Channels 是外部系统把事件推到已经打开的 Claude Code 会话里。官方把 Channel 定义为一个 MCP server：它把事件推入正在运行的 Claude Code session，Claude 也可以通过同一个 channel 回消息。这个功能仍处在 research preview，要求 Claude Code v2.1.80 或更高版本；它支持 claude.ai 或 Console API key 认证，但不支持 Bedrock、Vertex AI、Microsoft Foundry。1

今天拆 Channels。它适合的场景很明确：你的本地机器已经有项目、依赖、凭据和上下文，外部消息只负责把 Claude 叫醒。

01. Channels 不是新开一个 Agent，而是给现有会话接一根事件线

把 Claude Code 的几种「离开终端」能力放在一起看，Channels 的位置会清楚很多。

能力	事件到哪里	更适合什么任务
Remote Control	进入你正在操作的本地会话	人在手机或浏览器上继续控制本地工作
Routines	启动新的云端 Claude Code session	定时、API、GitHub 事件触发的无人值守任务
Channels	推进已经打开的本地会话	聊天消息、告警、CI/webhook 事件打进本地上下文

官方对 Routines 的定义是：保存一段 prompt、一个或多个仓库和一组 connectors，然后由 schedule、API 或 GitHub trigger 自动运行；它跑在 Anthropic-managed cloud infrastructure 上，所以电脑关了也能继续。2 Channels 则相反：事件只会在 session 开着的时候到达。如果想长期在线，你需要让 Claude 跑在后台进程或持久终端里。1

这两个差异决定了架构选择：

要处理「每天 9 点扫一遍 PR」这类固定任务，用 Routines。
要处理「Sentry 告警一来就让本地 Claude 看当前分支」这类事件，用 Channels。
要人在路上继续点按钮、看 diff、批准操作，用 Remote Control。

Channels 最有价值的地方，是它不丢本地上下文。你的 shell 环境、未提交代码、刚读过的文件、上一轮推理，都还在同一个 session 里。外部消息不是创建一个新任务，而是插入当前工作现场。

02. 最小启动链路：插件、凭据、`--channels`

官方 research preview 里内置了 Telegram、Discord、iMessage 三类 channel。每个都是插件，并且需要 Bun 运行。1

Telegram 的流程最典型：

/plugin install telegram@claude-plugins-official
/reload-plugins
/telegram:configure

配置时要填 BotFather 给你的 token。然后退出 Claude Code，用 channel flag 重新启动：

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

第一次使用时，先从 Telegram 给 bot 发一条消息。bot 会返回 pairing code，再回到 Claude Code 里执行配对命令，并把访问策略锁成 allowlist：

/telegram:access pair
/telegram:access policy allowlist

Discord 也遵循同一条主线：创建 bot、打开 Message Content Intent、邀请 bot 进服务器、安装插件、配置 token、用 --channels 重启、通过 DM 配对。iMessage 不需要 bot token，但它会读取本机 Messages 数据库并通过 AppleScript 发回复，所以只适合 macOS，而且需要给终端 Full Disk Access。1

如果你只想确认机制，不想先接真实平台，官方给了 fakechat demo：安装 fakechat@claude-plugins-official，用 claude --channels plugin:fakechat@claude-plugins-official 启动，然后打开本地 http://localhost:8787 发消息。消息会进入当前 Claude Code session，Claude 再通过 fakechat 的 reply tool 回到浏览器聊天界面。1

这个 demo 值得先跑一遍。它能帮你确认三件事：channel server 是否启动、事件是否能进入 session、Claude 是否能通过同一条 channel 回消息。

03. `--channels` 是一道显式闸门

Channels 的安全边界不是「装了插件就能推消息」。官方文档说得很直接：.mcp.json 里有 server 还不够，channel server 必须在启动时被 --channels 点名，消息才会进入 session。1

这层设计很重要。普通 MCP server 是 Claude 在任务中按需查询；Channel 是外部系统主动把事件推给 Claude。一个是拉，一个是推。推模式如果没有显式启用，很容易变成「任何接了 MCP 的东西都能打扰当前会话」。

所以生产用法里，我会把启动命令写得很保守：

claude \
  --channels plugin:telegram@claude-plugins-official \
  --append-system-prompt "Only respond to allowed operational messages. Ask before changing files unless the alert says auto-fix is approved."

上面的 system prompt 不是官方固定要求，只是一个实战护栏：先把「什么消息算任务」「什么时候能改文件」写清楚。Channels 解决的是入口问题，不替你设计权限策略。

04. 权限提示会改变「无人值守」体验

Channels 可以把你从终端前挪开，但不等于所有任务都会自动跑到底。官方提醒：如果 Claude 遇到 permission prompt，而你不在终端前，session 会暂停，直到你回应。声明了 permission relay capability 的 channel server 可以把这些提示转发给你，让你远程批准或拒绝。1

这句话决定了两种落地方式。

第一种是「人在回路里」。Telegram 或 Discord 收到告警后，Claude 先读日志、定位文件、提出 diff，真正写入或执行危险命令时再让你批。这适合生产仓库、值班排障、数据库迁移这类任务。

第二种是「受信环境里自动跑」。官方提到，unattended use 可以用 --dangerously-skip-permissions 跳过除 explicit ask rules 之外的提示，但只应该在你信任的环境里使用。1 这不是一个日常默认开关，更像是 CI worker、临时 sandbox、只读副本环境里的选择。

还有一个容易踩的点：非交互模式 -p 下，需要终端输入的工具会被禁用，比如多选问题和 plan mode approval。官方这样设计，是为了避免 session 卡在一个无人能回答的输入上。1

05. Allowlist 不是装饰，它决定谁能影响你的本地会话

官方批准的 channel plugin 都维护 sender allowlist。Telegram 和 Discord 通过 pairing code 把你的 sender ID 加进去；iMessage 默认只放行自己给自己的消息，其他联系人要手动加 handle。1

这里不要只把 allowlist 当成「防陌生人发消息」。如果 channel 支持 permission relay，那么能通过这个 channel 回复的人，也可能批准或拒绝当前 session 的 tool use。官方明确提醒：只把你信任拥有这项权限的人加入 allowlist。1

我的建议是按环境拆三档：

环境	推荐策略	原因
个人实验	只 allowlist 自己	先验证 event flow，不扩大权限面
团队值班	单独建值班 bot 和频道	不让私人聊天入口直接触达工程会话
生产自动化	使用专门账号、最小权限 token、隔离工作目录	让事件入口、代码权限、密钥范围能分别收紧

如果你的组织使用 Team 或 Enterprise，Channels 默认也不一定可用。claude.ai Team 和 Enterprise 需要 Owner 显式打开 Channels；Console API key 认证在未部署 managed settings 时默认允许，但组织可以通过 managed settings 控制开关和可用插件列表。1

06. 什么时候该自己写 Channel

官方文档把 Channels 放在 MCP server 的语境里，这说明它不只是聊天 bot。聊天只是最容易理解的入口。更工程化的用法，是把外部系统事件翻译成 Claude 能处理的消息。

可以从三个事件源开始：

CI 失败：pipeline 把失败 job、commit、日志摘要推给本地 session，让 Claude 在已经 checkout 的分支里排查。
错误告警：Sentry、Datadog、Prometheus 告警推入会话，Claude 结合当前代码和近期改动给出初步定位。
部署事件：部署完成后把版本号、环境、健康检查结果推给 Claude，让它跑一组本地或远程验证。

这些任务的共同点是：事件本身很短，但诊断依赖大量本地上下文。把它们丢给云端新 session，可能还要重新 clone、装依赖、补密钥；推给已经打开的本地 session，Claude 可以接着刚才的状态往下做。

反过来，如果任务本身不依赖本地状态，Channels 可能不是最省事的路。比如「每天凌晨扫所有仓库依赖」「PR 打开后自动跑安全 review」，Routines 或 GitHub Actions 更直接。Routines 支持 schedule、API、GitHub trigger，一个 routine 还可以组合多个触发器；GitHub trigger 支持 pull request 和 release 事件，并可按作者、标题、分支、label、draft/merged 状态等字段过滤。2

07. 今天就能落地的最小实验

如果你还没用过 Channels，不要一上来接生产告警。先跑一个 20 分钟实验：

安装 Bun，并确认 bun --version 能输出版本。
在 Claude Code 里安装 fakechat plugin。
用 claude --channels plugin:fakechat@claude-plugins-official 重启。
打开 fakechat 页面，发一句「列出当前目录里最近改过的 5 个文件，只读不要改」。
再发一句「基于这些文件，给我一个排查建议，不要执行命令」。

这个实验覆盖了 Channels 的核心链路：外部消息进入 session、Claude 利用本地上下文、结果再回到外部聊天界面。等这条链路稳定，再把 fakechat 换成 Telegram 或 Discord。

最后给一个实战判断：

你想「人在外面继续控制 Claude」：优先 Remote Control。
你想「没人在线也定时跑」：优先 Routines。
你想「外部事件打进当前本地工作现场」：这才是 Channels。

Channels 的价值，不是多了一个聊天入口，而是让 Claude Code 从「你主动输入 prompt」变成「工程事件也能触发会话继续往前走」。这一步做好之后，本地 Agent 才真正开始接近事件驱动的开发工作流。

Claude Code SDK #36：Channels 全解——--channels × Telegram/Discord/iMessage，把外部事件推进本地会话