feat: add zalouser channel + directory CLI (#1032) (thanks @suminhthanh)

- Unified UX: channels login + message send; no plugin-specific top-level command\n- Added generic directory CLI for channel identity/groups\n- Docs: channel + plugin pages

docs/channels/index.md

@@ -20,6 +20,7 @@ Text is supported everywhere; media and reactions vary by channel.
 - [Microsoft Teams](/channels/msteams) — Bot Framework; enterprise support (plugin, installed separately).
 - [Matrix](/channels/matrix) — Matrix protocol (plugin, installed separately).
 - [Zalo](/channels/zalo) — Zalo Bot API; Vietnam's popular messenger (plugin, installed separately).
+- [Zalo Personal](/channels/zalouser) — Zalo personal account via QR login (plugin, installed separately).
 - [WebChat](/web/webchat) — Gateway WebChat UI over WebSocket.
 
 ## Notes

docs/channels/zalouser.md

@@ -0,0 +1,98 @@
+---
+summary: "Zalo personal account support via zca-cli (QR login), capabilities, and configuration"
+read_when:
+  - Setting up Zalo Personal for Clawdbot
+  - Debugging Zalo Personal login or message flow
+---
+# Zalo Personal (unofficial)
+
+Status: experimental. This integration automates a **personal Zalo account** via `zca-cli`.
+
+> **Warning:** This is an unofficial integration and may result in account suspension/ban. Use at your own risk.
+
+## Plugin required
+Zalo Personal ships as a plugin and is not bundled with the core install.
+- Install via CLI: `clawdbot plugins install @clawdbot/zalouser`
+- Or from a source checkout: `clawdbot plugins install ./extensions/zalouser`
+- Details: [Plugins](/plugin)
+
+## Prerequisite: zca-cli
+The Gateway machine must have the `zca` binary available in `PATH`.
+
+- Verify: `zca --version`
+- If missing, install zca-cli (see `extensions/zalouser/README.md` or the upstream zca-cli docs).
+
+## Quick setup (beginner)
+1) Install the plugin (see above).
+2) Login (QR, on the Gateway machine):
+   - `clawdbot channels login --channel zalouser`
+   - Scan the QR code in the terminal with the Zalo mobile app.
+3) Enable the channel:
+
+```json5
+{
+  channels: {
+    zalouser: {
+      enabled: true,
+      dmPolicy: "pairing"
+    }
+  }
+}
+```
+
+4) Restart the Gateway (or finish onboarding).
+5) DM access defaults to pairing; approve the pairing code on first contact.
+
+## What it is
+- Uses `zca listen` to receive inbound messages.
+- Uses `zca msg ...` to send replies (text/media/link).
+- Designed for “personal account” use cases where Zalo Bot API is not available.
+
+## Naming
+Channel id is `zalouser` to make it explicit this automates a **personal Zalo user account** (unofficial). We keep `zalo` reserved for a potential future official Zalo API integration.
+
+## Finding IDs (directory)
+Use the directory CLI to discover peers/groups and their IDs:
+
+```bash
+clawdbot directory self --channel zalouser
+clawdbot directory peers list --channel zalouser --query "name"
+clawdbot directory groups list --channel zalouser --query "work"
+```
+
+## Limits
+- Outbound text is chunked to ~2000 characters (Zalo client limits).
+- Streaming is blocked by default.
+
+## Access control (DMs)
+`channels.zalouser.dmPolicy` supports: `pairing | allowlist | open | disabled` (default: `pairing`).
+
+Approve via:
+- `clawdbot pairing list zalouser`
+- `clawdbot pairing approve zalouser <code>`
+
+## Multi-account
+Accounts map to zca profiles. Example:
+
+```json5
+{
+  channels: {
+    zalouser: {
+      enabled: true,
+      defaultAccount: "default",
+      accounts: {
+        work: { enabled: true, profile: "work" }
+      }
+    }
+  }
+}
+```
+
+## Troubleshooting
+
+**`zca` not found:**
+- Install zca-cli and ensure it’s on `PATH` for the Gateway process.
+
+**Login doesn’t stick:**
+- `clawdbot channels status --probe`
+- Re-login: `clawdbot channels logout --channel zalouser && clawdbot channels login --channel zalouser`

docs/cli/directory.md

