picoclaw/docs/zh/chat-apps.md

💬 聊天应用配置

返回 README

💬 聊天应用集成 (Chat Apps)

PicoClaw 支持多种聊天平台，使您的 Agent 能够连接到任何地方。

注意: 所有 Webhook 类渠道（LINE、WeCom 等）均挂载在同一个 Gateway HTTP 服务器上（gateway.host:gateway.port，默认 127.0.0.1:18790），无需为每个渠道单独配置端口。注意：飞书（Feishu）使用 WebSocket/SDK 模式，不通过该共享 HTTP webhook 服务器接收消息。

核心渠道

渠道	设置难度	特性说明	文档链接
Telegram	⭐ 简单	推荐，支持语音转文字，长轮询无需公网	查看文档
Discord	⭐ 简单	Socket Mode，支持群组/私信，Bot 生态成熟	查看文档
WhatsApp	⭐ 简单	原生 (QR 扫码) 或 Bridge URL	查看文档
Slack	⭐ 简单	Socket Mode (无需公网 IP)，企业级支持	查看文档
Matrix	⭐⭐ 中等	联邦协议，支持自建 homeserver 与公开服务器	查看文档
QQ	⭐⭐ 中等	官方机器人 API，适合国内社群	查看文档
钉钉 (DingTalk)	⭐⭐ 中等	Stream 模式无需公网，企业办公首选	查看文档
LINE	⭐⭐⭐ 较难	需要 HTTPS Webhook	查看文档
企业微信 (WeCom)	⭐⭐⭐ 较难	支持群机器人(Webhook)、自建应用(API)和智能机器人(AI Bot)	Bot 文档 / App 文档 / AI Bot 文档
飞书 (Feishu)	⭐⭐⭐ 较难	企业级协作，功能丰富	查看文档
IRC	⭐⭐ 中等	服务器 + TLS 配置	-
OneBot	⭐⭐ 中等	兼容 NapCat/Go-CQHTTP，社区生态丰富	查看文档
MaixCam	⭐ 简单	专为 AI 摄像头设计的硬件集成通道	查看文档
Pico	⭐ 简单	PicoClaw 原生协议通道

---

Telegram（推荐）

1. 创建 Bot

• 打开 Telegram，搜索 @BotFather
• 发送 /newbot，按提示操作
• 复制 Token

2. 配置

{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN",
      "allow_from": ["YOUR_USER_ID"]
    }
  }
}

通过 Telegram 上的 @userinfobot 获取你的 User ID。

3. 运行

picoclaw gateway

4. Telegram 命令菜单（启动时自动注册）

PicoClaw 使用统一的命令定义来源。启动时会自动将 Telegram 支持的命令（例如 /start、/help、/show、/list）注册到 Bot 命令菜单，确保菜单展示与实际行为一致。 Telegram 侧保留的是命令菜单注册能力；通用命令的实际执行统一走 Agent Loop 中的 commands executor。

如果注册因网络或 API 短暂异常失败，不会阻塞 channel 启动；系统会在后台自动重试。

Discord

1. 创建 Bot

• 前往 https://discord.com/developers/applications
• 创建应用 → Bot → 添加 Bot
• 复制 Bot Token

2. 启用 Intents

• 在 Bot 设置中启用 MESSAGE CONTENT INTENT
• （可选）启用 SERVER MEMBERS INTENT（如需基于成员数据的白名单）

3. 获取 User ID

• Discord 设置 → 高级 → 启用 开发者模式
• 右键点击头像 → 复制用户 ID

4. 配置

{
  "channels": {
    "discord": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN",
      "allow_from": ["YOUR_USER_ID"]
    }
  }
}

5. 邀请 Bot

• OAuth2 → URL Generator
• Scopes: bot
• Bot Permissions: Send Messages, Read Message History
• 打开生成的邀请链接，将 Bot 添加到服务器

可选：群组触发模式

默认情况下 Bot 会回复服务器频道中的所有消息。如需仅在 @提及时回复：

{
  "channels": {
    "discord": {
      "group_trigger": { "mention_only": true }
    }
  }
}

也可通过关键词前缀触发（如 !bot）：

