​

WhatsApp (веб‑канал)

​

Быстрая настройка (для начинающих)

1. По возможности используйте отдельный номер телефона (рекомендуется).
2. Настройте WhatsApp в ~/.openclaw/openclaw.json.
3. Запустите openclaw channels login для сканирования QR‑кода (Связанные устройства).
4. Запустите gateway.

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

​

Цели

• Несколько аккаунтов WhatsApp (multi‑account) в одном процессе Gateway.
• Детерминированная маршрутизация: ответы возвращаются в WhatsApp, без маршрутизации по модели.
• Модель получает достаточный контекст для понимания ответов с цитированием.

​

Запись конфига

{
  channels: { whatsapp: { configWrites: false } },
}

​

Архитектура (кто чем владеет)

• Gateway владеет сокетом Baileys и циклом входящих.
• CLI / приложение для macOS общаются с gateway; прямого использования Baileys нет.
• Активный слушатель обязателен для исходящих отправок; иначе отправка быстро завершится ошибкой.

​

Получение номера телефона (два режима)

​

Выделенный номер (рекомендуется)

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

​

Личный номер (запасной вариант)

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

​

Советы по получению номера

• Локальная eSIM от мобильного оператора вашей страны (самый надёжный вариант)
  • Австрия: hot.at
  • Великобритания: giffgaff — бесплатная SIM, без контракта
• Предоплаченная SIM — дёшево, достаточно получить одно SMS для верификации

​

Почему не Twilio?

• Ранние сборки OpenClaw поддерживали интеграцию WhatsApp Business от Twilio.
• Номера WhatsApp Business плохо подходят для персонального ассистента.
• Meta применяет 24‑часовое окно ответа: если вы не отвечали последние 24 часа, бизнес‑номер не может инициировать новые сообщения.
• Высокий объём или «болтливое» использование вызывает агрессивные блокировки, так как бизнес‑аккаунты не предназначены для десятков сообщений персонального ассистента.
• Итог: ненадёжная доставка и частые блокировки, поэтому поддержка была удалена.

​

Вход + учётные данные

• Команда входа: openclaw channels login (QR через Связанные устройства).
• Вход для нескольких аккаунтов: openclaw channels login --account <id> (<id> = accountId).
• Аккаунт по умолчанию (если --account не указан): default, если задан, иначе первый настроенный id аккаунта (по сортировке).
• Учётные данные хранятся в ~/.openclaw/credentials/whatsapp/<accountId>/creds.json.
• Резервная копия в creds.json.bak (восстанавливается при повреждении).
• Совместимость с устаревшими версиями: старые установки хранили файлы Baileys напрямую в ~/.openclaw/credentials/.
• Выход: openclaw channels logout (или --account <id>) удаляет состояние аутентификации WhatsApp (но сохраняет общий oauth.json).
• Разлогиненный сокет ⇒ ошибка с инструкцией повторно привязать.

​

Входящий поток (DM + группы)

• События WhatsApp поступают из messages.upsert (Baileys).
• Слушатели входящих отключаются при завершении работы, чтобы избежать накопления обработчиков событий в тестах/перезапусках.
• Чаты статусов/рассылок игнорируются.
• Личные чаты используют E.164; группы — group JID.
• Политика DM: channels.whatsapp.dmPolicy управляет доступом к личным чатам (по умолчанию: pairing).
  • Сопряжение: неизвестные отправители получают код сопряжения (подтверждение через openclaw pairing approve whatsapp <code>; коды истекают через 1 час).
  • Открыто: требует, чтобы channels.whatsapp.allowFrom включал "*".
  • Ваш связанный номер WhatsApp считается доверенным, поэтому сообщения самому себе пропускают проверки channels.whatsapp.dmPolicy и channels.whatsapp.allowFrom.

​

Режим личного номера (запасной вариант)

• Исходящие DM никогда не вызывают ответы сопряжения (предотвращает спам контактам).
• Входящие неизвестные отправители всё равно следуют channels.whatsapp.dmPolicy.
• Режим self‑chat (allowFrom включает ваш номер) избегает авто‑уведомлений о прочтении и игнорирует JID упоминаний.
• Уведомления о прочтении отправляются для DM, не относящихся к self‑chat.

​

Уведомления о прочтении

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

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

• Режим self‑chat всегда пропускает уведомления о прочтении.

​

WhatsApp FAQ: отправка сообщений + сопряжение

• Первое DM от нового отправителя возвращает короткий код (сообщение не обрабатывается).
• Подтвердите командой: openclaw pairing approve whatsapp <code> (список — openclaw pairing list whatsapp).
• Коды истекают через 1 час; ожидающие запросы ограничены 3 на канал.

​

Нормализация сообщений (что видит модель)

