Channels 参考

用 MCP server 把 webhook/告警/聊天消息推入 Claude Code 会话的契约参考。

是什么

Channel 是一个运行在 Claude Code 同机上的 MCP server，Claude Code 把它作为子进程启动并通过 stdio 通信，作为外部系统与会话之间的桥梁。它把外部事件（CI、监控、聊天平台消息）推入会话让 Claude 响应。

可以是单向（仅转发告警/webhook）或双向（聊天桥，额外暴露 reply 工具发回消息）。具备可信发送方校验的双向 channel 还能选择性地中继权限审批提示，让你远程批准/拒绝工具调用。当前为 research preview，需 Claude Code v2.1.80 及以上；Team/Enterprise 组织须显式启用。

怎么工作

声明 claude/channel capability，Claude Code 据此注册通知监听器
通过 stdio transport 连接（Claude Code spawn 该 server 为子进程）
发生事件时发出 notifications/claude/channel，事件以 <channel source="..."> 标签注入 Claude 上下文
聊天平台型：插件本地轮询平台 API 拉取新消息再转发；webhook 型：本地 HTTP 端口监听外部 POST
双向 channel 额外声明 tools: {} 并注册 reply 工具，Claude 调用它发回消息
声明 claude/channel/permission 后，Claude Code 把工具审批提示并行转发到 channel，终端对话框与远程同时存在，先到的回答生效
通知不被确认（fire-and-forget）：await mcp.notification() 在写入 transport 时 resolve，未加载/被组织策略拦截则静默丢弃

怎么配置 / 用法

必填能力声明与通知发送：

const mcp = new Server(
  { name: 'webhook', version: '0.0.1' },
  {
    capabilities: {
      experimental: {
        'claude/channel': {},            // 必填，恒为 {}，注册监听器
        'claude/channel/permission': {}, // 可选，恒为 {}，开启权限中继
      },
      tools: {},                          // 仅双向需要，恒为 {}
    },
    instructions: 'Messages arrive as <channel source="webhook" ...>...',
  },
)
await mcp.connect(new StdioServerTransport())

推送事件：

await mcp.notification({
  method: 'notifications/claude/channel',
  params: {
    content: 'build failed on main',     // string，成为 <channel> 标签正文
    meta: { severity: 'high', run_id: '1234' }, // 每个键成为标签属性
  },
})

json

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

权限中继回传 verdict：

await mcp.notification({
  method: 'notifications/claude/channel/permission',
  params: { request_id: 'abcde', behavior: 'allow' }, // 或 'deny'
})

什么时候用

把 CI/监控/webhook 等外部事件转发给 Claude 处理（单向 channel）
搭建聊天桥（Telegram/Discord/iMessage 等），与 Claude 双向收发消息
希望在另一台设备（手机）上远程批准或拒绝 Bash/Write/Edit 等工具审批
需要让外部 HTTP POST（curl、流水线）触发会话中的 Claude 行为

限制 / 坑

research preview，要求 v2.1.80+；权限中继要求 v2.1.81+
自定义 channel 不在审批 allowlist 上，须用 --dangerously-load-development-channels 才能加载；该 flag 仅跳过 allowlist，channelsEnabled 组织策略仍生效
通知无投递确认，未加载或被策略拦截时静默丢弃；并发事件会在下一回合成组送达
meta 键只能是标识符（字母/数字/下划线），含连字符等会被静默丢弃；权限中继不覆盖项目信任与 MCP server consent 对话框

硬事实速查（12 条）

channel capability key：claude/channel（在 capabilities.experimental 下，恒 {}）
权限中继 capability：claude/channel/permission（恒 {}）；仅在已校验发送方时才声明
事件通知方法：notifications/claude/channel，params 为 content(string) + meta(Record<string,string>，可选)
事件注入格式：<channel source="<server name>" ...meta>content</channel>，source 由 server name 自动填充
权限请求方法：notifications/claude/channel/permission_request，params 四字段：request_id/tool_name/description/input_preview
request_id：5 个小写字母，取自 a-z 但跳过 l（避免与 1/I 混淆）；input_preview 截断到 200 字符
verdict 方法：notifications/claude/channel/permission，params：request_id + behavior('allow'|'deny')，不影响后续调用
唯一硬依赖：@modelcontextprotocol/sdk + Node 兼容运行时（Bun/Node/Deno 均可）；transport 用 stdio
单向 channel 省略 capabilities.tools；双向需 tools: {} 并注册 reply 工具
发送方门控用 message.from.id（发送者）而非 message.chat.id（房间），防群聊注入
开发测试 flag 按条目生效：claude --dangerously-load-development-channels server:webhook 或 plugin:name@marketplace
打包为 plugin 后用 /plugin install 安装，按会话用 --channels plugin:<name>@<marketplace> 启用；社区 marketplace 不在 channel allowlist

官方出处：https://code.claude.com/docs/en/channels-reference

Channels 参考 ​

是什么 ​

怎么工作 ​

怎么配置 / 用法 ​

什么时候用 ​

限制 / 坑 ​