@vama/openclaw 2026.5.5-1 → 2026.5.5-4

package/README.md

@@ -0,0 +1,202 @@
+# @vama/openclaw
+
+Connect your own [OpenClaw](https://openclaw.ai) agent to **Vama** direct messages — the BotFather-style "bring your own claw" flow. This plugin adds a `vama` channel that talks to Vama's BotHub, so an agent you run appears natively in Vama DMs.
+
+> **Full setup guide:** https://web.vama.com/connect-guide
+
+## Install the channel
+
+The Vama channel ships **bundled** in Vama-provided OpenClaw builds (for example, agents created from inside the Vama app), so if you use one of those you can skip straight to **Get a token** below.
+
+If you run **stock OpenClaw** from upstream, install the Vama channel first. It is published to both npm and ClawHub; npm is the default:
+
+```bash
+openclaw plugins install @vama/openclaw
+```
+
+Prefer ClawHub? Use the `clawhub:` spec instead:
+
+```bash
+openclaw plugins install clawhub:@vama/openclaw
+```
+
+Either one pulls the published plugin so `vama` becomes available to `openclaw onboard` and the `channels.vama` config block below. The channel requires OpenClaw `>=2026.5.12`.
+
+## Get a token (Bring your own claw)
+
+If you run your own OpenClaw gateway and just want to connect it to Vama — the BotFather-style flow — mint a token straight from the Vama app:
+
+1. On stock OpenClaw, install the channel first (see **Install the channel**). Vama-provided builds already bundle it.
+2. In Vama, go to **Settings → Agents → Connect an agent** (the "Bring your own claw" page).
+3. Optionally name the agent, then click **Create agent**. Vama shows a one-time **agent token** and **webhook secret**, plus a ready-to-paste `channels.vama` config block.
+4. Copy the config into `~/.openclaw/openclaw.json` (see below).
+5. Fill in `webhookUrl` with your gateway's public URL and start the gateway with `openclaw gateway run` — it registers the URL with BotHub automatically on every start (see **Receiving messages**).
+
+Each token is shown **once**. If you lose one, use **Regenerate token** on that agent — the old token stops working immediately. **Delete agent** disconnects the claw and removes that agent from your Vama DMs.
+
+> You can connect **as many agents as you like** — each **Create agent** provisions a new, independent agent with its own token. Run a separate OpenClaw gateway (or a separate `accounts` entry — see **Multi-account**) per agent.
+
+## CLI onboarding (alternative)
+
+Instead of minting a token in the app, you can auto-provision from the CLI:
+
+```bash
+openclaw onboard
+```
+
+Select **Vama** from the channel list. The wizard prompts for your Vama username, auto-provisions a bot via BotHub, and configures webhook settings. Then start the gateway:
+
+```bash
+openclaw gateway run
+```
+
+## Manual configuration
+
+Set the following in `~/.openclaw/openclaw.json`:
+
+```json
+{
+  "channels": {
+    "vama": {
+      "enabled": true,
+      "botToken": "<bot_token from provisioning>",
+      "webhookSecret": "<webhook_secret from provisioning>",
+      "webhookUrl": "https://<your-public-host>/vama/events",
+      "webhookPort": 3001,
+      "webhookPath": "/vama/events",
+      "webhookHost": "127.0.0.1"
+    }
+  }
+}
+```
+
+## Receiving messages (webhook reachability)
+
+BotHub delivers inbound messages to your gateway over an HTTP **webhook**, so BotHub must be able to reach your gateway's webhook listener from the internet. Two things make that work:
+
+1. **A public HTTPS URL that forwards to the local listener.** The listener binds to `webhookHost`:`webhookPort``webhookPath` (default `127.0.0.1:3001/vama/events`). If your machine isn't directly reachable, any tunnel or reverse proxy works, e.g.:
+
+```bash
+cloudflared tunnel --url http://localhost:3001
+# prints something like https://random-words.trycloudflare.com
+```
+
+2. **Registering that URL with BotHub.** Set it as `channels.vama.webhookUrl` (include the `/vama/events` path). The gateway registers it with BotHub **automatically every time it starts** — no manual API calls. If your tunnel URL changes (quick tunnels are ephemeral), update `webhookUrl` and restart the gateway. For a set-and-forget setup, use a stable URL (named Cloudflare tunnel, Tailscale Funnel, or a reverse proxy on a domain you own).
+
+The `openclaw onboard` wizard also prompts for this URL, registers it immediately, and saves it to `webhookUrl` for you.
+
+Verify end-to-end with:
+
+```bash
+openclaw channels status --probe
+```
+
+The probe checks both that your token is valid **and** that a webhook URL is registered with BotHub. If registration is missing it fails with instructions — a bot in that state shows **"Awaiting claw"** in Vama and cannot receive messages.
+
+### WebSocket delivery (no public URL needed)
+
+BotHub can also deliver events over an **outbound WebSocket** (`GET /v1/bot/ws`) — the gateway dials out, so there's nothing to expose: no tunnel, no reverse proxy, works behind any NAT. The gateway probes for it automatically at startup (`transport` defaults to `"auto"`) and falls back to webhook delivery when the bot doesn't have WebSocket enabled server-side. When the socket is connected, BotHub prefers it and uses the registered webhook only as fallback. The probe also accepts a WebSocket-enabled bot without a registered webhook URL.
+
+## Configuration reference
+
+| Key              | Type    | Default          | Description                                                                                               |
+| ---------------- | ------- | ---------------- | --------------------------------------------------------------------------------------------------------- |
+| `enabled`        | boolean | `false`          | Enable/disable the Vama channel                                                                           |
+| `botToken`       | string  | —                | Bot authentication token from provisioning                                                                |
+| `webhookSecret`  | string  | —                | HMAC secret for webhook signature verification                                                            |
+| `webhookUrl`     | string  | —                | Public URL of your webhook listener. Auto-registered with BotHub at every gateway start.                  |
+| `transport`      | string  | `"auto"`         | Inbound delivery: `"auto"` (WebSocket when BotHub allows it, else webhook), `"webhook"`, or `"websocket"` |
+| `webhookPort`    | integer | `3001`           | Local port for the webhook listener                                                                       |
+| `webhookPath`    | string  | `"/vama/events"` | URL path for webhook events                                                                               |
+| `webhookHost`    | string  | `"127.0.0.1"`    | Bind address for the webhook listener                                                                     |
+| `dmPolicy`       | string  | `"open"`         | DM access policy: `"open"`, `"pairing"`, or `"allowlist"`                                                 |
+| `allowFrom`      | array   | `[]`             | Vama user IDs allowed to message the bot                                                                  |
+| `textChunkLimit` | integer | `10000`          | Max characters per outbound message                                                                       |
+| `bothubUrl`      | string  | _(canonical)_    | Override the BotHub API base URL. Only needed for self-hosted BotHub deployments.                         |
+
+## Access control
+
+Control who can message the bot with `channels.vama.dmPolicy`:
+
+- **`open`** (default) — any Vama user can DM the bot.
+- **`pairing`** — unknown users get a pairing code to request approval.
+- **`allowlist`** — only users listed in `channels.vama.allowFrom` can DM the bot.
+
+```json
+{
+  "channels": {
+    "vama": {
+      "dmPolicy": "allowlist",
+      "allowFrom": ["user_alice", "user_bob"]
+    }
+  }
+}
+```
+
+## Webhook security
+
+BotHub signs every webhook delivery with HMAC-SHA256. OpenClaw verifies the signature using the `webhookSecret` from provisioning.
+
+Headers sent by BotHub:
+
+- `X-BotHub-Signature` — `sha256=<hex HMAC>`
+- `X-BotHub-Timestamp` — Unix seconds
+- `X-BotHub-Event` — Event type (e.g. `message.create`)
+- `X-BotHub-Delivery-ID` — Unique delivery identifier
+
+Signatures older than 5 minutes are rejected to prevent replay attacks.
+
+## Multi-account
+
+For multiple bot accounts, use the `accounts` map:
+
+```json
+{
+  "channels": {
+    "vama": {
+      "enabled": true,
+      "bothubUrl": "https://bothub.example.com",
+      "accounts": {
+        "staging": {
+          "botToken": "<staging_token>",
+          "webhookSecret": "<staging_secret>",
+          "webhookPort": 3002,
+          "name": "Staging Bot"
+        },
+        "production": {
+          "botToken": "<prod_token>",
+          "webhookSecret": "<prod_secret>",
+          "webhookPort": 3003,
+          "name": "Production Bot"
+        }
+      }
+    }
+  }
+}
+```
+
+Named accounts inherit top-level settings (like `bothubUrl`) and can override them individually.
+
+## Capabilities
+
+| Feature           | Supported            |
+| ----------------- | -------------------- |
+| Direct messages   | Yes                  |
+| Threads (replies) | Yes                  |
+| Media attachments | No (text-only in v1) |
+| Reactions         | No                   |
+| Message editing   | No                   |
+| Groups/channels   | No                   |
+
+## Troubleshooting
+
+- **Vama shows "Awaiting claw" even though the gateway is running**: no webhook URL is registered with BotHub. Set `channels.vama.webhookUrl` to your public URL and restart the gateway — it registers automatically. `openclaw channels status --probe` reports this state explicitly ("no webhook URL is registered with BotHub").
+- **Bot not responding**: run `openclaw channels status --probe`. It verifies both the token and webhook registration. Also check the gateway log for `webhook registered with BotHub` (or a registration error) at startup.
+- **Worked, then stopped after a tunnel restart**: ephemeral tunnel URLs change on restart. Update `webhookUrl` to the new URL and restart the gateway, or switch to a stable tunnel/domain.
+- **Signature verification failed**: ensure `webhookSecret` matches the value from provisioning. Re-provision if needed.
+- **Connection test fails during onboarding**: verify the `bothubUrl` is correct and reachable from your gateway host.
+- **Messages dropped**: check gateway logs for `dmPolicy` blocks. If using `allowlist`, verify the sender's user ID is in `channels.vama.allowFrom`.
+
+## License
+
+See the Vama OpenClaw distribution for license terms.

package/dist/{api-C0vtNv5b.js → api-lhR0QgC_.js}

@@ -1,4 +1,4 @@
-import { a as dispatchStarted, i as dispatchEnded } from "./probe-B2hFOc2Y.js";
+import { a as dispatchStarted, i as dispatchEnded } from "./monitor-CHFjRu2J.js";
 //#region extensions/vama/src/subagent-keepalive-hooks.ts
 function registerVamaSubagentKeepaliveHooks(api) {
 	api.on("subagent_spawned", () => {

package/dist/api.js

@@ -1,3 +1,3 @@
-import { n as monitorVamaProvider, r as sendMessageVama, t as probeVama } from "./probe-B2hFOc2Y.js";
-import { t as registerVamaSubagentKeepaliveHooks } from "./api-C0vtNv5b.js";
+import { n as probeVama, r as sendMessageVama, t as monitorVamaProvider } from "./monitor-CHFjRu2J.js";
+import { t as registerVamaSubagentKeepaliveHooks } from "./api-lhR0QgC_.js";
 export { monitorVamaProvider, probeVama, registerVamaSubagentKeepaliveHooks, sendMessageVama };

package/dist/{channel-plugin-api-CcZ_y9pT.js → channel-plugin-api-YGbkWmVM.js}

@@ -1,5 +1,5 @@
 import { a as provisionBot, i as createBotHubClient, n as attachmentHintFromExtension } from "./client-AsD46gcK.js";
-import { c as resolveVamaAccount, d as buildBaseChannelStatusSummary, f as createDefaultChannelRuntimeState, l as DEFAULT_ACCOUNT_ID$1, n as monitorVamaProvider, o as listVamaAccountIds, r as sendMessageVama, s as resolveDefaultVamaAccountId, t as probeVama, u as PAIRING_APPROVED_MESSAGE } from "./probe-B2hFOc2Y.js";
+import { c as buildBaseChannelStatusSummary, d as resolveDefaultVamaAccountId, f as resolveVamaAccount, l as createDefaultChannelRuntimeState, n as probeVama, o as DEFAULT_ACCOUNT_ID$1, r as sendMessageVama, s as PAIRING_APPROVED_MESSAGE, t as monitorVamaProvider, u as listVamaAccountIds } from "./monitor-CHFjRu2J.js";
 import { t as getVamaRuntime } from "./runtime-w-1oL50p.js";
 import { jsonResult, readStringOrNumberParam, readStringParam } from "openclaw/plugin-sdk/channel-actions";
 import { extractToolSend } from "openclaw/plugin-sdk/tool-send";
@@ -367,6 +367,15 @@ const vamaPlugin = {
 				minimum: 1
 			},
 			webhookHost: { type: "string" },
+			webhookUrl: { type: "string" },
+			transport: {
+				type: "string",
+				enum: [
+					"auto",
+					"webhook",
+					"websocket"
+				]
+			},
 			dmPolicy: {
 				type: "string",
 				enum: [
@@ -399,7 +408,16 @@ const vamaPlugin = {
 							type: "integer",
 							minimum: 1
 						},
-						webhookHost: { type: "string" }
+						webhookHost: { type: "string" },
+						webhookUrl: { type: "string" },
+						transport: {
+							type: "string",
+							enum: [
+								"auto",
+								"webhook",
+								"websocket"
+							]
+						}
 					}
 				}
 			}
@@ -625,13 +643,24 @@ const vamaPlugin = {
 					}
 				}
 			})).trim();
