WhatsApp

Статус: готово к промышленной эксплуатации через WhatsApp Web (Baileys). Gateway управляет связанными сеансами; отдельного канала Twilio WhatsApp нет.

Установка

openclaw onboard и openclaw channels add --channel whatsapp предлагают установить плагин при его первом выборе; openclaw channels login --channel whatsapp предлагает тот же процесс установки, если плагин отсутствует. В рабочих копиях для разработки используется локальный путь к плагину; при стабильной или бета-установке сначала устанавливается @openclaw/whatsapp из ClawHub, а при неудаче используется npm. Среда выполнения WhatsApp поставляется вне основного npm-пакета OpenClaw, поэтому её зависимости среды выполнения остаются во внешнем плагине. Установка вручную:

openclaw plugins install clawhub:@openclaw/whatsapp

Используйте пакет npm без префикса (@openclaw/whatsapp) только как резервный вариант для реестра; закрепляйте точную версию только для воспроизводимой установки.

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

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

openclaw channels login --channel whatsapp

openclaw channels login --channel whatsapp --account work

openclaw channels add --channel whatsapp --account work --auth-dir /path/to/wa-authopenclaw channels login --channel whatsapp --account work

openclaw gateway

openclaw pairing list whatsappopenclaw pairing approve whatsapp <CODE>

Схемы развёртывания

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

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

• Gateway управляет сокетом WhatsApp и циклом повторного подключения.
• Сторожевой механизм независимо отслеживает два сигнала: активность транспорта WhatsApp Web на низком уровне и активность сообщений приложения. Тихий, но подключённый сеанс не перезапускается только из-за того, что в последнее время не поступали сообщения; принудительное повторное подключение происходит, только если транспортные кадры перестают поступать в течение фиксированного внутреннего интервала (не настраивается пользователем) или сообщения приложения отсутствуют дольше четырёхкратного обычного тайм-аута сообщений. Сразу после повторного подключения недавно активного сеанса для первого интервала используется более короткий обычный тайм-аут сообщений вместо четырёхкратного интервала. OpenClaw может автоматически отвечать на офлайн-сообщения, которые Baileys доставляет в начале такого повторного подключения, в пределах срока дедупликации идентификаторов входящих сообщений; при первоначальном запуске сохраняется короткая защита от устаревшей истории.
• Временные параметры сокета Baileys явно задаются в web.whatsapp.*: keepAliveIntervalMs (интервал проверки связи приложения), connectTimeoutMs (тайм-аут начального рукопожатия), defaultQueryTimeoutMs (ожидание запросов Baileys, а также тайм-ауты OpenClaw для исходящей отправки, статуса присутствия и входящих подтверждений прочтения).
• Для исходящей отправки требуется активный слушатель WhatsApp для целевой учётной записи; в противном случае отправка немедленно завершается ошибкой.
• При отправке в группы добавляются собственные метаданные упоминаний для токенов @+<digits> и @<digits> (в тексте и подписях к медиафайлам), если токен соответствует текущим метаданным участника, включая группы на основе LID.
• Чаты статусов и рассылок (@status, @broadcast) игнорируются.
• В личных чатах применяются правила сеансов личных сообщений (session.dmScope; значение по умолчанию main объединяет личные сообщения в основном сеансе агента). Групповые сеансы изолируются по JID (agent:<agentId>:whatsapp:group:<jid>).
• Каналы и рассылки WhatsApp могут быть явно указаны в качестве целей исходящей отправки через их собственный JID @newsletter, при этом используются метаданные сеанса канала (agent:<agentId>:whatsapp:channel:<jid>), а не семантика личных сообщений.
• Транспорт WhatsApp Web учитывает стандартные переменные среды прокси на узле Gateway (HTTPS_PROXY, HTTP_PROXY, NO_PROXY и варианты в нижнем регистре). Предпочитайте настройку прокси на уровне узла параметрам отдельных каналов.
• Если включён messages.removeAckAfterReply, OpenClaw удаляет реакцию подтверждения после доставки видимого ответа.

