通道设置教程¶

将 PyClaw Agent 连接到消息平台，实现 7x24 小时自动回复。本文档提供主流通道的分步设置指南。

通用设置模式¶

所有通道遵循相同的配置模式：

在目标平台创建 Bot / 应用，获取凭证（Token、Key 等）
在 PyClaw 配置中添加通道配置
启动或重启 Gateway，验证连接

通道配置位于 ~/.pyclaw/pyclaw.json 的 channels 节下：

{
  channels: {
    <channel_name>: {
      enabled: true,
      // 通道特有凭证字段
      // 通用策略字段
    },
  },
}

通用策略字段¶

每个通道都支持以下 DM 和群组策略字段：

字段	可选值	说明
`dmPolicy`	`pairing` / `allowlist` / `open` / `disabled`	DM 访问策略
`allowFrom`	字符串数组	允许的发送者 ID
`groupPolicy`	`mention` / `open` / `disabled`	群组消息策略

DM 策略说明：

pairing -- 未知发送者需通过配对码验证身份
allowlist -- 仅 allowFrom 列表中的用户可以对话
open -- 允许所有人直接对话（谨慎使用）
disabled -- 禁用 DM

群组策略说明：

mention -- 群组中需要 @mention Bot 才触发回复（推荐）
open -- 群组中所有消息都触发回复
disabled -- 忽略群组消息

Telegram 设置¶

前置条件¶

一个 Telegram 账号
已安装并运行 PyClaw Gateway（pyclaw gateway）

第 1 步：创建 Telegram Bot¶

在 Telegram 中搜索 @BotFather
发送 /newbot
按提示输入 Bot 名称（显示名）和用户名（必须以 bot 结尾）
记录返回的 Bot Token，格式如 123456789:ABCdefGHIjklMNO

第 2 步：获取你的 Telegram User ID¶

在 Telegram 中搜索 @userinfobot
发送任意消息，记录返回的 Id 数字
这个 ID 将用于 allowFrom 配置，限制只有你能与 Bot 对话

第 3 步：配置 PyClaw¶

# 方式一：交互式向导（推荐新手）
pyclaw setup --wizard

# 方式二：CLI 命令
pyclaw config set channels.telegram.enabled true
pyclaw config set channels.telegram.token "123456789:ABCdefGHIjklMNO"
pyclaw config set channels.telegram.allowFrom '["12345678"]'

# 方式三：直接编辑配置文件

直接编辑 ~/.pyclaw/pyclaw.json：

{
  channels: {
    telegram: {
      enabled: true,
      token: "${TELEGRAM_BOT_TOKEN}",  // 推荐使用环境变量
      allowFrom: ["12345678"],          // 你的 Telegram User ID
      dmPolicy: "allowlist",            // 仅允许列表中的用户
      groupPolicy: "mention",           // 群组中需 @mention
    },
  },
}

第 4 步：设置环境变量¶

推荐将 Bot Token 存储在环境变量中而非明文写入配置：

# 写入 ~/.pyclaw/.env
echo 'TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNO' >> ~/.pyclaw/.env

第 5 步：验证连接¶

# 检查通道状态
pyclaw channels status

# 查看日志确认 Bot 已启动
pyclaw logs --follow

预期日志输出：

INFO  pyclaw.channels.telegram  Telegram channel starting (long polling)

第 6 步：测试对话¶

在 Telegram 中找到你的 Bot，发送一条消息。Agent 应在几秒内回复。

故障排除¶

问题	原因	解决方法
Bot 无响应	Token 无效	重新从 BotFather 获取 Token
Bot 无响应	`allowFrom` ID 不正确	用 `@userinfobot` 重新确认 ID
群组中不回复	未 @mention	群组默认需 @mention Bot
连接超时	网络问题	设置 `HTTPS_PROXY` 环境变量
Bot 上线但收不到消息	Bot 隐私模式	在 BotFather 中 `/setprivacy` 设为 Disable

Discord 设置¶

前置条件¶

一个 Discord 账号
有权创建 Bot 的 Discord 服务器
已安装并运行 PyClaw Gateway

第 1 步：创建 Discord Application¶

前往 Discord Developer Portal
点击 New Application，输入名称（如 PyClaw Bot）
记录 Application ID

