WhatsApp

​

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

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

openclaw plugins install clawhub:@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-auth
openclaw channels login --channel whatsapp --account work

openclaw gateway

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>

​

Виклик поточного запитувача за допомогою MeowCaller (експериментально)

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

git clone --branch feat/send-only-notify https://github.com/steipete/meowcaller.git
cd meowcaller
git checkout 752050471fc2bf7a8cdfbf7dbd3cd4e865d85d3f
mkdir -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

​

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

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

​

Runtime-модель

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

​

Prompt-и схвалення

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

​

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

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

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

​

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

​

Налаштовані прив’язки ACP

{
  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.
• Allowlist-и груп, політика відправників і перевірка згадки або активації виконуються до того, як OpenClaw забезпечує існування налаштованого сеансу ACP.
• Зіставлена налаштована прив’язка ACP володіє маршрутом. Групи трансляції WhatsApp не розгалужують цей turn до звичайних сеансів WhatsApp.

​

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

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

​

Доставка, chunking і медіа

​

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

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

​

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

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

​

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

{
  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,
      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
• Записи конфігурації, ініційовані каналом, увімкнено типово (вимкнення через channels.whatsapp.configWrites=false).

​

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

openclaw channels login --channel whatsapp
openclaw channels status

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

openclaw channels status --probe
openclaw doctor
openclaw logs --follow
openclaw gateway status

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

​

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

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

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

• channels.whatsapp.groups є одночасно мапою конфігурації для окремих груп і allowlist груп рівня чату. На кореневому рівні або в області облікового запису groups["*"] означає “усі групи допускаються” для цієї області.
• Додавайте wildcard-групу systemPrompt лише тоді, коли вже хочете, щоб ця область допускала всі групи. Якщо ви все ще хочете, щоб придатним був лише фіксований набір ідентифікаторів груп, не використовуйте groups["*"] як типовий промпт. Натомість повторіть промпт у кожному явно внесеному до allowlist записі групи.
• Допуск групи та авторизація відправника є окремими перевірками. 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

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

​

Пов’язане

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