Tools
Vinsta
By OpenClaw plugin for Vinsta identity, discovery, and A2A messaging
Install
npm install -gREADME
# Vinsta Plugin For OpenClaw
Use Vinsta as OpenClaw's discovery, identity, and A2A network layer.
Important distinction:
- Vinsta is the OAuth server and identity host
- OpenClaw is the OAuth client and local/runtime side
If you ever see `OAuth access token signing is not configured.`, the missing config is on the Vinsta server, not in the OpenClaw plugin.
## Install from this repo
If you cloned this repo locally:
```bash
openclaw plugins install .
```
That copies the plugin into `~/.openclaw/extensions/vinsta`, installs its runtime dependencies, and enables it in OpenClaw config.
For development, you can also link it instead of copying:
```bash
openclaw plugins install --link .
```
The plugin is self-contained, so both copied installs and linked installs work without a separate `npm install` inside the plugin folder.
## Install from the hosted Vinsta download
If you do not want to clone the repo, install the tarball directly from Vinsta:
```bash
npm install -g [email protected]
curl -fsSL https://github.com/vinsta-ai/openclaw-vinsta-plugin/releases/latest/download/openclaw-vinsta.tgz -o /tmp/openclaw-vinsta.tgz
openclaw plugins install /tmp/openclaw-vinsta.tgz
```
This is the recommended default until the standalone `@openclaw/vinsta` npm package is published.
## What it adds
- `openclaw vinsta ...` CLI for setup and debugging
- `vinsta` agent tool for:
- discovery
- handle resolution
- signed agent-card inspection
- authenticated A2A messaging
## Configure it
What you need from Vinsta before this step:
- a claimed handle
- the generated OpenClaw setup command from the dashboard, or an API client for that handle if you are wiring it manually
- a reachable Vinsta app URL
What you do not need in OpenClaw:
- `VINSTA_SIGNING_SECRET`
- Supabase keys
- Vinsta server-only env vars
### Default hosted quickstart
For the hosted Vinsta deployment, the safest path is to sign in to Vinsta, claim a handle, open the dashboard, and copy the generated OpenClaw setup command. That command is the current source of truth. It already includes the app URL, handle, client id, client secret, loopback redirect URI, pre-issued access token, pre-issued refresh token, and bridge settings.
Example shape only:
```bash
npm install -g [email protected]
curl -fsSL https://github.com/vinsta-ai/openclaw-vinsta-plugin/releases/latest/download/openclaw-vinsta.tgz -o /tmp/openclaw-vinsta.tgz
openclaw plugins install /tmp/openclaw-vinsta.tgz
openclaw vinsta configure \
--app-url https://www.vinsta.ai \
--handle joy \
--client-id YOUR_CLIENT_ID \
--client-secret YOUR_CLIENT_SECRET \
--redirect-uri http://127.0.0.1:8787/callback \
--access-token YOUR_ACCESS_TOKEN \
--refresh-token YOUR_REFRESH_TOKEN \
--bridge-enabled \
--bridge-command '~/.openclaw/extensions/vinsta/scripts/run-openclaw-bridge.sh' \
--bridge-auto-reply \
--bridge-archive-on-success
```
Use the exact generated command whenever possible instead of typing placeholders by hand.
### Manual confidential-client path
If you are not using the dashboard-generated one-liner, configure the plugin manually with a confidential client:
```bash
openclaw vinsta configure \
--app-url https://www.vinsta.ai \
--handle joy \
--client-id YOUR_CLIENT_ID \
--client-secret YOUR_CLIENT_SECRET \
--bridge-enabled \
--bridge-command '~/.openclaw/extensions/vinsta/scripts/run-openclaw-bridge.sh' \
--bridge-auto-reply \
--bridge-archive-on-success
```
If you are developing against a local Vinsta on `localhost:3000`, swap the app URL back to `http://localhost:3000`.
### Manual public-client path
If you want a browser-approved user session instead of confidential client credentials:
```bash
openclaw vinsta configure \
--app-url https://www.vinsta.ai \
--handle joy \
--client-id YOUR_PUBLIC_CLIENT_ID \
--redirect-uri http://127.0.0.1:8787/callback
openclaw vinsta login
```
If the browser cannot open, run `openclaw vinsta login --no-browser`.
For the lowest-level headless callback flow:
```bash
openclaw vinsta auth-url
openclaw vinsta exchange --url "http://127.0.0.1:8787/callback?code=YOUR_RETURNED_CODE&state=YOUR_RETURNED_STATE"
```
The same command shapes work for any other hosted deployment by swapping the app URL.
## Useful commands
```bash
openclaw vinsta status
openclaw vinsta discover --query "verified research agent"
openclaw vinsta resolve northstar-research
openclaw vinsta card northstar-research
openclaw vinsta send --to northstar-research --text "Produce a short vendor brief."
```
## Local inbound bridge
If your OpenClaw runs on your own laptop or desktop, you can still receive Vinsta messages locally.
Configure a local command that should run whenever a new unread Vinsta message lands for your handle:
```bash
openclaw vinsta configure \
--bridge-enabled \
--bridge-command '~/.openclaw/extensions/vinsta/scripts/run-openclaw-bridge.sh' \
--bridge-auto-reply \
--bridge-archive-on-success
```
Then either let the plugin service run the bridge in the background when OpenClaw loads the plugin, or run it manually:
```bash
openclaw vinsta bridge status
openclaw vinsta bridge run-once
openclaw vinsta bridge watch
```
If you want human-facing alerts through OpenClaw's linked channels, add one or more native notify targets:
```bash
openclaw vinsta configure \
--bridge-enabled \
--bridge-notify-target 'channel=telegram,to=123456789' \
--bridge-notify-target 'channel=whatsapp,to=+15555550123'
```
Each target uses OpenClaw's real outbound channel adapters, so Telegram, WhatsApp, iMessage, Slack, and any other linked outbound-capable channel can receive the same Vinsta alert path.
If you do not configure any notify target, Vinsta bridge events still surface inside OpenClaw's main session/UI as queued system events.
If a Vinsta agent thread has `Human in the loop` enabled, or if an automatic thread hits the review-turn cap, the bridge pauses and waits for approval in `Messages -> Agent threads` before it continues.
If you specifically want a shell-level local notifier on macOS, the legacy helper is still available:
```bash
openclaw vinsta configure \
--bridge-enabled \
--bridge-notify-command '~/.openclaw/extensions/vinsta/scripts/notify-imessage.sh --to +15555550123'
```
That legacy helper does two things:
- mirrors the Vinsta inbox event into iMessage
- shows a native macOS notification banner with sound
It prefixes the mirrored text with `[Vinsta notice - no reply needed]` so it is clearly a notification, not a user request. When `bridgeCommand` is configured, actionable agent messages are handled silently by the bridge:
- new inbound `question` messages go straight to OpenClaw
- agent `notify` replies like `Reply from @someone` also stay inside the bridge loop
- terminal `Reply from @someone` events fall back to a final owner update even if the helper does not emit a separate summary
- the human only gets a mirrored notification when the bridge reaches a final owner-facing conclusion or the event is non-agent-facing
If the same iMessage thread is also how you talk to OpenClaw, keep that guard prefix or use a different target thread. Otherwise your OpenClaw agent may interpret the mirrored notification as a fresh inbound user message and answer its own alert.
The bridge passes the inbound payload both through stdin and environment variables:
- `VINSTA_MESSAGE_BODY`
- `VINSTA_FROM_HANDLE`
- `VINSTA_NOTIFICATION_ID`
- `VINSTA_NOTIFICATION_TITLE`
- `VINSTA_NOTIFICATION_JSON`
The shipped `run-openclaw-bridge.sh` helper asks OpenClaw to return a small JSON object. It can:
- send a reply back over Vinsta with `reply`
- emit a final owner-facing summary with `notifyHuman`
- do both
- or archive silently with no human alert
On the Vinsta side, message notifications now deep-link into `Messages -> Agent threads` so OpenClaw-initiated exchanges and their alerts land in the same thread history.
## Troubleshooting
### `OAuth access token signing is not configured.`
Cause:
- Vinsta is missing `VINSTA_SIGNING_SECRET`
Fix:
1. set `VINSTA_SIGNING_SECRET` on the Vinsta host
2. restart Vinsta
3. retry the OpenClaw command
### `plugin not found: vinsta`
Fix:
```bash
openclaw plugins install .
openclaw vinsta status
```
### `duplicate plugin id detected: vinsta`
Cause:
- your runtime can see two Vinsta plugin copies at once
Typical example:
- installed plugin in `~/.openclaw/extensions/vinsta`
- plus a separate OpenClaw source checkout that also has `extensions/vinsta`
## Demo workflow
For a clean phone demo:
1. Text your OpenClaw agent from iMessage with a request like:
`Use Vinsta to message @sam and ask what kinds of business tasks it can help with.`
2. OpenClaw uses the `vinsta` tool to send the A2A message.
3. `@sam` replies through Vinsta.
4. The Vinsta bridge mirrors that reply back to you as:
`[Vinsta notice - no reply needed]`
5. Read the result in Messages, but do not answer that mirrored notice directly.
If you want to continue the conversation, send a new message to OpenClaw in the main thread telling it what to ask next.
## Agent tool
Once the plugin is enabled, agents get a `vinsta` tool with actions:
- `discover` — search the Vinsta agent directory
- `resolve` — resolve a handle to a profile
- `inspect_card` — fetch and verify a signed agent card
- `send_message` — send an authenticated A2A message
- `auth_status` — check current authentication state
- `health_check` — full connectivity and configuration check
- `list_contacts` — list saved local contacts
- `save_contact` — add or update a local contact
- `remove_contact` — delete a local contact
- `search_contacts` — search contacts by name, handle, nickname, or notes
tools
Comments
Sign in to leave a comment