@vama/openclaw 2026.5.5-2 → 2026.5.5-5

package/README.md

@@ -29,8 +29,8 @@ If you run your own OpenClaw gateway and just want to connect it to Vama — the
 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) and start your gateway with `openclaw gateway run`.
-5. Register your gateway's public webhook URL so BotHub can deliver messages (see **Receiving messages**).
+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.
 
@@ -61,6 +61,7 @@ Set the following in `~/.openclaw/openclaw.json`:
       "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"
@@ -71,33 +72,47 @@ Set the following in `~/.openclaw/openclaw.json`:
 
 ## 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. After your token is configured, register your gateway's public URL:
+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:
 
-- Run `openclaw onboard` → Vama. The wizard prompts for a *"Public webhook URL for BotHub to send events"* (e.g. `https://your-gateway-host.example.com/vama/events`) and registers it with BotHub. Leave it blank to skip and register later.
-- If your gateway isn't directly reachable, put it behind a tunnel or reverse proxy and register that public URL.
+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.:
 
-Verify the channel is connected with:
+```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 webhook listener binds to `webhookHost`:`webhookPort``webhookPath` (default `127.0.0.1:3001/vama/events`) — make sure your public URL forwards to that address.
+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                                    |
-| `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. |
+| 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
 
@@ -175,8 +190,9 @@ Named accounts inherit top-level settings (like `bothubUrl`) and can override th
 
 ## Troubleshooting
 
