Add WhatsApp transport via openclaw/wacli + wp-admin pairing UI

[lezama]

Summary

Connects openclaWP to WhatsApp by treating an inbound webhook from openclaw/wacli (whatsmeow-based linked-device CLI, brew install steipete/tap/wacli) as the entry point into the openclawp/chat ability. Each incoming message is HMAC-verified, forwarded to a configured agent, and the reply is posted back through wacli send.

This is the first public consumer of AgentsAPI\AI\Channels\WP_Agent_Channel. The portable agent-loop plumbing (validate, extract, dispatch, deliver, lifecycle hooks, session continuity) lives in agents-api; this PR only fills in wacli-specific I/O.

What's in it

Channel + transport

• OpenclaWP_Wacli_Channel extends WP_Agent_Channel. The base class owns the agent loop; this concrete channel does payload parsing, allowlist, silent_skip for own-bot echoes / disallowed chats, and the wacli send text shell-out.
• OpenclaWP_Wacli_Transport — REST endpoint /openclawp/v1/wacli/webhook. Verifies the X-Wacli-Signature: sha256=… HMAC, parses the wacli payload, constructs the channel, scopes a single-request add_filter('openclawp_chat_ability_permission', '__return_true') while running the chat ability, and returns 200/4xx/5xx based on the channel result.

Pair from wp-admin

• OpenclaWP_Wacli_Process — process manager that spawns wacli auth --follow --qr-format text --events detached via nohup, reads the NDJSON event stream, exposes a state machine to wp-admin.
• OpenclaWP_Wacli_Admin + assets/wacli-admin.{js,css} + assets/qrcode.min.js — wp-admin → openclaWP → WhatsApp page. Polls /openclawp/v1/wacli/state every 2s, renders a live QR in the browser as wacli rotates it, switches to a "Connected ✅" panel once paired. Settings card below for target agent (dropdown of registered agents), allowed chats (JID textarea), and wacli binary (auto-detected, overridable).
• OpenclaWP_Wacli_Rest — admin REST routes (manage_options): GET /wacli/state, POST /wacli/connect, POST /wacli/disconnect, GET|POST /wacli/settings.

WP-CLI

• wp openclawp wacli setup [--rotate] — prints the wacli sync --follow --webhook … --webhook-secret … command with an auto-generated HMAC secret.
• wp openclawp wacli ping <jid> <text> — exercise the outbound path without a webhook in the loop.

Setup

brew install steipete/tap/wacli
wp option update openclawp_wacli_agent <slug-of-registered-agent>

Then wp-admin → openclaWP → WhatsApp → Connect WhatsApp, scan the QR with WhatsApp → Settings → Linked Devices. Configure the allowlist and agent in the Settings card on the same page.

The webhook URL and HMAC secret are exposed via wp openclawp wacli setup for users who'd rather configure wacli from the CLI.

Loop prevention + safety

• Messages with from_me: true are dropped via silent_skip, so the agent never reacts to its own outgoing replies appearing on the next sync event.
• openclawp_wacli_allowed_jids is a comma/newline-separated allowlist of chat JIDs. Empty allowlist = allow every inbound chat (called out as risky in the UI).
• Send errors log to error_log instead of replying to the user's WhatsApp — the agent's failures don't bleed into the personal thread.

Test plan

• 23 PHPUnit unit tests — HMAC verification (WacliTransportTest, 7 cases), settings normalizer (WacliSettingsTest, 4 cases), wacli process state machine (WacliProcessTest, 6 cases), plus 6 misc.
• End-to-end smoke in a Studio WP 7.0-RC2 site:
  • POST /wacli/webhook with valid HMAC → 200 {ok: true, note: "replied"}.
  • POST with bad signature → 401 {error: "bad_signature"}.
  • POST with from_me: true → 200 {ok: true, note: "self_message"} (silent_skip path).
• No regressions: existing 5 message-adapter tests still pass.

Dependency

composer.json pinned to automattic/agents-api: dev-add/agent-channel as dev-main so the PR can be installed against the open agents-api PR. Once Automattic/agents-api#99 merges, this can flip back to dev-main.

Architecture

The channel is the portable piece — anyone can write a Telegram, Email, or Slack channel by extending WP_Agent_Channel, and the agent loop behaves identically. See Automattic/agents-api#99 for the base class contract.

🤖 Generated with Claude Code