Claude Code Channels 参考 — MCP 频道服务器开发手册 · 参考

本页目录17

AI 摘要 · 已核查整理于 2026-06-14原文:Channels reference(Anthropic)Claude CodeMCP频道开发Webhook

要点速览

在 `capabilities.experimental` 中声明 `claude/channel: {}` 是成为频道的唯一必要条件
通知方法名为 `notifications/claude/channel`，`meta` 字段键名只允许字母/数字/下划线，含连字符会被静默丢弃
双向频道须额外声明 `capabilities.tools: {}` 并注册 MCP 工具，供 Claude 调用以回复
权限审批中继须声明 `claude/channel/permission: {}` 能力，且 Claude Code 须 >= v2.1.81
开发测试期间须使用 `--dangerously-load-development-channels` 标志绕过白名单
发送者验证必须用 `message.from.id`（sender ID），不能只验证 `message.chat.id`（群组 ID），防止群内成员注入消息

本文是对官方参考页 Channels reference 的中文整理，完整与最新内容以原文为准。

概述

频道（Channel）是运行在 Claude Code 同机器上的 MCP 服务器，以 stdio 子进程方式通信，将外部系统事件推送到 Claude Code 会话。

聊天平台型（如 Telegram、Discord）：本地轮询平台 API，无需暴露公网 URL
Webhook 型（如 CI、监控）：本地监听 HTTP 端口，外部系统 POST 到该端口

版本要求：research preview 阶段，需要 Claude Code v2.1.80+；Team / Enterprise 组织须管理员显式开启。

最低要求

要求项	说明
运行时	Node.js、Bun、Deno 均可
依赖包	`@modelcontextprotocol/sdk`
传输方式	stdio（Claude Code 作为父进程启动服务器子进程）
开发测试标志	`--dangerously-load-development-channels`

服务器须完成三项：1) 声明 claude/channel 能力；2) 发出 notifications/claude/channel 通知；3) 使用 stdio transport 连接。

Server 构造函数选项

字段	类型	必填	说明
`capabilities.experimental['claude/channel']`	`object`	是	固定 `{}`；存在即注册通知监听器，使该服务器成为频道
`capabilities.experimental['claude/channel/permission']`	`object`	否	固定 `{}`；声明后 Claude Code 将工具审批提示转发给该频道；需 Claude Code v2.1.81+
`capabilities.tools`	`object`	双向必填	固定 `{}`；让 Claude 发现回复工具；单向频道省略
`instructions`	`string`	推荐	写入 Claude 系统提示；说明事件格式、`<channel>` 属性含义、是否回复及用哪个工具

通知事件格式

方法名：notifications/claude/channel

params 字段

字段	类型	说明
`content`	`string`	必填。事件消息体，成为 `<channel>` 标签正文
`meta`	`Record<string, string>`	可选。每个键值对成为 `<channel>` 标签属性（如 chat_id、severity）。键名限字母/数字/下划线；含连字符等字符的键静默丢弃

Claude 收到的格式示例（source 由 Claude Code 自动填入服务器配置名）：

<channel source="your-channel" severity="high" run_id="1234">
build failed on main
</channel>

投递行为

行为	说明
无确认机制	`await mcp.notification()` 在消息写入 transport 时 resolve，不等待 Claude 处理完毕
静默丢弃	会话未注册该频道或被组织策略阻止时，事件丢弃，服务器无报错
顺序排队	Claude 忙碌时多条通知排队，下一轮一起投递并作为一组处理

双向频道：回复工具

让 Claude 向外发送消息，需注册标准 MCP 工具。三个组成部分：

组成部分	说明
`capabilities.tools: {}`	在 `Server` 构造函数中声明，让 Claude Code 发现工具
`ListToolsRequestSchema` 处理器	返回工具列表及各工具的 `inputSchema`
`CallToolRequestSchema` 处理器	实现工具的实际发送逻辑

在 instructions 中说明何时调用工具、传入哪个属性（如 chat_id）。