-			if (publicWebhookUrl) try {
-				await createBotHubClient(resolveVamaAccount({ cfg: next })).registerWebhook({ url: publicWebhookUrl });
-				await prompter.note(`Webhook registered: ${publicWebhookUrl}`, "Vama webhook registration");
-			} catch (err) {
-				await prompter.note(`Webhook registration failed: ${String(err)}\nYou can register later via the BotHub API.`, "Vama webhook registration");
-			}
-			else await prompter.note("Skipped webhook registration. Run the setup wizard again once your gateway is publicly reachable to register a webhook URL.", "Vama webhook registration");
+			if (publicWebhookUrl) {
+				next = {
+					...next,
+					channels: {
+						...next.channels,
+						vama: {
+							...next.channels?.vama,
+							webhookUrl: publicWebhookUrl
+						}
+					}
+				};
+				try {
+					await createBotHubClient(resolveVamaAccount({ cfg: next })).registerWebhook({ url: publicWebhookUrl });
+					await prompter.note(`Webhook registered: ${publicWebhookUrl}`, "Vama webhook registration");
+				} catch (err) {
+					await prompter.note(`Webhook registration failed: ${String(err)}\nThe gateway will retry automatically at startup (channels.vama.webhookUrl is saved).`, "Vama webhook registration");
+				}
+			} else await prompter.note("Skipped webhook registration. Once your gateway is publicly reachable, set channels.vama.webhookUrl to its public URL (e.g. https://your-host/vama/events) — it registers automatically at startup.", "Vama webhook registration");
 			const account = resolveVamaAccount({ cfg: next });
 			try {
 				const probe = await probeVama(account);

package/dist/channel-plugin-api.js

@@ -1,2 +1,2 @@
-import { t as vamaPlugin } from "./channel-plugin-api-CcZ_y9pT.js";
+import { t as vamaPlugin } from "./channel-plugin-api-YGbkWmVM.js";
 export { vamaPlugin };

package/dist/index.js

@@ -1,7 +1,7 @@
-import { n as monitorVamaProvider, r as sendMessageVama, t as probeVama } from "./probe-B2hFOc2Y.js";
+import { n as probeVama, r as sendMessageVama, t as monitorVamaProvider } from "./monitor-CHFjRu2J.js";
 import { n as setVamaRuntime } from "./runtime-w-1oL50p.js";
-import { t as registerVamaSubagentKeepaliveHooks } from "./api-C0vtNv5b.js";
-import { t as vamaPlugin } from "./channel-plugin-api-CcZ_y9pT.js";
+import { t as registerVamaSubagentKeepaliveHooks } from "./api-lhR0QgC_.js";
+import { t as vamaPlugin } from "./channel-plugin-api-YGbkWmVM.js";
 import "./runtime-api.js";
 //#region extensions/vama/index.ts
 const channelEntry = {

package/dist/{probe-B2hFOc2Y.js → monitor-CHFjRu2J.js}

@@ -3,6 +3,11 @@ import { t as getVamaRuntime } from "./runtime-w-1oL50p.js";
 import * as fs from "node:fs";
 import { promises } from "node:fs";
 import * as http from "node:http";
+import { DEFAULT_ACCOUNT_ID, DEFAULT_ACCOUNT_ID as DEFAULT_ACCOUNT_ID$1, normalizeAccountId } from "openclaw/plugin-sdk/account-id";
+import path from "node:path";
+import { WebSocket, fetch } from "undici";
+import { homedir } from "node:os";
+import { resolvePreferredOpenClawTmpDir } from "openclaw/plugin-sdk/temp-path";
 import { createDedupeCache } from "openclaw/plugin-sdk/dedupe-runtime";
 import { installRequestBodyLimitGuard } from "openclaw/plugin-sdk/webhook-request-guards";
 import { logTypingFailure } from "openclaw/plugin-sdk/channel-logging";
@@ -10,34 +15,8 @@ import { PAIRING_APPROVED_MESSAGE } from "openclaw/plugin-sdk/channel-plugin-com
 import { createReplyPrefixContext, createTypingCallbacks } from "openclaw/plugin-sdk/channel-message";
 import { createPersistentDedupe } from "openclaw/plugin-sdk/persistent-dedupe";
 import { buildBaseChannelStatusSummary, createDefaultChannelRuntimeState } from "openclaw/plugin-sdk/status-helpers";
-import { DEFAULT_ACCOUNT_ID, DEFAULT_ACCOUNT_ID as DEFAULT_ACCOUNT_ID$1, normalizeAccountId } from "openclaw/plugin-sdk/account-id";
-import path from "node:path";
-import { homedir } from "node:os";
-import { resolvePreferredOpenClawTmpDir } from "openclaw/plugin-sdk/temp-path";
 import * as crypto from "node:crypto";
 import { createHash } from "node:crypto";
-//#region extensions/vama/src/host-pairing-access.ts
-/** Scope pairing store operations to one channel/account pair for plugin-facing helpers. */
-function createScopedPairingAccess(params) {
-	const resolvedAccountId = normalizeAccountId(params.accountId);
-	return {
-		accountId: resolvedAccountId,
-		readAllowFromStore: () => params.core.channel.pairing.readAllowFromStore({
-			channel: params.channel,
-			accountId: resolvedAccountId
-		}),
-		readStoreForDmPolicy: (provider, accountId) => params.core.channel.pairing.readAllowFromStore({
-			channel: provider,
-			accountId: normalizeAccountId(accountId)
-		}),
-		upsertPairingRequest: (input) => params.core.channel.pairing.upsertPairingRequest({
-			channel: params.channel,
-			accountId: resolvedAccountId,
-			...input
-		})
-	};
-}
-//#endregion
 //#region extensions/vama/src/accounts.ts
 function listConfiguredAccountIds(cfg) {
 	const accounts = (cfg.channels?.vama)?.accounts;
@@ -77,6 +56,9 @@ function resolveVamaAccount(params) {
 	const webhookSecret = merged.webhookSecret?.trim() || void 0;
 	const webhookSecretFile = merged.webhookSecretFile?.trim() || void 0;
 	const bothubUrl = merged.bothubUrl?.trim() || "https://bothub.vama.com";
+	const webhookUrl = merged.webhookUrl?.trim() || void 0;
+	const rawTransport = merged.transport?.trim();
+	const transport = rawTransport === "auto" || rawTransport === "webhook" || rawTransport === "websocket" ? rawTransport : void 0;
 	return {
 		accountId,
 		enabled,
@@ -86,10 +68,34 @@ function resolveVamaAccount(params) {
 		webhookSecret,
 		webhookSecretFile,
 		bothubUrl,
+		webhookUrl,
+		transport,
 		config: merged
 	};
 }
 //#endregion
+//#region extensions/vama/src/host-pairing-access.ts
+/** Scope pairing store operations to one channel/account pair for plugin-facing helpers. */
+function createScopedPairingAccess(params) {
+	const resolvedAccountId = normalizeAccountId(params.accountId);
+	return {
+		accountId: resolvedAccountId,
+		readAllowFromStore: () => params.core.channel.pairing.readAllowFromStore({
+			channel: params.channel,
+			accountId: resolvedAccountId
+		}),
+		readStoreForDmPolicy: (provider, accountId) => params.core.channel.pairing.readAllowFromStore({
+			channel: provider,
+			accountId: normalizeAccountId(accountId)
+		}),
+		upsertPairingRequest: (input) => params.core.channel.pairing.upsertPairingRequest({
+			channel: params.channel,
+			accountId: resolvedAccountId,
+			...input
+		})
+	};
+}
+//#endregion
 //#region extensions/vama/src/dedup.ts
 const DEDUP_TTL_MS = 1440 * 60 * 1e3;
 const MEMORY_MAX_SIZE = 1e3;
@@ -703,6 +709,335 @@ async function handleVamaMessage(params) {
 	}
 }
 //#endregion
+//#region extensions/vama/src/ws.ts
+/**
+* WebSocket transport for inbound BotHub events.
+*
+* BotHub exposes `GET /v1/bot/ws` (Authorization: Bot <token>). When a bot
+* has `websocket_enabled` set server-side, BotHub prefers delivering events
+* over the live WebSocket and only falls back to the registered webhook when
+* no connection is up. Frames are the exact same JSON envelopes as webhook
+* POST bodies (`{type, timestamp, bot_id, data}`) — no HMAC headers, since
+* authentication already happened at the upgrade.
+*
+* Why this exists: a connected WebSocket needs NO public URL — no tunnel,
+* no reverse proxy, works behind any NAT. That makes it the easiest possible
+* "bring your own claw" transport. The flag is off by default server-side,
+* so this client is written to probe first and fall back to webhook-only
+* silently — the day BotHub enables WebSocket for a bot, the very next
+* gateway start picks it up with zero config changes.
+*
+* Server behavior this client is built against (BotHub `internal/ws/hub.go`):
+*   - server pings every 30s, expects a pong within 60s (undici auto-pongs)
+*   - client frames are ignored (bots send via REST) — we never send
+*   - a new connection for the same bot replaces the old one server-side
+*/
+/** Reconnect schedule. Index advances per consecutive failure, clamps at the tail. */
+const DEFAULT_BACKOFF_MS = [
+	1e3,
+	2e3,
+	5e3,
+	1e4,
+	3e4
+];
+function resolveVamaWsUrl(bothubUrl) {
+	const base = new URL(bothubUrl);
+	base.protocol = base.protocol === "http:" ? "ws:" : "wss:";
+	base.pathname = `${base.pathname.replace(/\/$/, "")}/v1/bot/ws`;
+	base.search = "";
+	base.hash = "";
+	return base.toString();
+}
+/**
+* Plain authed GET against the WS endpoint to learn whether an upgrade can
+* ever succeed, without burning a real upgrade attempt. The server checks
+* token auth and `websocket_enabled` BEFORE upgrading, so a non-upgrade GET
+* deterministically distinguishes "would work" (400/426 from the upgrader
+* rejecting a plain GET) from "will never work" (403 disabled / 401 / 404).
+*
+* Throws on transport errors — callers treat those as retryable.
+*/
+async function checkVamaWebSocketSupport(account, deps = {}) {
+	const fetchImpl = deps.fetchImpl ?? fetch;
+	const url = new URL(account.bothubUrl ?? "https://bothub.vama.com");
+	url.pathname = `${url.pathname.replace(/\/$/, "")}/v1/bot/ws`;
+	const res = await fetchImpl(url.toString(), {
+		method: "GET",
+		headers: { Authorization: `Bot ${account.botToken ?? ""}` }
+	});
+	const body = await res.text().catch(() => "");
+	if (res.status === 400 || res.status === 426) return { supported: true };
+	if (res.status === 403) {
+		let code;
+		try {
+			code = JSON.parse(body).error;
+		} catch {}
+		return {
+			supported: false,
+			reason: code === "websocket_disabled" ? "disabled" : "http_403"
+		};
+	}
+	if (res.status === 401) return {
+		supported: false,
+		reason: "unauthorized"
+	};
+	if (res.status === 404) return {
+		supported: false,
+		reason: "unsupported"
+	};
+	return {
+		supported: false,
+		reason: `http_${res.status}`
+	};
+}
+function sleep$1(ms, abortSignal) {
+	return new Promise((resolve) => {
+		if (ms <= 0 || abortSignal?.aborted) {
+			resolve();
+			return;
+		}
+		const timer = setTimeout(() => {
+			abortSignal?.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		const onAbort = () => {
+			clearTimeout(timer);
+			resolve();
+		};
+		abortSignal?.addEventListener("abort", onAbort, { once: true });
+	});
+}
+/**
+* Starts the WebSocket transport loop. Never throws; the loop ends either on
+* abort, or when the preflight rules WS out (caller stays on webhook
+* delivery — BotHub falls back server-side automatically).
+*/
+function startVamaWebSocket(opts) {
+	const { account, onEvent, log, error } = opts;
+	const accountId = account.accountId;
+	const mode = opts.mode ?? "auto";
+	const backoff = opts.backoffMs ?? DEFAULT_BACKOFF_MS;
+	const WebSocketCtor = opts.deps?.webSocketCtor ?? WebSocket;
+	let state = "connecting";
+	let active;
+	const abort = new AbortController();
+	if (opts.abortSignal?.aborted) abort.abort();
+	else opts.abortSignal?.addEventListener("abort", () => abort.abort(), { once: true });
+	const aborted = () => abort.signal.aborted;
+	const connectOnce = () => new Promise((resolve) => {
+		const ws = new WebSocketCtor(resolveVamaWsUrl(account.bothubUrl ?? "https://bothub.vama.com"), { headers: { Authorization: `Bot ${account.botToken ?? ""}` } });
+		active = ws;
+		let opened = false;
+		let settled = false;
+		const settle = () => {
+			if (!settled) {
+				settled = true;
+				active = void 0;
+				resolve({ opened });
+			}
+		};
+		ws.addEventListener("open", () => {
+			opened = true;
+			state = "open";
+			log(`vama[${accountId}]: WebSocket connected to BotHub — events arrive in real time`);
+		});
+		ws.addEventListener("message", (ev) => {
+			let parsed;
+			try {
+				parsed = JSON.parse(String(ev.data));
+			} catch {
+				error(`vama[${accountId}]: ignoring malformed WebSocket frame`);
+				return;
+			}
+			try {
+				onEvent(parsed);
+			} catch (err) {
+				error(`vama[${accountId}]: WebSocket event handler error: ${String(err)}`);
+			}
+		});
+		ws.addEventListener("error", () => {});
+		ws.addEventListener("close", () => settle());
+	});
+	const loop = async () => {
+		let failures = 0;
+		while (!aborted()) {
+			let preflight;
+			try {
+				preflight = await checkVamaWebSocketSupport(account, opts.deps);
+			} catch (err) {
+				failures += 1;
+				const delay = backoff[Math.min(failures - 1, backoff.length - 1)];
+				if (failures === 1) log(`vama[${accountId}]: WebSocket preflight failed (${err instanceof Error ? err.message : String(err)}); retrying in ${Math.round(delay / 1e3)}s`);
+				await sleep$1(delay, abort.signal);
+				continue;
+			}
+			if (!preflight.supported) {
+				if (mode === "websocket") error(`vama[${accountId}]: transport is set to "websocket" but BotHub refused (${preflight.reason}). ` + (preflight.reason === "disabled" ? "WebSocket delivery is not enabled for this bot — falling back to webhook delivery. Remove transport or set it to \"auto\"." : "Falling back to webhook delivery."));
+				else if (preflight.reason !== "disabled") log(`vama[${accountId}]: WebSocket unavailable (${preflight.reason}); using webhook delivery`);
+				state = "fallback";
+				return;
+			}
+			if (aborted()) break;
+			state = "connecting";
+			const { opened } = await connectOnce();
+			if (aborted()) break;
+			if (opened) {
+				failures = 0;
+				log(`vama[${accountId}]: WebSocket closed; reconnecting`);
+			} else failures += 1;
+			const delay = opened ? backoff[0] : backoff[Math.min(failures - 1, backoff.length - 1)];
+			await sleep$1(Math.round(delay * (.8 + Math.random() * .4)), abort.signal);
+		}
+		state = "stopped";
+	};
+	return {
+		state: () => state,
+		done: loop().catch((err) => {
+			state = "stopped";
+			error(`vama[${accountId}]: WebSocket transport loop crashed: ${String(err)}`);
+		}),
+		stop: () => {
+			abort.abort();
+			try {
+				active?.close();
+			} catch {}
+		}
+	};
+}
+//#endregion
+//#region extensions/vama/src/probe.ts
+const probeCache = /* @__PURE__ */ new Map();
+const PROBE_CACHE_TTL_MS = 600 * 1e3;
+const MAX_PROBE_CACHE_SIZE = 64;
+async function probeVama(account) {
+	if (!account.botToken) return {
+		ok: false,
+		error: "missing credentials (botToken)"
+	};
+	const cacheKey = account.accountId;
+	const cached = probeCache.get(cacheKey);
+	if (cached && cached.expiresAt > Date.now()) return cached.result;
+	try {
+		const me = await createBotHubClient(account).getMe();
+		const botId = me.bot_id;
+		const registeredUrl = me.webhook_url?.trim() || void 0;
+		if (!registeredUrl) {
+			let wsEnabled = false;
+			if (account.transport !== "webhook") try {
+				wsEnabled = (await checkVamaWebSocketSupport(account)).supported;
+			} catch {}
+			if (!wsEnabled) return {
+				ok: false,
+				botId,
+				error: "bot token is valid, but no webhook URL is registered with BotHub — Vama cannot deliver messages to this gateway (the agent shows \"Awaiting claw\"). Set channels.vama.webhookUrl to your gateway's public URL (e.g. https://your-host/vama/events) and restart the gateway, or re-run `openclaw onboard`."
+			};
+			const wsResult = {
+				ok: true,
+				botId,
+				wsEnabled: true
+			};
+			probeCache.set(cacheKey, {
+				result: wsResult,
+				expiresAt: Date.now() + PROBE_CACHE_TTL_MS
+			});
+			return wsResult;
+		}
+		const result = {
+			ok: true,
+			botId,
+			webhookUrl: registeredUrl
+		};
+		probeCache.set(cacheKey, {
+			result,
+			expiresAt: Date.now() + PROBE_CACHE_TTL_MS
+		});
+		if (probeCache.size > MAX_PROBE_CACHE_SIZE) {
+			const oldest = probeCache.keys().next().value;
+			if (oldest !== void 0) probeCache.delete(oldest);
+		}
+		return result;
+	} catch (err) {
+		return {
+			ok: false,
+			error: err instanceof Error ? err.message : String(err)
+		};
+	}
+}
+function clearProbeCache() {
+	probeCache.clear();
+}
+//#endregion
+//#region extensions/vama/src/register.ts
+/**
+* Outer retry schedule for startup webhook registration. The BotHub
+* client already retries transport errors per call (fetchWithRetry);
+* these delays cover application-level failures around gateway boot —
+* e.g. the tunnel in front of the listener still coming up, or BotHub
+* rejecting the URL while DNS for a freshly-minted tunnel propagates.
+*/
+const DEFAULT_RETRY_DELAYS_MS = [5e3, 15e3];
+function sleep(ms, abortSignal) {
+	return new Promise((resolve) => {
+		if (abortSignal?.aborted) {
+			resolve();
+			return;
+		}
+		const timer = setTimeout(() => {
+			abortSignal?.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		const onAbort = () => {
+			clearTimeout(timer);
+			resolve();
+		};
+		abortSignal?.addEventListener("abort", onAbort, { once: true });
+	});
+}
+/**
+* Register `account.webhookUrl` with BotHub (PUT /v1/bot/webhook).
+*
+* Called fire-and-forget from the monitor once the local webhook server
+* is listening (ordering matters: BotHub replays buffered messages
+* synchronously on registration, so the listener must be up first).
+*
+* Never throws — a registration failure must not take down the channel
+* (outbound sends still work; the probe surfaces the broken inbound
+* path). Returns true when registration succeeded.
+*/
+async function registerVamaWebhook(opts) {
+	const { account, log, error, abortSignal } = opts;
+	const url = account.webhookUrl;
+	if (!url) return false;
+	const accountId = account.accountId;
+	const webhookPath = account.config?.webhookPath ?? "/vama/events";
+	try {
+		const parsed = new URL(url);
+		if (parsed.pathname !== webhookPath) log(`vama[${accountId}]: webhookUrl path "${parsed.pathname}" differs from webhookPath "${webhookPath}" — BotHub will POST to ${url}; make sure that forwards to the local listener path ${webhookPath}`);
+	} catch {
+		error(`vama[${accountId}]: webhookUrl is not a valid URL: ${url} — skipping registration`);
+		return false;
+	}
+	const delays = opts.retryDelaysMs ?? DEFAULT_RETRY_DELAYS_MS;
+	let lastErr;
+	for (let attempt = 0; attempt <= delays.length; attempt++) {
+		if (abortSignal?.aborted) return false;
+		try {
+			await createBotHubClient(account).registerWebhook({ url });
+			log(`vama[${accountId}]: webhook registered with BotHub: ${url}`);
+			clearProbeCache();
+			return true;
+		} catch (err) {
+			lastErr = err;
+			if (attempt < delays.length) {
+				log(`vama[${accountId}]: webhook registration attempt ${attempt + 1} failed (${err instanceof Error ? err.message : String(err)}); retrying in ${Math.round(delays[attempt] / 1e3)}s`);
+				await sleep(delays[attempt], abortSignal);
+			}
+		}
+	}
+	error(`vama[${accountId}]: webhook registration failed: ${lastErr instanceof Error ? lastErr.message : String(lastErr)}. BotHub cannot deliver messages until this succeeds (the agent shows "Awaiting claw" in Vama). Check that ${url} is a public HTTPS URL that forwards to the local listener, then restart the gateway.`);
+	return false;
+}
+//#endregion
 //#region extensions/vama/src/webhook.ts
 const MAX_TIMESTAMP_AGE_S = 300;
 /**
@@ -820,6 +1155,20 @@ async function monitorVamaProvider(opts = {}) {
 	const webhookPath = account.config?.webhookPath ?? "/vama/events";
 	const host = account.config?.webhookHost ?? "127.0.0.1";
 	log(`vama[${accountId}]: starting webhook server on ${host}:${port}, path ${webhookPath}...`);
+	const dispatchEvent = (event, replayId) => {
+		if (event.type === "message.create") {
+			const messageEvent = event.data;
+			handleVamaMessage({
+				cfg,
+				event: messageEvent,
+				runtime: opts.runtime,
+				accountId,
+				replayId
+			}).catch((err) => {
+				error(`vama[${accountId}]: error handling message: ${String(err)}`);
+			});
+		} else log(`vama[${accountId}]: ignoring event type=${event.type}`);
+	};
 	const server = http.createServer();
 	server.on("request", (req, res) => {
 		if (isRateLimited(`${accountId}:${req.socket.remoteAddress ?? "unknown"}`, Date.now())) {
@@ -875,28 +1224,17 @@ async function monitorVamaProvider(opts = {}) {
 				error(`vama[${accountId}]: failed to parse webhook body`);
 				return;
 			}
-			const eventType = event.type;
-			const deliveryId = req.headers["x-bothub-delivery-id"];
 			const replayId = req.headers["x-replay-id"];
-			if (eventType === "message.create") {
-				const messageEvent = event.data;
-				handleVamaMessage({
-					cfg,
-					event: messageEvent,
-					runtime: opts.runtime,
-					accountId,
-					replayId
-				}).catch((err) => {
-					error(`vama[${accountId}]: error handling message: ${String(err)}`);
-				});
-			} else log(`vama[${accountId}]: ignoring event type=${eventType} delivery=${deliveryId}`);
+			dispatchEvent(event, replayId);
 		}).catch((err) => {
 			if (!guard.isTripped()) error(`vama[${accountId}]: webhook handler error: ${String(err)}`);
 			guard.dispose();
 		});
 	});
+	let wsHandle;
 	return new Promise((resolve, reject) => {
 		const cleanup = () => {
+			wsHandle?.stop();
 			server.close();
 		};
 		const handleAbort = () => {
@@ -912,6 +1250,20 @@ async function monitorVamaProvider(opts = {}) {
 		opts.abortSignal?.addEventListener("abort", handleAbort, { once: true });
 		server.listen(port, host, () => {
 			log(`vama[${accountId}]: webhook server listening on ${host}:${port}`);
+			registerVamaWebhook({
+				account,
+				log,
+				error,
+				abortSignal: opts.abortSignal
+			});
+			if (account.transport !== "webhook") wsHandle = startVamaWebSocket({
+				account,
+				onEvent: (event) => dispatchEvent(event),
+				log,
+				error,
+				abortSignal: opts.abortSignal,
+				mode: account.transport === "websocket" ? "websocket" : "auto"
+			});
 		});
 		server.on("error", (err) => {
 			error(`vama[${accountId}]: webhook server error: ${err}`);
@@ -922,38 +1274,4 @@ async function monitorVamaProvider(opts = {}) {
 	});
 }
 //#endregion
-//#region extensions/vama/src/probe.ts
-const probeCache = /* @__PURE__ */ new Map();
-const PROBE_CACHE_TTL_MS = 600 * 1e3;
-const MAX_PROBE_CACHE_SIZE = 64;
-async function probeVama(account) {
-	if (!account.botToken) return {
-		ok: false,
-		error: "missing credentials (botToken)"
-	};
-	const cacheKey = account.accountId;
-	const cached = probeCache.get(cacheKey);
-	if (cached && cached.expiresAt > Date.now()) return cached.result;
-	try {
-		const result = {
-			ok: true,
-			botId: (await createBotHubClient(account).getMe()).bot_id
-		};
-		probeCache.set(cacheKey, {
-			result,
-			expiresAt: Date.now() + PROBE_CACHE_TTL_MS
-		});
-		if (probeCache.size > MAX_PROBE_CACHE_SIZE) {
-			const oldest = probeCache.keys().next().value;
-			if (oldest !== void 0) probeCache.delete(oldest);
-		}
-		return result;
-	} catch (err) {
-		return {
-			ok: false,
-			error: err instanceof Error ? err.message : String(err)
-		};
-	}
-}
-//#endregion
-export { dispatchStarted as a, resolveVamaAccount as c, buildBaseChannelStatusSummary as d, createDefaultChannelRuntimeState as f, dispatchEnded as i, DEFAULT_ACCOUNT_ID$1 as l, monitorVamaProvider as n, listVamaAccountIds as o, sendMessageVama as r, resolveDefaultVamaAccountId as s, probeVama as t, PAIRING_APPROVED_MESSAGE as u };
+export { dispatchStarted as a, buildBaseChannelStatusSummary as c, resolveDefaultVamaAccountId as d, resolveVamaAccount as f, dispatchEnded as i, createDefaultChannelRuntimeState as l, probeVama as n, DEFAULT_ACCOUNT_ID$1 as o, sendMessageVama as r, PAIRING_APPROVED_MESSAGE as s, monitorVamaProvider as t, listVamaAccountIds as u };

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@vama/openclaw",
-  "version": "2026.5.5-1",
+  "version": "2026.5.5-4",
   "description": "OpenClaw Vama channel plugin via BotHub",
+  "homepage": "https://web.vama.com/connect-guide",
   "repository": {
     "type": "git",
     "url": "https://github.com/VamaSingapore/openclaw"
@@ -10,14 +11,6 @@
   "dependencies": {
     "undici": "8.2.0"
   },
-  "peerDependencies": {
-    "openclaw": ">=2026.5.12"
-  },
-  "peerDependenciesMeta": {
-    "openclaw": {
-      "optional": true
-    }
-  },
   "openclaw": {
     "extensions": [
       "./index.ts"
@@ -53,6 +46,15 @@
   },
   "files": [
     "dist/**",
-    "openclaw.plugin.json"
-  ]
+    "openclaw.plugin.json",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "openclaw": ">=2026.5.12"
+  },
+  "peerDependenciesMeta": {
+    "openclaw": {
+      "optional": true
+    }
+  }
 }