WhatsApp

​

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

• Онбординг (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

​

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

{
  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, а не только объем входящих сообщений приложения, поэтому тихая сессия связанного устройства не перезапускается только потому, что никто недавно не отправлял сообщения. Более длинный лимит тишины приложения все равно принудительно выполняет переподключение, если транспортные 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 после доставки видимого ответа.

​

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

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

​

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

{
  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.
• Списки разрешённых групп, политика отправителей и шлюзы упоминаний или активации выполняются до того, как OpenClaw проверяет наличие настроенной сессии ACP.
• Совпавшая настроенная привязка ACP владеет маршрутом. Группы рассылки WhatsApp не рассылают этот ход обычным сессиям 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,
        },
      },
    },
  },
}

​

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

​

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

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

​

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

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

​

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

{
  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,
      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 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 является пустой строкой (""), подстановочный вариант подавляется и системный промпт не применяется.
2. Подстановочный системный промпт для групп (groups["*"].systemPrompt): используется, когда запись конкретной группы полностью отсутствует в карте или когда она существует, но не определяет ключ systemPrompt.

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

• 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

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

​

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

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