第7章渠道接入全攻略

一句话：渠道是 Agent 的”嘴巴和耳朵”——每个渠道都有自己的申请流程、配置方式和注意事项，本章逐一讲解。

7.1 Telegram（核心渠道，最快上手）

Telegram 是 OpenClaw 用户最常用的渠道，基于 grammY 框架实现。支持 Bot 模式、群组、Forum Topic。

申请凭证

打开 Telegram，搜索 @BotFather
发送 /newbot，按提示创建 Bot
获取 Bot Token（格式：123456789:ABCdef...）

可选设置（在 @BotFather 中）：

/setdescription — 设置 Bot 描述
/setuserpic — 设置 Bot 头像
/setcommands — 注册命令菜单

配置

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123456789:ABCdefGHIjklMNOpqrsTUVwxyz",

      // DM 策略
      dmPolicy: "pairing",    // pairing | allowlist | open | disabled
      allowFrom: ["8734062810"],  // Telegram user ID 白名单

      // 群组设置
      // 群组设置
      groupPolicy: "allowlist",   // 群组策略（channel 顶层字段）
      groups: {
        "-1001234567890": {       // 群组 ID（负数）
          requireMention: true,   // 是否需要 @bot 才响应
        },
        "*": { requireMention: true },  // 所有群组默认需要 @
      },

      // 流式回复
      streaming: "partial",   // off | partial | block | progress

      // 国内用户需要代理
      proxy: "socks5://127.0.0.1:1080",
      // 支持 socks5:// 和 http://，支持带认证：
      // proxy: "socks5://user:password@127.0.0.1:1080",
    },
  },
}

DM 策略

模式	说明
`"pairing"`	新用户需要配对审批（默认）
`"allowlist"`	只有 `allowFrom` 中的用户可以对话
`"open"`	任何人都可以对话
`"disabled"`	禁止私聊

配对审批流程：

openclaw pairing list telegram        # 查看待审批列表
openclaw pairing approve telegram <CODE>  # 审批（配对码 1 小时过期）

群组使用

Bot 加入群组后，默认只响应 @bot_username 提及或 / 命令。要让它响应所有消息：

方法一：在 @BotFather 中关闭 Privacy Mode

给 @BotFather 发送 /mybots
选择你的 Bot → Bot Settings → Group Privacy → Turn off

方法二：在配置中设置 requireMention: false

{
  channels: {
    telegram: {
      // ...
      groups: {
        "-1001234567890": { requireMention: false },  // 此群不需要 @
      },
    },
  },
}

Forum Topic 支持

Telegram 群组开启 Forum（话题）模式后，每个 Topic 可以有独立的对话上下文。OpenClaw 自动识别 Topic ID 进行会话隔离。还可以为不同 Topic 路由到不同 Agent：

{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          topics: {
            "1": { agentId: "main" },
            "42": { agentId: "code-review" },
          },
        },
      },
    },
  },
}

踩坑提示

Bot Token 泄露后立即在 @BotFather 中 /revoke 重新生成
国内必须配置代理，否则无法连接 Telegram API
如果 Bot 在群里不响应，检查 Privacy Mode 是否已关闭，并确认 groups 配置
修改配置后需要 openclaw gateway restart
Telegram 不支持 Markdown 表格，Agent 会自动转为列表格式

7.2 微信（官方插件，两步搞定）

2026 年 3 月 22 日，微信官方推出了微信 ClawBot 插件，原生接入 OpenClaw——个人微信直接用，不需要企业微信，不需要第三方协议，不存在风控问题。

要求：微信 8.0.70+、OpenClaw 2026.3.22+。目前灰度放量中。

安装

npx -y @tencent-weixin/openclaw-weixin-cli@latest install

配置

{
  channels: {
    wechat: {
      enabled: true,
    },
  },
}

备选方案：社区插件（历史方案）

在官方插件推出之前，社区通过 @icesword760/openclaw-wechat（iPad 协议）实现微信接入。如果你的微信版本低于 8.0.70 或尚未收到灰度，仍可使用：

openclaw plugins install @icesword760/openclaw-wechat

注意：社区插件基于 iPad 协议，存在封号风险。建议优先使用官方插件。

7.3 Discord（Bot + Gateway）

