Zalo

Status: experimentell. Direktnachrichten und Gruppenchats sind beide implementiert; die nachstehende Tabelle Funktionen gibt das verifizierte Verhalten für Zalo Bot Creator-/Marketplace-Bots wieder.

Mitgeliefertes Plugin

Zalo wird in aktuellen OpenClaw-Versionen als mitgeliefertes Plugin ausgeliefert, daher benötigen paketierte Builds keine separate Installation.

Installieren Sie bei einem älteren Build oder einer benutzerdefinierten Installation, die Zalo ausschließt, das npm-Paket direkt:

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

Schnelle Einrichtung

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

Minimale Konfiguration:

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

Mehrere Konten: Fügen Sie unter channels.zalo.accounts.<id> weitere Einträge hinzu, jeweils mit eigenem botToken/name. channels.zalo.botToken (flach, ohne accounts) ist eine veraltete Kurzform für ein einzelnes Konto; bevorzugen Sie für neue Konfigurationen accounts.<id>.*.

Was es ist

Zalo ist eine auf Vietnam ausgerichtete Messaging-App. Über ihre Bot API kann das Gateway einen Bot sowohl für 1:1-Unterhaltungen als auch für Gruppenchats ausführen, wobei die Antworten deterministisch an Zalo zurückgeleitet werden (das Modell wählt niemals Kanäle aus).

Diese Seite behandelt Zalo Bot Creator-/Marketplace-Bots. Zalo Official Account (OA)-Bots bilden eine andere Produktoberfläche und können sich anders verhalten; sie werden auf dieser Seite nicht behandelt.

Funktionsweise

• Eingehende Nachrichten werden mit Medienplatzhaltern in den gemeinsamen Kanal-Umschlag normalisiert.
• Antworten werden immer an denselben Zalo-Chat zurückgeleitet; Antworten mit Zitat 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 ist nicht pro Kanal konfigurierbar.

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

Gruppenchats werden vom Plugin unterstützt (chatTypes: ["direct", "group"]) und durch Erwähnung sowie Gruppenrichtlinie beschränkt:

• channels.zalo.groupPolicy: open | allowlist | disabled.
• channels.zalo.groupAllowFrom beschränkt, 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, schließt die Laufzeit den Zugriff standardmäßig mit allowlist.
• Aus der Praxis gemeldete Einschränkung: Bei einigen Marketplace-Bot-Konfigurationen konnte der Bot überhaupt keiner Gruppe hinzugefügt werden. Falls dies bei Ihnen auftritt, überprüfen Sie die Zalo Bot Platform-Einstellungen Ihres Bots; es handelt sich um eine plattformseitige Einschränkung, nicht um eine OpenClaw-Richtlinie.

Long-Polling oder 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-Geheimnis muss 8-256 Zeichen lang sein.
  • Zalo sendet Ereignisse mit einem X-Bot-Api-Secret-Token-Header, der mit einem Vergleich in konstanter Zeit 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.
  • getUpdates-Polling und Webhook schließen sich gemäß der Zalo API-Dokumentation gegenseitig aus.

Unterstützte Nachrichtentypen

• Text: vollständig unterstützt, in Segmente von 2000 Zeichen aufgeteilt.
• Medien: ein- und ausgehend, durch mediaMaxMb begrenzt.
• Reaktionen, Threads, Umfragen, 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 die Zusammenführung von Text (anders als einige andere regionale Kanäle). Überprüfen Sie das aktuelle Verhalten in Ihrer Umgebung, falls dies für Ihren Anwendungsfall wichtig ist.

Funktionen

Zustellziele (CLI/Cron)

Verwenden Sie eine Chat-ID als Ziel:

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

Fehlerbehebung

Bot antwortet nicht:

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

Webhook empfängt keine Ereignisse:

• Vergewissern Sie sich, dass die Webhook-URL HTTPS verwendet
• Vergewissern Sie sich, dass das Geheimnis 8-256 Zeichen lang ist
• Vergewissern Sie sich, dass der Gateway-HTTP-Endpunkt unter dem konfigurierten Pfad erreichbar ist
• Vergewissern Sie sich, dass getUpdates-Polling nicht ebenfalls 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

Vollständige Konfiguration: Konfiguration

channels.zalo.botToken, channels.zalo.dmPolicy und andere flache Schlüssel auf oberster Ebene sind die veraltete Kurzform für ein einzelnes Konto für die oben genannten Felder; beide Formen werden unterstützt.

Umgebungsoption: ZALO_BOT_TOKEN=... wird nur als Token des Standardkontos aufgelöst.

Verwandte Themen

• Kanalübersicht - alle unterstützten Kanäle
• Kopplung - Direktnachrichtenauthentifizierung und Kopplungsablauf
• Gruppen - Verhalten von Gruppenchats und Auslösung durch Erwähnung
• Kanalrouting - Sitzungsrouting für Nachrichten
• Sicherheit - Zugriffsmodell und Absicherung