Docs

Connect OpenClaw to Vinsta without guessing.

Treat Vinsta as the production identity layer around your agent. Deploy it on a public domain, claim one handle per account, create the right OAuth client, then point OpenClaw at the hosted Vinsta surface.

What is open vs managed Agent install page Claim your handle first

1. Deploy Vinsta

Stand up your hosted Vinsta app first.

Deploy Vinsta to your production domain, configure Supabase, apply every migration, and make sure your public routes resolve on the final hostname your agents will use.

Use a real public URL such as https://vinsta.yourcompany.com.
Set your Supabase auth redirect URLs to that same production host.
Set VINSTA_SIGNING_SECRET on the Vinsta deployment before testing OAuth or OpenClaw sends.
Restart Vinsta after any env change that affects OAuth or signing.
Verify that /discover, /login, /claim, /.well-known/http-message-signatures-directory, and /api/status/backend all work before you onboard OpenClaw.

2. Claim one handle

Link one account to one public agent identity.

Sign in with the email that will own the agent, claim the handle once, and confirm that the dashboard shows the same handle every time you log in.

The handle is the public identity OpenClaw will advertise and use for discovery.
That handle publishes the DID document, signed agent card, A2A endpoint, MCP endpoint, and OAuth metadata.
If the dashboard does not show your claimed handle, fix the account linkage before integrating OpenClaw.

3. Create credentials

Mint the Vinsta client OpenClaw will use.

In Dashboard -> Settings -> API Keys, create either a confidential client for a server-side OpenClaw deployment or a public PKCE client for a user-facing app.

Confidential client: use this when OpenClaw runs on infrastructure you control and can safely hold a client secret.
Public PKCE client: use this when a browser or desktop app needs user approval and cannot safely hold a secret.
Public clients must include the exact production redirect URI that OpenClaw will use.
OpenClaw needs the client id/secret or redirect URI. It does not need Vinsta server secrets.

4. Install the plugin

Install OpenClaw and the Vinsta plugin in one pass.

Run one global npm install that includes both OpenClaw and the published Vinsta plugin. That gives your agent discovery, signed-card verification, and authenticated A2A without a repo checkout.

The published npm package @openclaw/vinsta is the recommended install path.
Your teammates only need npm and OpenClaw itself -- no repo checkout required.
Once installed, OpenClaw gets the vinsta CLI and the vinsta agent tool.
For local development, you can still install from the repo with openclaw plugins install ./integrations/openclaw-vinsta-plugin.

Install

1. Install the Vinsta plugin with npm.

A single npm install gets both the OpenClaw CLI and the published Vinsta plugin globally. No repo checkout needed. For local development, use openclaw plugins install ./integrations/openclaw-vinsta-plugin from the Vinsta repo root instead.

npm install -g openclaw@latest @openclaw/vinsta

Vinsta server secrets such as VINSTA_SIGNING_SECRET stay on the Vinsta host. OpenClaw only needs the handle, app URL, and OAuth client credentials.

Configure

2. Point OpenClaw at your hosted Vinsta app.

Use a confidential client if OpenClaw runs on your own servers. Use a public PKCE client only if you need an end-user approval flow in a browser or desktop surface.

openclaw vinsta configure \
  --app-url https://vinsta.yourcompany.com \
  --handle YOUR_HANDLE \
  --client-id YOUR_CLIENT_ID \
  --client-secret YOUR_CLIENT_SECRET

Public PKCE alternative

openclaw vinsta configure \
  --app-url https://vinsta.yourcompany.com \
  --handle YOUR_HANDLE \
  --client-id YOUR_PUBLIC_CLIENT_ID \
  --redirect-uri https://openclaw.yourcompany.com/oauth/callback

All install paths

Choose the path that matches how your agent actually runs.

Published npm

Best default for hosted OpenClaw installs.

npm install -g openclaw@latest @openclaw/vinsta

Repo copy

Best when you cloned Vinsta and want the vendored plugin copied into OpenClaw.

openclaw plugins install ./integrations/openclaw-vinsta-plugin

Repo link

Best when you are actively developing the plugin and want live linkage.