Discord 渠道基于 @buape/carbon 库实现（语音功能使用 @discordjs/voice），功能丰富：支持线程、频道、语音频道、交互组件（按钮、下拉菜单等）。

申请凭证

打开 https://discord.com/developers/applications
点击 “New Application” 创建应用
左侧 Bot 页面 → “Add Bot” → 复制 Token
左侧 OAuth2 → URL Generator → 勾选 bot + applications.commands
Bot Permissions 勾选：View Channels、Send Messages、Read Message History、Embed Links、Attach Files、Add Reactions（可选）
复制生成的 URL，在浏览器打开，邀请 Bot 到你的服务器

重要：开启 Privileged Intents

在 Developer Portal 的 Bot 页面，必须开启：

Message Content Intent（必须，否则收不到消息内容）
Server Members Intent（推荐，用于角色路由）
Presence Intent（可选）

配置

{
  channels: {
    discord: {
      enabled: true,
      token: "your-discord-bot-token",
      dmPolicy: "pairing",
      groupPolicy: "allowlist",

      // 服务器配置
      guilds: {
        "SERVER_ID": {
          requireMention: false,
          channels: {
            "CHANNEL_ID_1": { allow: true, requireMention: false },
            "CHANNEL_ID_2": { allow: true, requireMention: true },
          },
          users: ["USER_ID_1"],  // 用户白名单
        },
      },

      // 流式回复
      streaming: "partial",

      // 语音频道（可选）
      voice: {
        enabled: true,
        autoJoin: [
          { guildId: "SERVER_ID", channelId: "VOICE_CHANNEL_ID" },
        ],
      },

      // Bot 状态（可选，直接在 discord 下配置）
      status: "online",               // online | idle | dnd
      activity: "Helping humans",     // 活动文本（字符串）
      activityType: 0,                // 0=Playing 1=Streaming 2=Listening 3=Watching 4=Custom
    },
  },
}

获取 ID：在 Discord 设置中开启”开发者模式”，然后右键点击服务器/频道/用户可以复制 ID。

线程与频道

每个频道有独立的 Session 上下文
Bot 可以在频道中创建线程回复
Forum 频道的每个帖子也被视为独立上下文

交互组件（Discord 独有）

Agent 可以发送带按钮和下拉菜单的消息：

// Agent 可以发送这样的交互消息
{
  components: {
    blocks: [{
      type: "actions",
      buttons: [
        { label: "批准", style: "success" },
        { label: "拒绝", style: "danger" },
      ],
    }],
  },
}

基于角色的 Agent 路由

不同角色的用户可以路由到不同 Agent：

{
  bindings: [
    {
      agentId: "premium-agent",
      match: { channel: "discord", guildId: "SERVER_ID", roles: ["PRO_ROLE_ID"] },
    },
    {
      agentId: "basic-agent",
      match: { channel: "discord", guildId: "SERVER_ID" },
    },
  ],
}

国内网络

Discord 在国内需要代理。和 Telegram 一样在渠道配置中添加 proxy 字段。

踩坑提示

“Used disallowed intents” → 必须在 Developer Portal 开启 Message Content Intent
Bot 在群里没反应 → 检查 guilds 配置和频道白名单
DM 不工作 → 检查 dmPolicy 和 Discord 的 DM 隐私设置

7.4 WhatsApp（Baileys Web 协议扫码）

WhatsApp 渠道基于 Baileys 库实现，使用 WhatsApp Web 协议——不是 Business API，是通过模拟 Web 客户端扫码登录。

配置

{
  channels: {
    whatsapp: {
      enabled: true,
      // Baileys 会自动管理凭证，存储在 ~/.openclaw/credentials/whatsapp/
    },
  },
}

功能特性

支持私聊和群组
支持图片、语音、文件等多媒体消息
支持 WhatsApp Status
支持引用回复

踩坑提示

首次登录需扫码，后续会自动重连
如果长时间断线（超过 14 天），需要重新扫码
WhatsApp Web 协议有反检测机制，过于频繁的自动回复可能触发限制
凭证文件在 ~/.openclaw/credentials/whatsapp/，备份时记得包含此目录

7.5 飞书 Feishu/Lark（内置插件）

飞书是内置插件（bundled），不需要单独安装。支持 WebSocket 事件订阅和流式卡片消息。

申请凭证

