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 на низком уровне и активность сообщений приложения. Тихий, но подключённый сеанс не перезапускается только из-за того, что в последнее время не поступали сообщения; принудительное повторное подключение происходит, только если транспортные кадры перестают поступать в течение фиксированного внутреннего интервала (не настраивается пользователем) или сообщения приложения отсутствуют дольше четырёхкратного обычного тайм-аута сообщений. Сразу после повторного подключения недавно активного сеанса для первого интервала используется более короткий обычный тайм-аут сообщений вместо четырёхкратного интервала. 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" }],
    },
  },
}

​

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

{
  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: "Промпт по умолчанию для рабочих личных чатов." },
          },
        },
      },
    },
  },
}

​

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

​

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

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