@vama/openclaw 2026.5.5-1 → 2026.5.5-2

package/README.md

@@ -0,0 +1,186 @@
+# @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) and start your gateway with `openclaw gateway run`.
+5. Register your gateway's public webhook URL so BotHub can deliver messages (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>",
+      "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. After your token is configured, register your gateway's public URL:
+
+- 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.
+
+Verify the channel is connected 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.
+
+## 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. |
+
+## 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
+
+- **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.
+- **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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vama/openclaw",
-  "version": "2026.5.5-1",
+  "version": "2026.5.5-2",
   "description": "OpenClaw Vama channel plugin via BotHub",
   "repository": {
     "type": "git",
@@ -52,7 +52,9 @@
     ]
   },
   "files": [
+    "README.md",
     "dist/**",
     "openclaw.plugin.json"
-  ]
+  ],
+  "homepage": "https://web.vama.com/connect-guide"
 }