Skip to main content

Gateway 消息网关

PilotDeck 内置 16+ 聊天平台 channel，全部走 ~/.pilotdeck/pilotdeck.yaml 的 adapters.<name> 段开关。本文只列配 yaml 怎么填、怎么启动。

启动入口都一样：

cd /path/to/PilotDeck
npm install
npm run server

飞书（推荐）​

PilotDeck 默认走 Stream Mode（长连接）：服务器主动连飞书云 WSS，不需要公网 URL、不需要 ngrok。

1. 飞书后台准备​

在 飞书开放平台 创建企业自建应用：

步骤关键点
凭证记下 App ID (cli_xxx) 和 App Secret
事件与回调 → 订阅方式选 「使用长连接接收事件/回调」（不要选 Webhook）
事件配置添加 im.message.receive_v1
权限勾 im:message、im:message:send_as_bot、im:chat:readonly
版本管理创建版本并发布，否则机器人收不到消息
warning

应用商店应用不支持长连接，必须走 Webhook 模式（见底部）。

2. yaml​

adapters:
  feishu:
    enabled: true
    appId: cli_xxxxxxxxxxxx
    appSecret: xxxxxxxxxxxxxxxxxxxxxxxx
    defaultSessionLabel: default
    # domainName: lark    # 国际版改成 lark（默认 feishu）

启动后看到 feishu: stream mode connected (appId=...) 即就绪，去飞书 @机器人测试。

需要 ClawBot 灰度白名单。微信 channel 默认关闭，避免无名单的机器误触 QR 登录。

yaml​

adapters:
  weixin:
    enabled: true   # 必填，否则不实例化

无需其他凭据：启动后终端会显示 QR 登录链接，用已加灰度的微信号扫码即可。凭证落到 ~/.pilotdeck/weixin-credentials.json，之后免登录。/new 命令开新 session，删凭证文件可强制重登。

QQ 官方机器人​

通过 QQ 官方 Bot Gateway WSS 接入，群聊 + 单聊都支持。目前用环境变量配置（不在 yaml 里）。

1. QQ 开放平台准备​

QQ 开放平台 → 创建机器人 → 拿到 AppId / AppSecret，订阅事件：

  • GROUP_AT_MESSAGE_CREATE —— 群里 @机器人
  • C2C_MESSAGE_CREATE —— 私聊机器人

2. 启动​

export QQ_BOT_APPID=102xxxxxxx
export QQ_BOT_SECRET=xxxxxxxxxxxxxxxxxxxxxxxx
# 可选：限制只在白名单群响应
# export QQ_ALLOW_GROUPS=GROUP_OPENID_A,GROUP_OPENID_B

npm run server

启动看到 qq: authenticated, listening for group messages 即就绪。

沙箱阶段只能在测试群响应；正式上架后才能服务任意群。

其他平台（一段 yaml 搞定）​

Telegram、Discord、Slack、Matrix、Mattermost、Signal、WhatsApp、BlueBubbles、DingTalk、WeCom、Email、SMS、HomeAssistant、ApiServer、Webhook 共 16 个 channel 全部用同一个 schema：

adapters:
  <name>:
    enabled: true
    token: xxx           # 大多数平台用 token
    apiKey: xxx          # 部分平台
    webhookUrl: https://...   # 部分平台
    extra:
      # 平台专属字段（如 slack 的 appToken、matrix 的 homeserver 等）

具体字段看 src/adapters/channel/loadEnabledChannels.ts 里的 loader。常见示例：

Telegram
adapters:
  telegram:
    enabled: true
    token: 123456:ABC...   # @BotFather 拿到的
Discord
adapters:
  discord:
    enabled: true
    token: NTk3...         # Discord Developer Portal → Bot → Token
Slack
adapters:
  slack:
    enabled: true
    token: xoxb-...        # Bot User OAuth Token
    extra:
      appToken: xapp-...   # Socket Mode app-level token
钉钉 / Stream Mode
adapters:
  dingtalk:
    enabled: true
    extra:
      clientId: dingxxxxxxxx
      clientSecret: xxxxxxxxxxxxxxxxxxxxxxxx
Matrix
adapters:
  matrix:
    enabled: true
    token: syt_...                 # access token
    extra:
      homeserver: https://matrix.org
      userId: "@bot:matrix.org"

每个 channel 实现都在 src/adapters/channel/<name>/ 下，三件套：<Name>Channel.ts + <Name>SessionMapper.ts + <name>-render.ts。

通用约定​

行为说明
/new用户在任何 channel 发 /new 会创建新 session；/new 你好 会顺带把"你好"作为第一条消息
Session key格式 <channel>:chat=<id>:general 或 <channel>:chat=<id>:s_<uuid>
并发保护同一 chat 内一条消息正在跑时，新消息会被跳过（避免乱序回复）
日志启动日志里每个 channel 会打印 <channel>: ready 或 <channel>: connected，看不到就是没启用或凭据错

Webhook 模式（飞书备选）​

如果你的飞书应用是商店应用必须走 webhook：

adapters:
  feishu:
    enabled: true
    connectionMode: webhook
    appId: cli_xxx
    appSecret: xxx
    encryptKey: xxx     # 后台启用了加密就填
    verifyToken: xxx    # 后台启用了校验就填

把 https://<your-tunnel>/feishu/webhook 填到飞书后台「事件订阅」即可。url_verification、加密事件解密、event_id 去重 PilotDeck 都自动处理。