Connect your agent to Vama

Run your own OpenClaw agent and connect it to Vama direct messages — the "bring your own claw" flow. Create an agent in Vama, paste one command on the machine running OpenClaw, and your agent shows up natively in Vama DMs.

This guide is for connecting an agent you run yourself. If you created your agent from inside the Vama app, it's already connected — you don't need any of this.

Install the channel

The Vama channel ships bundled in Vama-provided OpenClaw builds, 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 the vama channel and the openclaw vama connect command become available. The channel requires OpenClaw >=2026.5.12; connect codes require plugin @vama/openclaw >=2026.5.5-5.

Connect with one command (recommended)

Install the channel (above) — once per machine.
In Vama, go to Settings → Agents → Connect an agent (the "Bring your own claw" page).
Optionally name the agent, then click Create agent. Vama shows a ready-to-paste command like:

openclaw vama connect vmc1_eyJjIjoi...

Paste it on the machine running OpenClaw. That's it — the command exchanges the code for credentials, writes your channels.vama config, restarts the gateway, and connects over WebSocket, so your machine needs no public URL and no tunnel. Your agent sends you a hello message in Vama when it's live.

The code is single-use and expires in 15 minutes — if it lapses, click Get connect command on the agent card for a fresh one. The same button re-pairs an agent you've moved to a new machine.

You can connect as many agents as you like — each Create agent provisions a new, independent agent. Run a separate OpenClaw gateway (or a separate accounts entry — see Multi-account) per agent.

Get a token (manual fallback)

If you can't use connect codes (e.g. an older plugin version), expand Manual setup (advanced) on the agent card after creating it. Vama shows a one-time agent token and webhook secret, plus a ready-to-paste channels.vama config block:

Copy the config into ~/.openclaw/openclaw.json (see below).
Fill in webhookUrl with your gateway's public URL (see Receiving messages — a tunnel one-liner is enough) and start your gateway with openclaw gateway run. The gateway registers the URL with Vama automatically and your agent sends you a hello message when it's connected.

Each token is shown once. If you lose one, use Regenerate token on that agent — the old token stops working immediately (a fresh connect command is shown there too). Delete agent disconnects the claw and removes that agent from your Vama DMs.

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 an agent 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": "<agent_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)

Vama (BotHub) delivers inbound messages to your gateway over an HTTP webhook, so it must be able to reach your gateway's webhook listener from the internet. Two things make that work:

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

Telling Vama that URL. Set it as channels.vama.webhookUrl (include the /vama/events path):

{
  "channels": {
    "vama": {
      "webhookUrl": "https://random-words.trycloudflare.com/vama/events"
    }
  }
}

That's it — the gateway registers webhookUrl with BotHub automatically every time it starts. No manual API calls, no extra registration step. Your agent's status flips to Connected in Vama and it sends you a hello message.

If your tunnel URL changes (quick tunnels are ephemeral — they get a new URL each run), update webhookUrl and restart the gateway. For a set-and-forget setup, use a stable URL: a named Cloudflare tunnel, Tailscale Funnel, or a reverse proxy on a domain you own.

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 Vama. If registration is missing it fails with instructions — an agent in that state shows "Awaiting claw" and can't receive messages.

Configuration reference

Key	Type	Default	Description
`enabled`	boolean	`false`	Enable/disable the Vama channel
`botToken`	string	—	Agent authentication token from provisioning
`webhookSecret`	string	—	HMAC secret for webhook signature verification
`webhookUrl`	string	—	Public URL of your webhook listener. Auto-registered with Vama at every gateway start.
`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 agent
`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 agent with channels.vama.dmPolicy:

open (default) — any Vama user can DM the agent.
pairing — unknown users get a pairing code to request approval.
allowlist — only users listed in channels.vama.allowFrom can DM the agent.

{
  "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 agent 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 Agent"
        },
        "production": {
          "botToken": "<prod_token>",
          "webhookSecret": "<prod_secret>",
          "webhookPort": 3003,
          "name": "Production Agent"
        }
      }
    }
  }
}

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 your gateway is running: no webhook URL is registered with Vama. 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").
Agent 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.