Перейти к основному содержимому

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

WhatsApp

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

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

Шаг 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 для OpenClaw
  • более четкие списки разрешений для DM и границы маршрутизации
  • меньшая вероятность путаницы с собственными чатами

Минимальный шаблон политики:

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

Процесс подключения поддерживает режим личного номера и создает базовую конфигурацию, удобную для собственных чатов:

  • dmPolicy: "allowlist"
  • allowFrom включает ваш личный номер
  • selfChatMode: true

Во время выполнения защита от собственных чатов использует привязанный собственный номер и allowFrom.

Канал платформы обмена сообщениями в текущей архитектуре каналов OpenClaw основан на WhatsApp Web (Baileys). Встроенный реестр чат-каналов не содержит отдельного канала обмена сообщениями WhatsApp от Twilio.

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

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

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

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

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

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

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

Доступ к группам имеет два уровня:

  1. Список разрешенных участников группы (channels.whatsapp.groups)
    • если groups опущен, все группы подходят
    • если groups присутствует, он действует как список разрешенных групп ("*" разрешено)
  2. Политика отправителя в группе (channels.whatsapp.groupPolicy + groupAllowFrom)
    • open: список разрешений отправителя обходится
    • allowlist: отправитель должен соответствовать groupAllowFrom (или *)
    • disabled: блокировать все входящие сообщения из групп

Резервный список разрешений отправителя:

  • если groupAllowFrom не задан, во время выполнения используется allowFrom, если он доступен
  • списки разрешений отправителя оцениваются до активации упоминания/ответа

Примечание: если блок channels.whatsapp вообще отсутствует, резервная политика группы во время выполнения — allowlist (с предупреждением в логе), даже если задан channels.defaults.groupPolicy.

Ответы в группах по умолчанию требуют упоминания.Обнаружение упоминаний включает:

  • явные упоминания идентичности бота в WhatsApp
  • настроенные шаблоны регулярных выражений для упоминаний (agents.list[].groupChat.mentionPatterns, резервный вариант messages.groupChat.mentionPatterns)
  • неявное обнаружение ответа-боту (отправитель ответа соответствует идентичности бота)

Примечание по безопасности:

  • цитирование/ответ удовлетворяет только условию упоминания; оно не предоставляет авторизацию отправителя
  • при groupPolicy: "allowlist" отправители, не входящие в список разрешений, все равно блокируются, даже если они отвечают на сообщение пользователя из списка разрешений

Команда активации на уровне сессии:

  • /activation mention
  • /activation always

activation обновляет состояние сессии (не глобальную конфигурацию). Она доступна только владельцу.

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

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

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

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

Входящие сообщения WhatsApp оборачиваются в общий входящий конверт.Если существует цитируемый ответ, контекст добавляется в такой форме:

[Ответ <sender> id:<stanzaId>]
<цитируемый текст или заполнитель медиа>
[/Ответ]

Метаданные ответа также заполняются, когда доступны (ReplyToId, ReplyToBody, ReplyToSender, JID/E.164 отправителя).

Входящие сообщения, содержащие только медиа, нормализуются с заполнителями, такими как:

  • <media:image>
  • <media:video>
  • <media:audio>
  • <media:document>
  • <media:sticker>

Полезные нагрузки местоположения и контактов нормализуются в текстовый контекст перед маршрутизацией.

Для групп необработанные сообщения могут буферизоваться и вводиться как контекст, когда бот наконец срабатывает.

  • лимит по умолчанию: 50
  • конфигурация: channels.whatsapp.historyLimit
  • резервный вариант: messages.groupChat.historyLimit
  • 0 отключает

Маркеры инъекции:

  • [Сообщения в чате с момента вашего последнего ответа - для контекста]
  • [Текущее сообщение - ответьте на него]

Квитанции о прочтении включены по умолчанию для принятых входящих сообщений WhatsApp.Отключить глобально:

{
  channels: {
    whatsapp: {
      sendReadReceipts: false,
    },
  },
}

Переопределение для конкретного аккаунта:

{
  channels: {
    whatsapp: {
      accounts: {
        work: {
          sendReadReceipts: false,
        },
      },
    },
  },
}

Ходы в собственном чате пропускают квитанции о прочтении, даже если они включены глобально.

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

  • лимит частей по умолчанию: channels.whatsapp.textChunkLimit = 4000

  • channels.whatsapp.chunkMode = "length" | "newline"

  • режим newline предпочитает границы абзацев (пустые строки), затем возвращается к безопасному разбиению по длине

  • поддерживает изображения, видео, аудио (голосовые сообщения PTT) и документы

  • audio/ogg переписывается в audio/ogg; codecs=opus для совместимости с голосовыми сообщениями

  • воспроизведение анимированных GIF поддерживается через gifPlayback: true при отправке видео

  • подписи применяются к первому медиафайлу при отправке ответов с несколькими медиафайлами

  • источник медиа может быть HTTP(S), file:// или локальными путями

  • лимит сохранения входящих медиа: channels.whatsapp.mediaMaxMb (по умолчанию 50)

  • лимит отправки исходящих медиа: channels.whatsapp.mediaMaxMb (по умолчанию 50)

  • переопределения для конкретного аккаунта используют channels.whatsapp.accounts..mediaMaxMb

  • изображения автоматически оптимизируются (изменение размера/качества) для соответствия лимитам

  • при сбое отправки медиа, резервный вариант для первого элемента отправляет текстовое предупреждение вместо тихого сброса ответа

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

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

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

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

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

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

  • идентификаторы аккаунтов берутся из channels.whatsapp.accounts

  • выбор аккаунта по умолчанию: default, если присутствует, иначе первый настроенный идентификатор аккаунта (отсортированный)

  • идентификаторы аккаунтов нормализуются внутренне для поиска

  • текущий путь аутентификации: ~/.openclaw/credentials/whatsapp//creds.json

  • резервный файл: creds.json.bak

  • устаревшая аутентификация по умолчанию в ~/.openclaw/credentials/ все еще распознается/мигрируется для потоков с аккаунтом по умолчанию

openclaw channels logout --channel whatsapp [--account ] очищает состояние аутентификации WhatsApp для этого аккаунта.В устаревших каталогах аутентификации oauth.json сохраняется, а файлы аутентификации Baileys удаляются.

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

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

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

Симптом: статус канала сообщает "не привязан".Исправление:

openclaw channels login --channel whatsapp
openclaw channels status

Симптом: привязанный аккаунт с повторяющимися отключениями или попытками переподключения.Исправление:

openclaw doctor
openclaw logs --follow

При необходимости повторно привяжите с помощью channels login.

Исходящие отправки быстро завершаются сбоем, когда для целевого аккаунта нет активного слушателя шлюза.Убедитесь, что шлюз запущен и аккаунт привязан.

Проверьте в следующем порядке:

  • groupPolicy
  • groupAllowFrom / allowFrom
  • записи в списке разрешенных групп groups
  • условие упоминания (requireMention + шаблоны упоминаний)
  • дублирующиеся ключи в openclaw.json (JSON5): более поздние записи переопределяют более ранние, поэтому оставляйте только одну groupPolicy для каждой области

Среда выполнения шлюза WhatsApp должна использовать Node. Bun помечается как несовместимый для стабильной работы шлюзов WhatsApp/Telegram.

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

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

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

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

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

TwitchZalo