打开飞书开放平台 https://open.feishu.cn
创建企业自建应用
获取 App ID 和 App Secret
开通权限：消息读取、消息发送、机器人
在事件订阅中配置 WebSocket 模式

配置

{
  channels: {
    feishu: {
      enabled: true,
      domain: "feishu",       // 或 "lark"（国际版）
      accounts: {
        main: {
          appId: "cli_xxxxx",
          appSecret: "your-app-secret",
          botName: "小克AI助手",
        },
      },
      defaultAccount: "main",
      dmPolicy: "pairing",
      streaming: true,         // 流式卡片回复
      groupPolicy: "allowlist",
      groups: {
        "oc_xxx": {            // 群组 ID
          requireMention: false,
        },
      },
    },
  },
}

配置步骤详解

在飞书开放平台创建企业自建应用
获取 App ID（cli_xxx 格式）和 App Secret
批量导入权限：im:message、im:message:send_as_bot、im:resource
开启机器人能力
事件订阅：选择**长连接（WebSocket）**模式，添加 im.message.receive_v1 事件
创建版本并发布

重要：事件订阅必须使用长连接（WebSocket），不要用 Webhook。并且要先启动 Gateway 再配置事件订阅。

获取 ID

群组 ID（oc_xxx）：在群里 @Bot → 查看 Gateway 日志中的 chat_id
用户 ID（ou_xxx）：私聊 Bot → 查看日志中的 open_id

功能特性

WebSocket 事件订阅（不需要公网回调地址）
流式卡片消息（打字机效果）
支持 DocX 文档读取
支持群组和私聊
Lark 国际版：设置 domain: "lark"，使用 https://open.larksuite.com

企业部署注意

飞书应用需要管理员审批后才能在组织内使用
建议先在测试企业中验证，再发布到正式环境
检查：应用已发布、事件订阅包含消息事件、权限齐全

7.6 Slack（Socket Mode + HTTP Events）

Slack 渠道基于 Bolt SDK，支持两种连接模式。

申请凭证

打开 https://api.slack.com/apps → “Create New App”
选择 “From scratch” → 填写名称和 Workspace
OAuth & Permissions → 添加 Bot Token Scopes：chat:write、channels:history、im:history、groups:history
Install to Workspace → 复制 Bot User OAuth Token
Socket Mode → 开启 → 获取 App-Level Token

配置

{
  channels: {
    slack: {
      enabled: true,
      botToken: "xoxb-xxxxx",
      appToken: "xapp-xxxxx",  // Socket Mode 需要
    },
  },
}

Socket Mode vs HTTP Events

Socket Mode（推荐）：不需要公网地址，适合本地开发和个人服务器
HTTP Events：需要公网可达的回调 URL，适合生产环境

7.7 Signal（signal-cli，需 Java）

Signal 渠道基于 signal-cli 实现，需要 Java 运行时。

前置要求

# 安装 Java
sudo apt install default-jre  # Ubuntu
brew install openjdk           # macOS

配置

{
  channels: {
    signal: {
      enabled: true,
      account: "+1234567890",  // 绑定的 Signal 账号（手机号）
    },
  },
}

注册

Signal 需要通过 signal-cli 完成注册/链接：

# 方式一：链接到已有 Signal 账号（推荐）
signal-cli link -n "OpenClaw Gateway"
# 扫描终端显示的二维码

# 方式二：注册新号码（需要能接收短信的手机号）
signal-cli -a +1234567890 register
signal-cli -a +1234567890 verify <验证码>

7.8 LINE（插件，Messaging API）

LINE 需要安装插件，使用 Messaging API，需要 HTTPS webhook。

安装插件

openclaw plugins install @openclaw/line

申请凭证

打开 LINE Developers Console：https://developers.line.biz
创建 Provider → 创建 Messaging API Channel
获取 Channel Access Token 和 Channel Secret

配置

{
  channels: {
    line: {
      enabled: true,
      channelAccessToken: "your-token",
      channelSecret: "your-secret",
      // Webhook URL 在 LINE Developers Console 中配置，指向：
      // https://your-domain.com/line/webhook（默认 webhookPath）
      webhookPath: "/line/webhook",
    },
  },
}

注意：LINE Messaging API 需要 HTTPS webhook 地址，你需要有公网域名和 SSL 证书。

