- 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; after a transient reconnect for a recently active session, that application-silence check uses the normal message timeout for the first recovery 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 waits plus OpenClaw's local outbound send/presence operation bound.

- 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 waits plus OpenClaw's local outbound send/presence and inbound read-receipt operation bounds.

- Outbound sends require an active WhatsApp listener for the target account.

- Group sends attach native mention metadata for `@+<digits>` and `@<digits>` tokens in text and media captions when the token matches current WhatsApp participant metadata, including LID-backed groups.

- Status and broadcast chats are ignored (`@status`, `@broadcast`).

isWhatsAppSocketOperationTimeoutError,

resolveWhatsAppSocketOperationTimeoutMs,

resolveWhatsAppSocketTiming,

withWhatsAppSocketOperationTimeout,

type WhatsAppSocketOperationAdapter,

type WhatsAppSocketTimingOptions,

} from "../socket-timing.js";

}

const { id, remoteJid, participant } = target;

try {

await (getCurrentSock() ?? sock).readMessages([

{ remoteJid, id, participant, fromMe: false },

]);

await withWhatsAppSocketOperationTimeout(

"readMessages",

(getCurrentSock() ?? sock).readMessages([{ remoteJid, id, participant, fromMe: false }]),

sendOperationTimeoutMs,

);

const suffix = participant ? ` (participant ${participant})` : "";

logWhatsAppVerbose(options.verbose, `Marked message ${id} as read for ${remoteJid}${suffix}`);

} catch (err) {

import fsSync from "node:fs";

import path from "node:path";

import "./monitor-inbox.test-harness.js";

import { defaultRuntime } from "openclaw/plugin-sdk/runtime-env";

import { beforeEach, describe, expect, it, vi } from "vitest";

import {

registerWhatsAppConnectionController,

}

});

it("bounds stalled read-receipt socket operations instead of hanging", async () => {

const onMessage = vi.fn(async () => undefined);

const logSpy = vi.spyOn(defaultRuntime, "log").mockImplementation(() => undefined);

const { listener, sock } = await startInboxMonitor(onMessage as InboxOnMessage, {

verbose: true,

});

vi.useFakeTimers();

try {

const messageId = nextMessageId("read-receipt-timeout");

// A WhatsApp socket whose read-receipt acknowledgement never resolves

// (e.g. a stalled Baileys privacy IQ query) would otherwise hang the

// inbound delivery pipeline forever.

sock.readMessages.mockImplementationOnce(() => new Promise(() => {}));

sock.ev.emit(

"messages.upsert",

buildNotifyMessageUpsert({

id: messageId,

remoteJid: "999@s.whatsapp.net",

text: "ping",

timestamp: 1_700_000_000,

pushName: "Tester",

}),

);

await waitForMessageCalls(onMessage, 1);

// The read receipt is attempted on the stalled socket...

await vi.waitFor(() => {

expect(sock.readMessages).toHaveBeenCalledWith([

{ remoteJid: "999@s.whatsapp.net", id: messageId, participant: undefined, fromMe: false },

]);

});

// ...and is bounded by the socket operation timeout rather than hanging.

await vi.advanceTimersByTimeAsync(DEFAULT_WHATSAPP_SOCKET_TIMING.defaultQueryTimeoutMs);

await vi.waitFor(() => {

const loggedTimeoutFailure = logSpy.mock.calls.some(

([message]) =>

typeof message === "string" &&

message.includes(`Failed to mark message ${messageId} read`) &&

message.includes("readMessages timed out"),

);

expect(loggedTimeoutFailure).toBe(true);

});

expect(vi.getTimerCount()).toBe(0);

} finally {

vi.useRealTimers();

await listener.close();

logSpy.mockRestore();

}

});

it("bounds reconnect-gap retries even when reconnect attempts are unlimited", async () => {

const onMessage = vi.fn(async () => undefined);

const socketRef = createSocketRef();

import { MAX_TIMER_TIMEOUT_MS } from "openclaw/plugin-sdk/number-runtime";

// Whatsapp tests cover socket timing plugin behavior.

import { describe, expect, it } from "vitest";

import { afterEach, describe, expect, it, vi } from "vitest";

import {

DEFAULT_WHATSAPP_SOCKET_TIMING,

WhatsAppSocketOperationTimeoutError,

isWhatsAppSocketOperationTimeoutError,

resolveWhatsAppSocketOperationTimeoutMs,

resolveWhatsAppSocketTiming,

withWhatsAppSocketOperationTimeout,

} from "./socket-timing.js";

describe("resolveWhatsAppSocketTiming", () => {

);

});

});

