mirror of
https://github.com/openclaw/openclaw.git
synced 2026-03-12 07:20:45 +00:00
docs(zalouser): document js-native migration and breaking change
This commit is contained in:
Peter Steinberger
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
- **Gateway Integration**: Real-time message listening via the gateway
|
||||
- **Multi-Account Support**: Manage multiple Zalo personal accounts
|
||||
- **CLI Commands**: Full command-line interface for messaging
|
||||
- **Agent Tool**: AI agent integration for automated messaging
|
||||
- Channel plugin integration with onboarding + QR login
|
||||
- In-process listener/sender via `zca-js` (no external CLI)
|
||||
- Multi-account support
|
||||
- Agent tool integration (`zalouser`)
|
||||
- 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
|
||||
|
||||
# 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
|
||||
openclaw plugins install @openclaw/zalouser
|
||||
```
|
||||
|
||||
**Windows (PowerShell):**
|
||||
|
||||
```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:**
|
||||
### Option B: local source checkout
|
||||
|
||||
```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
|
||||
Invoke-WebRequest -Uri https://get.zca-cli.dev/latest/zca-windows-x64.exe -OutFile zca.exe
|
||||
```
|
||||
## Quick start
|
||||
|
||||
Available binaries:
|
||||
|
||||
- `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)
|
||||
### Login (QR)
|
||||
|
||||
```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
|
||||
openclaw message send --channel zalouser --target <threadId> --message "Hello from OpenClaw!"
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
After onboarding, your config will include:
|
||||
### Enable channel
|
||||
|
||||
```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
|
||||
|
||||
### Authentication
|
||||
## Useful commands
|
||||
|
||||
```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
|
||||
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"
|
||||
}
|
||||
```
|
||||
The extension registers a `zalouser` tool for AI agents.
|
||||
|
||||
Available actions: `send`, `image`, `link`, `friends`, `groups`, `me`, `status`
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
- **Login Issues:** Run `zca auth logout` then `zca auth login`
|
||||
- **API Errors:** Try `zca auth cache-refresh` or re-login
|
||||
- **File Uploads:** Check size (max 100MB) and path accessibility
|
||||
- Login not persisted: `openclaw channels logout --channel zalouser && openclaw channels login --channel zalouser`
|
||||
- Probe status: `openclaw channels status --probe`
|
||||
- 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).
|
||||
|
||||
Reference in New Issue
Block a user