Вызов текущего отправителя с помощью MeowCaller (экспериментальная функция)

Плагин может предоставлять whatsapp_call в запусках агента, инициированных из WhatsApp. Он использует MeowCaller, чтобы совершить голосовой вызов WhatsApp текущему авторизованному отправителю и воспроизвести сообщение OpenClaw, синтезированное посредством TTS, после ответа. У инструмента нет параметра номера назначения, поэтому запрос не может перенаправить вызов. По умолчанию отключено.

{"channels": {"whatsapp": {  "actions": {    "calls": true  }}}}

git clone --branch feat/send-only-notify https://github.com/steipete/meowcaller.gitcd meowcallergit checkout 752050471fc2bf7a8cdfbf7dbd3cd4e865d85d3fmkdir -p "$HOME/.local/bin"go build -o "$HOME/.local/bin/meowcaller" ./cmd/meowcaller

state_dir="$HOME/.openclaw/credentials/whatsapp-calls/default"mkdir -p "$state_dir"chmod 700 "$state_dir"meowcaller pair --store "$state_dir/wa-voip.db"

Ограничения: только исходящие аудиовызовы один на один, без произвольных номеров назначения, без общей аутентификации с подключением чата, без вызовов самому себе в режиме личного номера или чата с самим собой, длительность синтезированного аудио ограничена 60 секундами, подтверждение слышимости на стороне телефона отсутствует помимо завершения этапов ответа, воспроизведения и завершения вызова в MeowCaller, а OpenClaw останавливает сопутствующий процесс по истечении ограниченного интервала в 115–175 секунд (охватывающего этапы подключения, ответа, воспроизведения и завершения работы MeowCaller).

Запросы на одобрение

WhatsApp может отображать запросы на одобрение выполнения команд и действий плагинов в виде реакций 👍/👎, управляемых конфигурацией пересылки одобрений верхнего уровня:

{  approvals: {    exec: {      enabled: true,      mode: "session",    },    plugin: {      enabled: true,      mode: "targets",      targets: [{ channel: "whatsapp", to: "+15551234567" }],    },  },}

approvals.exec и approvals.plugin независимы друг от друга; включение WhatsApp в качестве канала только подключает транспорт и ничего не отправляет, если соответствующий тип одобрений не включён и не направлен туда. Режим сеанса доставляет собственные одобрения с помощью эмодзи только для запросов на одобрение, поступивших из WhatsApp. Режим целей использует общий конвейер пересылки для явно заданных целей и не создаёт отдельную рассылку личных сообщений утверждающим лицам.

Для реакций одобрения WhatsApp требуется явно указать утверждающих лиц в allowFrom (или "*"). defaultTo задаёт обычные цели сообщений по умолчанию, а не список утверждающих лиц. Команды /approve, введённые вручную, по-прежнему проходят обычную проверку авторизации отправителя WhatsApp перед обработкой одобрения.

Хуки плагинов и конфиденциальность

Входящие сообщения WhatsApp могут содержать личные сведения, номера телефонов, идентификаторы групп, имена отправителей и поля корреляции сеансов. WhatsApp не рассылает входящие полезные нагрузки хука message_received плагинам, если вы явно не разрешите это:

{  channels: {    whatsapp: {      pluginHooks: {        messageReceived: true,      },    },  },}

Ограничьте разрешение одной учётной записью в channels.whatsapp.accounts.<id>.pluginHooks.messageReceived. Включайте его только для плагинов, которым вы доверяете содержимое и идентификаторы входящих сообщений WhatsApp.

Управление доступом и активация

Настроенные привязки ACP

WhatsApp поддерживает постоянные привязки ACP через bindings[] верхнего уровня:

{  bindings: [    {      type: "acp",      agentId: "codex",      match: {        channel: "whatsapp",        accountId: "work",        peer: { kind: "direct", id: "+15555550123" },      },    },    {      type: "acp",      agentId: "codex",      match: {        channel: "whatsapp",        accountId: "work",        peer: { kind: "group", id: "120363424282127706@g.us" },      },    },  ],}

