OpenClaw Zalo Personal: Privates Konto in 5 Minuten verbinde

Kennst du das Problem? Du willst einen Messenger-Account automatisieren, aber es gibt keine offizielle API oder die Hürden sind für ein privates Projekt einfach zu hoch. Das bremst deine Produktivität und macht einfache Integrationen unnötig kompliziert.

Zalo Personal (inoffiziell)

Status: experimentell. Diese Integration automatisiert einen persönlichen Zalo-Account über natives zca-js innerhalb von OpenClaw.

Warnung: Dies ist eine inoffizielle Integration und kann zur Sperrung oder zum Bann deines Accounts führen. Die Nutzung erfolgt auf eigene Gefahr.

Plugin erforderlich

Zalo Personal wird als Plugin ausgeliefert und ist nicht im Core-Install enthalten.

Installation via CLI: openclaw plugins install @openclaw/zalouser
Oder aus einem Source-Checkout: openclaw plugins install ./path/to/local/zalouser-plugin
Details: Plugins

Es ist keine externe zca/openzca CLI-Binary erforderlich.

Schnelle Einrichtung (Anfänger)

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

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

Starte das Gateway neu (oder schließe das Setup ab).
Der DM-Zugriff steht standardmäßig auf “pairing”; bestätige den Pairing-Code beim ersten Kontakt.

Was es ist

Läuft vollständig in-process via zca-js.
Nutzt native Event-Listener, um eingehende Nachrichten zu empfangen.
Sendet Antworten direkt über die JS API (Text/Media/Link).
Entwickelt für Anwendungsfälle mit “persönlichen Accounts”, bei denen die Zalo Bot API nicht verfügbar ist.

Benennung

Die Channel-ID ist zalouser, um explizit zu machen, dass dies einen persönlichen Zalo-User-Account automatisiert (inoffiziell). Wir halten zalo für eine potenzielle zukünftige Integration der offiziellen Zalo API frei.

IDs finden (Directory)

Nutze die Directory CLI, um Peers/Gruppen und deren IDs zu finden:

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 in Blöcke von ca. 2000 Zeichen unterteilt (Zalo-Client-Limits).
Streaming ist standardmäßig blockiert.

Zugriffskontrolle (DMs)

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

channels.zalouser.allowFrom akzeptiert User-IDs oder Namen. Während des Setups werden Namen mithilfe der Kontakt-Suche des Plugins in IDs aufgelöst.

Freigabe über:

openclaw pairing list zalouser
openclaw pairing approve zalouser <code>

Gruppen-Zugriff (optional)

Standard: channels.zalouser.groupPolicy = "open" (Gruppen erlaubt). Nutze channels.defaults.groupPolicy, um den Standardwert zu überschreiben.
Beschränkung auf eine Allowlist mit:
- channels.zalouser.groupPolicy = "allowlist"
- channels.zalouser.groups (Keys sollten stabile Gruppen-IDs sein; Namen werden beim Start nach Möglichkeit in IDs aufgelöst)
- channels.zalouser.groupAllowFrom (steuert, welche Absender in erlaubten Gruppen den Bot triggern können)
Alle Gruppen blockieren: channels.zalouser.groupPolicy = "disabled".
Der Konfigurations-Assistent kann nach Gruppen-Allowlists fragen.
Beim Start löst OpenClaw Gruppen-/Usernamen in Allowlists in IDs auf und protokolliert das Mapping.
Das Matching der Gruppen-Allowlist erfolgt standardmäßig nur über die ID. Nicht aufgelöste Namen werden für die Authentifizierung ignoriert, außer channels.zalouser.dangerouslyAllowNameMatching: true ist aktiviert.
channels.zalouser.dangerouslyAllowNameMatching: true ist ein Notfall-Modus, der das Matching über veränderbare Gruppennamen wieder aktiviert.
Wenn groupAllowFrom nicht gesetzt ist, nutzt das System allowFrom für die Absenderprüfung in Gruppen.
Absenderprüfungen gelten sowohl für normale Gruppennachrichten als auch für Control-Commands (zum Beispiel /new, /reset).

Beispiel:

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

Group mention gating

channels.zalouser.groups.<group>.requireMention steuert, ob Antworten in Gruppen eine Erwähnung (Mention) erfordern.
Reihenfolge der Auflösung: exakte Gruppen-ID/Name -> normalisierter Gruppen-Slug -> * -> Standard (true).
Dies gilt sowohl für Gruppen auf der Allowlist als auch für den offenen Gruppen-Modus.
Autorisierte Control-Commands (zum Beispiel /new) können das Mention-Gating umgehen.
Wenn eine Gruppennachricht übersprungen wird, weil eine Erwähnung fehlt, speichert OpenClaw diese als ausstehende Gruppen-Historie und fügt sie der nächsten verarbeiteten Nachricht hinzu.
Das Limit für die Gruppen-Historie ist standardmäßig messages.groupChat.historyLimit (Fallback 50). Du kannst dies pro Account mit channels.zalouser.historyLimit überschreiben.

Beispiel:

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

Multi-Account

Accounts werden auf zalouser-Profile im OpenClaw-State gemappt. Beispiel:

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

Tipp-Status, Reaktionen und Empfangsbestätigungen

OpenClaw sendet ein Tipp-Event (Typing), bevor eine Antwort verschickt wird (Best-Effort).
Die Nachrichten-Reaktion react wird für zalouser in Channel-Actions unterstützt.
- Nutze remove: true, um ein spezifisches Reaktions-Emoji von einer Nachricht zu entfernen.
- Semantik der Reaktionen: Reactions
Für eingehende Nachrichten, die Event-Metadaten enthalten, sendet OpenClaw Empfangs- und Gelesen-Bestätigungen (Best-Effort).

Fehlerbehebung

Login bleibt nicht bestehen:

openclaw channels status --probe
Erneuter Login: openclaw channels logout --channel zalouser && openclaw channels login --channel zalouser

Allowlist/Gruppenname wurde nicht aufgelöst:

Nutze numerische IDs in allowFrom/groupAllowFrom/groups oder exakte Freundes-/Gruppennamen.

Upgrade von altem CLI-basiertem Setup:

Entferne alle Annahmen über alte externe zca-Prozesse.
Der Channel läuft jetzt vollständig in OpenClaw ohne externe CLI-Binaries.

Noch festgefahren?

Wenn diese Seite nicht hilft, frage OpenClaw Expert nach Schritt-fuer-Schritt-Loesungen.