第 2 步：创建 Bot¶

在应用页面左侧点击 Bot
点击 Add Bot，确认创建
记录 Bot Token（点击 Reset Token 获取，只显示一次）
在 Bot 设置页面，启用以下 Privileged Gateway Intents：
Message Content Intent
Server Members Intent（可选，用于用户 ID 验证）

第 3 步：邀请 Bot 到服务器¶

在 OAuth2 > URL Generator 中：

Scopes 勾选 bot
Bot Permissions 勾选：
Send Messages
Read Message History
Add Reactions（可选）
Embed Links（可选）
复制生成的 URL，在浏览器中打开并选择服务器

第 4 步：获取你的 Discord User ID¶

在 Discord 设置中启用 Developer Mode（Settings > Advanced > Developer Mode）
右键点击你的用户名，选择 Copy User ID
记录这个数字 ID

第 5 步：配置 PyClaw¶

{
  channels: {
    discord: {
      enabled: true,
      token: "${DISCORD_BOT_TOKEN}",
      allowFrom: ["123456789012345678"],  // 你的 Discord User ID
      dmPolicy: "allowlist",
      groupPolicy: "mention",
    },
  },
}

第 6 步：验证连接¶

pyclaw channels status
pyclaw logs --follow

预期日志输出：

INFO  pyclaw.channels.discord  Discord channel starting
INFO  discord.py  Logged in as PyClaw Bot#1234

第 7 步：测试对话¶

在 Discord 中私信 Bot 或在服务器频道中 @mention Bot 发送消息。

故障排除¶

问题	原因	解决方法
Bot 不在线	Token 无效或未启用	重新获取 Token，检查 Privileged Intents
收不到消息	缺少 Message Content Intent	在 Developer Portal 中启用
消息被截断	Discord 2000 字符限制	PyClaw 自动分片，无需手动处理
Bot 无权限发消息	权限不足	重新生成邀请链接，添加 Send Messages 权限

Slack 设置¶

前置条件¶

一个 Slack Workspace 的管理权限
已安装并运行 PyClaw Gateway

第 1 步：创建 Slack App¶

前往 Slack API: Applications
点击 Create New App > From scratch
输入 App Name（如 PyClaw）并选择 Workspace

第 2 步：配置 Bot Token Scopes¶

在左侧菜单点击 OAuth & Permissions
在 Bot Token Scopes 中添加：
chat:write -- 发送消息
channels:history -- 读取频道消息
groups:history -- 读取私聊消息
im:history -- 读取 DM 消息
im:write -- 发送 DM
im:read -- 获取 DM 列表
commands -- 斜杠命令（可选）

第 3 步：启用 Socket Mode¶

在左侧菜单点击 Socket Mode
启用 Socket Mode
记录生成的 App-Level Token（以 xapp- 开头）

第 4 步：安装 App 到 Workspace¶

在左侧菜单点击 Install App
点击 Install to Workspace 并授权
记录 Bot User OAuth Token（以 xoxb- 开头）

第 5 步：配置 PyClaw¶

{
  channels: {
    slack: {
      enabled: true,
      botToken: "${SLACK_BOT_TOKEN}",    // xoxb-...
      appToken: "${SLACK_APP_TOKEN}",    // xapp-...
      allowFrom: ["U1234567890"],        // Slack Member ID
      dmPolicy: "allowlist",
      groupPolicy: "mention",
    },
  },
}

第 6 步：设置环境变量¶

echo 'SLACK_BOT_TOKEN=xoxb-...' >> ~/.pyclaw/.env
echo 'SLACK_APP_TOKEN=xapp-...' >> ~/.pyclaw/.env

第 7 步：验证连接¶

pyclaw channels status
pyclaw logs --follow

预期日志输出：

INFO  pyclaw.channels.slack  Slack channel starting
INFO  slack_bolt  Bolt app is running!

故障排除¶

问题	原因	解决方法
连接失败	Token 错误	确认 `botToken` 以 `xoxb-` 开头，`appToken` 以 `xapp-` 开头
连接失败	未启用 Socket Mode	在 Slack App 设置中启用
收不到消息	缺少 Scope	添加 `im:history` 和 `channels:history`
App 未安装	未安装到 Workspace	在 Install App 页面重新安装

通道能力矩阵¶