@@ -0,0 +1,38 @@
+---
+summary: "CLI reference for `clawdbot directory` (self, peers, groups)"
+read_when:
+  - You want to look up contacts/groups/self ids for a channel
+  - You are developing a channel directory adapter
+---
+
+# `clawdbot directory`
+
+Directory lookups for channels that support it (contacts/peers, groups, and “me”).
+
+## Common flags
+- `--channel <name>`: channel id/alias (default: `whatsapp`)
+- `--account <id>`: account id (default: channel default)
+- `--json`: output JSON
+
+## Self (“me”)
+
+```bash
+clawdbot directory self --channel zalouser
+```
+
+## Peers (contacts/users)
+
+```bash
+clawdbot directory peers list --channel zalouser
+clawdbot directory peers list --channel zalouser --query "name"
+clawdbot directory peers list --channel zalouser --limit 50
+```
+
+## Groups
+
+```bash
+clawdbot directory groups list --channel zalouser
+clawdbot directory groups list --channel zalouser --query "work"
+clawdbot directory groups members --channel zalouser --group-id <id>
+```
+

docs/docs.json

@@ -792,6 +792,7 @@
           "cli/health",
           "cli/sessions",
           "cli/channels",
+          "cli/directory",
           "cli/skills",
           "cli/plugins",
           "cli/memory",
@@ -907,6 +908,7 @@
           "channels/msteams",
           "channels/matrix",
           "channels/zalo",
+          "channels/zalouser",
           "broadcast-groups",
           "channels/troubleshooting",
           "channels/location"
@@ -945,6 +947,7 @@
           "tools",
           "plugin",
           "plugins/voice-call",
+          "plugins/zalouser",
           "tools/exec",
           "tools/web",
           "tools/apply-patch",

docs/plugin.md

@@ -37,6 +37,7 @@ See [Voice Call](/plugins/voice-call) for a concrete example plugin.
 
 - Microsoft Teams is plugin-only as of 2026.1.15; install `@clawdbot/msteams` if you use Teams.
 - [Voice Call](/plugins/voice-call) — `@clawdbot/voice-call`
+- [Zalo Personal](/plugins/zalouser) — `@clawdbot/zalouser`
 - [Matrix](/channels/matrix) — `@clawdbot/matrix`
 - [Zalo](/channels/zalo) — `@clawdbot/zalo`
 - [Microsoft Teams](/channels/msteams) — `@clawdbot/msteams`

docs/plugins/zalouser.md

@@ -0,0 +1,75 @@
+---
+summary: "Zalo Personal plugin: QR login + messaging via zca-cli (plugin install + channel config + CLI + tool)"
+read_when:
+  - You want Zalo Personal (unofficial) support in Clawdbot
+  - You are configuring or developing the zalouser plugin
+---
+
+# Zalo Personal (plugin)
+
+Zalo Personal support for Clawdbot via a plugin, using `zca-cli` to automate a normal Zalo user account.
+
+> **Warning:** Unofficial automation may lead to account suspension/ban. Use at your own risk.
+
+## Naming
+Channel id is `zalouser` to make it explicit this automates a **personal Zalo user account** (unofficial). We keep `zalo` reserved for a potential future official Zalo API integration.
+
+## Where it runs
+This plugin runs **inside the Gateway process**.
+
+If you use a remote Gateway, install/configure it on the **machine running the Gateway**, then restart the Gateway.
+
+## Install
+
+### Option A: install from npm
+
+```bash
+clawdbot plugins install @clawdbot/zalouser
+```
+
+Restart the Gateway afterwards.
+
+### Option B: install from a local folder (dev)
+
+```bash
+clawdbot plugins install ./extensions/zalouser
+cd ./extensions/zalouser && pnpm install
+```
+
+Restart the Gateway afterwards.
+
+## Prerequisite: zca-cli
+The Gateway machine must have `zca` on `PATH`:
+
+```bash
+zca --version
+```
+
+## Config
+Channel config lives under `channels.zalouser` (not `plugins.entries.*`):
+
+```json5
+{
+  channels: {
+    zalouser: {
+      enabled: true,
+      dmPolicy: "pairing"
+    }
+  }
+}
+```
+
+## CLI
+
+```bash
+clawdbot channels login --channel zalouser
+clawdbot channels logout --channel zalouser
+clawdbot channels status --probe
+clawdbot message send --channel zalouser --to <threadId> --message "Hello from Clawdbot"
+clawdbot directory peers list --channel zalouser --query "name"
+```
+
+## Agent tool
+Tool name: `zalouser`
+
+Actions: `send`, `image`, `link`, `friends`, `groups`, `me`, `status`