Платформы обмена сообщениями

WhatsApp

Статус: готов к работе в production через WhatsApp Web (Baileys). Шлюз владеет связанными сессиями.

Спаривание

Политика DM по умолчанию — спаривание для неизвестных отправителей.

Устранение неполадок каналов

Диагностика и сценарии восстановления для всех каналов.

Конфигурация шлюза

Полные шаблоны и примеры конфигурации каналов.

Быстрая настройка

Шаг 1: Настройте политику доступа WhatsApp

{
  channels: {
    whatsapp: {
      dmPolicy: "pairing",
      allowFrom: ["+15551234567"],
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
    },
  },
}

Шаг 2: Привяжите WhatsApp (QR)

openclaw channels login --channel whatsapp

Для конкретного аккаунта:

openclaw channels login --channel whatsapp --account work

Шаг 3: Запустите шлюз

openclaw gateway

Шаг 4: Одобрите первый запрос на спаривание (если используется режим спаривания)

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>

Запросы на спаривание истекают через 1 час. Ожидающие запросы ограничены 3 на канал.

ℹ️ OpenClaw рекомендует по возможности использовать для WhatsApp отдельный номер. (Метаданные канала и процесс подключения оптимизированы для такой настройки, но также поддерживается использование личного номера.)

Паттерны развертывания

Модель выполнения

  • Шлюз владеет сокетом WhatsApp и циклом переподключения.
  • Для исходящих отправок требуется активный слушатель WhatsApp для целевого аккаунта.
  • Статусные и широковещательные чаты игнорируются (@status, @broadcast).
  • Прямые чаты используют правила сессии DM (session.dmScope; по умолчанию main объединяет DM в основную сессию агента).
  • Групповые сессии изолированы (agent:<agentId>:whatsapp:group:<jid>).

Контроль доступа и активация

channels.whatsapp.dmPolicy управляет доступом к прямым чатам:

  • pairing (по умолчанию)
  • allowlist
  • open (требует, чтобы allowFrom включал "*")
  • disabled

allowFrom принимает номера в формате E.164 (нормализуются внутренне).Переопределение для нескольких аккаунтов: channels.whatsapp.accounts.<id>.dmPolicy (и allowFrom) имеют приоритет над настройками уровня канала по умолчанию для этого аккаунта.Детали поведения во время выполнения:

  • спаривания сохраняются в хранилище разрешений канала и объединяются с настроенным allowFrom
  • если список разрешений не настроен, привязанный собственный номер разрешен по умолчанию
  • исходящие DM fromMe никогда не спариваются автоматически

Личный номер и поведение в собственных чатах

Когда привязанный собственный номер также присутствует в allowFrom, активируются защитные механизмы собственных чатов WhatsApp:

  • пропускать квитанции о прочтении для ходов в собственном чате
  • игнорировать поведение автоматического срабатывания по JID упоминания, которое в противном случае отправляло бы пинг вам самому
  • если messages.responsePrefix не задан, ответы в собственном чате по умолчанию имеют вид [{identity.name}] или [openclaw]

Нормализация сообщений и контекст

Доставка, разбиение на части и медиа

Реакции подтверждения

WhatsApp поддерживает немедленные реакции подтверждения на входящие сообщения через channels.whatsapp.ackReaction.

{
  channels: {
    whatsapp: {
      ackReaction: {
        emoji: "👀",
        direct: true,
        group: "mentions", // always | mentions | never
      },
    },
  },
}

Примечания по поведению:

  • отправляется сразу после принятия входящего сообщения (до ответа)
  • сбои логируются, но не блокируют обычную доставку ответа
  • групповой режим mentions реагирует на ходы, вызванные упоминанием; групповая активация always действует как обход этой проверки
  • WhatsApp использует channels.whatsapp.ackReaction (устаревший messages.ackReaction здесь не используется)

Несколько аккаунтов и учетные данные

Инструменты, действия и запись конфигурации

  • Поддержка инструментов агента включает действие реакции WhatsApp (react).
  • Ворота действий:
    • channels.whatsapp.actions.reactions
    • channels.whatsapp.actions.polls
  • Запись конфигурации, инициированная каналом, включена по умолчанию (отключите через channels.whatsapp.configWrites=false).

Устранение неполадок

Указатели на справочник конфигурации

Основной справочник:

Важные поля WhatsApp:

  • доступ: dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups
  • доставка: textChunkLimit, chunkMode, mediaMaxMb, sendReadReceipts, ackReaction
  • несколько аккаунтов: accounts.<id>.enabled, accounts.<id>.authDir, переопределения на уровне аккаунта
  • операции: configWrites, debounceMs, web.enabled, web.heartbeatSeconds, web.reconnect.*
  • поведение сессии: session.dmScope, historyLimit, dmHistoryLimit, dms.<id>.historyLimit

Связанные темы

TwitchZalo