WhatsApp

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

Установка (по требованию)

• Онбординг (openclaw onboard) и openclaw channels add --channel whatsapp предлагают установить WhatsApp Plugin при первом выборе.
• openclaw channels login --channel whatsapp также предлагает поток установки, когда Plugin еще не установлен.
• Dev-канал + git checkout: по умолчанию используется локальный путь Plugin.
• Stable/Beta: сначала устанавливает официальный Plugin @openclaw/whatsapp из ClawHub, с npm как резервным вариантом.
• Среда выполнения WhatsApp распространяется вне основного npm-пакета OpenClaw, чтобы специфичные для WhatsApp зависимости среды выполнения оставались во внешнем Plugin.

Ручная установка остается доступной:

openclaw plugins install clawhub:@openclaw/whatsapp

Используйте простой npm-пакет (@openclaw/whatsapp) только когда нужен резервный вариант через registry. Фиксируйте точную версию только когда нужна воспроизводимая установка.

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

{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 и циклом переподключения.
• Watchdog переподключения использует активность транспорта WhatsApp Web, а не только объем входящих сообщений приложения, поэтому тихая сессия связанного устройства не перезапускается только потому, что никто недавно не отправлял сообщения. Более длинный лимит тишины приложения все равно принудительно выполняет переподключение, если транспортные frames продолжают поступать, но сообщения приложения не обрабатываются в течение окна watchdog; после временного переподключения для недавно активной сессии эта проверка тишины приложения использует обычный тайм-аут сообщений для первого окна восстановления.
• Тайминги сокета Baileys явно задаются в web.whatsapp.*: keepAliveIntervalMs управляет application ping WhatsApp Web, connectTimeoutMs управляет тайм-аутом начального handshake, а defaultQueryTimeoutMs управляет ожиданиями запросов Baileys, а также локальными границами OpenClaw для исходящей отправки/presence и операций входящих read receipt.
• Для исходящих отправок требуется активный слушатель WhatsApp для целевой учетной записи.
• Групповые отправки добавляют нативные метаданные упоминаний для токенов @+<digits> и @<digits> в тексте и подписях к медиа, когда токен соответствует текущим метаданным участников WhatsApp, включая группы на базе LID.
• Статусы и broadcast-чаты игнорируются (@status, @broadcast).
• Watchdog переподключения следует активности транспорта WhatsApp Web, а не только объему входящих сообщений приложения: тихие сессии связанного устройства остаются активными, пока транспортные frames продолжаются, но остановка транспорта принудительно вызывает переподключение задолго до более позднего пути удаленного отключения.
• Прямые чаты используют правила DM-сессий (session.dmScope; значение по умолчанию main сворачивает DM в основную сессию агента).
• Групповые сессии изолированы (agent:<agentId>:whatsapp:group:<jid>).
• WhatsApp Channels/Newsletters могут быть явными исходящими целями со своим нативным JID @newsletter. Исходящие отправки newsletter используют метаданные сессии канала (agent:<agentId>:whatsapp:channel:<jid>), а не семантику DM-сессий.
• Транспорт WhatsApp Web учитывает стандартные переменные окружения proxy на хосте Gateway (HTTPS_PROXY, HTTP_PROXY, NO_PROXY / варианты в нижнем регистре). Предпочитайте конфигурацию proxy на уровне хоста настройкам proxy, специфичным для канала WhatsApp.
• Когда messages.removeAckAfterReply включен, OpenClaw очищает ack-реакцию WhatsApp после доставки видимого ответа.

Запросы подтверждения

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

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

approvals.exec и approvals.plugin независимы. Включение WhatsApp как канала только связывает транспорт; оно не отправляет запросы подтверждения, если соответствующее семейство подтверждений не включено и не маршрутизируется в WhatsApp. Режим session доставляет нативные emoji-подтверждения только для подтверждений, которые исходят из WhatsApp. Режим target использует общий pipeline пересылки для явных целей WhatsApp и не создает отдельную рассылку approver-DM.

Реакции подтверждения WhatsApp требуют явных approvers WhatsApp из allowFrom или "*". defaultTo управляет обычными целями сообщений по умолчанию; это не approver подтверждений. Ручные команды /approve все равно проходят через обычный путь авторизации отправителя WhatsApp перед разрешением подтверждения.

Хуки Plugin и приватность

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

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

Вы можете ограничить включение одной учетной записью:

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

Включайте это только для Plugins, которым вы доверяете получение содержимого и идентификаторов входящих сообщений 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, такими как +15555550123.
• Группы сопоставляются с JID групп WhatsApp, такими как 120363424282127706@g.us.
• Списки разрешённых групп, политика отправителей и шлюзы упоминаний или активации выполняются до того, как OpenClaw проверяет наличие настроенной сессии ACP.
• Совпавшая настроенная привязка ACP владеет маршрутом. Группы рассылки WhatsApp не рассылают этот ход обычным сессиям WhatsApp.

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

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

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

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

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

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

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

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

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

WhatsApp поддерживает нативное цитирование ответов, когда исходящие ответы видимо цитируют входящее сообщение. Управляйте этим с помощью channels.whatsapp.replyToMode.

По умолчанию используется "off". Переопределения для отдельных аккаунтов используют channels.whatsapp.accounts.<id>.replyToMode.

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

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

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

По умолчанию: "minimal".

Переопределения для отдельных аккаунтов используют channels.whatsapp.accounts.<id>.reactionLevel.

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

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

WhatsApp поддерживает немедленные реакции ack при получении входящего сообщения через channels.whatsapp.ackReaction. Реакции ack ограничиваются reactionLevel — они подавляются, когда reactionLevel равен "off".

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

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

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

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

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

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

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

• channels.whatsapp.ackReaction по-прежнему управляет тем, доступны ли реакции статуса для прямых сообщений и групп.
• Реакция статуса в очереди использует тот же эффективный emoji ack, что и обычные реакции ack.
• У WhatsApp есть один слот реакции бота на сообщение, поэтому обновления жизненного цикла заменяют текущую реакцию на месте.
• messages.removeAckAfterReply: true очищает финальную реакцию статуса после настроенной задержки done/error.
• Категории emoji инструментов включают tool, coding, web, deploy, build и concierge.

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

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

• Поддержка инструментов агента включает действие реакции WhatsApp (react).
• Шлюзы действий:
  • channels.whatsapp.actions.reactions
  • channels.whatsapp.actions.polls
• Записи конфигурации, инициированные каналом, включены по умолчанию (отключение через 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 определен. Если systemPrompt является пустой строкой (""), подстановочный вариант подавляется и системный промпт не применяется.
2. Подстановочный системный промпт для групп (groups["*"].systemPrompt): используется, когда запись конкретной группы полностью отсутствует в карте или когда она существует, но не определяет ключ systemPrompt.

Иерархия разрешения для прямых сообщений:

Эффективная карта direct определяется первой: если учетная запись определяет собственный direct, он полностью заменяет корневую карту direct (без глубокого слияния). Затем поиск промпта выполняется в получившейся единственной карте:

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

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

Важное поведение:

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

Пример:

{  channels: {    whatsapp: {      groups: {        // Use only if all groups should be admitted at the root scope.        // Applies to all accounts that do not define their own groups map.        "*": { systemPrompt: "Default prompt for all groups." },      },      direct: {        // Applies to all accounts that do not define their own direct map.        "*": { systemPrompt: "Default prompt for all direct chats." },      },      accounts: {        work: {          groups: {            // This account defines its own groups, so root groups are fully            // replaced. To keep a wildcard, define "*" explicitly here too.            "120363406415684625@g.us": {              requireMention: false,              systemPrompt: "Focus on project management.",            },            // Use only if all groups should be admitted in this account.            "*": { systemPrompt: "Default prompt for work groups." },          },          direct: {            // This account defines its own direct map, so root direct entries are            // fully replaced. To keep a wildcard, define "*" explicitly here too.            "+15551234567": { systemPrompt: "Prompt for a specific work direct chat." },            "*": { systemPrompt: "Default prompt for work direct chats." },          },        },      },    },  },}

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

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

• Справочник конфигурации - WhatsApp

Наиболее важные поля WhatsApp:

• доступ: dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups
• доставка: textChunkLimit, chunkMode, mediaMaxMb, sendReadReceipts, ackReaction, reactionLevel
• несколько учетных записей: accounts.<id>.enabled, accounts.<id>.authDir, переопределения на уровне учетной записи
• операции: configWrites, debounceMs, web.enabled, web.heartbeatSeconds, web.reconnect.*, web.whatsapp.*
• поведение сессии: session.dmScope, historyLimit, dmHistoryLimit, dms.<id>.historyLimit
• промпты: groups.<id>.systemPrompt, groups["*"].systemPrompt, direct.<id>.systemPrompt, direct["*"].systemPrompt

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

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