fix(whatsapp): expose Baileys socket timing (#73580)

Merged via squash.

Prepared head SHA: d34755262f
Co-authored-by: velvet-shark <126378+velvet-shark@users.noreply.github.com>
Co-authored-by: velvet-shark <126378+velvet-shark@users.noreply.github.com>
Reviewed-by: @velvet-shark

docs/.generated/config-baseline.sha256

@@ -1,4 +1,4 @@
-85842690af24b21a5e074d722930af95faaf6e91a918061bdc1b5c956860a7a0  config-baseline.json
-86ad0927d992bc873affb3e20a31c6e3c95b2185a91f46cc8e6262a723a78f7d  config-baseline.core.json
+39c5c0620611f355f20d5e9d2ddd74e198c344c63d5551a987e4b7538833ceac  config-baseline.json
+805bd3f63ff7327da45c01b78dbc990ed53bd13b89e0cbf50f319aa99334ba92  config-baseline.core.json
 323a9fd49a669951ca5b3442d95aad243bd1330083f9857e83a8dcfae2bbc9d0  config-baseline.channel.json
 1f5592bfd141ba1e982ce31763a253c10afb080ab4ea2b6538299b114e29cee1  config-baseline.plugin.json

docs/channels/whatsapp.md

@@ -147,6 +147,7 @@ OpenClaw recommends running WhatsApp on a separate number when possible. (The ch
 
 - Gateway owns the WhatsApp socket and reconnect loop.
 - The reconnect watchdog uses WhatsApp Web transport activity, not only inbound app-message volume, so a quiet linked-device session is not restarted solely because nobody has sent a message recently. A longer application-silence cap still forces a reconnect if transport frames keep arriving but no application messages are handled for the watchdog window.
+- Baileys socket timings are explicit under `web.whatsapp.*`: `keepAliveIntervalMs` controls WhatsApp Web application pings, `connectTimeoutMs` controls the opening handshake timeout, and `defaultQueryTimeoutMs` controls Baileys query timeouts.
 - Outbound sends require an active WhatsApp listener for the target account.
 - Status and broadcast chats are ignored (`@status`, `@broadcast`).
 - Direct chats use DM session rules (`session.dmScope`; default `main` collapses DMs to the agent main session).
@@ -520,6 +521,23 @@ Behavior notes:
     restarts when WhatsApp Web transport activity stops, the socket closes, or
     application-level activity stays silent beyond the longer safety window.
 
+    If logs show repeated `status=408 Request Time-out Connection was lost`, tune
+    Baileys socket timings under `web.whatsapp`. Start by shortening
+    `keepAliveIntervalMs` below your network's idle timeout and increasing
+    `connectTimeoutMs` on slow or lossy links:
+
+    ```json5
+    {
+      web: {
+        whatsapp: {
+          keepAliveIntervalMs: 15000,
+          connectTimeoutMs: 60000,
+          defaultQueryTimeoutMs: 60000,
+        },
+      },
+    }
+    ```
+
     Fix:
 
     ```bash
@@ -643,7 +661,7 @@ High-signal WhatsApp fields:
 - access: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`
 - delivery: `textChunkLimit`, `chunkMode`, `mediaMaxMb`, `sendReadReceipts`, `ackReaction`, `reactionLevel`
 - multi-account: `accounts.<id>.enabled`, `accounts.<id>.authDir`, account-level overrides
-- operations: `configWrites`, `debounceMs`, `web.enabled`, `web.heartbeatSeconds`, `web.reconnect.*`
+- operations: `configWrites`, `debounceMs`, `web.enabled`, `web.heartbeatSeconds`, `web.reconnect.*`, `web.whatsapp.*`
 - session behavior: `session.dmScope`, `historyLimit`, `dmHistoryLimit`, `dms.<id>.historyLimit`
 - prompts: `groups.<id>.systemPrompt`, `groups["*"].systemPrompt`, `direct.<id>.systemPrompt`, `direct["*"].systemPrompt`
 

docs/gateway/config-channels.md

@@ -96,6 +96,13 @@ WhatsApp runs through the gateway's web channel (Baileys Web). It starts automat
 
 ```json5
 {
+  web: {
+    whatsapp: {
+      keepAliveIntervalMs: 25000,
+      connectTimeoutMs: 60000,
+      defaultQueryTimeoutMs: 60000,
+    },
+  },
   channels: {
     whatsapp: {
       dmPolicy: "pairing", // pairing | allowlist | open | disabled