Zalo Personal (inoffiziell)

Status: Experimentell. Diese Integration automatisiert ein persönliches Zalo-Konto via nativem zca-js in OpenClaw.

Warnung: Dies ist eine inoffizielle Integration und kann zu einer Kontosperre/-sperrung führen. Verwendung auf eigene Gefahr.

Plugin erforderlich

Zalo Personal wird als Plugin ausgeliefert und ist nicht in der Kerninstallation enthalten.

Installation über CLI: openclaw plugins install @openclaw/zalouser
Oder aus einem Quell-Checkout: openclaw plugins install ./extensions/zalouser
Details: Plugins

Kein externer zca/openzca-CLI-Binary wird benötigt.

Schnelleinrichtung (Einsteiger)

Installiere das Plugin (siehe oben).
Login (QR, auf der Gateway-Maschine):
- openclaw channels login --channel zalouser
- Scanne den QR-Code mit der Zalo-Mobil-App.
Aktiviere den Kanal:

{
  channels: {
    zalouser: {
      enabled: true,
      dmPolicy: "pairing",
    },
  },
}

Starte das Gateway neu (oder schließe das Onboarding ab).
DM-Zugang ist standardmäßig Pairing; genehmige den Pairing-Code beim ersten Kontakt.

Was es ist

Läuft komplett im Prozess via zca-js.
Verwendet native Event-Listener zum Empfang eingehender Nachrichten.
Sendet Antworten direkt über die JS-API (Text/Medien/Link).
Konzipiert für „Privatkonto”-Anwendungsfälle, bei denen die Zalo-Bot-API nicht verfügbar ist.

Namensgebung

Die Kanal-ID ist zalouser, um klarzumachen, dass ein persönliches Zalo-Benutzerkonto automatisiert wird (inoffiziell). Wir halten zalo für eine mögliche zukünftige offizielle Zalo-API-Integration frei.

IDs finden (Verzeichnis)

Verwende die Verzeichnis-CLI, um Peers/Gruppen und deren IDs zu ermitteln:

openclaw directory self --channel zalouser
openclaw directory peers list --channel zalouser --query "name"
openclaw directory groups list --channel zalouser --query "work"

Limits

Ausgehender Text wird auf ca. 2000 Zeichen aufgeteilt (Zalo-Client-Limits).
Streaming ist standardmäßig blockiert.

Zugriffssteuerung (DMs)

channels.zalouser.dmPolicy unterstützt: pairing | allowlist | open | disabled (Standard: pairing).

channels.zalouser.allowFrom akzeptiert Benutzer-IDs oder Namen. Während des Onboardings werden Namen über die prozessinterne Kontaktsuche des Plugins zu IDs aufgelöst.

Genehmigung über:

openclaw pairing list zalouser
openclaw pairing approve zalouser <code>

Gruppenzugriff (optional)

Standard: channels.zalouser.groupPolicy = "open" (Gruppen erlaubt). Verwende channels.defaults.groupPolicy, um den Standard zu überschreiben, wenn nicht gesetzt.
Auf eine Allowlist beschränken mit:
- channels.zalouser.groupPolicy = "allowlist"
- channels.zalouser.groups (Schlüssel sollten stabile Gruppen-IDs sein; Namen werden beim Start wenn möglich zu IDs aufgelöst)
- channels.zalouser.groupAllowFrom (steuert, welche Absender in erlaubten Gruppen den Bot auslösen können)
Alle Gruppen blockieren: channels.zalouser.groupPolicy = "disabled".
Der Konfigurationsassistent kann nach Gruppen-Allowlists fragen.
Beim Start löst OpenClaw Gruppen-/Benutzernamen in Allowlists zu IDs auf und protokolliert die Zuordnung.
Gruppen-Allowlist-Matching basiert standardmäßig nur auf IDs. Nicht aufgelöste Namen werden für die Autorisierung ignoriert, es sei denn, channels.zalouser.dangerouslyAllowNameMatching: true ist aktiviert.
channels.zalouser.dangerouslyAllowNameMatching: true ist ein Notfall-Kompatibilitätsmodus, der veränderbares Gruppennamen-Matching wieder aktiviert.
Wenn groupAllowFrom nicht gesetzt ist, fällt die Laufzeit für Gruppen-Absenderprüfungen auf allowFrom zurück.
Absenderprüfungen gelten sowohl für normale Gruppennachrichten als auch für Steuerbefehle (z. B. /new, /reset).

Beispiel:

{
  channels: {
    zalouser: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["1471383327500481391"],
      groups: {
        "123456789": { allow: true },
        "Work Chat": { allow: true },
      },
    },
  },
}

Gruppen-Mention-Gating

channels.zalouser.groups.<group>.requireMention steuert, ob Gruppenantworten eine Erwähnung erfordern.
Auflösungsreihenfolge: exakte Gruppen-ID/Name -> normalisierter Gruppen-Slug -> * -> Standard (true).
Dies gilt sowohl für Allowlist-Gruppen als auch für den offenen Gruppenmodus.
Autorisierte Steuerbefehle (z. B. /new) können das Mention-Gating umgehen.
Wenn eine Gruppennachricht übersprungen wird, weil eine Erwähnung erforderlich ist, speichert OpenClaw sie als ausstehenden Gruppenverlauf und fügt sie bei der nächsten verarbeiteten Gruppennachricht ein.
Das Gruppenverlaufslimit entspricht standardmäßig messages.groupChat.historyLimit (Fallback 50). Du kannst es pro Konto überschreiben mit channels.zalouser.historyLimit.

Beispiel:

{
  channels: {
    zalouser: {
      groupPolicy: "allowlist",
      groups: {
        "*": { allow: true, requireMention: true },
        "Work Chat": { allow: true, requireMention: false },
      },
    },
  },
}

Multi-Account

Konten bilden zalouser-Profile im OpenClaw-State ab. Beispiel:

{
  channels: {
    zalouser: {
      enabled: true,
      defaultAccount: "default",
      accounts: {
        work: { enabled: true, profile: "work" },
      },
    },
  },
}

Tippanzeige, Reaktionen und Zustellbestätigungen

OpenClaw sendet vor dem Versand einer Antwort ein Tipp-Event (Best-Effort).
Die Nachrichtenreaktions-Aktion react wird für zalouser in Kanalaktionen unterstützt.
- Verwende remove: true, um ein bestimmtes Reaktions-Emoji von einer Nachricht zu entfernen.
- Reaktionssemantik: Reactions
Für eingehende Nachrichten, die Event-Metadaten enthalten, sendet OpenClaw Zugestellt- und Gelesen-Bestätigungen (Best-Effort).

Fehlerbehebung

Login hält nicht:

openclaw channels status --probe
Erneut einloggen: openclaw channels logout --channel zalouser && openclaw channels login --channel zalouser

Allowlist-/Gruppenname wurde nicht aufgelöst:

Verwende numerische IDs in allowFrom/groupAllowFrom/groups oder exakte Freund-/Gruppennamen.

Upgrade von alter CLI-basierter Einrichtung:

Entferne alle alten externen zca-Prozess-Annahmen.
Der Kanal läuft jetzt vollständig in OpenClaw ohne externe CLI-Binaries.