Zalo

​

Mitgeliefertes Plugin

• Installation: openclaw plugins install @openclaw/zalo
• Festgelegte Version: openclaw plugins install @openclaw/zalo@2026.6.11
• Aus einem lokalen Checkout: openclaw plugins install ./path/to/local/zalo-plugin
• Details: Plugins

​

Schnelleinrichtung

1. Erstellen Sie unter https://bot.zaloplatforms.com ein Bot-Token (anmelden, Bot erstellen, Einstellungen konfigurieren). Das Token lautet numeric_id:secret; bei Marketplace-Bots kann das verwendbare Laufzeit-Token in der Willkommensnachricht des Bots erscheinen.
2. Legen Sie das Token entweder über die Umgebungsvariable ZALO_BOT_TOKEN=... (nur Standardkonto) oder in der Konfiguration fest.
3. Starten Sie den Gateway neu.
4. Genehmigen Sie beim ersten Kontakt per Direktnachricht den Kopplungscode (die standardmäßige Direktnachrichtenrichtlinie ist die Kopplung).

{
  channels: {
    zalo: {
      enabled: true,
      accounts: {
        default: {
          botToken: "12345689:abc-xyz",
          dmPolicy: "pairing",
        },
      },
    },
  },
}

​

Was es ist

​

Funktionsweise

• Eingehende Nachrichten werden mit Medienplatzhaltern in den gemeinsamen Kanal-Umschlag normalisiert.
• Antworten werden immer an denselben Zalo-Chat zurückgeleitet; Zitatantworten werden nicht verwendet (replyToMode ist fest deaktiviert).
• Standardmäßig Long-Polling (getUpdates); der Webhook-Modus ist über channels.zalo.webhookUrl verfügbar.
• In Gruppen ist eine @Erwähnung erforderlich, um den Bot auszulösen; dies kann nicht pro Kanal konfiguriert werden.

​

Grenzwerte

​

Zugriffskontrolle

​

Direktnachrichten

• channels.zalo.dmPolicy: pairing (Standard) | allowlist | open | disabled.
• Kopplung: Unbekannte Absender erhalten einen Kopplungscode; Nachrichten werden bis zur Genehmigung ignoriert. Codes laufen nach 1 Stunde ab.
  • openclaw pairing list zalo
  • openclaw pairing approve zalo <CODE>
  • Details: Kopplung
• channels.zalo.allowFrom akzeptiert numerische Zalo-Benutzer-IDs (keine Suche nach Benutzernamen). open erfordert "*".

​

Gruppen

• channels.zalo.groupPolicy: open | allowlist | disabled.
• channels.zalo.groupAllowFrom schränkt ein, welche Absender-IDs den Bot in Gruppen auslösen können; wenn nicht festgelegt, wird auf allowFrom zurückgegriffen.
• Standardauflösung: Wenn channels.zalo konfiguriert ist, wird ein nicht festgelegtes groupPolicy als open aufgelöst. Wenn channels.zalo vollständig fehlt, verwendet die Laufzeit aus Sicherheitsgründen allowlist.
• Aus der Praxis gemeldete Einschränkung: Bei einigen Marketplace-Bot-Konfigurationen konnte der Bot überhaupt nicht zu einer Gruppe hinzugefügt werden. Wenn dies auftritt, überprüfen Sie die Einstellungen Ihres Bots auf der Zalo Bot Platform; es handelt sich um eine plattformseitige Einschränkung, nicht um eine OpenClaw-Richtlinie.

​

Long-Polling im Vergleich zu Webhook

• Standard: Long-Polling (keine öffentliche URL erforderlich).
• Webhook-Modus: Legen Sie channels.zalo.webhookUrl und channels.zalo.webhookSecret fest.
  • Die Webhook-URL muss HTTPS verwenden.
  • Das Webhook-Secret muss 8-256 Zeichen lang sein.
  • Zalo sendet Ereignisse mit einem X-Bot-Api-Secret-Token-Header, der mit einem zeitkonstanten Vergleich geprüft wird.
  • Gateway HTTP verarbeitet Webhook-Anfragen unter channels.zalo.webhookPath (standardmäßig der Pfad der Webhook-URL).
  • Anfragen müssen Content-Type: application/json (oder einen +json-Medientyp) verwenden.
  • HTTP 200 wird erst zurückgegeben, nachdem das Rohereignis dauerhaft gespeichert wurde; Speicherfehler geben HTTP 500 zurück.
  • getUpdates-Polling und Webhook schließen sich laut Zalo-API-Dokumentation gegenseitig aus.

​

Unterstützte Nachrichtentypen

• Text: vollständig unterstützt, in Blöcke von 2000 Zeichen aufgeteilt.
• Medien: ein- und ausgehend, begrenzt durch mediaMaxMb.
• Reaktionen, Threads, Umfragen und native Befehle: vom Plugin nicht unterstützt.
• Streaming: Das Plugin deklariert die Fähigkeit zum Block-Streaming, Zalo verfügt jedoch über keine speziellen Einstellmöglichkeiten für ausgehende Warteschlangen oder das Zusammenführen von Text (anders als einige andere regionale Kanäle); überprüfen Sie das aktuelle Verhalten in Ihrer Umgebung, falls dies für Ihren Anwendungsfall relevant ist.

​

Funktionen

​

Zustellziele (CLI/Cron)

openclaw message send --channel zalo --target 123456789 --message "hi"

​

Fehlerbehebung

• Überprüfen Sie das Token: openclaw channels status --probe
• Stellen Sie sicher, dass der Absender genehmigt ist (Kopplung oder allowFrom)
• Prüfen Sie die Gateway-Protokolle: openclaw logs --follow

• Stellen Sie sicher, dass die Webhook-URL HTTPS verwendet
• Stellen Sie sicher, dass das Secret 8-256 Zeichen lang ist
• Stellen Sie sicher, dass der Gateway-HTTP-Endpunkt unter dem konfigurierten Pfad erreichbar ist
• Stellen Sie sicher, dass nicht gleichzeitig getUpdates-Polling ausgeführt wird (beide schließen sich gegenseitig aus)
• Eine Anfragespitze kann HTTP 429 zurückgeben (120 Anfragen / 60s pro Pfad+IP); warten Sie und versuchen Sie es erneut

​

Konfigurationsreferenz

​

Verwandte Themen

• Kanalübersicht - alle unterstützten Kanäle
• Kopplung - Direktnachrichtenauthentifizierung und Kopplungsablauf
• Gruppen - Verhalten von Gruppenchats und Einschränkung durch Erwähnungen
• Kanalrouting - Sitzungsrouting für Nachrichten
• Sicherheit - Zugriffsmodell und Härtung