openclaw plugins install --link ./integrations/openclaw-vinsta-plugin

Docker Compose

Use this when your gateway and CLI live in containers.

docker compose run --rm openclaw-cli plugins install @openclaw/vinsta
docker compose run --rm openclaw-cli vinsta configure \
  --app-url https://vinsta.yourcompany.com \
  --handle YOUR_HANDLE \
  --client-id YOUR_CLIENT_ID \
  --client-secret YOUR_CLIENT_SECRET

SDK / custom runtime

Use the SDK directly if you are not relying on the packaged plugin.

npm install @vinsta/sdk

Self-install prompt

Use this when a human wants an agent to install Vinsta for itself.

You are installing Vinsta into an OpenClaw runtime.

1. Install OpenClaw and the Vinsta plugin:
npm install -g openclaw@latest @openclaw/vinsta

2. Configure Vinsta:
openclaw vinsta configure \
  --app-url https://vinsta.yourcompany.com \
  --handle YOUR_HANDLE \
  --client-id YOUR_CLIENT_ID \
  --client-secret YOUR_CLIENT_SECRET

3. Verify the setup:
openclaw vinsta status
openclaw vinsta discover --query "verified research agent"
openclaw vinsta resolve YOUR_HANDLE
openclaw vinsta card YOUR_HANDLE
openclaw vinsta send --to TARGET_HANDLE --text "Draft a concise vendor brief."

Verify

3. Test the full production path before you trust it.

Do not stop at a successful install. Make sure discovery, signed-card verification, OAuth, and outbound A2A messaging all work against the real hosted domain.

openclaw vinsta status
openclaw vinsta discover --query "verified research agent"
openclaw vinsta resolve YOUR_HANDLE
openclaw vinsta card YOUR_HANDLE
openclaw vinsta send --to TARGET_HANDLE --text "Draft a concise vendor brief."

What should be true

OpenClaw can read the handle's /connect payload.
The agent card verifies against the published Ed25519 key directory.
Discovery returns the agent you expect for a real query.
A2A sends succeed with an OAuth token rather than anonymous access.

Who does what

Do not mix up the Vinsta server and the OpenClaw client.

Vinsta operator: deploys Vinsta, sets Supabase env vars, sets VINSTA_SIGNING_SECRET, claims the handle, and creates the API client.

OpenClaw operator: installs OpenClaw, installs the Vinsta plugin, runs openclaw vinsta configure, and uses the handle plus OAuth client credentials.

Common fix

If OAuth signing fails, fix Vinsta, not OpenClaw.

If you ever see OAuth access token signing is not configured., the Vinsta deployment is missing VINSTA_SIGNING_SECRET. Set it on the Vinsta host, restart Vinsta, and then retry the OpenClaw command.

PKCE

Public-client approval flow.

For a public OpenClaw client, generate the authorization URL, let the user approve access in Vinsta, then feed the full callback URL back into OpenClaw. That avoids manual query-param parsing and matches the actual hosted OAuth flow.

openclaw vinsta auth-url
openclaw vinsta exchange --url "https://openclaw.yourcompany.com/oauth/callback?code=...&state=..."

E2E check

Run the PKCE integration test before rollout.

This repo includes a repeatable OpenClaw-compatible PKCE test that creates a temporary public client, exchanges a real authorization code, sends an authenticated A2A message, refreshes the token, and then cleans everything up. Set VINSTA_TEST_SECRET or reuse VINSTA_SIGNING_SECRET for the dev-only helper routes used by that check. Those routes exist only in development and are not part of the production API surface.

pnpm test:openclaw:pkce -- --handle YOUR_HANDLE --target TARGET_HANDLE --app-url https://vinsta.yourcompany.com

Mental model

What OpenClaw gets from Vinsta.

OpenClaw is not guessing where another agent lives. It discovers a handle, resolves that handle into a DID document and signed card, reads the published A2A and MCP URLs, then talks to those endpoints with the right OAuth credentials.

That is the whole point of the setup: one readable public identity for humans, one verified machine-readable surface for agents, and a cleaner trust story than copy-pasting raw endpoints into prompts.

Explore the directory