waha-openclaw-channel 1.2.1 → 1.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (13) hide show
  1. package/README.md +454 -65
  2. package/package.json +1 -1
  3. package/src/accounts.ts +149 -149
  4. package/src/monitor.ts +3 -0
  5. package/src/presence.ts +4 -17
  6. package/src/send.ts +5 -5
  7. package/config-example.json +0 -48
  8. package/docs/admin-panel.md +0 -72
  9. package/docs/configuration.md +0 -118
  10. package/docs/directory.md +0 -53
  11. package/docs/dm-filter.md +0 -41
  12. package/docs/presence.md +0 -43
  13. package/docs/troubleshooting.md +0 -57
package/README.md CHANGED
@@ -1,103 +1,492 @@
1
- # OpenClaw WAHA Plugin
1
+ # OpenClaw WAHA Plugin — Developer Reference
2
2
 
3
- WhatsApp channel plugin for [OpenClaw](https://openclaw.dev) via [WAHA](https://waha.devlike.pro/) (WhatsApp HTTP API).
3
+ **Plugin ID:** `waha`
4
+ **Platform:** WhatsApp (via WAHA HTTP API)
5
+ **Last updated:** 2026-03-07
4
6
 
5
- Receive WhatsApp messages, route them through OpenClaw AI agents, and reply with text and voice — with human-like typing simulation.
7
+ ---
6
8
 
7
- ## Features
9
+ ## 1. Overview
8
10
 
9
- - **Webhook receiver** — HMAC-verified inbound message handling
10
- - **Access control** — DM policies, group allowlists, per-contact settings
11
- - **DM keyword filter** — gate messages by pattern before they reach the AI (saves tokens)
12
- - **Human presence** — realistic read receipts, typing indicators with random pauses
13
- - **Contact directory** — SQLite-backed contact tracking with per-DM overrides
14
- - **Admin panel** — browser-based SPA for stats, settings, directory, and docs
15
- - **Multi-account** — run multiple WAHA sessions from one plugin instance
11
+ This plugin bridges OpenClaw AI agents to WhatsApp through the WAHA (WhatsApp HTTP API) server. It enables the "Sammie" bot to receive WhatsApp messages via webhook, route them through OpenClaw's AI agent pipeline, and deliver replies back through WAHA — including text responses and TTS-generated voice notes.
16
12
 
17
- ## Installation
13
+ The plugin operates as a channel adapter within the OpenClaw plugin-sdk framework. It:
18
14
 
19
- ```bash
20
- npm install waha-openclaw-channel
15
+ - Runs an HTTP webhook server to receive inbound WAHA events
16
+ - Applies access control (DM policy, group allowlists with both `@c.us` and `@lid` JID formats)
17
+ - Simulates human-like presence (read receipts, typing indicators with random pauses) before replying
18
+ - Delivers AI-generated text and voice replies through WAHA's REST API
19
+ - Enforces session guardrails (only the "logan" session can send outbound messages)
20
+
21
+ ---
22
+
23
+ ## 2. File Listing
24
+
25
+ | File | Lines | Description |
26
+ |------|-------|-------------|
27
+ | `channel.ts` | ~340 | Channel plugin registration and lifecycle. Exports the `ChannelPlugin` definition with metadata, capabilities (reactions, media, markdown), account resolution, and outbound delivery adapter. Wires up the webhook monitor, inbound handler, and send functions. |
28
+ | `inbound.ts` | ~380 | Inbound message handler. Receives parsed `WahaInboundMessage` from the monitor, applies DM/group access control via `resolveDmGroupAccessWithCommandGate`, runs the DM keyword filter, starts the human presence simulation, dispatches the message to the AI agent, and delivers the reply. |
29
+ | `dm-filter.ts` | ~145 | DM keyword filter. `DmFilter` class with regex caching, god mode bypass for super-users, and stats tracking (dropped/allowed/tokensEstimatedSaved). Fail-open: any error allows messages through. |
30
+ | `send.ts` | ~250 | WAHA REST API wrappers. Provides `sendWahaText()`, `sendWahaMediaBatch()`, `sendWahaReaction()`, `sendWahaPresence()`, `sendWahaSeen()`, and the internal `callWahaApi()` HTTP client. Includes `assertAllowedSession()` guardrail, `buildFilePayload()` for base64 encoding of local TTS files, and `resolveMime()` for MIME type detection with file-extension fallback. |
31
+ | `presence.ts` | ~170 | Human mimicry presence system. Implements the 4-phase presence simulation: seen, read delay, typing with random pauses (flicker), and reply-length padding. Exports `startHumanPresence()` which returns a `PresenceController` with `finishTyping()` and `cancelTyping()` methods. |
32
+ | `types.ts` | ~130 | TypeScript type definitions. Defines `CoreConfig`, `WahaChannelConfig`, `WahaAccountConfig`, `PresenceConfig`, `DmFilterConfig`, `WahaWebhookEnvelope`, `WahaInboundMessage`, `WahaReactionEvent`, and `WahaWebhookConfig`. |
33
+ | `config-schema.ts` | ~86 | Zod validation schema for the `channels.waha` config section. Validates all account-level and channel-level settings including secret inputs, policies, presence parameters, DM filter config, and markdown options. |
34
+ | `accounts.ts` | ~140 | Multi-account resolution. Resolves which WAHA account (baseUrl, apiKey, session) to use for a given operation. Supports a default account plus named sub-accounts under `channels.waha.accounts`. Handles API key resolution from env vars, files, or direct strings. |
35
+ | `normalize.ts` | ~30 | JID normalization utilities. `normalizeWahaMessagingTarget()` strips `waha:`, `whatsapp:`, `chat:` prefixes. `normalizeWahaAllowEntry()` lowercases for allowlist comparison. `resolveWahaAllowlistMatch()` checks if a sender JID is in the allowlist (supports `*` wildcard). |
36
+ | `monitor.ts` | ~506 | Webhook HTTP server, health monitoring, and admin panel. Starts an HTTP server on the configured port (default 8050). Handles `/healthz`, `/admin` (HTML dashboard), `/api/admin/stats` (JSON stats), and the main webhook path. Validates HMAC signatures and dispatches inbound events. |
37
+ | `runtime.ts` | ~15 | Runtime singleton access. `setWahaRuntime()` / `getWahaRuntime()` store and retrieve the OpenClaw `PluginRuntime` instance for use across modules. |
38
+ | `signature.ts` | ~30 | HMAC webhook verification. `verifyWahaWebhookHmac()` validates the `X-Webhook-Hmac` header using SHA-512, accepting hex or base64 signature formats. Uses `crypto.timingSafeEqual()` for constant-time comparison. |
39
+ | `secret-input.ts` | ~15 | Secret field schema. Re-exports OpenClaw SDK secret input utilities and provides `buildSecretInputSchema()` which accepts either a plain string or a `{ source, provider, id }` object for env/file/exec-based secret resolution. |
40
+
41
+ ---
42
+
43
+ ## 3. DM Keyword Filter
44
+
45
+ The DM keyword filter (`dm-filter.ts`) gates inbound DMs by keyword BEFORE they reach the AI agent. Only messages matching at least one pattern are processed; others are silently dropped. This prevents the AI from consuming tokens on irrelevant or unsolicited messages.
46
+
47
+ ### Config (under `channels.waha`)
48
+
49
+ ```json
50
+ "dmFilter": {
51
+ "enabled": true,
52
+ "mentionPatterns": ["sammie", "help", "hello", "bot", "ai"],
53
+ "godModeBypass": true,
54
+ "godModeSuperUsers": [
55
+ { "identifier": "972544329000", "platform": "whatsapp", "passwordRequired": false }
56
+ ],
57
+ "tokenEstimate": 2500
58
+ }
21
59
  ```
22
60
 
23
- > Requires `better-sqlite3` (native addon) — ensure a C++ build toolchain is available (`node-gyp`).
61
+ | Field | Type | Default | Description |
62
+ |-------|------|---------|-------------|
63
+ | `enabled` | `boolean` | `false` | Enable/disable the filter |
64
+ | `mentionPatterns` | `string[]` | `[]` | Regex patterns (case-insensitive). Message must match at least one. Empty list means no restriction. |
65
+ | `godModeBypass` | `boolean` | `true` | Super-users bypass the filter entirely |
66
+ | `godModeSuperUsers` | `array` | `[]` | List of users who bypass the filter (phone in E.164 or JID format) |
67
+ | `tokenEstimate` | `number` | `2500` | Estimated tokens saved per dropped message (used for stats display) |
68
+
69
+ ### Behavior
70
+
71
+ - **Filter disabled**: All messages pass through (stats count as allowed)
72
+ - **No patterns**: All messages pass through (no restriction configured)
73
+ - **God mode**: Super-users bypass pattern matching entirely. Israeli phone normalization handles 05X/972X/+972X and JID suffixes (`@c.us`, `@lid`, `@s.whatsapp.net`)
74
+ - **Pattern match**: Message is allowed if ANY pattern matches (case-insensitive regex)
75
+ - **No match**: Message is silently dropped — no reply, no error, no pairing message
76
+ - **Fail-open**: Any error in the filter allows the message through (avoids outages from filter bugs)
77
+
78
+ ### Regex caching
79
+
80
+ Patterns are compiled to `RegExp` objects once and cached. The cache key is the joined pattern array. If config updates (e.g. via `updateConfig()`), the cache is invalidated and rebuilt on next check.
81
+
82
+ ### Stats tracking
83
+
84
+ The filter maintains runtime counters per account:
85
+ - `dropped`: messages silently dropped
86
+ - `allowed`: messages passed through
87
+ - `tokensEstimatedSaved`: `dropped * tokenEstimate` — rough estimate of AI tokens saved
24
88
 
25
- ## Quick Start
89
+ Recent events (last 50) are stored in memory with timestamp, pass/fail, reason, and text preview.
26
90
 
27
- 1. Add the WAHA channel to your `openclaw.json`:
91
+ ---
28
92
 
93
+ ## 4. Admin Panel
94
+
95
+ A browser-based admin panel is served at `http://<host>:<webhookPort>/admin` (default port 8050).
96
+
97
+ ### Access
98
+
99
+ ```
100
+ http://100.114.126.43:8050/admin
101
+ ```
102
+
103
+ ### Features
104
+
105
+ - **DM Filter card**: Shows enabled status, keyword patterns, stats (dropped/allowed/tokens saved), and a live event log (last 20 events with timestamp, reason, and message preview)
106
+ - **Presence System card**: Displays current presence config (wpm, read delays, typing durations, jitter)
107
+ - **Access Control card**: Shows dmPolicy, groupPolicy, allowFrom, groupAllowFrom, and allowedGroups
108
+ - **Session Info card**: Shows session name, baseUrl, webhookPort, and server time
109
+ - **Auto-refresh**: Reloads stats every 30 seconds. Manual refresh via button.
110
+
111
+ ### Stats API
112
+
113
+ ```bash
114
+ curl http://100.114.126.43:8050/api/admin/stats
115
+ ```
116
+
117
+ Returns JSON:
29
118
  ```json
119
+ {
120
+ "dmFilter": {
121
+ "enabled": true,
122
+ "patterns": ["sammie", "help"],
123
+ "stats": { "dropped": 5, "allowed": 12, "tokensEstimatedSaved": 12500 },
124
+ "recentEvents": [
125
+ { "ts": 1772902231754, "pass": false, "reason": "no_keyword_match", "preview": "hello world" }
126
+ ]
127
+ },
128
+ "presence": { "enabled": true, "wpm": 42, ... },
129
+ "access": { "dmPolicy": "pairing", "allowFrom": [...], ... },
130
+ "session": "3cf11776_logan",
131
+ "webhookPort": 8050,
132
+ "serverTime": "2026-03-07T18:50:00.000Z"
133
+ }
134
+ ```
135
+
136
+ ### Implementation notes
137
+
138
+ - Zero build tooling: the entire admin dashboard is an embedded HTML/CSS/JS template string in `monitor.ts`
139
+ - Admin routes are added BEFORE the POST-only webhook guard in the HTTP server handler
140
+ - No authentication on admin routes (only accessible from localhost by default since `webhookHost: 0.0.0.0` binds to all interfaces — restrict via firewall if needed)
141
+
142
+ ---
143
+
144
+ ## 5. Human Mimicry Presence System
145
+
146
+ ### Problem
147
+
148
+ A bot that instantly shows "typing..." and replies in 200ms is obviously non-human. WhatsApp users notice deterministic timing patterns, which degrades the conversational experience.
149
+
150
+ ### Solution
151
+
152
+ The presence system simulates a 4-phase human interaction pattern with randomized timing at every step:
153
+
154
+ ```
155
+ Phase 1: SEEN Phase 2: READ Phase 3: TYPING Phase 4: REPLY
156
+ (with pauses)
157
+ [msg arrives] --> [blue ticks] --> [typing... ···] --> [send message]
158
+ | | |
159
+ v v v
160
+ sendSeen() sleep(readDelay) typing ON/OFF flicker
161
+ (random pauses)
162
+ + padding if AI was fast
163
+ ```
164
+
165
+ ### Flow Detail
166
+
167
+ 1. **Seen** (`sendSeen`): If enabled, immediately marks the message as read (blue ticks).
168
+ 2. **Read Delay** (`readDelayMs`): Pauses to simulate the time a human takes to read the incoming message. Duration scales with message length (`msPerReadChar * charCount`), clamped to `readDelayMs` bounds, then jittered.
169
+ 3. **Typing with Flicker**: Sets typing indicator ON, then enters a loop where it randomly pauses typing (OFF for `pauseDurationMs`, then ON again) at `pauseIntervalMs` intervals with `pauseChance` probability. This continues while the AI generates its response.
170
+ 4. **Reply-Length Padding** (`finishTyping`): After the AI responds, calculates how long a human would take to type the reply at `wpm` words-per-minute. If the AI was faster than that, pads with additional typing flicker. If the AI was slower, no padding is needed.
171
+
172
+ ### Timing Parameters
173
+
174
+ | Parameter | Type | Default | Description |
175
+ |-----------|------|---------|-------------|
176
+ | `enabled` | `boolean` | `true` | Master switch for the entire presence system |
177
+ | `sendSeen` | `boolean` | `true` | Send read receipt (blue ticks) before typing |
178
+ | `wpm` | `number` | `42` | Simulated typing speed in words-per-minute |
179
+ | `readDelayMs` | `[min, max]` | `[500, 4000]` | Clamp range for read delay (ms) |
180
+ | `msPerReadChar` | `number` | `30` | Base read time per character of incoming message |
181
+ | `typingDurationMs` | `[min, max]` | `[1500, 15000]` | Clamp range for total typing duration (ms) |
182
+ | `pauseChance` | `number` | `0.3` | Probability (0-1) of pausing typing each interval |
183
+ | `pauseDurationMs` | `[min, max]` | `[500, 2000]` | Duration range for each typing pause (ms) |
184
+ | `pauseIntervalMs` | `[min, max]` | `[2000, 5000]` | Interval range between pause-chance checks (ms) |
185
+ | `jitter` | `[min, max]` | `[0.7, 1.3]` | Multiplier range applied to all computed durations |
186
+
187
+ ### Jitter Mechanics
188
+
189
+ Every computed duration is multiplied by `rand(jitter[0], jitter[1])` before use. With the default `[0.7, 1.3]`, a base delay of 2000ms becomes anywhere from 1400ms to 2600ms. This prevents timing fingerprinting.
190
+
191
+ ### AI Fast vs Slow
192
+
193
+ - **AI responds in 2s, human typing estimate is 8s**: Presence pads with 6s of additional typing flicker before sending.
194
+ - **AI responds in 12s, human typing estimate is 8s**: No padding needed. Reply sends immediately after AI finishes (typing indicator was already running during generation).
195
+
196
+ ---
197
+
198
+ ## 6. Configuration Reference
199
+
200
+ All configuration lives in `~/.openclaw/openclaw.json` AND `/home/omer/.openclaw/workspace/openclaw.json` under `channels.waha`. The gateway uses the **workspace config** (set by `OPENCLAW_CONFIG_PATH`), so changes must be applied there.
201
+
202
+ ### Full Config Structure
203
+
204
+ ```jsonc
30
205
  {
31
206
  "channels": {
32
207
  "waha": {
208
+ // --- Connection ---
33
209
  "enabled": true,
34
- "baseUrl": "http://localhost:3004",
35
- "apiKey": "your-waha-api-key",
36
- "session": "your-session-name",
37
- "webhookPort": 8050,
38
- "webhookHmacKey": "your-hmac-key",
39
- "dmPolicy": "allowlist",
40
- "allowFrom": ["15551234567@c.us"]
210
+ "baseUrl": "http://127.0.0.1:3004", // WAHA server URL
211
+ "apiKey": "XcTCX9cn84LE/...", // WHATSAPP_API_KEY (NOT WAHA_API_KEY)
212
+ "session": "3cf11776_logan", // WAHA session name
213
+
214
+ // --- Webhook Server ---
215
+ "webhookHost": "0.0.0.0", // Bind address (default: 0.0.0.0)
216
+ "webhookPort": 8050, // Webhook listener port (default: 8050)
217
+ "webhookPath": "/webhook/waha", // Webhook URL path
218
+ "webhookHmacKey": "95b5f1b4ae57...", // HMAC-SHA512 key for signature verification
219
+
220
+ // --- Access Control ---
221
+ "dmPolicy": "allowlist", // "pairing" | "open" | "closed" | "allowlist"
222
+ "groupPolicy": "allowlist", // "allowlist" | "open" | "closed"
223
+ "allowFrom": [ // DM senders allowed (when dmPolicy=allowlist)
224
+ "972544329000@c.us",
225
+ "271862907039996@lid"
226
+ ],
227
+ "groupAllowFrom": [ // Group message senders allowed
228
+ "972544329000@c.us", // @c.us JID
229
+ "271862907039996@lid" // @lid JID (NOWEB engine sends these!)
230
+ ],
231
+
232
+ // --- Presence (Human Mimicry) ---
233
+ "presence": {
234
+ "enabled": true,
235
+ "sendSeen": true,
236
+ "wpm": 42,
237
+ "readDelayMs": [500, 4000],
238
+ "msPerReadChar": 30,
239
+ "typingDurationMs": [1500, 15000],
240
+ "pauseChance": 0.3,
241
+ "pauseDurationMs": [500, 2000],
242
+ "pauseIntervalMs": [2000, 5000],
243
+ "jitter": [0.7, 1.3]
244
+ },
245
+
246
+ // --- Optional Features ---
247
+ "actions": {
248
+ "reactions": true // Enable emoji reactions
249
+ },
250
+ "markdown": {
251
+ "enabled": true,
252
+ "tables": "auto" // "auto" | "markdown" | "text"
253
+ },
254
+ "replyPrefix": {
255
+ "enabled": false
256
+ },
257
+ "blockStreaming": false,
258
+
259
+ // --- Multi-Account (optional) ---
260
+ "accounts": {
261
+ "secondary": {
262
+ "baseUrl": "http://other-waha:3004",
263
+ "apiKey": "...",
264
+ "session": "other_session"
265
+ }
266
+ },
267
+ "defaultAccount": "default"
41
268
  }
42
269
  }
43
270
  }
44
271
  ```
45
272
 
46
- 2. Configure your WAHA session to send webhooks to `http://your-server:8050/webhook/waha`.
273
+ ### Access Control Notes
274
+
275
+ - `dmPolicy: "allowlist"` + `allowFrom` restricts DMs to listed JIDs only
276
+ - `groupPolicy: "allowlist"` + `groupAllowFrom` restricts group responses to messages from listed sender JIDs
277
+ - `groupAllowFrom` filters by **sender JID** (participant), NOT by group JID
278
+ - Use `"*"` to allow all senders (dangerous in production)
279
+ - **CRITICAL**: WAHA NOWEB engine sends sender JIDs as `@lid`, not `@c.us`. You MUST include BOTH formats for each allowed user.
47
280
 
48
- 3. Restart the OpenClaw gateway. Verify with:
281
+ ### Finding a User's LID
49
282
 
50
283
  ```bash
51
- curl http://localhost:8050/healthz
284
+ docker exec -i postgres-waha psql -U admin -d waha_noweb_3cf11776_logan \
285
+ -c "SELECT id, pn FROM lid_map WHERE pn LIKE '%PHONE_NUMBER%'"
52
286
  ```
53
287
 
54
- 4. Open the admin panel at `http://localhost:8050/admin`.
288
+ ---
55
289
 
56
- See [`config-example.json`](config-example.json) for a full configuration example.
290
+ ## 7. Installation / Reinstallation
57
291
 
58
- ## Documentation
292
+ ### File Locations
59
293
 
60
- | Doc | Description |
61
- |-----|-------------|
62
- | [Configuration](docs/configuration.md) | Full config reference with all options |
63
- | [Admin Panel & API](docs/admin-panel.md) | Admin SPA tabs, REST endpoints |
64
- | [DM Filter](docs/dm-filter.md) | Keyword filter setup, god mode, stats |
65
- | [Presence System](docs/presence.md) | Human mimicry timing parameters |
66
- | [Directory & Per-DM Settings](docs/directory.md) | Contact tracking, per-contact overrides |
67
- | [Troubleshooting](docs/troubleshooting.md) | Common issues and fixes |
294
+ The plugin source exists in TWO locations that must always be kept in sync:
68
295
 
69
- ## Architecture
296
+ | Location | Purpose |
297
+ |----------|---------|
298
+ | `/home/omer/.openclaw/extensions/waha/src/` | **Runtime** — what OpenClaw actually loads |
299
+ | `/home/omer/.openclaw/workspace/skills/waha-openclaw-channel/src/` | **Development** — workspace copy |
70
300
 
301
+ The main config file is at `/home/omer/.openclaw/openclaw.json` under `channels.waha`.
302
+
303
+ ### Deploying Changes
304
+
305
+ After editing source files, deploy to BOTH locations and restart:
306
+
307
+ ```bash
308
+ # 1. Copy files (if editing in workspace)
309
+ cp /home/omer/.openclaw/workspace/skills/waha-openclaw-channel/src/*.ts \
310
+ /home/omer/.openclaw/extensions/waha/src/
311
+
312
+ # 2. Verify both copies match
313
+ md5sum /home/omer/.openclaw/extensions/waha/src/*.ts
314
+ md5sum /home/omer/.openclaw/workspace/skills/waha-openclaw-channel/src/*.ts
315
+
316
+ # 3. Restart gateway (systemd auto-restarts on kill)
317
+ kill -9 $(pgrep -f "openclaw-gatewa") 2>/dev/null
318
+
319
+ # 4. Wait ~5 seconds, then verify it came back up
320
+ ss -tlnp | grep 18789
321
+ curl -s http://127.0.0.1:8050/healthz
71
322
  ```
72
- WAHA ──webhook──> Plugin (port 8050)
73
- ├── monitor.ts verify HMAC, parse event
74
- ├── inbound.ts access control, DM filter, presence
75
- ├── AI Agent generate reply
76
- ├── presence.ts pad typing to human speed
77
- └── send.ts deliver via WAHA REST API
78
- │
79
- WAHA <──REST API──────────┘
80
323
 
81
- User sees: ✓✓ read → typing... → reply
324
+ ### Remote Deployment (from Windows dev machine)
325
+
326
+ Use base64 transfer to avoid shell escaping issues with TypeScript `!==` operators:
327
+
328
+ ```bash
329
+ # Encode locally
330
+ B64=$(base64 -w 0 /path/to/file.ts)
331
+
332
+ # Transfer to both locations
333
+ ssh omer@100.114.126.43 "echo '$B64' | base64 -d > /home/omer/.openclaw/extensions/waha/src/file.ts"
334
+ ssh omer@100.114.126.43 "echo '$B64' | base64 -d > /home/omer/.openclaw/workspace/skills/waha-openclaw-channel/src/file.ts"
82
335
  ```
83
336
 
84
- ## Source Files
337
+ ---
338
+
339
+ ## 8. Troubleshooting
340
+
341
+ ### CRITICAL: Gateway Uses Workspace Config, Not ~/.openclaw/openclaw.json
342
+
343
+ The openclaw gateway service sets `OPENCLAW_CONFIG_PATH=/home/omer/.openclaw/workspace/openclaw.json` (visible in `/proc/<pid>/environ`). The gateway reads FROM and writes TO this file, NOT `~/.openclaw/openclaw.json`.
344
+
345
+ When WAHA is not starting (port 8050 not bound), verify the **workspace config** has the waha section:
346
+
347
+ ```bash
348
+ python3 -c "import json; cfg=json.load(open('/home/omer/.openclaw/workspace/openclaw.json')); print(list(cfg.get('channels',{}).keys()))"
349
+ # Should show: ['telegram', 'waha']
350
+ ```
351
+
352
+ To sync WAHA config from `~/.openclaw/openclaw.json` to workspace:
353
+ ```bash
354
+ python3 << 'PYEOF'
355
+ import json, shutil
356
+ full = json.load(open('/home/omer/.openclaw/openclaw.json'))
357
+ ws = json.load(open('/home/omer/.openclaw/workspace/openclaw.json'))
358
+ ws.setdefault('channels', {})['waha'] = full['channels']['waha']
359
+ shutil.copy('/home/omer/.openclaw/workspace/openclaw.json', '/home/omer/.openclaw/workspace/openclaw.json.bak')
360
+ json.dump(ws, open('/home/omer/.openclaw/workspace/openclaw.json', 'w'), indent=2)
361
+ print('Done')
362
+ PYEOF
363
+ ```
85
364
 
86
- | File | Description |
87
- |------|-------------|
88
- | `channel.ts` | Plugin registration, lifecycle, outbound delivery |
89
- | `inbound.ts` | Message handler, access control, DM filter, AI dispatch |
90
- | `monitor.ts` | Webhook server, admin panel SPA, health/stats APIs |
91
- | `send.ts` | WAHA REST API wrappers (text, voice, reactions, presence) |
92
- | `dm-filter.ts` | Keyword filter with regex caching and god mode |
93
- | `presence.ts` | Human mimicry presence simulation (4-phase) |
94
- | `directory.ts` | SQLite contact directory and per-DM settings |
95
- | `accounts.ts` | Multi-account resolution |
96
- | `types.ts` | TypeScript type definitions |
97
- | `config-schema.ts` | Zod validation schema |
98
- | `normalize.ts` | JID normalization utilities |
99
- | `signature.ts` | HMAC webhook verification |
365
+ ### WAHA API Key: Use WHATSAPP_API_KEY, Not WAHA_API_KEY
100
366
 
101
- ## License
367
+ WAHA defines two keys in its `.env`. Only `WHATSAPP_API_KEY` authenticates API calls (returns 200). Using `WAHA_API_KEY` returns 401 on every request. The `channels.waha.apiKey` config value must use the correct key.
102
368
 
103
- MIT
369
+ **Test which key works:**
370
+ ```bash
371
+ curl -s -o /dev/null -w "%{http_code}" \
372
+ -H "X-Api-Key: YOUR_KEY_HERE" \
373
+ http://127.0.0.1:3004/api/sessions
374
+ # 200 = correct key, 401 = wrong key
375
+ ```
376
+
377
+ ### groupAllowFrom Needs BOTH @c.us AND @lid JIDs
378
+
379
+ WAHA's NOWEB engine sends group message sender JIDs as `@lid` (linked device ID), not `@c.us`. If you only list `@c.us` JIDs in `groupAllowFrom`, all group messages will be silently dropped.
380
+
381
+ **Fix:** Add both formats for each allowed user:
382
+ ```json
383
+ "groupAllowFrom": ["972544329000@c.us", "271862907039996@lid"]
384
+ ```
385
+
386
+ ### Voice Files: Use /api/sendVoice, Not Base64 File Conversion
387
+
388
+ The `send.ts` module includes `buildFilePayload()` which automatically handles local TTS file paths by reading them as base64. Audio files with recognized MIME types (`audio/*`) are routed to WAHA's `/api/sendVoice` endpoint with `convert: true` to produce proper WhatsApp voice bubbles (PTT format).
389
+
390
+ If voice notes appear as document attachments instead of voice bubbles, check that:
391
+ 1. `resolveMime()` correctly detects the audio MIME type
392
+ 2. The WAHA endpoint is `/api/sendVoice` (not `/api/sendFile`)
393
+ 3. The payload includes `"convert": true`
394
+
395
+ ### TTS Local Paths: buildFilePayload() Handles Base64 Automatically
396
+
397
+ OpenClaw TTS generates voice files at `/tmp/openclaw/tts-*/voice-*.mp3`. WAHA cannot access local filesystem paths. The `buildFilePayload()` function in `send.ts` detects paths starting with `/` or `file://`, reads the file with `readFileSync`, converts to base64, and builds the correct WAHA payload format with `{ data, mimetype, filename }`.
398
+
399
+ ### Plugin ID Mismatch Warning (Benign)
400
+
401
+ ```
402
+ plugin id mismatch (config uses "waha-openclaw-channel", export uses "waha")
403
+ ```
404
+
405
+ This warning appears because the config `plugins.entries` key is `waha-openclaw-channel` but the plugin exports `id: "waha"`. It is cosmetic only — the plugin loads and operates normally.
406
+
407
+ ### Shell ! Escaping: Use Base64 Transfer for TypeScript Files Over SSH
408
+
409
+ SSH heredocs with `!` characters (in `!==`, `!response.ok`, etc.) trigger bash history expansion, which inserts backslashes into the file content and causes TypeScript parse errors. Always use the base64 transfer pattern (see Section 5) when deploying TypeScript files remotely.
410
+
411
+ ### Gateway Not Responding After Restart
412
+
413
+ 1. Check if the process is running: `pgrep -af "openclaw-gateway"`
414
+ 2. Check if port 18789 is bound: `ss -tlnp | grep 18789`
415
+ 3. Check webhook port: `ss -tlnp | grep 8050`
416
+ 4. Check logs: `tail -100 /tmp/openclaw/openclaw-gateway.log`
417
+ 5. If an old process holds the port, force kill: `kill -9 $(pgrep -f "openclaw-gatewa")`
418
+ 6. Systemd auto-restarts the gateway — wait ~5 seconds after kill
419
+
420
+ ---
421
+
422
+ ## 9. Key Guardrails
423
+
424
+ ### Session Blocking (`assertAllowedSession`)
425
+
426
+ The `send.ts` module enforces a hard guardrail that prevents the bot from sending messages as Omer:
427
+
428
+ ```typescript
429
+ if (normalized === "omer" || normalized.endsWith("_omer")) {
430
+ throw new Error(`WAHA session '${normalized}' is explicitly blocked by guardrail`);
431
+ }
432
+ ```
433
+
434
+ Only sessions matching `"logan"` or `"*_logan"` are allowed to send outbound messages. This prevents accidental or malicious use of Omer's personal WhatsApp session by the AI bot.
435
+
436
+ ### HMAC Webhook Verification
437
+
438
+ All incoming webhooks are verified against the configured `webhookHmacKey` using SHA-512 HMAC. Requests without a valid `X-Webhook-Hmac` header receive HTTP 401. This prevents unauthorized parties from injecting fake messages into the bot pipeline.
439
+
440
+ ### Access Control Enforcement
441
+
442
+ Messages are dropped silently (with logging) if:
443
+ - The sender JID is not in `allowFrom` (for DMs when `dmPolicy: "allowlist"`)
444
+ - The sender JID is not in `groupAllowFrom` (for group messages when `groupPolicy: "allowlist"`)
445
+ - The session in the webhook payload does not match the configured session
446
+
447
+ ---
448
+
449
+ ## Appendix: Architecture Diagram
450
+
451
+ ```
452
+ WAHA (hpg6:3004)
453
+ |
454
+ |--- webhook (X-Webhook-Hmac signed) ---> OpenClaw Webhook Server (hpg6:8050)
455
+ | |
456
+ | monitor.ts (verify HMAC, parse envelope)
457
+ | |
458
+ | inbound.ts (access control, presence start)
459
+ | |
460
+ | OpenClaw AI Agent (generate reply)
461
+ | |
462
+ | presence.ts (pad typing to human speed)
463
+ | |
464
+ | <--- WAHA REST API (sendText/sendVoice) --- send.ts (assertAllowedSession)
465
+ |
466
+ v
467
+ WhatsApp recipient sees: blue ticks -> typing... -> text reply -> voice note
468
+ ```
469
+
470
+ ---
471
+
472
+ ## Appendix: Useful Commands
473
+
474
+ ```bash
475
+ # Check gateway status
476
+ pgrep -af "openclaw gateway"
477
+
478
+ # Check webhook health
479
+ curl -s http://127.0.0.1:8050/healthz
480
+
481
+ # Check WAHA sessions
482
+ curl -s -H "X-Api-Key: $WHATSAPP_API_KEY" http://127.0.0.1:3004/api/sessions
483
+
484
+ # View recent gateway logs
485
+ tail -50 /tmp/openclaw/openclaw-gateway.log | grep waha
486
+
487
+ # Restart gateway (systemd auto-restarts)
488
+ kill -9 $(pgrep -f "openclaw-gatewa") 2>/dev/null
489
+
490
+ # Verify port binding after restart
491
+ ss -tlnp | grep 18789
492
+ ```
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "waha-openclaw-channel",
3
- "version": "1.2.1",
3
+ "version": "1.2.2",
4
4
  "description": "OpenClaw WAHA (WhatsApp HTTP API) channel plugin",
5
5
  "type": "module",
6
6
  "main": "./index.ts",