WhatsApp

​

Установлення

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>

​

Схеми розгортання

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

​

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

• Gateway керує сокетом WhatsApp і циклом повторного підключення.
• Сторожовий процес незалежно відстежує два сигнали: активність необробленого транспорту WhatsApp Web та активність повідомлень застосунку. Тихий, але підключений сеанс не перезапускається лише через те, що останнім часом не надходили повідомлення; повторне підключення виконується примусово, тільки якщо транспортні кадри не надходять протягом фіксованого внутрішнього проміжку часу (користувач не може його налаштувати) або повідомлення застосунку не надходять довше ніж 4-кратний звичайний час очікування повідомлення. Відразу після повторного підключення нещодавно активного сеансу для першого проміжку використовується коротший звичайний час очікування повідомлення замість 4-кратного проміжку. 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 (експериментальна функція)

{
  "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"

​

Запити на схвалення

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

​

Хуки Plugin і конфіденційність

{
  channels: {
    whatsapp: {
      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" },
      },
    },
  ],
}

​

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

​

Нормалізація повідомлень і контекст

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

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

​

Доставка, поділ на фрагменти та медіафайли

​

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

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

​

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

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

​

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

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

​

Реакції на стан життєвого циклу

{
  messages: {
    statusReactions: {
      enabled: true,
      emojis: {
        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 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. Порожній рядок ("") пригнічує шаблон і не застосовує жодної підказки.
2. Групова підказка-шаблон (groups["*"].systemPrompt): використовується, коли запис конкретної групи відсутній або існує без ключа systemPrompt.

• 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: "Типова підказка для робочих прямих чатів." },
          },
        },
      },
    },
  },
}

​

Посилання на довідник конфігурації

​

Пов’язані матеріали

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