@lofa199419/waha-v2 2026.3.6 → 2026.3.7

package/README.md

@@ -0,0 +1,50 @@
+# `@lofa199419/waha-v2`
+
+OpenClaw WAHA v2 channel plugin with a packaged local CLI wrapper for WAHA session and messaging operations.
+
+## What ships
+
+- OpenClaw plugin files: `index.ts`, `src/`, `openclaw.plugin.json`
+- Skill docs: `skills/waha-v2/SKILL.md`
+- Local CLI wrappers:
+  - `bin/waha-cli`
+  - `bin/wa`
+  - `bin/wa-adv`
+  - `bin/waha-advanced-entrypoint`
+  - `bin/waha_cli.py`
+
+## Install into an OpenClaw state dir
+
+```bash
+npm install @lofa199419/waha-v2
+node node_modules/@lofa199419/waha-v2/scripts/install-openclaw-extension.mjs --state-dir /data/.openclaw --force
+```
+
+Or with `OPENCLAW_STATE_DIR`:
+
+```bash
+OPENCLAW_STATE_DIR=/data/.openclaw node node_modules/@lofa199419/waha-v2/scripts/install-openclaw-extension.mjs --force
+```
+
+## Runtime configuration
+
+The plugin package does not ship secrets. Provide WAHA configuration through your container or startup flow and render:
+
+```bash
+/data/.openclaw/extensions/waha-v2/bin/.env
+```
+
+Expected values:
+
+```dotenv
+WAHA_URL=https://your-waha-host
+WAHA_API_KEY=your-api-key
+WAHA_SESSION_DEFAULT=power
+```
+
+## Publish checklist
+
+```bash
+npm pack --dry-run
+npm publish --access public
+```