Личные чаты сопоставляются по номерам E.164, а группы — по групповым JID WhatsApp. Списки разрешённых групп, политика отправителей и условия активации по упоминанию выполняются до того, как OpenClaw обеспечит существование привязанного сеанса ACP. Совпавшая привязка становится владельцем маршрута — широковещательные группы не направляют этот ход в обычные сеансы WhatsApp.

Поведение личного номера и чата с собой

Когда привязанный собственный номер также присутствует в allowFrom, активируются защитные меры для чата с собой: отключаются уведомления о прочтении для сообщений в чате с собой, игнорируется автоматический запуск по JID упоминания, который привёл бы к упоминанию самого себя, а ответы по умолчанию направляются в [{identity.name}] (или [openclaw]), если messages.responsePrefix не задан.

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

[Replying to <sender> id:<stanzaId>]<quoted body or media placeholder>[/Replying]

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

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

Цитирование при ответе

channels.whatsapp.replyToMode управляет встроенным цитированием ответов (исходящие ответы визуально цитируют входящее сообщение):

Переопределение для отдельной учётной записи: channels.whatsapp.accounts.<id>.replyToMode.

{ channels: { whatsapp: { replyToMode: "first" } } }

Уровень реакций

channels.whatsapp.reactionLevel определяет, насколько широко агент использует реакции с эмодзи:

Переопределение для отдельной учётной записи: channels.whatsapp.accounts.<id>.reactionLevel.

{ channels: { whatsapp: { reactionLevel: "ack" } } }

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

channels.whatsapp.ackReaction отправляет немедленную реакцию при получении входящего сообщения с учётом reactionLevel (подавляется при "off"):

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

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

Реакции состояния жизненного цикла

Задайте messages.statusReactions.enabled: true, чтобы WhatsApp во время хода заменял реакцию подтверждения вместо сохранения статичного эмодзи получения, последовательно переключаясь между такими состояниями, как ожидание в очереди, размышление, активность инструментов, Compaction, завершение и ошибка:

{  messages: {    statusReactions: {      enabled: true,      emojis: {        deploy: "🛫",        build: "🏗️",        concierge: "💁",      },    },  },}

Примечания: channels.whatsapp.ackReaction по-прежнему определяет доступность для личных сообщений и групп; состояние ожидания в очереди использует тот же фактический эмодзи, что и обычные реакции подтверждения; WhatsApp предоставляет один слот реакции бота на сообщение, поэтому обновления жизненного цикла заменяют текущую реакцию на месте; messages.removeAckAfterReply: true удаляет финальную реакцию состояния после настроенного периода удержания состояния завершения или ошибки; категории эмодзи инструментов включают tool, coding, web, deploy, build и concierge.

Несколько учётных записей и учётные данные

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

• Инструменты агента поддерживают действие реакции WhatsApp (react).
• Ограничители действий: channels.whatsapp.actions.reactions, channels.whatsapp.actions.polls (для существующих действий по умолчанию используется true), channels.whatsapp.actions.calls (по умолчанию false, см. MeowCaller выше).
• Запись конфигурации, инициированная каналом, по умолчанию включена; отключите её через channels.whatsapp.configWrites: false.

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

openclaw channels login --channel whatsappopenclaw channels status

{  web: {    whatsapp: {      keepAliveIntervalMs: 15000,      connectTimeoutMs: 60000,      defaultQueryTimeoutMs: 60000,    },  },}

openclaw channels status --probeopenclaw doctoropenclaw logs --followopenclaw gateway status

cp -a ~/.openclaw/credentials/whatsapp/<accountId> \  ~/.openclaw/credentials/whatsapp/<accountId>.bakopenclaw channels logout --channel whatsapp --account <accountId>openclaw channels login --channel whatsapp --account <accountId>

Системные промпты

