# Channels：将外部事件推送到会话中 [Beta]

> **Beta 功能**：Channels 目前处于 Beta 阶段，功能和接口可能会根据反馈进行调整。

Channel 是一种 MCP 服务器，可以将消息、告警和 Webhook 推送到你正在运行的 CodeBuddy Code 会话中，让 CodeBuddy Code 在你不在终端时也能对外部事件做出反应。

Channel 可以是双向的：CodeBuddy Code 读取事件后通过同一 channel 回复，就像一个聊天桥。事件仅在会话打开时到达，如需持续运行，可以在后台进程或持久终端中运行 CodeBuddy Code。

你可以通过安装插件或使用内置 channel 来启用。微信、Telegram、Discord 以及 fakechat 演示都已支持。

当 CodeBuddy Code 通过 channel 回复时，终端会显示工具调用和确认（如"sent"），实际回复内容出现在对应的聊天平台上。

本页涵盖：

* [支持的 Channel](#支持的-channel)：微信、Telegram、Discord 以及 fakechat 设置
* [快速开始](#快速开始)：使用微信 channel 快速体验
* [安全机制](#安全机制)：发送者白名单和配对流程
* [组织管控](#组织管控)：为团队和企业启用 channel
* [Channel 与其他功能的对比](#功能对比)

要构建自己的 channel，请参阅 [Channels 参考](./channels-reference.md)。

## 支持的 Channel

### 微信（内置）

微信 channel 是 CodeBuddy Code 内置的，无需安装插件。通过微信 ClawBot 实现双向消息通信，支持文本、图片和文件收发。

**前提条件**：
- 微信版本 iOS 8.0.70 及以上
- 在微信中启用 ClawBot 插件（微信 → 我 → 设置 → 插件 → ClawBot）

**扫码绑定**：

1. 在 CodeBuddy Code 中执行 `/remote-control wechat` 或 `/remote-control` 选择 wechat
2. 终端显示二维码（如果二维码显示异常，会提供浏览器链接）
3. 用微信扫描二维码并确认
4. 绑定成功后自动开始接收消息

**使用**：

绑定后，在微信 ClawBot 对话中发送消息，消息会自动出现在 CodeBuddy Code 会话中：

```
#wechat · user_id: 你好，帮我看一下这个 bug
```

CodeBuddy Code 会处理消息并通过 `WechatReply` 工具回复，回复内容出现在微信中。

支持的消息类型：

| 类型 | 接收 | 发送 |
|------|------|------|
| 文本 | 支持 | 支持 |
| 图片 | 支持（自动下载解密到本地） | 支持（自动加密上传到 CDN） |
| 文件 | 支持 | 支持 |

**凭证管理**：

扫码成功后凭证保存在 `~/.codebuddy/channels/wechat/credentials.json`。下次启动时自动使用已保存的凭证，无需重新扫码。

```bash
# 查看连接状态
/remote-control wechat status

# 断开连接
/remote-control wechat stop

# 重新连接（使用已保存凭证）
/remote-control wechat start
```

### Telegram

需要安装插件。查看完整 [Telegram 插件源码](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins/telegram)。

1. 在 Telegram 中通过 [BotFather](https://t.me/BotFather) 创建一个 bot，获取 token
2. 安装插件：`/plugin install telegram@claude-plugins-official`
3. 配置 token：`/telegram:configure <token>`
4. 启动：`codebuddy --channels plugin:telegram@claude-plugins-official`
5. 向 bot 发消息获取配对码，执行 `/telegram:access pair <code>` 完成配对

### Discord

需要安装插件。查看完整 [Discord 插件源码](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins/discord)。

1. 在 [Discord 开发者门户](https://discord.com/developers/applications) 创建应用和 bot
2. 启用 Message Content Intent，邀请 bot 到服务器
3. 安装插件：`/plugin install discord@claude-plugins-official`
4. 配置 token：`/discord:configure <token>`
5. 启动：`codebuddy --channels plugin:discord@claude-plugins-official`
6. DM bot 获取配对码，执行 `/discord:access pair <code>` 完成配对

### fakechat（演示）

fakechat 是官方支持的演示 channel，在 localhost 上运行一个聊天 UI，无需认证和外部服务。

```bash
# 安装
/plugin install fakechat@claude-plugins-official

# 启动
codebuddy --channels plugin:fakechat@claude-plugins-official
```

打开 `http://localhost:8787` 即可开始聊天。

## 快速开始

以微信 channel 为例，快速体验完整的双向通信流程：

**第 1 步：确保 ClawBot 已启用**

在微信中打开 **我 → 设置 → 插件**，找到 ClawBot 并启用。

**第 2 步：扫码绑定**

启动 CodeBuddy Code，执行：

```
/remote-control wechat
```

终端显示二维码。用微信扫描并确认绑定。

**第 3 步：发送消息**

在微信 ClawBot 对话中发送：

```
帮我看一下当前目录有什么文件
```

消息到达 CodeBuddy Code 会话，显示为：

```
#wechat · user_id: 帮我看一下当前目录有什么文件
```

CodeBuddy Code 执行任务后通过 `WechatReply` 工具回复，回复内容出现在微信中。

**第 4 步：发送图片**

在微信中发一张截图给 ClawBot，CodeBuddy Code 会自动下载并识别图片内容。你可以要求它编辑图片并发回：

```
给图片中的人物加一顶帽子
```

CodeBuddy Code 使用 ImageEdit 工具处理图片，然后通过 `WechatReply` 将编辑后的图片发送回微信。

## 安全机制

### 微信

微信 channel 通过 ClawBot 的扫码认证机制保证安全。只有扫码绑定的微信账号可以发送消息，其他人的消息会被静默丢弃。

凭证（包含 bot_token 和 account_id）保存在本地，权限设为 600（仅所有者可读写）。

### 插件 Channel

Telegram 和 Discord 等插件 channel 维护一个发送者白名单。通过配对流程添加信任的发送者：

1. 向 bot 发送任意消息
2. bot 回复配对码
3. 在 CodeBuddy Code 中确认配对码
4. 发送者 ID 加入白名单

白名单同时控制[权限中继](./channels-reference.md#权限中继)。通过 channel 回复的人可以审批或拒绝工具调用，因此只将信任的发送者加入白名单。

### 其他安全要素

- 仅在 `.mcp.json` 中配置不足以推送消息，还必须在 `--channels` 中指定
- 组织可以通过 `channelsEnabled` 设置统一管控

## 组织管控

Channel 功能受 `channelsEnabled` 设置控制：

| 计划类型 | 默认行为 |
|---------|---------|
| 个人用户 | 可用；用户通过 `--channels` 按会话启用 |
| 团队/企业 | 默认禁用，管理员需显式启用 |

### 为组织启用 Channel

管理员可以在 `settings.json` 中设置：

```json
{
  "channelsEnabled": true
}
```

启用后，组织中的用户可以使用 `--channels` 将 channel 服务器接入各自的会话。如果设置被禁用，MCP 服务器仍然连接且工具可用，但 channel 消息不会到达。

## 功能对比

CodeBuddy Code 有多种连接外部系统的功能，各有适用场景：

| 功能 | 作用 | 适用场景 |
|------|------|---------|
| 标准 MCP 服务器 | CodeBuddy Code 在任务中查询它；不推送到会话 | 按需读取或查询系统 |
| Remote Control | 从远程控制本地会话 | 离开桌面时操控进行中的会话 |
| **Channel** | **将外部事件推送到已运行的本地会话** | **聊天桥、Webhook 接收、告警响应** |

Channel 通过将非 CodeBuddy Code 来源的事件推送到已运行的本地会话来填补空白：

* **聊天桥**：通过微信向 CodeBuddy Code 提问，回答出现在微信中，而实际工作在你的机器上运行，使用你的真实文件
* **Webhook 接收器**：CI、错误追踪器或部署管线的 Webhook 到达时，CodeBuddy Code 已经打开了你的文件并记住你在调试什么

## 下一步

* [构建自己的 Channel](./channels-reference.md)：为还没有插件的系统创建 channel
* 使用 `/remote-control` 管理所有远程控制连接