package/bin/wa

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+set -euo pipefail
+DIR="$(cd "$(dirname "$0")" && pwd)"
+if [[ -f "$DIR/.env" ]]; then
+  set -a
+  source "$DIR/.env"
+  set +a
+fi
+ARGS=("$@")
+HAS_SESSION=0
+for ((i=0; i<${#ARGS[@]}; i++)); do
+  if [[ "${ARGS[$i]}" == "--session" ]]; then
+    HAS_SESSION=1
+    break
+  fi
+done
+if [[ $HAS_SESSION -eq 0 && -n "${WAHA_SESSION_DEFAULT:-}" ]]; then
+  ARGS+=(--session "$WAHA_SESSION_DEFAULT")
+fi
+exec "$DIR/waha-cli" "${ARGS[@]}"

package/bin/wa-adv

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+set -euo pipefail
+DIR="$(cd "$(dirname "$0")" && pwd)"
+if [[ -f "$DIR/.env" ]]; then
+  set -a
+  source "$DIR/.env"
+  set +a
+fi
+exec "$DIR/waha-advanced-entrypoint" "$@"

package/bin/waha-advanced-entrypoint

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+DIR="$(cd "$(dirname "$0")" && pwd)"
+ENTRYPOINT="$DIR/waha_cli.py"
+
+if [[ ! -f "$ENTRYPOINT" ]]; then
+  echo "waha-v2: missing WAHA CLI shim at $ENTRYPOINT" >&2
+  exit 1
+fi
+
+exec python3 "$ENTRYPOINT" "$@"

package/bin/waha-cli

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+set -euo pipefail
+DIR="$(cd "$(dirname "$0")" && pwd)"
+ENV_FILE="$DIR/.env"
+if [ -f "$ENV_FILE" ]; then
+  set -a
+  # shellcheck disable=SC1090
+  . "$ENV_FILE"
+  set +a
+fi
+exec "$DIR/waha-advanced-entrypoint" "$@"

package/bin/waha_cli.py

@@ -0,0 +1,308 @@
+#!/usr/bin/env python3
+import argparse
+import json
+import os
+import sys
+import urllib.error
+import urllib.parse
+import urllib.request
+
+VERSION = "3.0.0"
+
+
+def env(name: str, default: str | None = None) -> str | None:
+    return os.environ.get(name, default)
+
+
+def require_env(name: str) -> str:
+    value = env(name)
+    if not value:
+        print(f"Missing required env: {name}", file=sys.stderr)
+        sys.exit(2)
+    return value
+
+
+def default_session() -> str:
+    return (
+        env("WAHA_SESSION_DEFAULT")
+        or env("WAHA_DEFAULT_SESSION")
+        or "default"
+    )
+
+
+def normalize_base_url(value: str) -> str:
+    return value.rstrip("/")
+
+
+def waha_request(method: str, path: str, body: dict | None = None, query: dict | None = None):
+    base_url = normalize_base_url(require_env("WAHA_URL"))
+    api_key = require_env("WAHA_API_KEY")
+    url = f"{base_url}{path}"
+    if query:
+      filtered = {k: v for k, v in query.items() if v is not None}
+      if filtered:
+        url = f"{url}?{urllib.parse.urlencode(filtered)}"
+    data = None
+    headers = {
+        "X-Api-Key": api_key,
+        "User-Agent": f"waha-cli/{VERSION}",
+        "Accept": "application/json, text/plain;q=0.9, */*;q=0.8",
+    }
+    if body is not None:
+        data = json.dumps(body).encode("utf-8")
+        headers["Content-Type"] = "application/json"
+    req = urllib.request.Request(url, data=data, headers=headers, method=method)
+    try:
+        with urllib.request.urlopen(req) as resp:
+            payload = resp.read()
+            content_type = resp.headers.get("content-type", "")
+            if "application/json" in content_type:
+                return json.loads(payload.decode("utf-8"))
+            return payload.decode("utf-8")
+    except urllib.error.HTTPError as exc:
+        try:
+            error_body = exc.read().decode("utf-8")
+            parsed = json.loads(error_body)
+            message = parsed.get("message", error_body)
+        except Exception:
+            message = exc.reason
+        print(f"WAHA API error ({exc.code}): {message}", file=sys.stderr)
+        sys.exit(1)
+    except urllib.error.URLError as exc:
+        print(f"WAHA API request failed: {exc.reason}", file=sys.stderr)
+        sys.exit(1)
+
+
+def print_json(data):
+    print(json.dumps(data, indent=2, ensure_ascii=False))
+
+
+def print_help():
+    print(
+        f"""waha-cli v{VERSION}
+
+Usage:
+  waha-cli --help
+  waha-cli --version
+  waha-cli <command> [options]
+
+Session and Auth:
+  waha-list-sessions
+  waha-get-session --session NAME
+  waha-create-session --name NAME
+  waha-start-session --session NAME
+  waha-stop-session --session NAME
+  waha-restart-session --session NAME
+  waha-delete-session --session NAME
+  waha-logout-session --session NAME
+  waha-get-qr-code --session NAME
+  waha-request-pairing-code --session NAME --phone-number NUMBER
+  waha-check-auth-status --session NAME
+
+Chats and Messages:
+  waha-get-chats [--session NAME] [--limit N] [--offset N]
+  waha-get-messages --chat-id ID [--session NAME] [--limit N] [--offset N]
+  waha-send-text --chat-id ID --text TEXT [--session NAME]
+
+Optional env:
+  WAHA_SESSION_DEFAULT / WAHA_DEFAULT_SESSION
+Required env:
+  WAHA_URL
+  WAHA_API_KEY"""
+    )
+
+
+def add_session_arg(parser):
+    parser.add_argument("--session", default=default_session())
+
+
+def build_parser():
+    parser = argparse.ArgumentParser(add_help=False)
+    parser.add_argument("--help", action="store_true")
+    parser.add_argument("--version", action="store_true")
+    parser.add_argument("command", nargs="?")
+    parser.add_argument("rest", nargs=argparse.REMAINDER)
+    return parser
+
+
+def cmd_list_sessions(_args):
+    print_json(waha_request("GET", "/api/sessions"))
+
+
+def cmd_get_session(args):
+    print_json(waha_request("GET", f"/api/sessions/{urllib.parse.quote(args.session, safe='')}"))
+
+
+def cmd_create_session(args):
+    body = {"name": args.name}
+    print_json(waha_request("POST", "/api/sessions", body))
+
+
+def cmd_simple_post(args, suffix):
+    print_json(
+        waha_request(
+            "POST",
+            f"/api/sessions/{urllib.parse.quote(args.session, safe='')}/{suffix}",
+        )
+    )
+
+
+def cmd_delete_session(args):
+    waha_request("DELETE", f"/api/sessions/{urllib.parse.quote(args.session, safe='')}")
+    print(f'Session "{args.session}" deleted successfully.')
+
+
+def cmd_logout_session(args):
+    waha_request("POST", f"/api/sessions/{urllib.parse.quote(args.session, safe='')}/logout")
+    print(f'Session "{args.session}" logged out successfully.')
+
+
+def cmd_get_qr_code(args):
+    qr = waha_request(
+        "GET",
+        f"/api/{urllib.parse.quote(args.session, safe='')}/auth/qr",
+        query={"format": "raw"},
+    )
+    if isinstance(qr, dict) and "value" in qr:
+        qr = qr["value"]
+    print(f'QR Code value for session "{args.session}":')
+    print(qr)
+
+
+def cmd_request_pairing_code(args):
+    result = waha_request(
+        "POST",
+        f"/api/{urllib.parse.quote(args.session, safe='')}/auth/request-code",
+        {"phoneNumber": args.phone_number},
+    )
+    code = result.get("code", "<missing>")
+    print(
+        f'Pairing code requested for {args.phone_number} on session "{args.session}".\n'
+        f"Code: {code}\n"
+        "Enter this code in WhatsApp on your phone."
+    )
+
+
+def cmd_check_auth_status(args):
+    info = waha_request("GET", f"/api/sessions/{urllib.parse.quote(args.session, safe='')}")
+    messages = {
+        "STOPPED": "Session is stopped. Start it first.",
+        "STARTING": "Session is starting up...",
+        "SCAN_QR_CODE": "Waiting for QR code scan. Use waha-get-qr-code or waha-request-pairing-code.",
+        "WORKING": "Session is authenticated and working.",
+        "FAILED": "Session has failed. Try restarting or re-authenticating.",
+    }
+    text = [
+        f"Session: {args.session}",
+        f"Status: {info.get('status', 'UNKNOWN')}",
+        messages.get(info.get("status"), f"Unknown status: {info.get('status')}"),
+    ]
+    me = info.get("me")
+    if isinstance(me, dict):
+        if me.get("id"):
+            text.append(f"Account ID: {me['id']}")
+        if me.get("pushName"):
+            text.append(f"Name: {me['pushName']}")
+    print("\n".join(text))
+
+
+def cmd_get_chats(args):
+    print_json(
+        waha_request(
+            "GET",
+            f"/api/{urllib.parse.quote(args.session, safe='')}/chats",
+            query={"limit": args.limit, "offset": args.offset},
+        )
+    )
+
+
+def cmd_get_messages(args):
+    query = {"limit": args.limit, "offset": args.offset}
+    print_json(
+        waha_request(
+            "GET",
+            f"/api/{urllib.parse.quote(args.session, safe='')}/chats/{urllib.parse.quote(args.chat_id, safe='')}/messages",
+            query=query,
+        )
+    )
+
+
+def cmd_send_text(args):
+    result = waha_request(
+        "POST",
+        "/api/sendText",
+        {"session": args.session, "chatId": args.chat_id, "text": args.text},
+    )
+    print(f"Message sent successfully.\nMessage ID: {result.get('id', '<missing>')}")
+
+
+COMMANDS = {
+    "waha-list-sessions": ("List sessions", cmd_list_sessions),
+    "waha-get-session": ("Get session", cmd_get_session),
+    "waha-create-session": ("Create session", cmd_create_session),
+    "waha-start-session": ("Start session", lambda args: cmd_simple_post(args, "start")),
+    "waha-stop-session": ("Stop session", lambda args: cmd_simple_post(args, "stop")),
+    "waha-restart-session": ("Restart session", lambda args: cmd_simple_post(args, "restart")),
+    "waha-delete-session": ("Delete session", cmd_delete_session),
+    "waha-logout-session": ("Logout session", cmd_logout_session),
+    "waha-get-qr-code": ("Get QR code", cmd_get_qr_code),
+    "waha-request-pairing-code": ("Request pairing code", cmd_request_pairing_code),
+    "waha-check-auth-status": ("Check auth status", cmd_check_auth_status),
+    "waha-get-chats": ("Get chats", cmd_get_chats),
+    "waha-list-chats": ("List chats", cmd_get_chats),
+    "waha-get-messages": ("Get messages", cmd_get_messages),
+    "waha-send-text": ("Send text", cmd_send_text),
+}
+
+
+def command_parser(command: str):
+    parser = argparse.ArgumentParser(prog=f"waha-cli {command}")
+    if command in {"waha-get-session", "waha-start-session", "waha-stop-session", "waha-restart-session", "waha-delete-session", "waha-logout-session", "waha-get-qr-code", "waha-check-auth-status"}:
+        add_session_arg(parser)
+    elif command == "waha-create-session":
+        parser.add_argument("--name", required=True)
+    elif command == "waha-request-pairing-code":
+        add_session_arg(parser)
+        parser.add_argument("--phone-number", required=True)
+    elif command in {"waha-get-chats", "waha-list-chats"}:
+        add_session_arg(parser)
+        parser.add_argument("--limit", type=int, default=50)
+        parser.add_argument("--offset", type=int, default=0)
+    elif command == "waha-get-messages":
+        add_session_arg(parser)
+        parser.add_argument("--chat-id", required=True)
+        parser.add_argument("--limit", type=int, default=20)
+        parser.add_argument("--offset", type=int, default=0)
+    elif command == "waha-send-text":
+        add_session_arg(parser)
+        parser.add_argument("--chat-id", required=True)
+        parser.add_argument("--text", required=True)
+    return parser
+
+
+def main():
+    parser = build_parser()
+    args = parser.parse_args()
+
+    if args.help or not args.command:
+        print_help()
+        return 0
+    if args.version:
+        print(VERSION)
+        return 0
+
+    command = args.command.replace("_", "-")
+    handler_entry = COMMANDS.get(command)
+    if handler_entry is None:
+        print(f"Unknown command: {args.command}", file=sys.stderr)
+        print_help()
+        return 2
+
+    cmd_parser = command_parser(command)
+    cmd_args = cmd_parser.parse_args(args.rest)
+    handler_entry[1](cmd_args)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/index.ts

@@ -33,22 +33,31 @@ const plugin = {
     api.registerChannel({ plugin: wahaV2Plugin });
 
     // Inbound webhook — matches both:
-    //   /webhooks/waha-v2            (legacy, routes by session name in payload)
+    //   /webhooks/waha-v2             (legacy, routes by session name in payload)
     //   /webhooks/waha-v2/{accountId} (preferred, unambiguous — accountId from path)
-    // Using registerHttpHandler so we can capture the dynamic {accountId} segment.
-    api.registerHttpHandler(async (req, res) => {
-      const url = req.url ?? "";
-      if (!url.startsWith(WAHA_V2_WEBHOOK_BASE)) return false;
-      // Extract optional accountId from the path suffix.
-      const suffix = url.slice(WAHA_V2_WEBHOOK_BASE.length).split("?")[0] ?? "";
-      const accountId = suffix.startsWith("/") ? suffix.slice(1) || undefined : undefined;
-      await handleWahaV2WebhookRequest(req, res, api.runtime.config.loadConfig(), accountId);
-      return true;
+    // Newer OpenClaw plugin SDK requires explicit route auth and no longer supports
+    // registerHttpHandler or dynamic path params in plugin routes.
+    api.registerHttpRoute({
+      path: WAHA_V2_WEBHOOK_BASE,
+      auth: "plugin",
+      match: "prefix",
+      handler: async (req, res) => {
+        const url = req.url ?? "";
+        if (!url.startsWith(WAHA_V2_WEBHOOK_BASE)) {
+          return false;
+        }
+        const suffix = url.slice(WAHA_V2_WEBHOOK_BASE.length).split("?")[0] ?? "";
+        const accountId = suffix.startsWith("/") ? suffix.slice(1) || undefined : undefined;
+        await handleWahaV2WebhookRequest(req, res, api.runtime.config.loadConfig(), accountId);
+        return true;
+      },
     });
 
     // Session management API routes — used by UI, CLI, and setup flows.
     api.registerHttpRoute({
       path: WAHA_V2_ROUTE_STATUS,
+      auth: "gateway",
+      match: "exact",
       handler: async (req, res) => {
         await handleWahaV2StatusRoute(req, res, api.runtime.config.loadConfig());
       },
@@ -56,6 +65,8 @@ const plugin = {
 
     api.registerHttpRoute({
       path: WAHA_V2_ROUTE_START,
+      auth: "gateway",
+      match: "exact",
       handler: async (req, res) => {
         await handleWahaV2StartRoute(req, res, api.runtime.config.loadConfig());
       },
@@ -63,6 +74,8 @@ const plugin = {
 
     api.registerHttpRoute({
       path: WAHA_V2_ROUTE_QR,
+      auth: "gateway",
+      match: "exact",
       handler: async (req, res) => {
         await handleWahaV2QrRoute(req, res, api.runtime.config.loadConfig());
       },
@@ -70,6 +83,8 @@ const plugin = {
 
     api.registerHttpRoute({
       path: WAHA_V2_ROUTE_REQUEST_CODE,
+      auth: "gateway",
+      match: "exact",
       handler: async (req, res) => {
         await handleWahaV2RequestCodeRoute(req, res, api.runtime.config.loadConfig());
       },
@@ -77,6 +92,8 @@ const plugin = {
 
     api.registerHttpRoute({
       path: WAHA_V2_ROUTE_WAIT,
+      auth: "gateway",
+      match: "exact",
       handler: async (req, res) => {
         await handleWahaV2WaitRoute(req, res, api.runtime.config.loadConfig());
       },

package/package.json

@@ -1,9 +1,26 @@
 {
   "name": "@lofa199419/waha-v2",
-  "version": "2026.3.6",
+  "version": "2026.3.7",
   "private": false,
   "description": "OpenClaw WAHA v2 channel plugin — independent WhatsApp HTTP API integration",
   "type": "module",
+  "files": [
+    "index.ts",
+    "src",
+    "openclaw.plugin.json",
+    "skills",
+    "bin/waha-cli",
+    "bin/wa",
+    "bin/wa-adv",
+    "bin/waha-advanced-entrypoint",
+    "bin/waha_cli.py",
+    "scripts/install-openclaw-extension.mjs",
+    "README.md"
+  ],
+  "scripts": {
+    "pack:check": "npm pack --dry-run",
+    "install:openclaw": "node scripts/install-openclaw-extension.mjs"
+  },
   "dependencies": {
     "axios": "1.6.0",
     "waha-node": "1.0.0",
@@ -35,6 +52,7 @@
     "install": {
       "npmSpec": "@lofa199419/waha-v2",
       "localPath": "extensions/waha-v2",
+      "script": "node scripts/install-openclaw-extension.mjs",
       "defaultChoice": "npm"
     }
   }

package/scripts/install-openclaw-extension.mjs

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const packageRoot = path.resolve(path.dirname(new URL(import.meta.url).pathname), "..");
+
+function parseArgs(argv) {
+  const out = {
+    stateDir: process.env.OPENCLAW_STATE_DIR || path.join(process.env.HOME || "", ".openclaw"),
+    force: false,
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--state-dir") {
+      out.stateDir = argv[i + 1];
+      i += 1;
+    } else if (arg === "--force") {
+      out.force = true;
+    } else if (arg === "--help" || arg === "-h") {
+      out.help = true;
+    } else {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+
+  return out;
+}
+
+async function exists(target) {
+  try {
+    await fs.access(target);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function ensureDir(target) {
+  await fs.mkdir(target, { recursive: true });
+}
+
+async function copyFile(relPath, destinationRoot) {
+  const source = path.join(packageRoot, relPath);
+  const destination = path.join(destinationRoot, relPath);
+  await ensureDir(path.dirname(destination));
+  await fs.copyFile(source, destination);
+  const stat = await fs.stat(source);
+  await fs.chmod(destination, stat.mode);
+}
+
+async function copyDirectory(relPath, destinationRoot) {
+  const source = path.join(packageRoot, relPath);
+  const destination = path.join(destinationRoot, relPath);
+  await ensureDir(path.dirname(destination));
+  await fs.cp(source, destination, { recursive: true, force: true });
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) {
+    console.log("Usage: node scripts/install-openclaw-extension.mjs [--state-dir PATH] [--force]");
+    process.exit(0);
+  }
+
+  if (!args.stateDir) {
+    throw new Error("Missing OpenClaw state dir. Pass --state-dir or set OPENCLAW_STATE_DIR.");
+  }
+
+  const extensionRoot = path.join(args.stateDir, "extensions", "waha-v2");
+  if (await exists(extensionRoot)) {
+    if (!args.force) {
+      throw new Error(`Target already exists: ${extensionRoot}. Re-run with --force to replace it.`);
+    }
+    await fs.rm(extensionRoot, { recursive: true, force: true });
+  }
+
+  await ensureDir(extensionRoot);
+
+  const directories = ["src", "skills", "scripts"];
+  const files = [
+    "index.ts",
+    "openclaw.plugin.json",
+    "package.json",
+    "README.md",
+    "bin/waha-cli",
+    "bin/wa",
+    "bin/wa-adv",
+    "bin/waha-advanced-entrypoint",
+    "bin/waha_cli.py",
+  ];
+
+  for (const relPath of directories) {
+    await copyDirectory(relPath, extensionRoot);
+  }
+  for (const relPath of files) {
+    await copyFile(relPath, extensionRoot);
+  }
+
+  console.log(`Installed waha-v2 into ${extensionRoot}`);
+}
+
+main().catch((error) => {
+  console.error(`[waha-v2 install] ${error.message}`);
+  process.exit(1);
+});