{
  "channels": {
    "discord": {
      "group_trigger": { "prefixes": ["!bot"] }
    }
  }
}

6. 运行

picoclaw gateway

WhatsApp（原生 whatsmeow）

PicoClaw 支持两种 WhatsApp 连接方式：

• 原生（推荐）： 进程内使用 whatsmeow，无需独立 Bridge。设置 "use_native": true 并留空 bridge_url。首次运行时用 WhatsApp 扫描 QR 码（关联设备）。会话存储在工作区下（如 workspace/whatsapp/）。原生渠道为可选构建，使用 -tags whatsapp_native 编译（如 make build-whatsapp-native 或 go build -tags whatsapp_native ./cmd/...）。
• Bridge： 连接外部 WebSocket Bridge。设置 bridge_url（如 ws://localhost:3001），保持 use_native 为 false。

配置（原生）

{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "use_native": true,
      "session_store_path": "",
      "allow_from": []
    }
  }
}

如果 session_store_path 为空，会话存储在 <workspace>/whatsapp/。运行 picoclaw gateway；首次运行时在终端扫描 QR 码（WhatsApp → 关联设备）。

Matrix

1. 准备 Bot 账号

• 使用你的 homeserver（如 https://matrix.org 或自建）
• 创建 Bot 用户并获取 access token

2. 配置

{
  "channels": {
    "matrix": {
      "enabled": true,
      "homeserver": "https://matrix.org",
      "user_id": "@your-bot:matrix.org",
      "access_token": "YOUR_MATRIX_ACCESS_TOKEN",
      "allow_from": []
    }
  }
}

3. 运行

picoclaw gateway

完整选项（device_id、join_on_invite、group_trigger、placeholder、reasoning_channel_id）请参考 Matrix 渠道配置指南。

QQ

1. 创建 Bot

• 前往 QQ 开放平台
• 创建应用 → 获取 AppID 和 AppSecret

2. 配置

{
  "channels": {
    "qq": {
      "enabled": true,
      "app_id": "YOUR_APP_ID",
      "app_secret": "YOUR_APP_SECRET",
      "allow_from": []
    }
  }
}

allow_from 留空表示允许所有用户，或指定 QQ 号限制访问。

3. 运行

picoclaw gateway

Slack

1. 创建 Slack App

• 前往 Slack API 创建应用
• 启用 Socket Mode
• 获取 Bot Token 和 App-Level Token

2. 配置

{
  "channels": {
    "slack": {
      "enabled": true,
      "bot_token": "xoxb-YOUR_BOT_TOKEN",
      "app_token": "xapp-YOUR_APP_TOKEN",
      "allow_from": []
    }
  }
}

3. 运行

picoclaw gateway

IRC

1. 配置

{
  "channels": {
    "irc": {
      "enabled": true,
      "server": "irc.libera.chat:6697",
      "nick": "picoclaw-bot",
      "use_tls": true,
      "channels_to_join": ["#your-channel"],
      "allow_from": []
    }
  }
}

2. 运行

picoclaw gateway

钉钉 (DingTalk)

1. 创建 Bot

• 前往 开放平台
• 创建内部应用
• 复制 Client ID 和 Client Secret

2. 配置

{
  "channels": {
    "dingtalk": {
      "enabled": true,
      "client_id": "YOUR_CLIENT_ID",
      "client_secret": "YOUR_CLIENT_SECRET",
      "allow_from": []
    }
  }
}

allow_from 留空表示允许所有用户，或指定钉钉用户 ID 限制访问。

3. 运行

picoclaw gateway

LINE

1. 创建 LINE Official Account

• 前往 LINE Developers Console
• 创建 Provider → 创建 Messaging API Channel
• 复制 Channel Secret 和 Channel Access Token

2. 配置

{
  "channels": {
    "line": {
      "enabled": true,
      "channel_secret": "YOUR_CHANNEL_SECRET",
      "channel_access_token": "YOUR_CHANNEL_ACCESS_TOKEN",
      "webhook_path": "/webhook/line",
      "allow_from": []
    }
  }
}

LINE Webhook 挂载在共享 Gateway 服务器上（gateway.host:gateway.port，默认 127.0.0.1:18790）。