7.9 其他渠道速览

以下渠道通过插件系统支持，使用 openclaw plugins install 安装：

渠道	安装方式	特点
IRC	核心渠道（2026.2.9+ 一级渠道）	经典协议，简单直接
BlueBubbles	内置插件	iMessage 推荐方案，需 macOS
Google Chat	核心渠道	Google Workspace 集成
Microsoft Teams	插件	企业场景，Bot Framework
Matrix	插件	去中心化通讯，支持 E2EE
Mattermost	插件	开源团队协作
Twitch	插件	直播聊天，IRC 方式接入
Nostr	插件	去中心化社交，NIP-04 加密 DM
Zalo	插件	越南常用
Tlon	插件	Urbit 生态
Synology Chat	插件	NAS 用户
Nextcloud Talk	插件	私有云
WebChat	内置	浏览器控制台聊天
Voice Call	插件	Twilio/Telnyx 电话语音

插件安装示例：

openclaw plugins install @openclaw/matrix
openclaw plugins install @openclaw/msteams

7.10 多渠道同时使用 + Session 隔离

OpenClaw 的核心优势就是同时接入多个渠道。一个典型的多渠道配置：

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "telegram-bot-token",
      proxy: "socks5://127.0.0.1:1080",
    },
    discord: {
      enabled: true,
      token: "discord-bot-token",        // Discord 用 token（不是 botToken）
      proxy: "socks5://127.0.0.1:1080",
    },
    whatsapp: {
      enabled: true,
    },
    feishu: {
      enabled: true,
      accounts: {
        main: {
          appId: "cli_xxxxx",
          appSecret: "your-secret",
        },
      },
    },
  },
}

Session 隔离规则

配合第 5 章的 dmScope 设置，不同渠道的会话隔离行为：

dmScope	Telegram 和 Discord 的关系
`"main"`	共享同一个上下文（不推荐）
`"per-peer"`	同一用户跨渠道共享
`"per-channel-peer"`	各渠道独立（推荐）

渠道健康监控

# 查看所有渠道状态
openclaw gateway status

# 查看详细日志
openclaw logs --limit 50

渠道级别代理

每个渠道可以独立配置代理，互不影响：

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "...",
      proxy: "socks5://127.0.0.1:1080",  // Telegram 走代理
    },
    feishu: {
      enabled: true,
      accounts: {
        main: {
          appId: "...",
          appSecret: "...",
        },
      },
      // 飞书不需要代理，国内直连
    },
  },
}

7.11 小结

渠道	实现方式	国内可用性	推荐场景
Telegram	grammY	需代理	个人助手首选
微信	官方插件（ClawBot）	直连	国内社交首选
Discord	@buape/carbon	需代理	技术社区/团队
WhatsApp	Baileys	需代理	海外沟通
飞书	内置插件	直连	企业场景
Slack	Bolt SDK	需代理	国际团队
Signal	signal-cli	需代理	隐私优先
LINE	Messaging API	需配置	东南亚/日本

下一章进入模型接入——如何配置和切换各种 AI 模型。

第7章 渠道接入全攻略

7.1 Telegram（核心渠道，最快上手）

申请凭证

配置

DM 策略

群组使用

Forum Topic 支持

踩坑提示

7.2 微信（官方插件，两步搞定）

安装

配置

登录

备选方案：社区插件（历史方案）

7.3 Discord（Bot + Gateway）

申请凭证

重要：开启 Privileged Intents

配置

线程与频道

交互组件（Discord 独有）

基于角色的 Agent 路由

国内网络

踩坑提示

7.4 WhatsApp（Baileys Web 协议扫码）

登录

配置

功能特性

踩坑提示

7.5 飞书 Feishu/Lark（内置插件）

申请凭证

配置

配置步骤详解

获取 ID

功能特性

企业部署注意

7.6 Slack（Socket Mode + HTTP Events）

申请凭证

配置

Socket Mode vs HTTP Events

7.7 Signal（signal-cli，需 Java）

前置要求

配置

注册

7.8 LINE（插件，Messaging API）

安装插件

申请凭证

配置

7.9 其他渠道速览

7.10 多渠道同时使用 + Session 隔离

Session 隔离规则

渠道健康监控

渠道级别代理

7.11 小结

第7章渠道接入全攻略