Zalo Bot API in das OpenClaw Gateway integrieren

Du kennst das: Du willst deine Nutzer dort erreichen, wo sie sich aufhalten, aber jede neue Messaging-Plattform bringt eigene APIs und Eigenheiten mit. Besonders bei regionalspezifischen Apps verbringst du oft Stunden damit, das Nachrichten-Routing und die Authentifizierung manuell nachzubauen, anstatt dich auf die Logik deines Bots zu konzentrieren.

Wenn du Nutzer in Vietnam erreichen willst, ist Zalo unverzichtbar. Mit dem Zalo-Plugin für OpenClaw integrierst du den Dienst direkt in dein Gateway, ohne dich um die Details der Long-polling-Implementierung oder das Chunking von Nachrichten kümmern zu müssen.

Voraussetzungen

Bevor du startest, stelle sicher, dass du folgende Dinge bereit hast:

• Einen Account auf der Zalo Bot Platform
• Einen Zalo Bot Token (Format: 12345689:abc-xyz)
• Eine laufende OpenClaw Instanz
• Das @openclaw/zalo Plugin

Schnellstart

In weniger als 5 Minuten ist dein Zalo Bot einsatzbereit. Folge diesen Schritten:

1. Plugin installieren: Nutze die CLI: openclaw plugins install @openclaw/zalo
2. Token konfigurieren: Setze die Umgebungsvariable ZALO_BOT_TOKEN=dein_token oder bearbeite deine Config.
3. Gateway neu starten: Zalo startet automatisch, sobald der Token erkannt wird.
4. Pairing bestätigen: Standardmäßig nutzt Zalo den pairing Modus. Sende deinem Bot eine Nachricht und bestätige den Code via CLI.

Hier ist eine minimale Beispiel-Konfiguration für deine config.json5:

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

Setup (fast path)

1. Bot Token erstellen

Gehe auf https://bot.zaloplatforms.com und erstelle einen neuen Bot. Kopiere dir den Bot Token aus den Einstellungen.

2. Token hinterlegen

Du kannst den Token entweder über die Umgebungsvariable ZALO_BOT_TOKEN setzen (nur für den Standard-Account) oder die Config nutzen. Für mehrere Accounts verwendest du channels.zalo.accounts:

{
  channels: {
    zalo: {
      accounts: {
        account1: {
          botToken: "12345689:abc-xyz",
          name: "Support Bot"
        }
      }
    }
  }
}

3. Zugriffskontrolle (DMs)

Standardmäßig steht dmPolicy auf pairing. Unbekannte Absender erhalten einen Code, der 1 Stunde gültig ist. Du genehmigst den Zugriff so:

• openclaw pairing list zalo
• openclaw pairing approve zalo <CODE>

Alternativ kannst du mit channels.zalo.allowFrom eine Liste mit numerischen User IDs festlegen.

Long-polling vs Webhook

Das Plugin unterstützt zwei Arten, Nachrichten zu empfangen:

• Long-polling (Standard): Erfordert keine öffentliche URL und ist ideal für lokale Setups.
• Webhook Modus: Setze channels.zalo.webhookUrl (muss HTTPS sein) und channels.zalo.webhookSecret (8-256 Zeichen).

Beachte, dass Zalo laut API-Dokumentation nicht beide Modi gleichzeitig erlaubt. Sobald ein Webhook aktiv ist, wird das Polling deaktiviert.

Limits und Verhalten

Zalo hat einige spezifische Einschränkungen, die das Plugin automatisch handhabt:

• Text-Limit: Ausgehende Nachrichten werden bei 2000 Zeichen abgeschnitten/gechunked.
• Media-Limit: Uploads und Downloads sind standardmäßig auf 5 MB begrenzt (channels.zalo.mediaMaxMb).
• Streaming: Da das 2000-Zeichen-Limit Streaming weniger sinnvoll macht, ist es standardmäßig blockiert.
• Gruppen: Aktuell werden nur Direct Messages (1:1) unterstützt; Gruppenfunktionen sind laut Zalo “coming soon”.

Fehlerbehebung

Bot antwortet nicht:

• Prüfe den Token-Status: openclaw channels status --probe
• Stelle sicher, dass der Absender über pairing oder allowFrom zugelassen ist.
• Kontrolliere die Logs: openclaw logs --follow
• Vergewissere dich, dass der Gateway-Dienst läuft.

Webhook empfängt keine Events:

• Nutzt die Webhook URL zwingend HTTPS?
• Hat das Secret eine Länge zwischen 8 und 256 Zeichen?
• Ist der Gateway HTTP-Endpunkt von außen erreichbar?
• Läuft eventuell noch ein paralleler Prozess mit getUpdates Polling?

AI Setup Assistant

Nächste Schritte

• Plugins Dokumentation
• Allgemeine Konfiguration
• Pairing Details
• Zalo Bot Platform