• Body — текущее тело сообщения с конвертом.
• Контекст цитируемого ответа всегда добавляется:
  [Replying to +1555 id:ABC123]
  <quoted text or <media:...>>
  [/Replying]
  
• Также устанавливаются метаданные ответа:
  • ReplyToId = stanzaId
  • ReplyToBody = цитируемое тело или плейсхолдер медиа
  • ReplyToSender = E.164, если известно
• Входящие сообщения только с медиа используют плейсхолдеры:
  • <media:image|video|audio|document|sticker>

​

Группы

• Группы сопоставляются с сессиями agent:<agentId>:whatsapp:group:<jid>.
• Политика групп: channels.whatsapp.groupPolicy = open|disabled|allowlist (по умолчанию allowlist).
• Режимы активации:
  • mention (по умолчанию): требуется @упоминание или совпадение с regex.
  • always: всегда срабатывает.
• /activation mention|always — только для владельца и должно быть отправлено отдельным сообщением.
• Владелец = channels.whatsapp.allowFrom (или собственный E.164, если не задан).
• Инъекция истории (только ожидающие):
  • Недавние необработанные сообщения (по умолчанию 50) вставляются под: [Chat messages since your last reply - for context] (сообщения, уже находящиеся в сессии, не переинжектируются)
  • Текущее сообщение — под: [Current message - respond to this]
  • Добавляется суффикс отправителя: [from: Name (+E164)]
• Метаданные группы кэшируются 5 минут (тема + участники).

​

Доставка ответов (трединг)

• WhatsApp Web отправляет стандартные сообщения (в текущем gateway нет трединга цитируемых ответов).
• Теги ответов на этом канале игнорируются.

​

Реакции‑подтверждения (авто‑реакция при получении)

{
  "whatsapp": {
    "ackReaction": {
      "emoji": "👀",
      "direct": true,
      "group": "mentions"
    }
  }
}

• emoji (string): Emoji для подтверждения (например, ”👀”, ”✅”, ”📨”). Пусто или не задано = функция отключена.
• direct (boolean, по умолчанию: true): Отправлять реакции в личных/DM чатах.
• group (string, по умолчанию: "mentions"): Поведение в группах:
  • "always": реагировать на все сообщения группы (даже без @упоминания)
  • "mentions": реагировать только при @упоминании бота
  • "never": никогда не реагировать в группах

{
  "whatsapp": {
    "accounts": {
      "work": {
        "ackReaction": {
          "emoji": "✅",
          "direct": false,
          "group": "always"
        }
      }
    }
  }
}

• Реакции отправляются немедленно при получении сообщения, до индикаторов набора или ответов бота.
• В группах с requireMention: false (активация: всегда) group: "mentions" будет реагировать на все сообщения (не только @упоминания).
• Fire‑and‑forget: сбои реакций логируются, но не мешают ответу бота.
• Для групповых реакций автоматически включается JID участника.
• WhatsApp игнорирует messages.ackReaction; используйте channels.whatsapp.ackReaction.

​

Инструмент агента (реакции)

• Инструмент: whatsapp с действием react (chatJid, messageId, emoji, необязательный remove).
• Необязательно: participant (отправитель в группе), fromMe (реакция на собственное сообщение), accountId (multi‑account).
• Семантика удаления реакций: см. /tools/reactions.
• Ограничение инструмента: channels.whatsapp.actions.reactions (по умолчанию: включено).

​

Ограничения

• Исходящий текст разбивается на фрагменты до channels.whatsapp.textChunkLimit (по умолчанию 4000).
• Необязательное разбиение по переводам строк: установите channels.whatsapp.chunkMode="newline", чтобы сначала делить по пустым строкам (границы абзацев), затем по длине.
• Сохранение входящих медиа ограничено channels.whatsapp.mediaMaxMb (по умолчанию 50 МБ).
• Исходящие медиа ограничены agents.defaults.mediaMaxMb (по умолчанию 5 МБ).

​

Исходящая отправка (текст + медиа)

• Использует активный веб‑слушатель; ошибка, если gateway не запущен.
• Разбиение текста: максимум 4k на сообщение (настраивается через channels.whatsapp.textChunkLimit, необязательный channels.whatsapp.chunkMode).
• Медиа:
  • Поддерживаются изображения/видео/аудио/документы.
  • Аудио отправляется как PTT; audio/ogg ⇒ audio/ogg; codecs=opus.
  • Подпись только у первого медиа‑элемента.
  • Получение медиа поддерживает HTTP(S) и локальные пути.
  • Анимированные GIF: WhatsApp ожидает MP4 с gifPlayback: true для зацикленного воспроизведения.
    • CLI: openclaw message send --media <mp4> --gif-playback
    • Gateway: параметры send включают gifPlayback: true

​

Голосовые заметки (PTT‑аудио)

