Zalo Personal (unofficial)

Status: experimenteel. Deze integratie automatiseert een persoonlijk Zalo-account via native zca-js binnen OpenClaw.

Waarschuwing: Dit is een onofficiële integratie en kan leiden tot opschorting/blokkering van je account. Gebruik op eigen risico.

Plugin vereist

Zalo Personal wordt als plugin geleverd en is niet gebundeld met de kerninstallatie.

• Installeren via CLI: openclaw plugins install @openclaw/zalouser
• Of vanuit een broncode-checkout: openclaw plugins install ./extensions/zalouser
• Details: Plugins

Er is geen externe zca/openzca CLI-binary vereist.

Snelle installatie (beginner)

1. Installeer de plugin (zie hierboven).
2. Inloggen (QR, op de Gateway-machine):
   • openclaw channels login --channel zalouser
   • Scan de QR-code met de Zalo-mobiele app.
3. Schakel het kanaal in:

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

4. Herstart de Gateway (of voltooi de onboarding).
5. DM-toegang staat standaard op koppeling; keur de koppelingscode goed bij het eerste contact.

Wat het is

• Draait volledig in-process via zca-js.
• Gebruikt native event listeners om inkomende berichten te ontvangen.
• Stuurt antwoorden rechtstreeks via de JS API (tekst/media/link).
• Ontworpen voor “persoonlijk account”-scenario’s waarbij de Zalo Bot API niet beschikbaar is.

Naamgeving

Het kanaal-ID is zalouser om expliciet te maken dat dit een persoonlijk Zalo-gebruikersaccount automatiseert (onofficieel). We houden zalo gereserveerd voor een mogelijke toekomstige officiële Zalo API-integratie.

ID’s opzoeken (directory)

Gebruik de directory-CLI om peers/groepen en hun ID’s te ontdekken:

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

Limieten

• Uitgaande tekst wordt opgesplitst bij ~2000 tekens (Zalo-clientlimieten).
• Streaming is standaard geblokkeerd.

Toegangscontrole (DM’s)

channels.zalouser.dmPolicy ondersteunt: pairing | allowlist | open | disabled (standaard: pairing).

channels.zalouser.allowFrom accepteert gebruikers-ID’s of namen. Tijdens onboarding worden namen omgezet naar ID’s met behulp van de in-process contactopzoeking van de plugin.

Goedkeuren via:

• openclaw pairing list zalouser
• openclaw pairing approve zalouser <code>

Groepstoegang (optioneel)

• Standaard: channels.zalouser.groupPolicy = "open" (groepen toegestaan). Gebruik channels.defaults.groupPolicy om de standaard te overschrijven wanneer niet ingesteld.
• Beperk tot een allowlist met:
  • channels.zalouser.groupPolicy = "allowlist"
  • channels.zalouser.groups (sleutels moeten stabiele groeps-ID’s zijn; namen worden bij opstart waar mogelijk omgezet naar ID’s)
  • channels.zalouser.groupAllowFrom (bepaalt welke afzenders in toegestane groepen de bot kunnen triggeren)
• Blokkeer alle groepen: channels.zalouser.groupPolicy = "disabled".
• De configuratiewizard kan om groeps-allowlists vragen.
• Bij opstart zet OpenClaw groeps-/gebruikersnamen in allowlists om naar ID’s en logt de mapping.
• Groeps-allowlist-matching is standaard alleen op ID. Niet-opgeloste namen worden genegeerd voor authenticatie tenzij channels.zalouser.dangerouslyAllowNameMatching: true is ingeschakeld.
• channels.zalouser.dangerouslyAllowNameMatching: true is een noodmodus die veranderlijke groepsnaam-matching weer inschakelt.
• Als groupAllowFrom niet is ingesteld, valt de runtime terug op allowFrom voor groepsafzendercontroles.
• Afzendercontroles gelden zowel voor gewone groepsberichten als voor besturingscommando’s (bijvoorbeeld /new, /reset).

Voorbeeld:

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

Groeps-mention-gating

• channels.zalouser.groups.<group>.requireMention bepaalt of groepsantwoorden een vermelding vereisen.
• Resolutievolgorde: exact groeps-ID/naam -> genormaliseerde groepsslug -> * -> standaard (true).
• Dit geldt zowel voor allowlist-groepen als voor open groepsmodus.
• Geautoriseerde besturingscommando’s (bijvoorbeeld /new) kunnen mention-gating omzeilen.
• Wanneer een groepsbericht wordt overgeslagen omdat een vermelding vereist is, slaat OpenClaw het op als wachtende groepsgeschiedenis en neemt het mee bij het volgende verwerkte groepsbericht.
• Groepsgeschiedenislimiet staat standaard op messages.groupChat.historyLimit (terugval 50). Je kunt dit per account overschrijven met channels.zalouser.historyLimit.

Voorbeeld:

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

Multi-account

Accounts worden gekoppeld aan zalouser-profielen in de OpenClaw-status. Voorbeeld:

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

Typindicatoren, reacties en afleveringsbevestigingen

• OpenClaw stuurt een typ-event voordat een antwoord wordt verzonden (best-effort).
• Berichtreactie-actie react wordt ondersteund voor zalouser in kanaalacties.
  • Gebruik remove: true om een specifieke reactie-emoji van een bericht te verwijderen.
  • Reactiesemantiek: Reacties
• Voor inkomende berichten die event-metadata bevatten, stuurt OpenClaw afgeleverd- en gezien-bevestigingen (best-effort).

Probleemoplossing

Login houdt niet vast:

• openclaw channels status --probe
• Opnieuw inloggen: openclaw channels logout --channel zalouser && openclaw channels login --channel zalouser

Allowlist-/groepsnaam niet opgelost:

• Gebruik numerieke ID’s in allowFrom/groupAllowFrom/groups, of exacte vriend-/groepsnamen.

Upgrade vanuit oude CLI-gebaseerde setup:

• Verwijder alle aannames over oude externe zca-processen.
• Het kanaal draait nu volledig binnen OpenClaw zonder externe CLI-binaries.