-- **Bot not responding**: verify `openclaw channels status --probe` shows Vama as connected. Check that the webhook port is reachable from BotHub.
-- **Created a bot in the Vama app but it never replies**: you still need to register a public webhook URL so BotHub can reach your gateway — see **Receiving messages**. A token alone doesn't make your gateway reachable.
+- **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`.

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

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

package/dist/api.js

@@ -1,3 +1,4 @@
-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 } from "./probe-Cf1xor23.js";
+import { n as sendMessageVama, t as monitorVamaProvider } from "./monitor-DLgOtdLQ.js";
+import { t as registerVamaSubagentKeepaliveHooks } from "./api-DftFHS2s.js";
 export { monitorVamaProvider, probeVama, registerVamaSubagentKeepaliveHooks, sendMessageVama };

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

@@ -1,6 +1,8 @@
-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 { t as getVamaRuntime } from "./runtime-w-1oL50p.js";
+import { a as exchangeConnectCode, i as createBotHubClient, n as attachmentHintFromExtension, o as provisionBot } from "./client-BzhfASX8.js";
+import { a as resolveDefaultVamaAccountId, i as listVamaAccountIds, n as probeVama, o as resolveVamaAccount } from "./probe-Cf1xor23.js";
+import { a as DEFAULT_ACCOUNT_ID$1, c as createDefaultChannelRuntimeState, n as sendMessageVama, o as PAIRING_APPROVED_MESSAGE, s as buildBaseChannelStatusSummary, t as monitorVamaProvider } from "./monitor-DLgOtdLQ.js";
+import { t as getVamaRuntime } from "./runtime-Cq09Y5cd.js";
+import { t as parseVamaConnectCode } from "./connect-code-Bbp9J6TH.js";
 import { jsonResult, readStringOrNumberParam, readStringParam } from "openclaw/plugin-sdk/channel-actions";
 import { extractToolSend } from "openclaw/plugin-sdk/tool-send";
 import { DEFAULT_ACCOUNT_ID, addWildcardAllowFrom, createStandardChannelSetupStatus, formatDocsLink, setSetupChannelEnabled } from "openclaw/plugin-sdk/setup";
@@ -334,7 +336,7 @@ const vamaPlugin = {
 			const account = resolveVamaAccount({ cfg });
 			if (!account.configured) return;
 			try {
-				const { createBotHubClient } = await import("./client-AsD46gcK.js").then((n) => n.r);
+				const { createBotHubClient } = await import("./client-BzhfASX8.js").then((n) => n.r);
 				await createBotHubClient(account).sendMessage({
 					userId: id,
 					text: PAIRING_APPROVED_MESSAGE
@@ -367,6 +369,15 @@ const vamaPlugin = {
 				minimum: 1
 			},
 			webhookHost: { type: "string" },
+			webhookUrl: { type: "string" },
+			transport: {
+				type: "string",
+				enum: [
+					"auto",
+					"webhook",
+					"websocket"
+				]
+			},
 			dmPolicy: {
 				type: "string",
 				enum: [
@@ -399,7 +410,16 @@ const vamaPlugin = {
 							type: "integer",
 							minimum: 1
 						},
-						webhookHost: { type: "string" }
+						webhookHost: { type: "string" },
+						webhookUrl: { type: "string" },
+						transport: {
+							type: "string",
+							enum: [
+								"auto",
+								"webhook",
+								"websocket"
+							]
+						}
 					}
 				}
 			}
@@ -536,8 +556,8 @@ const vamaPlugin = {
 		introNote: {
 			title: "Vama setup",
 			lines: [
-				"Vama needs BotHub credentials.",
-				"You will be prompted for your Vama username to auto-provision a bot.",
+				"Easiest: paste a connect code from the Vama app (Settings → AI Agents).",
+				"Alternative: provision a bot by Vama username.",
 				`Docs: ${formatDocsLink("/channels/vama", "channels/vama")}`
 			],
 			shouldShow: ({ cfg }) => !resolveVamaAccount({ cfg }).configured
@@ -567,6 +587,65 @@ const vamaPlugin = {
 					return { cfg: next };
 				}
 			}
+			if (await prompter.select({
+				message: "How do you want to connect to Vama?",
+				options: [{
+					value: "code",
+					label: "Paste a connect code (recommended)",
+					hint: "Vama app → Settings → AI Agents → Connect your own — no tunnel needed"
+				}, {
+					value: "username",
+					label: "Provision by Vama username",
+					hint: "creates/reuses a bot for your account; webhook URL needed later"
+				}],
+				initialValue: "code"
+			}) === "code") {
+				const parsedCode = parseVamaConnectCode((await prompter.text({
+					message: "Connect code (vmc1_… or 64-char hex)",
+					validate: (value) => {
+						try {
+							parseVamaConnectCode(value ?? "");
+							return;
+						} catch (err) {
+							return err instanceof Error ? err.message : String(err);
+						}
+					}
+				})).trim());
+				const codeBothubUrl = parsedCode.bothubUrl || vamaCfg?.bothubUrl?.trim() || "https://bothub.vama.com";
+				await prompter.note("Exchanging connect code with BotHub...", "Vama setup");
+				try {
+					const exchanged = await exchangeConnectCode({
+						bothubUrl: codeBothubUrl,
+						code: parsedCode.code
+					});
+					next = {
+						...next,
+						channels: {
+							...next.channels,
+							vama: {
+								...next.channels?.vama,
+								enabled: true,
+								botToken: exchanged.bot_token,
+								webhookSecret: exchanged.webhook_secret,
+								...codeBothubUrl !== "https://bothub.vama.com" ? { bothubUrl: codeBothubUrl } : {}
+							}
+						}
+					};
+					const label = exchanged.display_name || exchanged.username || exchanged.bot_id;
+					await prompter.note(exchanged.websocket_enabled ? `Connected as ${label}. WebSocket delivery is enabled — no tunnel or public URL needed.` : `Connected as ${label}. This bot uses webhook delivery — set channels.vama.webhookUrl once your gateway is publicly reachable.`, "Vama connect");
+				} catch (err) {
+					await prompter.note(`Connect code exchange failed: ${err instanceof Error ? err.message : String(err)}\nMint a fresh code in Vama settings, or re-run setup and choose username provisioning.`, "Vama connect error");
+					return { cfg: next };
+				}
+				const account = resolveVamaAccount({ cfg: next });
+				try {
+					const probe = await probeVama(account);
+					await prompter.note(probe.ok ? `Connected successfully (bot ${probe.botId ?? "unknown"})` : `Connection test failed: ${probe.error ?? "unknown error"}`, "Vama connection test");
+				} catch (err) {
+					await prompter.note(`Connection test failed: ${String(err)}`, "Vama connection test");
+				}
+				return { cfg: next };
+			}
 			const bothubUrl = vamaCfg?.bothubUrl?.trim() || "https://bothub.vama.com";
 			const username = (await prompter.text({
 				message: "Your Vama username (for bot provisioning)",
@@ -625,13 +704,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-KLKTLQFV.js";
 export { vamaPlugin };

package/dist/cli-F0a1J9Rj.js

@@ -0,0 +1,150 @@
+import { a as exchangeConnectCode } from "./client-BzhfASX8.js";
+import { n as probeVama, o as resolveVamaAccount, t as clearProbeCache } from "./probe-Cf1xor23.js";
+import { t as getVamaRuntime } from "./runtime-Cq09Y5cd.js";
+import { t as parseVamaConnectCode } from "./connect-code-Bbp9J6TH.js";
+import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "openclaw/plugin-sdk/account-id";
+//#region extensions/vama/src/cli.ts
+/**
+* Apply freshly exchanged credentials to the config. Default account writes
+* top-level under channels.vama (matching the setup wizard); named accounts
+* write under channels.vama.accounts.<id>. Existing unrelated keys
+* (dmPolicy, webhookPort, …) are preserved.
+*/
+function applyVamaConnectCredentials(params) {
+	const { cfg, accountId } = params;
+	const vama = cfg.channels?.vama ?? {};
+	const credentialPatch = {
+		enabled: true,
+		botToken: params.botToken,
+		webhookSecret: params.webhookSecret
+	};
+	if (params.bothubUrl !== "https://bothub.vama.com") credentialPatch.bothubUrl = params.bothubUrl;
+	if (accountId === DEFAULT_ACCOUNT_ID) {
+		const next = {
+			...vama,
+			...credentialPatch
+		};
+		if (params.bothubUrl === "https://bothub.vama.com") delete next.bothubUrl;
+		return {
+			...cfg,
+			channels: {
+				...cfg.channels,
+				vama: {
+					...next,
+					enabled: true
+				}
+			}
+		};
+	}
+	const nextAccount = {
+		...vama.accounts?.[accountId] ?? {},
+		...credentialPatch
+	};
+	if (params.bothubUrl === "https://bothub.vama.com") delete nextAccount.bothubUrl;
+	return {
+		...cfg,
+		channels: {
+			...cfg.channels,
+			vama: {
+				...vama,
+				enabled: true,
+				accounts: {
+					...vama.accounts,
+					[accountId]: nextAccount
+				}
+			}
+		}
+	};
+}
+/**
+* `openclaw vama connect <code>` — the whole BYO onboarding in one command:
+* exchange the code for credentials, write the config, verify with a live
+* probe. WebSocket-enabled bots (the default for codes minted from Vama
+* settings) need no tunnel, no public URL, no webhook registration.
+*/
+async function runVamaConnect(params, deps = {}) {
+	const exchange = deps.exchange ?? exchangeConnectCode;
+	const probe = deps.probe ?? probeVama;
+	const log = deps.log ?? ((msg) => console.log(msg));
+	const parsed = parseVamaConnectCode(params.rawCode);
+	const runtime = getVamaRuntime();
+	const cfg = runtime.config.current();
+	const accountId = normalizeAccountId(params.account?.trim() || DEFAULT_ACCOUNT_ID);
+	const existingUrl = (cfg.channels?.vama ?? {}).bothubUrl?.trim();
+	const bothubUrl = (params.bothubUrlFlag?.trim() || parsed.bothubUrl || existingUrl || "https://bothub.vama.com").replace(/\/+$/, "");
+	log(`Exchanging connect code with ${bothubUrl}…`);
+	const exchanged = await exchange({
+		bothubUrl,
+		code: parsed.code
+	});
+	const updated = applyVamaConnectCredentials({
+		cfg,
+		accountId,
+		botToken: exchanged.bot_token,
+		webhookSecret: exchanged.webhook_secret,
+		bothubUrl
+	});
+	await runtime.config.replaceConfigFile({
+		nextConfig: updated,
+		afterWrite: { mode: "auto" }
+	});
+	clearProbeCache();
+	const result = {
+		accountId,
+		botId: exchanged.bot_id,
+		username: exchanged.username,
+		displayName: exchanged.display_name,
+		websocketEnabled: exchanged.websocket_enabled === true,
+		bothubUrl,
+		created: exchanged.created
+	};
+	try {
+		const probed = await probe(resolveVamaAccount({
+			cfg: updated,
+			accountId
+		}));
+		result.probeOk = probed.ok;
+		if (!probed.ok) result.probeError = probed.error;
+	} catch (err) {
+		result.probeOk = false;
+		result.probeError = err instanceof Error ? err.message : String(err);
+	}
+	return result;
+}
+function printConnectResult(result) {
+	const botLabel = result.displayName || result.username || result.botId;
+	console.log("");
+	console.log(`✔ Connected to Vama as ${botLabel}${result.username ? ` (@${result.username})` : ""}`);
+	if (result.websocketEnabled) console.log("  Transport: WebSocket — no tunnel or public URL needed.");
+	else console.log("  Transport: webhook — set channels.vama.webhookUrl to a public URL (or mint a new code from Vama settings to enable WebSocket).");
+	if (result.probeOk === false && result.probeError) {
+		console.log(`  Verification warning: ${result.probeError}`);
+		console.log("  Re-check later with: openclaw channels status --probe");
+	}
+	console.log("");
+	console.log("  If your gateway is running it reloads automatically; otherwise start it:");
+	console.log("    openclaw gateway");
+}
+function registerVamaCli({ program }) {
+	program.command("vama").description("Vama channel tools (connect codes, account state)").command("connect").description("Connect this OpenClaw to Vama with a one-time code from Vama settings (Settings → AI Agents)").argument("<code>", "connect code (vmc1_… token or 64-char hex)").option("--bothub-url <url>", "BotHub endpoint override (defaults to the URL embedded in the code)").option("--account <id>", "Vama account id to write credentials to", DEFAULT_ACCOUNT_ID).option("--json", "print the result as JSON", false).action(async (code, opts) => {
+		try {
+			const result = await runVamaConnect({
+				rawCode: code,
+				bothubUrlFlag: opts.bothubUrl,
+				account: opts.account
+			}, { log: opts.json ? () => {} : void 0 });
+			if (opts.json) console.log(JSON.stringify(result, null, 2));
+			else printConnectResult(result);
+		} catch (err) {
+			const message = err instanceof Error ? err.message : String(err);
+			if (opts.json) console.log(JSON.stringify({
+				ok: false,
+				error: message
+			}, null, 2));
+			else console.error(`✖ Connect failed: ${message}`);
+			process.exitCode = 1;
+		}
+	});
+}
+//#endregion
+export { registerVamaCli };

package/dist/{client-AsD46gcK.js → client-BzhfASX8.js}

@@ -19,6 +19,7 @@ var client_exports = /* @__PURE__ */ __exportAll({
 	FetchWithRetryError: () => FetchWithRetryError,
 	attachmentHintFromExtension: () => attachmentHintFromExtension,
 	createBotHubClient: () => createBotHubClient,
+	exchangeConnectCode: () => exchangeConnectCode,
 	mimeFromExtension: () => mimeFromExtension,
 	provisionBot: () => provisionBot
 });
@@ -312,6 +313,65 @@ function createBotHubClient(account) {
 	};
 }
 /**
+* Exchange a single-use connect code for bot credentials
+* (POST /v1/provision/exchange — unauthenticated; the code IS the
+* credential). BotHub consumes the code atomically: a second attempt with
+* the same code fails with `invalid_code`, so callers should treat errors
+* as "mint a fresh code in Vama settings", not retry-the-same-code.
+*/
+async function exchangeConnectCode(params) {
+	const baseUrl = params.bothubUrl.replace(/\/+$/, "");
+	const path = "/v1/provision/exchange";
+	const start = Date.now();
+	let resPair;
+	try {
+		resPair = await fetchWithRetry(`${baseUrl}${path}`, {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify({ code: params.code })
+		});
+	} catch (err) {
+		logBothubCall({
+			method: "POST",
+			path,
+			start,
+			status: null,
+			attemptsUsed: attemptsUsedFromError(err),
+			errorMsg: unwrapFetchErrorMsg(err)
+		});
+		throw err;
+	}
+	const { res, attemptsUsed } = resPair;
+	if (!res.ok) {
+		const text = await res.text().catch(() => "");
+		logBothubCall({
+			method: "POST",
+			path,
+			start,
+			status: res.status,
+			attemptsUsed,
+			bodyText: text
+		});
+		let errorCode = "";
+		let message = text;
+		try {
+			const parsed = JSON.parse(text);
+			errorCode = parsed.error ?? "";
+			message = parsed.message ?? text;
+		} catch {}
+		if (errorCode === "invalid_code") throw new Error("Connect code is invalid, expired, or already used. Mint a fresh one in Vama settings and paste the new command.");
+		throw new Error(`BotHub exchange failed (${res.status}): ${message}`);
+	}
+	logBothubCall({
+		method: "POST",
+		path,
+		start,
+		status: res.status,
+		attemptsUsed
+	});
+	return await res.json();
+}
+/**
 * Provision a new bot via the BotHub provisioning API (unauthenticated).
 */
 async function provisionBot(params) {
@@ -364,4 +424,4 @@ async function provisionBot(params) {
 	return await res.json();
 }
 //#endregion
-export { provisionBot as a, createBotHubClient as i, attachmentHintFromExtension as n, client_exports as r, BOTHUB_DEFAULT_URL as t };
+export { exchangeConnectCode as a, createBotHubClient as i, attachmentHintFromExtension as n, provisionBot as o, client_exports as r, BOTHUB_DEFAULT_URL as t };

package/dist/connect-code-Bbp9J6TH.js

@@ -0,0 +1,49 @@
+const HEX_CODE_RE = /^[0-9a-f]{64}$/i;
+function parseWrappedCode(raw) {
+	const payload = raw.slice(5);
+	let decoded;
+	try {
+		decoded = Buffer.from(payload, "base64url").toString("utf8");
+	} catch {
+		throw new Error("Invalid connect code: not valid base64url");
+	}
+	let parsed;
+	try {
+		parsed = JSON.parse(decoded);
+	} catch {
+		throw new Error("Invalid connect code: wrapper payload is not JSON");
+	}
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("Invalid connect code: wrapper payload is not an object");
+	const { u, c } = parsed;
+	if (typeof c !== "string" || !HEX_CODE_RE.test(c)) throw new Error("Invalid connect code: missing or malformed exchange code");
+	let bothubUrl;
+	if (u !== void 0) {
+		if (typeof u !== "string") throw new Error("Invalid connect code: BotHub URL must be a string");
+		let parsedUrl;
+		try {
+			parsedUrl = new URL(u);
+		} catch {
+			throw new Error(`Invalid connect code: BotHub URL is not a valid URL: ${u}`);
+		}
+		if (parsedUrl.protocol !== "https:" && parsedUrl.protocol !== "http:") throw new Error(`Invalid connect code: BotHub URL must be http(s): ${u}`);
+		bothubUrl = u.replace(/\/+$/, "");
+	}
+	return {
+		code: c.toLowerCase(),
+		bothubUrl
+	};
+}
+/**
+* Parse a connect code as pasted by the user. Accepts the `vmc1_` wrapped
+* form (URL + code in one token) and the bare 64-hex form. Throws a
+* user-presentable Error for anything else.
+*/
+function parseVamaConnectCode(raw) {
+	const trimmed = raw.trim();
+	if (!trimmed) throw new Error("Connect code is required");
+	if (trimmed.startsWith("vmc1_")) return parseWrappedCode(trimmed);
+	if (HEX_CODE_RE.test(trimmed)) return { code: trimmed.toLowerCase() };
+	throw new Error("Invalid connect code: expected a vmc1_… token or a 64-character hex code (copy the full command from Vama settings — codes expire after 15 minutes)");
+}
+//#endregion
+export { parseVamaConnectCode as t };

package/dist/index.js

@@ -1,8 +1,21 @@
-import { n as monitorVamaProvider, r as sendMessageVama, t as probeVama } from "./probe-B2hFOc2Y.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 { n as probeVama } from "./probe-Cf1xor23.js";
+import { n as sendMessageVama, t as monitorVamaProvider } from "./monitor-DLgOtdLQ.js";
+import { n as setVamaRuntime } from "./runtime-Cq09Y5cd.js";
+import { t as registerVamaSubagentKeepaliveHooks } from "./api-DftFHS2s.js";
+import { t as vamaPlugin } from "./channel-plugin-api-KLKTLQFV.js";
 import "./runtime-api.js";
+//#region extensions/vama/src/cli-metadata.ts
+function registerVamaCliMetadata(api) {
+	api.registerCli(async ({ program }) => {
+		const { registerVamaCli } = await import("./cli-F0a1J9Rj.js");
+		registerVamaCli({ program });
+	}, { descriptors: [{
+		name: "vama",
+		description: "Connect this OpenClaw to Vama and manage the Vama channel",
+		hasSubcommands: true
+	}] });
+}
+//#endregion
 //#region extensions/vama/index.ts
 const channelEntry = {
 	kind: "bundled-channel-entry",
@@ -41,10 +54,15 @@ const channelEntry = {
 		} }
 	},
 	register(api) {
-		if (api.registrationMode === "cli-metadata") return;
+		const mode = api.registrationMode;
+		if (mode === "cli-metadata") {
+			registerVamaCliMetadata(api);
+			return;
+		}
 		setVamaRuntime(api.runtime);
 		api.registerChannel({ plugin: vamaPlugin });
 		registerVamaSubagentKeepaliveHooks(api);
+		if (mode === "discovery" || mode === "full") registerVamaCliMetadata(api);
 	},
 	loadChannelPlugin: () => vamaPlugin,
 	setChannelRuntime: (runtime) => {

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

@@ -1,8 +1,13 @@
-import { i as createBotHubClient, n as attachmentHintFromExtension } from "./client-AsD46gcK.js";
-import { t as getVamaRuntime } from "./runtime-w-1oL50p.js";
+import { i as createBotHubClient, n as attachmentHintFromExtension } from "./client-BzhfASX8.js";
+import { o as resolveVamaAccount, r as startVamaWebSocket, t as clearProbeCache } from "./probe-Cf1xor23.js";
+import { t as getVamaRuntime } from "./runtime-Cq09Y5cd.js";
 import * as fs from "node:fs";
 import { promises } from "node:fs";
 import * as http from "node:http";
+import { 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 { 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,10 +15,6 @@ 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
@@ -38,58 +39,6 @@ function createScopedPairingAccess(params) {
 	};
 }
 //#endregion
-//#region extensions/vama/src/accounts.ts
-function listConfiguredAccountIds(cfg) {
-	const accounts = (cfg.channels?.vama)?.accounts;
-	if (!accounts || typeof accounts !== "object") return [];
-	return Object.keys(accounts).filter(Boolean);
-}
-function listVamaAccountIds(cfg) {
-	const ids = listConfiguredAccountIds(cfg);
-	if (ids.length === 0) return [DEFAULT_ACCOUNT_ID];
-	return [...ids].toSorted((a, b) => a.localeCompare(b));
-}
-function resolveDefaultVamaAccountId(cfg) {
-	const ids = listVamaAccountIds(cfg);
-	if (ids.includes(DEFAULT_ACCOUNT_ID)) return DEFAULT_ACCOUNT_ID;
-	return ids[0] ?? DEFAULT_ACCOUNT_ID;
-}
-function resolveAccountConfig(cfg, accountId) {
-	const accounts = (cfg.channels?.vama)?.accounts;
-	if (!accounts || typeof accounts !== "object") return;
-	return accounts[accountId];
-}
-function mergeVamaAccountConfig(cfg, accountId) {
-	const { accounts: _ignored, ...base } = cfg.channels?.vama ?? {};
-	const account = resolveAccountConfig(cfg, accountId) ?? {};
-	return {
-		...base,
-		...account
-	};
-}
-function resolveVamaAccount(params) {
-	const accountId = normalizeAccountId(params.accountId);
-	const baseEnabled = (params.cfg.channels?.vama)?.enabled !== false;
-	const merged = mergeVamaAccountConfig(params.cfg, accountId);
-	const accountEnabled = merged.enabled !== false;
-	const enabled = baseEnabled && accountEnabled;
-	const botToken = merged.botToken?.trim() || void 0;
-	const webhookSecret = merged.webhookSecret?.trim() || void 0;
-	const webhookSecretFile = merged.webhookSecretFile?.trim() || void 0;
-	const bothubUrl = merged.bothubUrl?.trim() || "https://bothub.vama.com";
-	return {
-		accountId,
-		enabled,
-		configured: Boolean(botToken),
-		name: merged.name?.trim() || void 0,
-		botToken,
-		webhookSecret,
-		webhookSecretFile,
-		bothubUrl,
-		config: merged
-	};
-}
-//#endregion
 //#region extensions/vama/src/dedup.ts
 const DEDUP_TTL_MS = 1440 * 60 * 1e3;
 const MEMORY_MAX_SIZE = 1e3;
@@ -703,6 +652,77 @@ async function handleVamaMessage(params) {
 	}
 }
 //#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 +840,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 +909,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 +935,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 +959,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 { DEFAULT_ACCOUNT_ID$1 as a, createDefaultChannelRuntimeState as c, dispatchStarted as i, sendMessageVama as n, PAIRING_APPROVED_MESSAGE as o, dispatchEnded as r, buildBaseChannelStatusSummary as s, monitorVamaProvider as t };

package/dist/probe-Cf1xor23.js

@@ -0,0 +1,319 @@
+import { i as createBotHubClient } from "./client-BzhfASX8.js";
+import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "openclaw/plugin-sdk/account-id";
+import { WebSocket, fetch } from "undici";
+//#region extensions/vama/src/accounts.ts
+function listConfiguredAccountIds(cfg) {
+	const accounts = (cfg.channels?.vama)?.accounts;
+	if (!accounts || typeof accounts !== "object") return [];
+	return Object.keys(accounts).filter(Boolean);
+}
+function listVamaAccountIds(cfg) {
+	const ids = listConfiguredAccountIds(cfg);
+	if (ids.length === 0) return [DEFAULT_ACCOUNT_ID];
+	return [...ids].toSorted((a, b) => a.localeCompare(b));
+}
+function resolveDefaultVamaAccountId(cfg) {
+	const ids = listVamaAccountIds(cfg);
+	if (ids.includes(DEFAULT_ACCOUNT_ID)) return DEFAULT_ACCOUNT_ID;
+	return ids[0] ?? DEFAULT_ACCOUNT_ID;
+}
+function resolveAccountConfig(cfg, accountId) {
+	const accounts = (cfg.channels?.vama)?.accounts;
+	if (!accounts || typeof accounts !== "object") return;
+	return accounts[accountId];
+}
+function mergeVamaAccountConfig(cfg, accountId) {
+	const { accounts: _ignored, ...base } = cfg.channels?.vama ?? {};
+	const account = resolveAccountConfig(cfg, accountId) ?? {};
+	return {
+		...base,
+		...account
+	};
+}
+function resolveVamaAccount(params) {
+	const accountId = normalizeAccountId(params.accountId);
+	const baseEnabled = (params.cfg.channels?.vama)?.enabled !== false;
+	const merged = mergeVamaAccountConfig(params.cfg, accountId);
+	const accountEnabled = merged.enabled !== false;
+	const enabled = baseEnabled && accountEnabled;
+	const botToken = merged.botToken?.trim() || void 0;
+	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,
+		configured: Boolean(botToken),
+		name: merged.name?.trim() || void 0,
+		botToken,
+		webhookSecret,
+		webhookSecretFile,
+		bothubUrl,
+		webhookUrl,
+		transport,
+		config: merged
+	};
+}
+//#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(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(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(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
+export { resolveDefaultVamaAccountId as a, listVamaAccountIds as i, probeVama as n, resolveVamaAccount as o, startVamaWebSocket as r, clearProbeCache as t };

package/dist/runtime-api.js

@@ -1,2 +1,2 @@
-import { n as setVamaRuntime } from "./runtime-w-1oL50p.js";
+import { n as setVamaRuntime } from "./runtime-Cq09Y5cd.js";
 export { setVamaRuntime };

package/openclaw.plugin.json

@@ -37,6 +37,15 @@
             "type": "string",
             "description": "BotHub base URL. Leave blank to use the default."
           },
+          "webhookUrl": {
+            "type": "string",
+            "description": "Public URL BotHub should deliver webhook events to. Registered automatically on every gateway start when set."
+          },
+          "transport": {
+            "type": "string",
+            "enum": ["auto", "webhook", "websocket"],
+            "description": "Inbound event transport. auto (default) probes for WebSocket delivery and falls back to webhook; websocket requires it; webhook never attempts it."
+          },
           "webhookPath": {
             "type": "string",
             "description": "HTTP path the gateway serves for inbound BotHub webhook events."
@@ -80,6 +89,8 @@
                 "webhookSecret": { "type": "string" },
                 "webhookSecretFile": { "type": "string" },
                 "bothubUrl": { "type": "string" },
+                "webhookUrl": { "type": "string" },
+                "transport": { "type": "string", "enum": ["auto", "webhook", "websocket"] },
                 "webhookPath": { "type": "string" },
                 "webhookPort": { "type": "integer", "minimum": 1, "maximum": 65535 },
                 "webhookHost": { "type": "string" }
@@ -115,6 +126,16 @@
           "label": "BotHub URL",
           "help": "Leave blank to use the default Vama BotHub endpoint."
         },
+        "webhookUrl": {
+          "label": "Public webhook URL",
+          "help": "Only needed for webhook transport. WebSocket-connected bots need no public URL.",
+          "advanced": true
+        },
+        "transport": {
+          "label": "Transport",
+          "help": "auto picks WebSocket when BotHub allows it, else webhook.",
+          "advanced": true
+        },
         "webhookPath": {
           "label": "Webhook path",
           "advanced": true

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@vama/openclaw",
-  "version": "2026.5.5-2",
+  "version": "2026.5.5-5",
   "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"
@@ -52,9 +45,16 @@
     ]
   },
   "files": [
-    "README.md",
     "dist/**",
-    "openclaw.plugin.json"
+    "openclaw.plugin.json",
+    "README.md"
   ],
-  "homepage": "https://web.vama.com/connect-guide"
+  "peerDependencies": {
+    "openclaw": ">=2026.5.12"
+  },
+  "peerDependenciesMeta": {
+    "openclaw": {
+      "optional": true
+    }
+  }
 }