发送者验证（防提示词注入）

未验证发送者的频道是提示词注入向量，必须在调用 mcp.notification() 之前校验发送者身份。

关键原则：验证 message.from.id（发送者 ID），不能只验证 message.chat.id（群组 ID）。群聊中二者不同，仅验证群组 ID 会允许群内任意成员注入消息。

权限审批中继

需要 Claude Code v2.1.81+；更早版本忽略 claude/channel/permission 能力声明。

当 Claude 需要工具审批时，本地终端对话框与远程频道同时收到提示，哪端先回复即采用，另一端关闭。

覆盖范围：Bash、Write、Edit 等工具的使用审批
不覆盖：项目信任对话框、MCP 服务器同意对话框（仅本地显示）

权限请求通知字段（Claude Code → 你的服务器）

方法名：notifications/claude/channel/permission_request

字段	说明
`request_id`	五位小写字母（字母表为 `a-z` 去掉 `l`，避免手机输入时与 `1`/`I` 混淆）。须原样包含在发出提示中供用户回复时输入。本地对话框不显示此 ID。
`tool_name`	工具名，如 `Bash`、`Write`
`description`	本次调用的人类可读摘要（与本地对话框文字相同）
`input_preview`	工具参数的 JSON 字符串，截断至 200 字符。是否展示由服务器决定。

权限裁决回传字段（你的服务器 → Claude Code）

方法名：notifications/claude/channel/permission

字段	取值	说明
`request_id`	字符串	与请求中的 `request_id` 完全一致（发送前转小写）
`behavior`	`'allow'` 或 `'deny'`	`allow` 放行工具调用；`deny` 拒绝（等同本地点 No）；均不影响后续调用

入站回复解析正则

/^\s*(y|yes|n|no)\s+([a-km-z]{5})\s*$/i

[a-km-z] 为 Claude Code 使用的 ID 字母表（小写，跳过 l）
/i 容忍手机自动大写；捕获到的 ID 须在发送前转小写

添加权限中继的三步

步骤	操作
1. 声明能力	在 `experimental` 下加 `'claude/channel/permission': {}`
2. 处理请求	注册 `notifications/claude/channel/permission_request` 通知处理器，格式化提示并转发给聊天平台
3. 拦截裁决	入站处理器中用正则匹配 `yes <id>` / `no <id>`；匹配则发 `notifications/claude/channel/permission`，不再转给 Claude

若远程回复格式不符（如无 ID 的 yes），正则不匹配，消息作为普通聊天转给 Claude；若格式正确但 ID 不对，Claude Code 静默丢弃，本地对话框保持开启。

开发测试标志

命令示例	说明
`claude --dangerously-load-development-channels server:webhook`	测试 `.mcp.json` 中的裸服务器
`claude --dangerously-load-development-channels plugin:yourplugin@yourmarketplace`	测试未在官方白名单中的插件

该标志仅绕过白名单；组织策略 channelsEnabled 仍有效
绕过是逐条目的，不延伸到 --channels 参数指定的条目
勿用于来源不可信的频道

MCP 注册配置（.mcp.json）

项目级文件 .mcp.json，用户级文件 ~/.claude.json（用户级须使用绝对路径）：

{
  "mcpServers": {
    "webhook": { "command": "bun", "args": ["./webhook.ts"] }
  }
}

Claude Code 启动时读取 MCP 配置，将服务器作为子进程启动，stdio 连接和 HTTP 监听均在同一进程中自动启动。

打包为插件

事项	说明
安装方式	包装为 plugin 发布到 marketplace，用户通过 `/plugin install` 安装；以 `--channels plugin:<name>@<marketplace>` 启用
白名单状态	发布到自己 marketplace 的频道仍需 `--dangerously-load-development-channels`（不在官方白名单）
Enterprise 白名单	管理员可将插件加入组织 `allowedChannelPlugins` 列表，替代默认 Anthropic 白名单
官方白名单	需联系 Anthropic 合作伙伴协调上官方白名单

概述