• Лучший формат: OGG/Opus. OpenClaw переписывает audio/ogg в audio/ogg; codecs=opus.
• [[audio_as_voice]] игнорируется для WhatsApp (аудио уже отправляется как голосовая заметка).

​

Лимиты медиа + оптимизация

• Лимит исходящих по умолчанию: 5 МБ (на элемент).
• Переопределение: agents.defaults.mediaMaxMb.
• Изображения автоматически оптимизируются в JPEG под лимит (изменение размера + подбор качества).
• Слишком большие медиа ⇒ ошибка; ответ с медиа откатывается к текстовому предупреждению.

​

Heartbeats

• Heartbeat Gateway логирует состояние соединения (web.heartbeatSeconds, по умолчанию 60 с).
• Heartbeat агента можно настроить для каждого агента (agents.list[].heartbeat) или глобально через agents.defaults.heartbeat (используется, если нет настроек на агента).
  • Использует настроенный промпт heartbeat (по умолчанию: Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.) + поведение пропуска HEARTBEAT_OK.
  • Доставка по умолчанию — последний использованный канал (или настроенная цель).

​

Поведение переподключения

• Политика backoff: web.reconnect:
  • initialMs, maxMs, factor, jitter, maxAttempts.
• При достижении maxAttempts веб‑мониторинг останавливается (деградация).
• Разлогинен ⇒ остановка и требование повторной привязки.

​

Быстрая карта конфига

• channels.whatsapp.dmPolicy (политика DM: pairing/allowlist/open/disabled).
• channels.whatsapp.selfChatMode (настройка same‑phone; бот использует ваш личный номер WhatsApp).
• channels.whatsapp.allowFrom (allowlist DM). WhatsApp использует номера E.164 (без имён пользователей).
• channels.whatsapp.mediaMaxMb (лимит сохранения входящих медиа).
• channels.whatsapp.ackReaction (авто‑реакция при получении: {emoji, direct, group}).
• channels.whatsapp.accounts.<accountId>.* (настройки для аккаунта + необязательный authDir).
• channels.whatsapp.accounts.<accountId>.mediaMaxMb (лимит входящих медиа для аккаунта).
• channels.whatsapp.accounts.<accountId>.ackReaction (переопределение реакции‑подтверждения для аккаунта).
• channels.whatsapp.groupAllowFrom (allowlist отправителей группы).
• channels.whatsapp.groupPolicy (политика групп).
• channels.whatsapp.historyLimit / channels.whatsapp.accounts.<accountId>.historyLimit (контекст истории группы; 0 отключает).
• channels.whatsapp.dmHistoryLimit (лимит истории DM в ходах пользователя). Переопределения для пользователя: channels.whatsapp.dms["<phone>"].historyLimit.
• channels.whatsapp.groups (allowlist групп + умолчания для gating по упоминаниям; используйте "*", чтобы разрешить всё)
• channels.whatsapp.actions.reactions (ограничение реакций инструмента WhatsApp).
• agents.list[].groupChat.mentionPatterns (или messages.groupChat.mentionPatterns)
• messages.groupChat.historyLimit
• channels.whatsapp.messagePrefix (входящий префикс; для аккаунта: channels.whatsapp.accounts.<accountId>.messagePrefix; устаревшее: messages.messagePrefix)
• messages.responsePrefix (исходящий префикс)
• agents.defaults.mediaMaxMb
• agents.defaults.heartbeat.every
• agents.defaults.heartbeat.model (необязательное переопределение)
• agents.defaults.heartbeat.target
• agents.defaults.heartbeat.to
• agents.defaults.heartbeat.session
• agents.list[].heartbeat.* (переопределения для агента)
• session.* (scope, idle, store, mainKey)
• web.enabled (отключить запуск канала при false)
• web.heartbeatSeconds
• web.reconnect.*

​

Логи + устранение неполадок

• Подсистемы: whatsapp/inbound, whatsapp/outbound, web-heartbeat, web-reconnect.
• Файл логов: /tmp/openclaw/openclaw-YYYY-MM-DD.log (настраивается).
• Руководство по устранению неполадок: Устранение неполадок Gateway.

​

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

• Симптом: channels status показывает linked: false или предупреждает «Not linked».
• Исправление: выполните openclaw channels login на хосте шлюза Gateway и отсканируйте QR (WhatsApp → Settings → Linked Devices).

• Симптом: channels status показывает running, disconnected или предупреждает «Linked but disconnected».
• Исправление: openclaw doctor (или перезапустите gateway). Если проблема сохраняется, перепривяжите через channels login и проверьте openclaw logs --follow.

• Bun не рекомендуется. WhatsApp (Baileys) и Telegram ненадёжны на Bun. Запускайте gateway на Node. (См. примечание к началу работы.)