3. 设置 Webhook URL

LINE 要求 HTTPS Webhook。使用反向代理或隧道：

# 示例：使用 ngrok（Gateway 默认端口 18790）
ngrok http 18790

然后在 LINE Developers Console 中将 Webhook URL 设置为 https://your-domain/webhook/line 并启用 Use webhook。

4. 运行

picoclaw gateway

在群聊中，Bot 仅在被 @提及时回复。回复会引用原始消息。

飞书 (Feishu)

1. 创建应用

• 前往 飞书开放平台
• 创建企业自建应用
• 获取 App ID 和 App Secret

2. 配置

{
  "channels": {
    "feishu": {
      "enabled": true,
      "app_id": "cli_xxx",
      "app_secret": "xxx",
      "encrypt_key": "",
      "verification_token": "",
      "allow_from": []
    }
  }
}

3. 运行

picoclaw gateway

企业微信 (WeCom)

PicoClaw 支持三种企业微信集成方式：

方式 1: 群机器人 (Bot) — 设置简单，支持群聊 方式 2: 自建应用 (App) — 功能更多，支持主动推送，仅私聊 方式 3: 智能机器人 (AI Bot) — 官方 AI Bot，流式回复，支持群聊和私聊

详细设置请参考 企业微信 AI Bot 配置指南。

快速设置 — 群机器人：

1. 创建 Bot

• 企业微信管理后台 → 群聊 → 添加群机器人
• 复制 Webhook URL（格式：https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx）

2. 配置

{
  "channels": {
    "wecom": {
      "enabled": true,
      "token": "YOUR_TOKEN",
      "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
      "webhook_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY",
      "webhook_path": "/webhook/wecom",
      "allow_from": []
    }
  }
}

WeCom Webhook 挂载在共享 Gateway 服务器上（gateway.host:gateway.port，默认 127.0.0.1:18790）。

快速设置 — 自建应用：

1. 创建应用

• 企业微信管理后台 → 应用管理 → 创建应用
• 复制 AgentId 和 Secret
• 前往"我的企业"页面，复制 CorpID

2. 配置接收消息

• 在应用详情中，点击"接收消息" → "设置 API"
• 设置 URL 为 http://your-server:18790/webhook/wecom-app
• 生成 Token 和 EncodingAESKey

3. 配置

{
  "channels": {
    "wecom_app": {
      "enabled": true,
      "corp_id": "wwxxxxxxxxxxxxxxxx",
      "corp_secret": "YOUR_CORP_SECRET",
      "agent_id": 1000002,
      "token": "YOUR_TOKEN",
      "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
      "webhook_path": "/webhook/wecom-app",
      "allow_from": []
    }
  }
}

4. 运行

picoclaw gateway

注意: WeCom Webhook 回调挂载在 Gateway 端口（默认 18790）。使用反向代理配置 HTTPS。

快速设置 — 智能机器人 (AI Bot)：

1. 创建 AI Bot

• 企业微信管理后台 → 应用管理 → AI Bot
• 在 AI Bot 设置中配置回调 URL：http://your-server:18791/webhook/wecom-aibot
• 复制 Token 并点击"随机生成" EncodingAESKey

2. 配置

{
  "channels": {
    "wecom_aibot": {
      "enabled": true,
      "token": "YOUR_TOKEN",
      "encoding_aes_key": "YOUR_43_CHAR_ENCODING_AES_KEY",
      "webhook_path": "/webhook/wecom-aibot",
      "allow_from": [],
      "welcome_message": "你好！有什么可以帮你的？"
    }
  }
}

3. 运行

picoclaw gateway

注意: 企业微信 AI Bot 使用流式拉取协议，无回复超时问题。长任务（>30 秒）会自动切换到 response_url 推送投递。

OneBot

1. 配置

兼容 NapCat / Go-CQHTTP 等 OneBot 实现。

{
  "channels": {
    "onebot": {
      "enabled": true,
      "allow_from": []
    }
  }
}

2. 运行

picoclaw gateway

MaixCam

专为 Sipeed AI 摄像头硬件设计的集成通道。

{
  "channels": {
    "maixcam": {
      "enabled": true
    }
  }
}

picoclaw gateway