WhatsApp поддерживает системные промпты в стиле Telegram для групп и личных чатов через карты groups и direct.

Разрешение для групповых сообщений: сначала определяется действующая карта groups — если в учётной записи вообще определён собственный ключ groups, он полностью заменяет корневую карту groups (без глубокого слияния). Затем поиск промпта выполняется в единственной результирующей карте:

1. Промпт для конкретной группы (groups["<groupId>"].systemPrompt): используется, когда запись группы существует и в ней определён ключ systemPrompt. Пустая строка ("") подавляет подстановочный знак, и промпт не применяется.
2. Промпт с подстановочным знаком для групп (groups["*"].systemPrompt): используется, когда запись конкретной группы отсутствует или существует без ключа systemPrompt.

Разрешение для личных сообщений выполняется по идентичной схеме для карты direct и direct["*"].

Отличие от Telegram: Telegram подавляет корневой groups для каждой учётной записи в конфигурации с несколькими учётными записями (даже если у учётной записи нет собственного groups), чтобы бот не получал сообщения из групп, в которых он не состоит. WhatsApp не применяет эту защиту — корневые groups/direct наследуются любой учётной записью без собственного переопределения независимо от количества учётных записей. Если в конфигурации WhatsApp с несколькими учётными записями нужны отдельные промпты для каждой учётной записи, явно определите полную карту в каждой из них.

Важные особенности поведения:

• channels.whatsapp.groups одновременно является картой конфигурации для отдельных групп и списком разрешений групп на уровне чата. Как в корневой области, так и в области учётной записи groups["*"] означает «разрешены все группы» для этой области.
• Добавляйте подстановочный знак systemPrompt, только если вы уже хотите разрешить все группы в этой области. Чтобы оставить доступным только фиксированный набор идентификаторов групп, повторите промпт в каждой явно разрешённой записи вместо использования groups["*"].
• Допуск группы и авторизация отправителя проверяются отдельно. groups["*"] расширяет перечень групп, сообщения из которых передаются в обработку групп; это не авторизует всех отправителей в этих группах — их авторизация по-прежнему управляется через groupPolicy/groupAllowFrom.
• channels.whatsapp.direct не имеет аналогичного побочного эффекта для личных сообщений: direct["*"] лишь предоставляет конфигурацию по умолчанию после того, как личное сообщение уже допущено согласно dmPolicy совместно с allowFrom или правилами хранилища сопряжений.

Пример:

{  channels: {    whatsapp: {      groups: {        // Используйте, только если в корневой области должны быть разрешены все группы.        // Применяется ко всем учётным записям без собственной карты groups.        "*": { systemPrompt: "Промпт по умолчанию для всех групп." },      },      direct: {        // Применяется ко всем учётным записям без собственной карты direct.        "*": { systemPrompt: "Промпт по умолчанию для всех личных чатов." },      },      accounts: {        work: {          groups: {            // Эта учётная запись определяет собственную карту groups, поэтому корневая            // карта groups полностью заменяется. Чтобы сохранить подстановочный знак, явно определите "*" и здесь.            "120363406415684625@g.us": {              requireMention: false,              systemPrompt: "Сосредоточьтесь на управлении проектом.",            },            // Используйте, только если в этой учётной записи должны быть разрешены все группы.            "*": { systemPrompt: "Промпт по умолчанию для рабочих групп." },          },          direct: {            // Эта учётная запись определяет собственную карту direct, поэтому корневые записи direct            // полностью заменяются. Чтобы сохранить подстановочный знак, явно определите "*" и здесь.            "+15551234567": { systemPrompt: "Промпт для конкретного рабочего личного чата." },            "*": { systemPrompt: "Промпт по умолчанию для рабочих личных чатов." },          },        },      },    },  },}

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

Основной справочник: Справочник по конфигурации — WhatsApp

Связанные разделы

• Сопряжение
• Группы
• Безопасность
• Маршрутизация каналов
• Маршрутизация между несколькими агентами
• Устранение неполадок