@vama/openclaw

Connect your own OpenClaw 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:

openclaw plugins install @vama/openclaw

Prefer ClawHub? Use the clawhub: spec instead:

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:

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:

openclaw gateway run

Manual configuration

Set the following in ~/.openclaw/openclaw.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.:

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:

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.

{
  "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:

{
  "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.