WhatsApp

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Встановлення (на вимогу)

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

openclaw plugins install @openclaw/whatsapp

winget install --id Git.Git -e

​

Швидке налаштування

{
  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-auth
openclaw channels login --channel whatsapp --account work

openclaw gateway

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>

​

Шаблони розгортання

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

​

Модель виконання

• Gateway керує сокетом WhatsApp і циклом повторного підключення.
• Watchdog повторного підключення використовує активність транспорту WhatsApp Web, а не лише обсяг вхідних повідомлень застосунку, тому тихий сеанс прив’язаного пристрою не перезапускається лише через те, що останнім часом ніхто не надсилав повідомлень. Довший ліміт тиші застосунку все одно примусово виконує повторне підключення, якщо транспортні кадри продовжують надходити, але жодні повідомлення застосунку не обробляються протягом вікна watchdog; після тимчасового повторного підключення для нещодавно активного сеансу ця перевірка тиші застосунку використовує звичайний таймаут повідомлень для першого вікна відновлення.
• Таймінги сокета Baileys явно задаються в web.whatsapp.*: keepAliveIntervalMs керує ping-ами застосунку WhatsApp Web, connectTimeoutMs керує таймаутом початкового handshake, а defaultQueryTimeoutMs керує таймаутами запитів Baileys.
• Вихідні надсилання потребують активного слухача WhatsApp для цільового облікового запису.
• Групові надсилання додають нативні метадані згадок для токенів @+<digits> і @<digits> у тексті та підписах медіа, коли токен збігається з поточними метаданими учасників WhatsApp, включно з групами на базі LID.
• Чати статусів і трансляцій ігноруються (@status, @broadcast).
• Watchdog повторного підключення відстежує активність транспорту WhatsApp Web, а не лише обсяг вхідних повідомлень застосунку: тихі сеанси прив’язаного пристрою залишаються активними, доки транспортні кадри продовжують надходити, але зупинка транспорту примусово викликає повторне підключення задовго до пізнішого шляху віддаленого відключення.
• Прямі чати використовують правила 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 після доставки видимої відповіді.

​

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

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

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

​

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

​

Особистий номер і поведінка чату із самим собою

• пропускати підтвердження прочитання для ходів чату із самим собою
• ігнорувати поведінку автоматичного запуску mention-JID, яка інакше ping-ала б вас самих
• якщо 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,
        },
      },
    },
  },
}

​

Доставка, розбиття на фрагменти та медіа

​

Цитування відповідей

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

​

Рівень реакцій

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

​

Реакції підтвердження

{
  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).

​

Усунення несправностей

openclaw channels login --channel whatsapp
openclaw channels status

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

openclaw doctor
openclaw logs --follow

​

Системні prompts

1. Системний prompt для конкретної групи (groups["<groupId>"].systemPrompt): використовується, коли конкретний запис групи існує в мапі і його ключ systemPrompt визначений. Якщо systemPrompt є порожнім рядком (""), wildcard пригнічується, і системний prompt не застосовується.
2. Wildcard системного prompt групи (groups["*"].systemPrompt): використовується, коли конкретний запис групи повністю відсутній у мапі або коли він існує, але не визначає ключ systemPrompt.

1. Системний промпт для конкретного direct (direct["<peerId>"].systemPrompt): використовується, коли конкретний запис peer існує в мапі і його ключ systemPrompt визначено. Якщо systemPrompt є порожнім рядком (""), wildcard пригнічується, і системний промпт не застосовується.
2. Wildcard системного промпту direct (direct["*"].systemPrompt): використовується, коли конкретний запис peer повністю відсутній у мапі або коли він існує, але не визначає ключ systemPrompt.

• channels.whatsapp.groups є одночасно мапою конфігурації для окремих груп і allowlist груп на рівні чату. На кореневому рівні або в scope облікового запису groups["*"] означає “допущено всі групи” для цього scope.
• Додавайте wildcard групового systemPrompt лише тоді, коли ви вже хочете, щоб цей scope допускав усі групи. Якщо ви все ще хочете, щоб придатним був лише фіксований набір ID груп, не використовуйте groups["*"] як значення промпту за замовчуванням. Натомість повторіть промпт у кожному явно внесеному до allowlist записі групи.
• Допуск групи й авторизація відправника є окремими перевірками. groups["*"] розширює набір груп, які можуть досягати обробки груп, але сам по собі не авторизує кожного відправника в цих групах. Доступ відправника все ще окремо контролюється channels.whatsapp.groupPolicy і channels.whatsapp.groupAllowFrom.
• channels.whatsapp.direct не має такого самого побічного ефекту для DM. direct["*"] лише надає конфігурацію direct-чату за замовчуванням після того, як DM уже допущено через dmPolicy плюс allowFrom або правила pairing-store.

{
  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

• доступ: 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

​

Пов’язане

• Сполучення
• Групи
• Безпека
• Маршрутизація каналів
• Маршрутизація кількох агентів
• Усунення несправностей