{/* TRANSLATED — 已翻译为中文 */}

> ## 文档索引
> 在此获取完整文档索引：https://code.claude.com/docs/llms.txt
> 使用此文件发现所有可用页面，然后再进一步探索。

# 使用通道将事件推送到运行中的会话

> 使用通道从 MCP 服务器将消息、提醒和 webhook 推送到您的 Claude Code 会话。转发 CI 结果、聊天消息和监控事件，以便 Claude 可以在您离开时做出反应。

<Note>
  通道处于[研究预览](#research-preview)阶段，需要 Claude Code v2.1.80 或更高版本。它们需要通过 claude.ai 或 Console API 密钥进行 Anthropic 身份验证，在 Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry 上不可用。Team 和 Enterprise 组织必须[显式启用它们](#enterprise-controls)。
</Note>

通道是一个 MCP 服务器，它将事件推送到您正在运行的 Claude Code 会话中，以便 Claude 可以在您不在终端时对发生的事件做出反应。通道可以是双向的：Claude 读取事件并通过同一通道回复，就像聊天桥接器。事件仅在会话打开时到达，因此对于始终在线的设置，您需要在后台进程或持久终端中运行 Claude。

与生成新的云会话或等待轮询的集成不同，事件到达您已经打开的会话中：请参阅[通道比较](#how-channels-compare)。

您将通道作为插件安装并使用自己的凭据进行配置。Telegram、Discord 和 iMessage 包含在研究预览中。

当 Claude 通过通道回复时，您会在终端中看到入站消息，但看不到回复文本。终端显示工具调用和确认（如"sent"），实际回复出现在另一个平台上。

本页面涵盖：

* [支持的通道](#supported-channels)：Telegram、Discord 和 iMessage 设置
* [安装和运行通道](#quickstart)：使用 fakechat（本地主机演示）
* [谁可以推送消息](#security)：发送者允许列表和配对方式
* [为您的组织启用通道](#enterprise-controls)：如果您管理 Team、Enterprise 或 Console 组织
* [通道比较](#how-channels-compare)：与 Web 会话、Slack、MCP 和 Remote Control 的对比

要构建自己的通道，请参阅[通道参考](/en/channels-reference)。

## 支持的通道

每个支持的通道都是一个需要 [Bun](https://bun.sh) 的插件。在连接真实平台之前，要获得插件流程的实际操作演示，请尝试 [fakechat 快速入门](#quickstart)。

<Tabs>
  <Tab title="Telegram">
    查看完整的 [Telegram 插件源代码](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins/telegram)。

    <Steps>
      <Step title="创建 Telegram 机器人">
        在 Telegram 中打开 [BotFather](https://t.me/BotFather) 并发送 `/newbot`。给它一个显示名称和一个以 `bot` 结尾的唯一用户名。复制 BotFather 返回的令牌。
      </Step>

      <Step title="安装插件">
        在 Claude Code 中运行：

        ```
        /plugin install telegram@claude-plugins-official
        ```

        如果 Claude Code 报告在任何市场中都找不到该插件，则您的市场缺失或过时。运行 `/plugin marketplace update claude-plugins-official` 刷新它，或者如果您之前未添加过，运行 `/plugin marketplace add anthropics/claude-plugins-official`。然后重试安装。

        安装后，运行 `/reload-plugins` 以激活插件的配置命令。
      </Step>

      <Step title="配置您的令牌">
        使用来自 BotFather 的令牌运行配置命令：

        ```
        /telegram:configure <token>
        ```

        这会将其保存到 `~/.claude/channels/telegram/.env`。您也可以在启动 Claude Code 之前在 shell 环境中设置 `TELEGRAM_BOT_TOKEN`。
      </Step>

      <Step title="启用通道后重启">
        退出 Claude Code 并使用通道标志重新启动。这会启动 Telegram 插件，该插件开始轮询来自您机器人的消息：

        ```bash theme={null}
        claude --channels plugin:telegram@claude-plugins-official
        ```
      </Step>

      <Step title="配对您的帐户">
        打开 Telegram 并向您的机器人发送任何消息。机器人会回复一个配对代码。

        <Note>如果您的机器人没有响应，请确保 Claude Code 使用上一步中的 `--channels` 运行。机器人只能在通道处于活动状态时回复。</Note>

        返回 Claude Code，运行：

        ```
        /telegram:access pair <code>
        ```

        然后锁定访问权限，以便只有您的帐户可以发送消息：

        ```
        /telegram:access policy allowlist
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="Discord">
    查看完整的 [Discord 插件源代码](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins/discord)。

    <Steps>
      <Step title="创建 Discord 机器人">
        前往 [Discord Developer Portal](https://discord.com/developers/applications)，点击 **New Application**，并命名。在 **Bot** 部分，创建用户名，然后点击 **Reset Token** 并复制令牌。
      </Step>

      <Step title="启用 Message Content Intent">
        在机器人的设置中，滚动到 **Privileged Gateway Intents** 并启用 **Message Content Intent**。
      </Step>

      <Step title="邀请机器人到您的服务器">
        前往 **OAuth2 > URL Generator**。选择 `bot` 范围并启用以下权限：

        * View Channels
        * Send Messages
        * Send Messages in Threads
        * Read Message History
        * Attach Files
        * Add Reactions

        打开生成的 URL 以将机器人添加到您的服务器。
      </Step>

      <Step title="安装插件">
        在 Claude Code 中运行：

        ```
        /plugin install discord@claude-plugins-official
        ```

        如果 Claude Code 报告在任何市场中都找不到该插件，则您的市场缺失或过时。运行 `/plugin marketplace update claude-plugins-official` 刷新它，或者如果您之前未添加过，运行 `/plugin marketplace add anthropics/claude-plugins-official`。然后重试安装。

        安装后，运行 `/reload-plugins` 以激活插件的配置命令。
      </Step>

      <Step title="配置您的令牌">
        使用您复制的机器人令牌运行配置命令：

        ```
        /discord:configure <token>
        ```

        这会将其保存到 `~/.claude/channels/discord/.env`。您也可以在启动 Claude Code 之前在 shell 环境中设置 `DISCORD_BOT_TOKEN`。
      </Step>

      <Step title="启用通道后重启">
        退出 Claude Code 并使用通道标志重新启动。这会连接 Discord 插件，以便您的机器人可以接收和响应消息：

        ```bash theme={null}
        claude --channels plugin:discord@claude-plugins-official
        ```
      </Step>

      <Step title="配对您的帐户">
        在 Discord 上给您的机器人发私信。机器人会回复一个配对代码。

        <Note>如果您的机器人没有响应，请确保 Claude Code 使用上一步中的 `--channels` 运行。机器人只能在通道处于活动状态时回复。</Note>

        返回 Claude Code，运行：

        ```
        /discord:access pair <code>
        ```

        然后锁定访问权限，以便只有您的帐户可以发送消息：

        ```
        /discord:access policy allowlist
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="iMessage">
    查看完整的 [iMessage 插件源代码](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins/imessage)。

    iMessage 通道直接读取您的 Messages 数据库，并通过 AppleScript 发送回复。它需要 macOS，不需要机器人令牌或外部服务。

    <Steps>
      <Step title="授予完全磁盘访问权限">
        位于 `~/Library/Messages/chat.db` 的 Messages 数据库受 macOS 保护。服务器首次读取时，macOS 会提示访问权限：点击 **Allow**。提示会显示启动 Bun 的应用程序名称，如 Terminal、iTerm 或您的 IDE。

        如果提示未出现或您点击了 Don't Allow，请在 **System Settings > Privacy & Security > Full Disk Access** 下手动授予权限并添加您的终端。没有此权限，服务器会立即以 `authorization denied` 退出。
      </Step>

      <Step title="安装插件">
        在 Claude Code 中运行：

        ```
        /plugin install imessage@claude-plugins-official
        ```

        如果 Claude Code 报告在任何市场中都找不到该插件，则您的市场缺失或过时。运行 `/plugin marketplace update claude-plugins-official` 刷新它，或者如果您之前未添加过，运行 `/plugin marketplace add anthropics/claude-plugins-official`。然后重试安装。
      </Step>

      <Step title="启用通道后重启">
        退出 Claude Code 并使用通道标志重新启动：

        ```bash theme={null}
        claude --channels plugin:imessage@claude-plugins-official
        ```
      </Step>

      <Step title="给自己发短信">
        在登录了您的 Apple ID 的任何设备上打开 Messages，给自己发送一条消息。它会立即到达 Claude：自助聊天无需设置即可绕过访问控制。

        <Note>Claude 发送的第一条回复会触发 macOS 自动化提示，询问您的终端是否可以控制 Messages。点击 **OK**。</Note>
      </Step>

      <Step title="允许其他发送者">
        默认情况下，只有您自己的消息会通过。要让其他联系人联系 Claude，请添加他们的句柄：

        ```
        /imessage:access allow +15551234567
        ```

        句柄是 `+country` 格式的电话号码或 Apple ID 电子邮件，如 `user@example.com`。
      </Step>
    </Steps>
  </Tab>
</Tabs>

您也可以[构建自己的通道](/en/channels-reference)，用于尚无插件的系统。

## 快速入门

Fakechat 是一个官方支持的演示通道，它在本地主机上运行聊天 UI，无需身份验证，也无需配置外部服务。

安装并启用 fakechat 后，您可以在浏览器中输入消息，消息会到达您的 Claude Code 会话。Claude 回复后，回复会显示回浏览器中。测试完 fakechat 界面后，尝试 [Telegram](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins/telegram)、[Discord](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins/discord) 或 [iMessage](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins/imessage)。

要尝试 fakechat 演示，您需要：

* Claude Code [已安装并已身份验证](/en/quickstart#step-1-install-claude-code)，使用 claude.ai 帐户或 Claude Console API 密钥
* 已安装 [Bun](https://bun.sh)。预构建的通道插件是 Bun 脚本。使用 `bun --version` 检查；如果失败，[安装 Bun](https://bun.sh/docs/installation)。
* **Team、Enterprise 或托管 Console 组织**：您的管理员必须在托管设置中[启用通道](#enterprise-controls)

<Steps>
  <Step title="安装 fakechat 通道插件">
    启动 Claude Code 会话并运行安装命令：

    ```text theme={null}
    /plugin install fakechat@claude-plugins-official
    ```

    如果 Claude Code 报告在任何市场中都找不到该插件，则您的市场缺失或过时。运行 `/plugin marketplace update claude-plugins-official` 刷新它，或者如果您之前未添加过，运行 `/plugin marketplace add anthropics/claude-plugins-official`。然后重试安装。
  </Step>

  <Step title="启用通道后重启">
    退出 Claude Code，然后使用 `--channels` 重新启动并传递您安装的 fakechat 插件：

    ```bash theme={null}
    claude --channels plugin:fakechat@claude-plugins-official
    ```

    fakechat 服务器自动启动。

    <Tip>
      您可以向 `--channels` 传递多个插件，用空格分隔。
    </Tip>
  </Step>

  <Step title="推送消息">
    在 [http://localhost:8787](http://localhost:8787) 打开 fakechat UI 并输入消息：

    ```text theme={null}
    hey, what's in my working directory?
    ```

    消息作为 `<channel source="fakechat">` 事件到达您的 Claude Code 会话。Claude 读取它，执行工作，并调用 fakechat 的 `reply` 工具。答案显示在聊天 UI 中。
  </Step>
</Steps>

如果 Claude 在您离开终端时遇到权限提示，会话会暂停直到您响应。声明[权限中继功能](/en/channels-reference#relay-permission-prompts)的通道服务器可以将这些提示转发给您，以便您可以远程批准或拒绝。对于无人值守使用，[`--dangerously-skip-permissions`](/en/permission-modes#skip-all-checks-with-bypasspermissions-mode) 完全绕过提示，但仅在您信任的环境中使用它。

当您使用 `-p` 在非交互模式下运行通道时，需要终端输入的工具（如多选题和计划模式审批）会被禁用，因此会话永远不会因等待输入而停滞。

## 安全

每个已批准的通道插件维护一个发送者允许列表：只有您添加的 ID 可以推送消息，其他人会被静默丢弃。

Telegram 和 Discord 通过配对来引导列表：

1. 在 Telegram 或 Discord 中找到您的机器人并发送任何消息
2. 机器人回复一个配对代码
3. 在您的 Claude Code 会话中，收到提示时批准该代码
4. 您的发送者 ID 被添加到允许列表

iMessage 的工作方式不同：给自己发短信会自动绕过门控，您可以使用 `/imessage:access allow` 按句柄添加其他联系人。

除此之外，您使用 `--channels` 控制每个会话启用哪些服务器，您的组织在 claude.ai Team 和 Enterprise 计划以及部署托管设置的 Console 组织上使用 [`channelsEnabled`](#enterprise-controls) 控制可用性。

仅在 `.mcp.json` 中不足以推送消息：服务器还必须在 `--channels` 中被命名。

允许列表还控制[权限中继](/en/channels-reference#relay-permission-prompts)（如果通道声明了它）。任何可以通过通道回复的人都可以批准或拒绝您会话中的工具使用，因此只允许您信任的发送者拥有该权限。

## 企业控制

管理员通过两个用户无法覆盖的[托管设置](/en/settings)控制可用性。默认值取决于您的身份验证方式：

* **claude.ai Team 和 Enterprise**：通道被阻止，直到管理员启用它们。
* **使用 API 密钥身份验证的 Anthropic Console**：通道默认被允许。仅当您的组织部署托管设置时才需要此设置。

在所有情况下，在用户使用 `--channels` 选择加入之前，没有通道会运行。

| 设置                 | 用途                                                                                                                                                                                                                                                     | 未配置时                                                                                                                                                                    |
| :---------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `channelsEnabled`       | 主开关。必须为 `true` 才能让任何通道传递消息。通过 [claude.ai Admin console](https://claude.ai/admin-settings/claude-code) 开关或直接在托管设置中设置。关闭时阻止所有通道，包括开发标志。 | claude.ai Team 和 Enterprise：通道被阻止。Console：通道被允许，除非您的组织部署了托管设置，在这种情况下通道被阻止直到设置此键 |
| `allowedChannelPlugins` | 启用通道后哪些插件可以注册。设置后替换 Anthropic 维护的列表。仅在 `channelsEnabled` 为 `true` 时适用。                                                                                                       | 应用 Anthropic 默认列表                                                                                                                                                         |

没有组织的 Pro 和 Max 用户完全跳过这些检查：通道可用，用户使用 `--channels` 按会话选择加入。

### 为您的组织启用通道

管理员可以从 [**claude.ai → Admin settings → Claude Code → Channels**](https://claude.ai/admin-settings/claude-code) 启用通道，或在托管设置中将 `channelsEnabled` 设置为 `true`。

启用后，您组织中的用户可以使用 `--channels` 将通道服务器选择加入到各个会话。如果设置被禁用或未设置，MCP 服务器仍然连接并且其工具可以工作，但通道消息不会到达。启动警告会告诉用户让管理员启用该设置。

### 限制哪些通道插件可以运行

默认情况下，Anthropic 维护的允许列表上的任何插件都可以注册为通道。Team 和 Enterprise 计划上的管理员可以通过在托管设置中设置 `allowedChannelPlugins` 来用他们自己的允许列表替换该列表。使用此功能限制允许哪些官方插件、批准您自己内部市场中的通道，或两者兼而有之。每个条目指定一个插件及其来源市场：

```json theme={null}
{
  "channelsEnabled": true,
  "allowedChannelPlugins": [
    { "marketplace": "claude-plugins-official", "plugin": "telegram" },
    { "marketplace": "claude-plugins-official", "plugin": "discord" },
    { "marketplace": "acme-corp-plugins", "plugin": "internal-alerts" }
  ]
}
```

设置 `allowedChannelPlugins` 后，它会完全替换 Anthropic 允许列表：只有列出的插件可以注册。保持未设置以回退到默认的 Anthropic 允许列表。空数组阻止来自允许列表的所有通道插件，但 `--dangerously-load-development-channels` 仍然可以为本地测试绕过它。要完全阻止通道（包括开发标志），请改为保持 `channelsEnabled` 未设置。

此设置需要 `channelsEnabled: true`。如果用户传递给 `--channels` 的插件不在您的列表中，Claude Code 正常启动但通道不会注册，启动通知会解释该插件不在组织的批准列表中。

## 研究预览

通道是研究预览功能。可用性正在逐步推出，`--channels` 标志语法和协议约定可能会根据反馈而更改。

在预览期间，`--channels` 仅接受来自 Anthropic 维护的允许列表的插件，或（如果管理员设置了 [`allowedChannelPlugins`](#restrict-which-channel-plugins-can-run)）来自您的组织允许列表的插件。[claude-plugins-official](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins) 中的通道插件是默认批准的集合。如果您传递不在有效允许列表上的内容，Claude Code 正常启动但通道不会注册，启动通知会告诉您原因。

要测试您正在构建的通道，请使用 `--dangerously-load-development-channels`。有关测试您构建的自定义通道的信息，请参阅[在研究预览期间测试](/en/channels-reference#test-during-the-research-preview)。

在 [Claude Code GitHub 仓库](https://github.com/anthropics/claude-code/issues)上报告问题或反馈。

## 通道比较

几个 Claude Code 功能连接到终端外部的系统，每个功能适合不同类型的工作：

| 功能                                              | 功能                                                          | 适合                                                  |
| ---------------------------------------------------- | --------------------------------------------------------------------- | --------------------------------------------------------- |
| [Web 上的 Claude Code](/en/claude-code-on-the-web) | 在新的云沙箱中运行任务，从 GitHub 克隆               | 委派独立的异步工作，稍后查看   |
| [Slack 中的 Claude](/en/slack)                         | 在频道或线程中从 `@Claude` 提及生成 Web 会话 | 直接从团队对话上下文中启动任务    |
| 标准 [MCP 服务器](/en/mcp)                       | Claude 在任务期间查询它；没有内容被推送到会话     | 让 Claude 按需访问以读取或查询系统  |
| [Remote Control](/en/remote-control)                 | 您从 claude.ai 或 Claude 移动应用驱动本地会话  | 在离开办公桌时引导正在进行的会话 |

通道通过将来自非 Claude 源的事件推送到您已运行的本地会话来填补该列表中的空白。

* **聊天桥接器**：通过 Telegram、Discord 或 iMessage 从手机向 Claude 提问，答案会在同一聊天中返回，同时工作在您的机器上针对您的真实文件运行。
* **[Webhook 接收器](/en/channels-reference#example-build-a-webhook-receiver)**：来自 CI、错误跟踪器、部署管道或其他外部服务的 webhook 到达 Claude 已经打开文件并记住您正在调试的内容的位置。

## 后续步骤

一旦您有一个通道在运行，请探索以下相关功能：

* [构建自己的通道](/en/channels-reference)：用于尚无插件的系统
* [Remote Control](/en/remote-control)：从手机驱动本地会话，而不是将事件转发到其中
* [定时任务](/en/scheduled-tasks)：按计时器轮询而不是对推送事件做出反应