describe("withWhatsAppSocketOperationTimeout", () => {

afterEach(() => {

vi.useRealTimers();

});

it("bounds a stalled readMessages socket operation with a typed timeout", async () => {

vi.useFakeTimers();

// A WhatsApp read-receipt call that never resolves (socket stall).

const stalled = new Promise<void>(() => {});

const bounded = withWhatsAppSocketOperationTimeout(

"readMessages",

stalled,

DEFAULT_WHATSAPP_SOCKET_TIMING.defaultQueryTimeoutMs,

);

const rejection = expect(bounded).rejects.toMatchObject({

name: "WhatsAppSocketOperationTimeoutError",

operation: "readMessages",

timeoutMs: DEFAULT_WHATSAPP_SOCKET_TIMING.defaultQueryTimeoutMs,

deliveryState: "unknown",

});

await vi.advanceTimersByTimeAsync(DEFAULT_WHATSAPP_SOCKET_TIMING.defaultQueryTimeoutMs);

await rejection;

// The bounding timer is cleared once the operation settles.

expect(vi.getTimerCount()).toBe(0);

});

it("resolves the operation value when it settles before the bound", async () => {

vi.useFakeTimers();

const bounded = withWhatsAppSocketOperationTimeout(

"readMessages",

Promise.resolve("read"),

DEFAULT_WHATSAPP_SOCKET_TIMING.defaultQueryTimeoutMs,

);

await expect(bounded).resolves.toBe("read");

expect(vi.getTimerCount()).toBe(0);

});

});

"web.reconnect.maxAttempts":

"Maximum reconnect attempts before giving up for the current failure sequence (0 means no retries). Use finite caps for controlled failure handling in automation-sensitive environments.",

"web.whatsapp":

"WhatsApp Web socket timing controls used by Baileys and OpenClaw's local outbound operation bounds. Tune these when network edges, proxies, or NATs are closing otherwise healthy WhatsApp Web sessions.",

"WhatsApp Web socket timing controls used by Baileys and OpenClaw's local outbound and inbound read-receipt operation bounds. Tune these when network edges, proxies, or NATs are closing otherwise healthy WhatsApp Web sessions.",

"web.whatsapp.keepAliveIntervalMs":

"Baileys WhatsApp Web application ping interval in milliseconds. Lower values detect and refresh idle links sooner; keep this comfortably below your network's idle-flow timeout.",

"web.whatsapp.connectTimeoutMs":

"Maximum time in milliseconds Baileys waits for the WhatsApp WebSocket opening handshake. Use a higher value on slow or lossy networks that report opening handshake 408 timeouts.",

"web.whatsapp.defaultQueryTimeoutMs":

"Default Baileys query timeout and OpenClaw outbound send/presence operation bound in milliseconds for WhatsApp Web requests. Keep aligned with upstream unless a network-specific investigation shows socket operations need longer.",

"Default Baileys query timeout and OpenClaw outbound send/presence and inbound read-receipt operation bound in milliseconds for WhatsApp Web requests. Keep aligned with upstream unless a network-specific investigation shows socket operations need longer.",

talk: "Talk-mode voice synthesis settings for voice identity, model selection, output format, and interruption behavior. Use this section to tune human-facing voice UX while controlling latency and cost.",

"gateway.auth.token":

"Required by default for gateway access (unless using Tailscale Serve identity); required for non-loopback binds.",

keepAliveIntervalMs?: number;

/** WebSocket opening handshake timeout in milliseconds. Default: 60000. */

connectTimeoutMs?: number;

/** Baileys query and WhatsApp outbound socket operation timeout in milliseconds. Default: 60000. */

/** Baileys query and WhatsApp outbound/read-receipt operation timeout in milliseconds. Default: 60000. */

defaultQueryTimeoutMs?: number;

};