Claude Code Channel 系统文档
通过 IM 平台远程控制 Claude Code Agent 的完整技术解析
文档目录
01-channel-system.md — Channel 系统架构解析
从源码视角深度剖析 Claude Code Channel 系统的设计与实现，涵盖：
- 什么是 Channel：IM 集成的核心概念、MCP 协议基础
- 整体架构：消息流转全链路、组件关系
- 消息协议：入站通知、XML 封装、出站工具调用
- 六层访问控制：能力声明 → 运行时开关 → OAuth 认证 → 组织策略 → 会话白名单 → 插件审批
- 权限中继系统：远程审批工具执行、5 字母请求 ID、多源竞争
- 插件架构：Channel 插件清单声明、用户配置流、作用域命名
- UI 组件：终端消息渲染、状态通知、开发者警告对话框
- 安全设计：防 XML 注入、marketplace 验证、信任边界分析
适合人群：想了解 AI Agent IM 集成架构的开发者、架构师、插件作者
配图说明
所有配图采用深色背景（#1a1a2e）+ Anthropic 品牌橙铜色（#D97757）风格。
| 图片 | 说明 | 所属文档 |
|---|---|---|
01-channel-overview.png | Channel 系统架构总览 — 组件关系全景 | 架构解析 |
02-message-flow.png | 消息流转全链路 — IM → Agent → IM | 架构解析 |
03-access-control.png | 六层访问控制 — 层层递进的安全门 | 架构解析 |
04-permission-relay.png | 权限中继系统 — 远程审批流程 | 架构解析 |
快速开始
用户
- 阅读 Channel 系统架构解析
- 了解如何通过
--channels启动 IM 集成 - 理解不同平台（Telegram、Feishu、Discord）的接入方式
插件开发者
- 阅读架构解析中的 插件架构 章节
- 了解
plugin.json中 Channel 声明格式 - 实现 MCP Server 的
notifications/claude/channel协议 - 查看源码位置：
src/services/mcp/channelNotification.ts— 核心门控与消息封装src/services/mcp/channelPermissions.ts— 权限中继系统src/services/mcp/channelAllowlist.ts— 白名单管理src/utils/plugins/mcpPluginIntegration.ts— 插件 MCP 集成src/utils/plugins/schemas.ts— 插件清单 Channel 声明 Schema
核心概念速查
| 概念 | 说明 |
|---|---|
| Channel | 一个声明了 claude/channel 能力的 MCP Server，可推送 IM 消息到 Agent |
| Channel Entry | --channels 参数解析后的条目，分 plugin 和 server 两种 |
| Channel Gate | 六层访问控制门，决定是否注册通知处理器 |
| Permission Relay | 将工具执行审批提示转发到 IM 平台的机制 |
| Channel Plugin | 在 plugin.json 中声明 channels 字段的插件 |
| Scoped Name | 插件服务器的作用域名称，格式 plugin:{pluginName}:{serverName} |
| Short Request ID | 5 字母权限请求标识符，基于 FNV-1a 哈希生成 |
| Channel Tag | <channel> XML 标签，封装来自 IM 的消息内容和元数据 |
| Dev Channels | 通过 --dangerously-load-development-channels 加载的本地开发频道 |
| tengu_harbor | GrowthBook 运行时特性开关，控制 Channel 功能总开关 |