通道配置参考¶

PyClaw 支持 24+ 消息通道，将 AI Agent 连接到主流即时通讯、团队协作和社交平台。

通道概览¶

类别	通道	状态	连接模式
即时通讯	Telegram	✅ 生产就绪	Long Polling / Webhook
	WhatsApp	⚠️ Web 模式	扫码登录
	Signal	⚠️ 需要 signal-cli	DBus / CLI
	iMessage	⚠️ 需要 macOS	Native / BlueBubbles
	LINE	✅ Bot API	Webhook
团队协作	Discord	✅ 生产就绪	Gateway WebSocket
	Slack	✅ 生产就绪	Socket Mode / HTTP
	Feishu/Lark	✅ 生产就绪	WebSocket / Webhook
	DingTalk	✅ 生产就绪	WebSocket / Webhook
	Microsoft Teams	✅ 生产就绪	Webhook
	Google Chat	✅ 生产就绪	HTTP / Webhook
	Mattermost	✅ 生产就绪	WebSocket / HTTP
社交平台	QQ Bot	✅ 生产就绪	WebSocket
	OneBot	✅ 生产就绪	HTTP / WebSocket
	IRC	✅ 生产就绪	TCP + TLS
	Twitch	✅ 生产就绪	IRC
	Nostr	✅ 生产就绪	WebSocket Relay
其他	Matrix	✅ 生产就绪	Client-Server API
	Web Chat	✅ 内置	WebSocket
	WeCom	⚠️ 需要企业认证	Webhook
	Voice Call	✅ 电话	Twilio

通用配置字段¶

所有通道都支持以下通用配置：

字段	类型	说明
`enabled`	bool	是否启用通道
`dmPolicy`	string	DM 访问策略：`pairing` / `allowlist` / `open` / `disabled`
`allowFrom`	array	DM 允许的发送者 ID 列表
`groupPolicy`	string	群组策略：`open` / `allowlist` / `disabled`
`groupAllowFrom`	array	群组允许列表（群组 ID）
`requireMention`	bool	群组是否需要 @提及

Telegram¶

状态: ✅ 生产就绪

快速配置¶

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123456:ABC-DEF...",
      dmPolicy: "pairing",
      allowFrom: [123456789],
      groupPolicy: "allowlist",
      requireMention: true,
    },
  },
}

完整配置¶

字段	类型	默认值	说明
`botToken`	string/SecretRef	—	Bot Token（从 @BotFather 获取）
`dmPolicy`	string	`pairing`	DM 访问策略
`allowFrom`	number[]	`[]`	允许的 Telegram 用户 ID
`groupPolicy`	string	`allowlist`	群组策略
`groupAllowFrom`	number[]	`[]`	允许的群组 ID（负数）
`requireMention`	bool	`true`	群组是否需要 @提及
`groups.*.requireMention`	bool	—	单群组覆盖
`groups.*.allowFrom`	number[]	—	群组内发送者白名单
`streaming.mode`	string	`partial`	流式回复：`off` / `partial` / `block` / `progress`
`textChunkLimit`	number	`4000`	消息分块大小
`mediaMaxMb`	number	`100`	媒体文件大小上限
`replyToMode`	string	`off`	回复引用：`off` / `first` / `all`
`linkPreview`	bool	`true`	是否启用链接预览

获取用户/群组 ID¶

# 方法 1：查看日志
pyclaw logs --follow

# 方法 2：Bot API
curl "https://api.telegram.org/bot<TOKEN>/getUpdates"

# 方法 3：第三方 bot
# 发送消息给 @userinfobot

配对流程¶

启动 Gateway：pyclaw gateway
DM 你的 bot，获取配对码
批准配对：

pyclaw pairing list telegram
pyclaw pairing approve telegram <CODE>

Discord¶

状态: ✅ 生产就绪

快速配置¶

{
  channels: {
    discord: {
      enabled: true,
      token: { source: "env", id: "DISCORD_BOT_TOKEN" },
      applicationId: "111111111111111111",
      dmPolicy: "pairing",
      groupPolicy: "allowlist",
      guilds: {
        "YOUR_SERVER_ID": {
          requireMention: true,
          users: ["YOUR_USER_ID"],
        },
      },
    },
  },
}

设置步骤¶

创建应用：https://discord.com/developers/applications
创建 Bot：Bot → Add Bot → 复制 Token
启用 Intents：Message Content Intent（必须）、Server Members Intent（推荐）
生成邀请链接：OAuth2 → URL Generator → bot + applications.commands
添加权限：View Channels, Send Messages, Read History, Embed Links, Attach Files
添加到服务器：复制链接到浏览器，选择服务器

获取 ID¶

启用 Developer Mode：User Settings → Advanced → Developer Mode
右键 Server → Copy Server ID
右键 User → Copy User ID

线程配置¶

{
  channels: {
    discord: {
      threadBindings: {
        enabled: true,
        idleHours: 24,
        maxAgeHours: 168,
        spawnSessions: false,
      },
    },
  },
}

Slack¶

状态: ✅ 生产就绪

选择连接模式¶

模式	适用场景	需要
Socket Mode（推荐）	开发/单机/内网	App Token + Bot Token
HTTP Mode	多实例/负载均衡	Bot Token + Signing Secret + 公网 HTTPS

Socket Mode 配置¶

{
  channels: {
    slack: {
      enabled: true,
      mode: "socket",
      appToken: "xapp-...",  // App-Level Token
      botToken: "xoxb-...",  // Bot Token
      dmPolicy: "pairing",
      groupPolicy: "allowlist",
    },
  },
}

HTTP Mode 配置¶

{
  channels: {
    slack: {
      enabled: true,
      mode: "http",
      botToken: "xoxb-...",
      signingSecret: "xxx...",
      webhookPath: "/slack/events",
      webhookPort: 8787,
    },
  },
}