不同通道支持的能力有所差异。PyClaw 通过 detect_capabilities() 在运行时自动探测每个通道的能力。

核心能力¶

能力	Telegram	Discord	Slack	DingTalk	Feishu	QQ	Matrix
收发文本	Y	Y	Y	Y	Y	Y	Y
Markdown 渲染	Y	部分	mrkdwn	部分	Y	部分	Y
流式回复	Y	Y	Y	N	Y	N	Y
消息反应	Y	Y	Y	N	Y	N	Y
置顶消息	Y	Y	Y	Y	Y	N	Y
文件发送	Y	Y	Y	Y	Y	Y	Y
图片发送	Y	Y	Y	Y	Y	Y	Y
群组消息	Y	Y	Y	Y	Y	Y	Y
DM 消息	Y	Y	Y	Y	Y	Y	Y
线程回复	Y	Y	Y	N	Y	N	Y

连接方式¶

通道	传输方式	依赖库
Telegram	Long Polling	aiogram
Discord	WebSocket (Gateway)	discord.py
Slack	Socket Mode	slack-bolt
DingTalk	HTTP Webhook	httpx
Feishu	WebSocket	httpx
QQ	HTTP API	httpx
Matrix	WebSocket (Sync)	matrix-nio
IRC	TCP Socket	irc3
WhatsApp	多设备协议	neonize
Signal	signal-cli	httpx
Line	Webhook	httpx
MS Teams	WebSocket	httpx
Mattermost	WebSocket	httpx

查看实时能力探测结果：

pyclaw channels capabilities

其他通道快速配置参考¶

DingTalk¶

{
  channels: {
    dingtalk: {
      enabled: true,
      clientId: "your_app_key",
      clientSecret: "your_app_secret",
    },
  },
}

Feishu (飞书)¶

{
  channels: {
    feishu: {
      enabled: true,
      appId: "cli_xxxxxxxx",
      appSecret: "your_app_secret",
    },
  },
}

QQ¶

{
  channels: {
    qq: {
      enabled: true,
      apiUrl: "http://localhost:3000",  // Napcat/Go-cqhttp 地址
      token: "your_access_token",
    },
  },
}

Matrix¶

{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.org",
      userId: "@pyclaw:matrix.org",
      accessToken: "${MATRIX_ACCESS_TOKEN}",
    },
  },
}

IRC¶

{
  channels: {
    irc: {
      enabled: true,
      server: "irc.libera.chat",
      nickname: "pyclaw-bot",
      channels: ["#pyclaw"],
    },
  },
}

多通道配置¶

PyClaw 支持同时运行多个通道。在 channels 下配置多个通道即可：

{
  channels: {
    telegram: {
      enabled: true,
      token: "${TELEGRAM_BOT_TOKEN}",
      allowFrom: ["12345678"],
    },
    discord: {
      enabled: true,
      token: "${DISCORD_BOT_TOKEN}",
      allowFrom: ["123456789012345678"],
    },
    slack: {
      enabled: true,
      botToken: "${SLACK_BOT_TOKEN}",
      appToken: "${SLACK_APP_TOKEN}",
    },
  },
}

所有通道共享同一个 Agent Runtime，但可以配置不同的路由绑定，将不同通道的消息路由到不同的 Agent：

{
  bindings: [
    { agent: "work-assistant", match: { channel: "slack" } },
    { agent: "community-bot", match: { channel: "discord" } },
    { agent: "personal", match: { channel: "telegram" } },
  ],
}

详见概念总览 -- 多 Agent 路由。

通用故障排除¶

通道无法启动¶

# 检查通道状态
pyclaw channels status

# 查看详细日志
pyclaw logs --follow

常见原因：

凭证（Token / Key）错误或过期
缺少通道依赖库（如 aiogram、discord.py），通过 pip install openclaw-py[all] 安装
网络连接问题，检查代理设置

消息延迟或丢失¶

检查 allowFrom 配置是否正确
群组消息需 @mention 才触发（默认行为）
查看日志中是否有速率限制错误

安全检查¶

# 扫描配置中的明文密钥
pyclaw secrets audit

# 自动替换为环境变量引用
pyclaw secrets apply

相关文档: 快速开始 · 配置说明 · 概念总览 · 故障排除