docs(zalouser): document js-native migration and breaking change

CHANGELOG.md

@@ -7,6 +7,7 @@ Docs: https://docs.openclaw.ai
 ### Changes
 
 - Outbound adapters/plugins: add shared `sendPayload` support across direct-text-media, Discord, Slack, WhatsApp, Zalo, and Zalouser with multi-media iteration and chunk-aware text fallback. (#30144) Thanks @nohat.
+- Zalo Personal plugin (`@openclaw/zalouser`): rebuilt channel runtime to use native `zca-js` integration in-process, removing external CLI transport usage and keeping QR/login + send/listen flows fully inside OpenClaw.
 - CLI/Config validation: add `openclaw config validate` (with `--json`) to validate config files before gateway startup, and include detailed invalid-key paths in startup invalid-config errors. (#31220) thanks @Sid-Qin.
 - Sessions/Attachments: add inline file attachment support for `sessions_spawn` (subagent runtime only) with base64/utf8 encoding, transcript content redaction, lifecycle cleanup, and configurable limits via `tools.sessions_spawn.attachments`. (#16761) Thanks @napetrov.
 - Agents/Thinking defaults: set `adaptive` as the default thinking level for Anthropic Claude 4.6 models (including Bedrock Claude 4.6 refs) while keeping other reasoning-capable models at `low` unless explicitly configured.
@@ -37,6 +38,7 @@ Docs: https://docs.openclaw.ai
 
 ### Breaking
 
+- **BREAKING:** Zalo Personal plugin (`@openclaw/zalouser`) no longer depends on external `zca`-compatible CLI binaries (`openzca`, `zca-cli`) for runtime send/listen/login; operators should use `openclaw channels login --channel zalouser` after upgrade to refresh sessions in the new JS-native path.
 - **BREAKING:** Node exec approval payloads now require `systemRunPlan`. `host=node` approval requests without that plan are rejected.
 - **BREAKING:** Node `system.run` execution now pins path-token commands to the canonical executable path (`realpath`) in both allowlist and approval execution flows. Integrations/tests that asserted token-form argv (for example `tr`) must now accept canonical paths (for example `/usr/bin/tr`).
 

docs/channels/zalouser.md

@@ -1,5 +1,5 @@
 ---
-summary: "Zalo personal account support via zca-cli (QR login), capabilities, and configuration"
+summary: "Zalo personal account support via native zca-js (QR login), capabilities, and configuration"
 read_when:
   - Setting up Zalo Personal for OpenClaw
   - Debugging Zalo Personal login or message flow
@@ -8,7 +8,7 @@ title: "Zalo Personal"
 
 # Zalo Personal (unofficial)
 
-Status: experimental. This integration automates a **personal Zalo account** via `zca-cli`.
+Status: experimental. This integration automates a **personal Zalo account** via native `zca-js` inside OpenClaw.
 
 > **Warning:** This is an unofficial integration and may result in account suspension/ban. Use at your own risk.
 
@@ -20,19 +20,14 @@ Zalo Personal ships as a plugin and is not bundled with the core install.
 - Or from a source checkout: `openclaw plugins install ./extensions/zalouser`
 - Details: [Plugins](/tools/plugin)
 
-## Prerequisite: zca-cli
+No external `zca`/`openzca` CLI binary is required.
-
-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):
    - `openclaw channels login --channel zalouser`
-   - Scan the QR code in the terminal with the Zalo mobile app.
+   - Scan the QR code with the Zalo mobile app.
 3. Enable the channel:
 
 ```json5
@@ -51,8 +46,9 @@ The Gateway machine must have the `zca` binary available in `PATH`.
 
 ## What it is
 
-- Uses `zca listen` to receive inbound messages.
+- Runs entirely in-process via `zca-js`.
-- Uses `zca msg ...` to send replies (text/media/link).
+- Uses native event listeners to receive inbound messages.
+- Sends replies directly through the JS API (text/media/link).
 - Designed for “personal account” use cases where Zalo Bot API is not available.
 
 ## Naming
@@ -77,7 +73,8 @@ openclaw directory groups list --channel zalouser --query "work"
 ## Access control (DMs)
 
 `channels.zalouser.dmPolicy` supports: `pairing | allowlist | open | disabled` (default: `pairing`).
-`channels.zalouser.allowFrom` accepts user IDs or names. The wizard resolves names to IDs via `zca friend find` when available.
+
+`channels.zalouser.allowFrom` accepts user IDs or names. During onboarding, names are resolved to IDs using the plugin's in-process contact lookup.
 
 Approve via:
 
@@ -112,7 +109,7 @@ Example:
 
 ## Multi-account
 
-Accounts map to zca profiles. Example:
+Accounts map to `zalouser` profiles in OpenClaw state. Example:
 
 ```json5
 {
@@ -130,11 +127,16 @@ Accounts map to zca profiles. Example:
 
 ## Troubleshooting
 
-**`zca` not found:**
+**Login doesn't stick:**
-
-- Install zca-cli and ensure it’s on `PATH` for the Gateway process.
-
-**Login doesn’t stick:**
 
 - `openclaw channels status --probe`
 - Re-login: `openclaw channels logout --channel zalouser && openclaw channels login --channel zalouser`
+
+**Allowlist/group name didn't resolve:**
+
+- Use numeric IDs in `allowFrom`/`groups`, or exact friend/group names.
+
+**Upgraded from old CLI-based setup:**
+
+- Remove any old external `zca` process assumptions.
+- The channel now runs fully in OpenClaw without external CLI binaries.

docs/plugins/zalouser.md

@@ -1,5 +1,5 @@
 ---
-summary: "Zalo Personal plugin: QR login + messaging via zca-cli (plugin install + channel config + CLI + tool)"
+summary: "Zalo Personal plugin: QR login + messaging via native zca-js (plugin install + channel config + tool)"
 read_when:
   - You want Zalo Personal (unofficial) support in OpenClaw
   - You are configuring or developing the zalouser plugin
@@ -8,7 +8,7 @@ title: "Zalo Personal Plugin"
 
 # Zalo Personal (plugin)
 
-Zalo Personal support for OpenClaw via a plugin, using `zca-cli` to automate a normal Zalo user account.
+Zalo Personal support for OpenClaw via a plugin, using native `zca-js` to automate a normal Zalo user account.
 
 > **Warning:** Unofficial automation may lead to account suspension/ban. Use at your own risk.
 
@@ -22,6 +22,8 @@ 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.
 
+No external `zca`/`openzca` CLI binary is required.
+
 ## Install
 
 ### Option A: install from npm
@@ -41,14 +43,6 @@ 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.*`):

extensions/zalouser/CHANGELOG.md

@@ -4,7 +4,11 @@
 
 ### Changes
 
-- Version alignment with core OpenClaw release numbers.
+- Rebuilt the plugin to use native `zca-js` integration inside OpenClaw (no external `zca` CLI runtime dependency).
+
+### Breaking
+
+- **BREAKING:** Removed the old external CLI-based backend (`zca`/`openzca`/`zca-cli`) from runtime flow. Existing setups that depended on external CLI binaries should re-login with `openclaw channels login --channel zalouser` after upgrading.
 
 ## 2026.3.1
 

extensions/zalouser/README.md

@@ -1,103 +1,52 @@
 # @openclaw/zalouser
 
-OpenClaw extension for Zalo Personal Account messaging via [zca-cli](https://zca-cli.dev).
+OpenClaw extension for Zalo Personal Account messaging via native `zca-js` integration.
 
 > **Warning:** Using Zalo automation may result in account suspension or ban. Use at your own risk. This is an unofficial integration.
 
 ## Features
 
-- **Channel Plugin Integration**: Appears in onboarding wizard with QR login
+- Channel plugin integration with onboarding + QR login
-- **Gateway Integration**: Real-time message listening via the gateway
+- In-process listener/sender via `zca-js` (no external CLI)
-- **Multi-Account Support**: Manage multiple Zalo personal accounts
+- Multi-account support
-- **CLI Commands**: Full command-line interface for messaging
+- Agent tool integration (`zalouser`)
-- **Agent Tool**: AI agent integration for automated messaging
+- DM/group policy support
 
 ## Prerequisites
 
-Install `zca` CLI and ensure it's in your PATH:
+- OpenClaw Gateway
+- Zalo mobile app (for QR login)
 
-**macOS / Linux:**
+No external `zca`, `openzca`, or `zca-cli` binary is required.
+
+## Install
+
+### Option A: npm
 
 ```bash
-curl -fsSL https://get.zca-cli.dev/install.sh | bash
+openclaw plugins install @openclaw/zalouser
-
-# Or with custom install directory
-ZCA_INSTALL_DIR=~/.local/bin curl -fsSL https://get.zca-cli.dev/install.sh | bash
-
-# Install specific version
-curl -fsSL https://get.zca-cli.dev/install.sh | bash -s v1.0.0
-
-# Uninstall
-curl -fsSL https://get.zca-cli.dev/install.sh | bash -s uninstall
 ```
 
-**Windows (PowerShell):**
+### Option B: local source checkout
-
-```powershell
-irm https://get.zca-cli.dev/install.ps1 | iex
-
-# Or with custom install directory
-$env:ZCA_INSTALL_DIR = "C:\Tools\zca"; irm https://get.zca-cli.dev/install.ps1 | iex
-
-# Install specific version
-iex "& { $(irm https://get.zca-cli.dev/install.ps1) } -Version v1.0.0"
-
-# Uninstall
-iex "& { $(irm https://get.zca-cli.dev/install.ps1) } -Uninstall"
-```
-
-### Manual Download
-
-Download binary directly:
-
-**macOS / Linux:**
 
 ```bash
-curl -fsSL https://get.zca-cli.dev/latest/zca-darwin-arm64 -o zca && chmod +x zca
+openclaw plugins install ./extensions/zalouser
+cd ./extensions/zalouser && pnpm install
 ```
 
-**Windows (PowerShell):**
+Restart the Gateway after install.
 
-```powershell
+## Quick start
-Invoke-WebRequest -Uri https://get.zca-cli.dev/latest/zca-windows-x64.exe -OutFile zca.exe
-```
 
-Available binaries:
+### Login (QR)
-
-- `zca-darwin-arm64` - macOS Apple Silicon
-- `zca-darwin-x64` - macOS Intel
-- `zca-linux-arm64` - Linux ARM64
-- `zca-linux-x64` - Linux x86_64
-- `zca-windows-x64.exe` - Windows
-
-See [zca-cli](https://zca-cli.dev) for manual download (binaries for macOS/Linux/Windows) or building from source.
-
-## Quick Start
-
-### Option 1: Onboarding Wizard (Recommended)
-
-```bash
-openclaw onboard
-# Select "Zalo Personal" from channel list
-# Follow QR code login flow
-```
-
-### Option 2: Login (QR, on the Gateway machine)
 
 ```bash
 openclaw channels login --channel zalouser
-# Scan QR code with Zalo app
 ```
 
-### Send a Message
+Scan the QR code with the Zalo app on your phone.
 
-```bash
+### Enable channel
-openclaw message send --channel zalouser --target <threadId> --message "Hello from OpenClaw!"
-```
-
-## Configuration
-
-After onboarding, your config will include:
 
 ```yaml
 channels:
@@ -106,7 +55,24 @@ channels:
     dmPolicy: pairing # pairing | allowlist | open | disabled
 ```
 
-For multi-account:
+### Send a message
+
+```bash
+openclaw message send --channel zalouser --target <threadId> --message "Hello from OpenClaw"
+```
+
+## Configuration
+
+Basic:
+
+```yaml
+channels:
+  zalouser:
+    enabled: true
+    dmPolicy: pairing
+```
+
+Multi-account:
 
 ```yaml
 channels:
@@ -122,104 +88,32 @@ channels:
         profile: work
 ```
 
-## Commands
+## Useful commands
-
-### Authentication
 
 ```bash
-openclaw channels login --channel zalouser              # Login via QR
+openclaw channels login --channel zalouser
 openclaw channels login --channel zalouser --account work
 openclaw channels status --probe
 openclaw channels logout --channel zalouser
-```
 
-### Directory (IDs, contacts, groups)
-
-```bash
 openclaw directory self --channel zalouser
 openclaw directory peers list --channel zalouser --query "name"
 openclaw directory groups list --channel zalouser --query "work"
 openclaw directory groups members --channel zalouser --group-id <id>
 ```
 
-### Account Management
+## Agent tool
 
-```bash
+The extension registers a `zalouser` tool for AI agents.
-zca account list      # List all profiles
-zca account current   # Show active profile
-zca account switch <profile>
-zca account remove <profile>
-zca account label <profile> "Work Account"
-```
-
-### Messaging
-
-```bash
-# Text
-openclaw message send --channel zalouser --target <threadId> --message "message"
-
-# Media (URL)
-openclaw message send --channel zalouser --target <threadId> --message "caption" --media-url "https://example.com/img.jpg"
-```
-
-### Listener
-
-The listener runs inside the Gateway when the channel is enabled. For debugging,
-use `openclaw channels logs --channel zalouser` or run `zca listen` directly.
-
-### Data Access
-
-```bash
-# Friends
-zca friend list
-zca friend list -j    # JSON output
-zca friend find "name"
-zca friend online
-
-# Groups
-zca group list
-zca group info <groupId>
-zca group members <groupId>
-
-# Profile
-zca me info
-zca me id
-```
-
-## Multi-Account Support
-
-Use `--profile` or `-p` to work with multiple accounts:
-
-```bash
-openclaw channels login --channel zalouser --account work
-openclaw message send --channel zalouser --account work --target <id> --message "Hello"
-ZCA_PROFILE=work zca listen
-```
-
-Profile resolution order: `--profile` flag > `ZCA_PROFILE` env > default
-
-## Agent Tool
-
-The extension registers a `zalouser` tool for AI agents:
-
-```json
-{
-  "action": "send",
-  "threadId": "123456",
-  "message": "Hello from AI!",
-  "isGroup": false,
-  "profile": "default"
-}
-```
 
 Available actions: `send`, `image`, `link`, `friends`, `groups`, `me`, `status`
 
 ## Troubleshooting
 
-- **Login Issues:** Run `zca auth logout` then `zca auth login`
+- Login not persisted: `openclaw channels logout --channel zalouser && openclaw channels login --channel zalouser`
-- **API Errors:** Try `zca auth cache-refresh` or re-login
+- Probe status: `openclaw channels status --probe`
-- **File Uploads:** Check size (max 100MB) and path accessibility
+- Name resolution issues (allowlist/groups): use numeric IDs or exact Zalo names
 
 ## Credits
 
-Built on [zca-cli](https://zca-cli.dev) which uses [zca-js](https://github.com/RFS-ADRENO/zca-js).
+Built on [zca-js](https://github.com/RFS-ADRENO/zca-js).