创建 Slack App¶

打开 https://api.slack.com/apps/new
使用 Manifest 创建（推荐）：

{
  "display_information": { "name": "PyClaw" },
  "features": {
    "bot_user": { "display_name": "PyClaw" },
    "slash_commands": [{
      "command": "/pyclaw",
      "description": "Send message to PyClaw"
    }]
  },
  "oauth_config": {
    "scopes": {
      "bot": [
        "app_mentions:read",
        "channels:history",
        "channels:read",
        "chat:write",
        "im:history",
        "im:read",
        "im:write",
        "users:read"
      ]
    }
  },
  "settings": {
    "socket_mode_enabled": true,
    "event_subscriptions": {
      "bot_events": ["app_mention", "message.im", "message.channels"]
    }
  }
}

Feishu / Lark¶

状态: ✅ 生产就绪

快速配置¶

{
  channels: {
    feishu: {
      enabled: true,
      appId: "cli_xxx",
      appSecret: { source: "env", id: "FEISHU_APP_SECRET" },
      domain: "feishu",  // feishu | lark
      connectionMode: "websocket",
      dmPolicy: "allowlist",
      groupPolicy: "allowlist",
      requireMention: true,
      groupSessionScope: "group",
      streaming: true,
    },
  },
}

配置字段¶

字段	类型	默认值	说明
`appId`	string	—	App ID（格式：`cli_xxx`）
`appSecret`	string/SecretRef	—	App Secret
`domain`	string	`feishu`	API 域名：`feishu`（国内）或 `lark`（国际）
`connectionMode`	string	`websocket`	连接模式：`websocket` 或 `webhook`
`groupSessionScope`	string	`group`	群组作用域
`streaming`	bool	`true`	流式回复

获取群组/用户 ID¶

群组 ID：群设置页面查看（格式：oc_xxx）
用户 ID：发送 DM 后查看日志（格式：ou_xxx）

群组作用域选项¶

值	说明
`group`	群内所有成员共享一个会话
`group_sender`	每个发送者独立会话
`group_topic`	每个话题独立会话
`group_topic_sender`	话题内每个发送者独立会话

DingTalk¶

状态: ✅ 生产就绪

{
  channels: {
    dingtalk: {
      enabled: true,
      appKey: "dingxxx",
      appSecret: { source: "env", id: "DINGTALK_APP_SECRET" },
      dmPolicy: "allowlist",
    },
  },
}

Microsoft Teams¶

状态: ✅ 生产就绪

{
  channels: {
    msteams: {
      enabled: true,
      appId: { source: "env", id: "MSTEAMS_APP_ID" },
      appPassword: { source: "env", id: "MSTEAMS_APP_PASSWORD" },
      tenantId: { source: "env", id: "MSTEAMS_TENANT_ID" },
    },
  },
}

QQ Bot¶

状态: ✅ 生产就绪

{
  channels: {
    qq: {
      enabled: true,
      appId: { source: "env", id: "QQ_APP_ID" },
      token: { source: "env", id: "QQ_TOKEN" },
    },
  },
}

OneBot (QQ 生态)¶

状态: ✅ 生产就绪

支持 OneBot v11/v12 协议实现（如 go-cqhttp、NapCat 等）。

{
  channels: {
    onebot: {
      enabled: true,
      endpoint: "http://localhost:3000",
      accessToken: "",  // 可选
    },
  },
}

Matrix¶

状态: ✅ 生产就绪

{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.org",
      accessToken: { source: "env", id: "MATRIX_ACCESS_TOKEN" },
      deviceId: "",  // 可选
    },
  },
}

Web Chat（内置）¶

状态: ✅ 生产就绪

内置 Web Chat 无需额外配置，Gateway 启动后自动可用。

{
  channels: {
    webchat: {
      enabled: true,  // 默认启用
    },
  },
}

执行审批配置¶

对于需要执行 Shell 命令的通道，可配置审批机制：

{
  channels: {
    telegram: {
      execApprovals: {
        enabled: true,
        approvers: [123456789],  // 审批人 Telegram ID
        target: "dm",           // dm | channel | both
        agentFilter: [],        // 空为全部 agent
        sessionFilter: [],      // 空为全部 session
      },
    },
  },
}

多账号支持¶

大部分通道支持多账号：

{
  channels: {
    telegram: {
      defaultAccount: "main",
      accounts: {
        main: {
          botToken: "123:ABC...",
        },
        work: {
          botToken: "456:DEF...",
          enabled: false,
        },
      },
    },
  },
}

环境变量速查¶

通道	变量名	说明
Telegram	`TELEGRAM_BOT_TOKEN`	Bot Token
Discord	`DISCORD_BOT_TOKEN`	Bot Token
Slack	`SLACK_APP_TOKEN`	App-Level Token (xapp-)
Slack	`SLACK_BOT_TOKEN`	Bot Token (xoxb-)
Feishu	`FEISHU_APP_ID`	App ID
Feishu	`FEISHU_APP_SECRET`	App Secret
DingTalk	`DINGTALK_APP_KEY`	App Key
DingTalk	`DINGTALK_APP_SECRET`	App Secret

故障排查¶

Bot 不响应群组消息¶

确认 bot 已加入群组
确认 groupPolicy 不是 disabled
确认已 @提及（如果 requireMention: true）
Telegram：检查 Privacy Mode，确保 bot 是管理员或已禁用隐私模式
Discord：确认 Message Content Intent 已启用

查看日志¶

pyclaw logs --follow

诊断命令¶

pyclaw doctor
pyclaw channels status
pyclaw pairing list <channel>

相关文档: 配置说明 · 架构设计 · 快速开始