diff --git a/CHANGELOG.md b/CHANGELOG.md index 95292623c6e..d4f4d6a1076 100644 --- a/CHANGELOG.md +++ b/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`). diff --git a/docs/channels/zalouser.md b/docs/channels/zalouser.md index e93e71a6f7e..f6abc4303ef 100644 --- a/docs/channels/zalouser.md +++ b/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 - -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). +No external `zca`/`openzca` CLI binary is required. ## 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. -- Uses `zca msg ...` to send replies (text/media/link). +- Runs entirely in-process via `zca-js`. +- 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:** - -- Install zca-cli and ensure it’s on `PATH` for the Gateway process. - -**Login doesn’t stick:** +**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. diff --git a/docs/plugins/zalouser.md b/docs/plugins/zalouser.md index 4d7981db0f7..1249db78bc9 100644 --- a/docs/plugins/zalouser.md +++ b/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.*`): diff --git a/extensions/zalouser/CHANGELOG.md b/extensions/zalouser/CHANGELOG.md index bf555f0b11f..002a5747cc3 100644 --- a/extensions/zalouser/CHANGELOG.md +++ b/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 diff --git a/extensions/zalouser/README.md b/extensions/zalouser/README.md index e5193080fee..c271de8bd4d 100644 --- a/extensions/zalouser/README.md +++ b/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 -- **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 --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 --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 ``` -### Account Management +## Agent tool -```bash -zca account list # List all profiles -zca account current # Show active profile -zca account switch -zca account remove -zca account label "Work Account" -``` - -### Messaging - -```bash -# Text -openclaw message send --channel zalouser --target --message "message" - -# Media (URL) -openclaw message send --channel zalouser --target --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 -zca group members - -# 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 --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).