WhatsApp 配置

Clawdbot 通过 Baileys 库集成 WhatsApp，支持私聊和群聊。

快速开始

最小配置

{
  channels: {
    whatsapp: {
      enabled: true,
      dmPolicy: "allowlist",
      allowFrom: ["+15551234567"]
    }
  }
}

运行模式

推荐：专用号码

使用独立的手机号专门运行 Clawdbot:

旧手机 + eSIM 效果很好
可以在同一设备上使用 WhatsApp Business (另一个号码)

{
  channels: {
    whatsapp: {
      dmPolicy: "open",  // 专用号码可以开放
      account: "+15559876543"
    }
  }
}

个人号码模式

在个人 WhatsApp 上运行:

{
  channels: {
    whatsapp: {
      // 只响应自己发的消息
      selfChatMode: true,
      dmPolicy: "allowlist",
      allowFrom: ["你自己的号码"]
    }
  }
}

通过给自己发消息来测试，避免打扰联系人。

手机号要求

必须是真实手机号: 能接收短信验证
避免: VoIP、虚拟号码 (通常会被封)
推荐: 本地 eSIM 或预付费 SIM 卡
不推荐: TextNow、Google Voice 等

访问控制

配对模式 (默认)

未知发送者会收到配对码，需要提供后才能使用:

{
  channels: {
    whatsapp: {
      dmPolicy: "pairing",
      // 配对码有效期 (秒)
      pairingExpiry: 3600
    }
  }
}

白名单模式

只响应指定的号码:

{
  channels: {
    whatsapp: {
      dmPolicy: "allowlist",
      allowFrom: [
        "+15551234567",
        "+15559876543"
      ]
    }
  }
}

群聊配置

基于提及的激活

只在被 @提及时响应:

{
  channels: {
    whatsapp: {
      groups: {
        "*": {
          requireMention: true
        }
      }
    }
  }
}

群组白名单

只在特定群组中响应:

{
  channels: {
    whatsapp: {
      groupPolicy: "allowlist",
      allowGroups: [
        "123456789@g.us"
      ]
    }
  }
}

功能特性

自动反应

消息收到时自动发送 emoji 反应:

{
  channels: {
    whatsapp: {
      ackReaction: "👀",
      processingReaction: "🤔",
      doneReaction: "✅"
    }
  }
}

媒体支持

支持图片、视频、音频和文档:

{
  channels: {
    whatsapp: {
      media: {
        // 最大图片大小 (MB)
        imageMaxMb: 6,
        // 最大视频大小 (MB)
        videoMaxMb: 16,
        // 最大文档大小 (MB)
        documentMaxMb: 100
      }
    }
  }
}

历史注入

群聊中注入历史消息作为上下文:

{
  channels: {
    whatsapp: {
      groups: {
        "*": {
          // 注入最近 50 条消息
          historyCount: 50
        }
      }
    }
  }
}

多账号支持

在一个网关进程中运行多个 WhatsApp 账号:

{
  channels: {
    whatsapp: {
      accounts: {
        personal: {
          phone: "+15551234567",
          dmPolicy: "pairing"
        },
        work: {
          phone: "+15559876543",
          dmPolicy: "allowlist",
          allowFrom: ["工作联系人"]
        }
      }
    }
  }
}

重要说明

不支持 Twilio API

Clawdbot 不再支持 Twilio 的 WhatsApp Business API，原因是:

24 小时回复窗口限制
高频个人助手使用会被封禁

避免封号

不要发送垃圾消息
避免频繁批量发送
使用专用号码
保持正常的使用模式

故障排除

二维码扫描失败

确保手机 WhatsApp 是最新版本
尝试重新生成二维码: clawdbot channels login whatsapp --refresh
检查网络连接

连接断开

# 检查状态
clawdbot channels status whatsapp
 
# 重新连接
clawdbot channels reconnect whatsapp

消息不响应

检查 dmPolicy/groupPolicy 配置
确认号码在白名单中
查看日志: clawdbot logs --channel whatsapp

下一步

概述 Telegram