@alter-ai/openclaw-plugin

Alter Vault OAuth integration plugin for OpenClaw. Gives your AI agent secure access to Gmail, GitHub, Slack, Google Calendar, Microsoft, and more — tokens are managed automatically and never exposed to the LLM.

Built as a thin tool layer on top of @alter-ai/alter-sdk (the Alter Vault TypeScript SDK). The plugin re-exports AlterVault and the SDK error classes for direct use. Requires Node.js >= 18.0.0.

Installation

openclaw plugins install @alter-ai/openclaw-plugin

Configuration

Set your Alter credentials in the OpenClaw config file (~/.openclaw/openclaw.json):

{
  "plugins": {
    "entries": {
      "alter-vault": {
        "enabled": true,
        "config": {
          "apiKey": "alter_key_...",
          "appId": "your-app-uuid",
          "attributes": {
            "user_id": "user_123"
          }
        }
      }
    }
  }
}

Or set individual values via the CLI:

openclaw config set plugins.entries.alter-vault.config.apiKey "alter_key_..."
openclaw config set plugins.entries.alter-vault.config.appId "your-app-uuid"

| Option | Required | Description | |--------|----------|-------------| | apiKey | Yes | Your Alter API key (alter_key_...) | | appId | Yes | Your Alter app UUID | | baseUrl | No | Alter backend URL (default: https://api.alter.com) | | attributes | No | Default user attributes for connection matching | | endUserId | No | End-user identifier for token scoping | | timeout | No | Request timeout in milliseconds (default: 30000) |

Tools

The plugin registers three tools for the OpenClaw agent:

alter_connections — List connected services

Check which OAuth services are available before making API calls.

{ "tool": "alter_connections" }

Filter by provider:

{ "tool": "alter_connections", "provider": "google" }

alter_api — Make authenticated API calls

Call any external API with automatic OAuth token injection. The agent never sees the token.

{
  "tool": "alter_api",
  "provider": "google",
  "method": "GET",
  "url": "https://www.googleapis.com/gmail/v1/users/me/messages",
  "query_params": "{\"maxResults\": \"10\"}",
  "reason": "List recent emails"
}

alter_connect — Connect a new service

Generate an OAuth link when the user needs to connect a new provider.

{ "tool": "alter_connect", "providers": "github" }

How It Works

OpenClaw Agent                    Alter Vault                   External API
     │                                │                              │
     │  1. alter_api(google, GET, url)│                              │
     │ ──────────────────────────────>│                              │
     │                                │  2. POST /oauth/token        │
     │                                │     (get fresh token)        │
     │                                │                              │
     │                                │  3. GET url                  │
     │                                │     Authorization: Bearer... │
     │                                │ ────────────────────────────>│
     │                                │                              │
     │                                │  4. Response data            │
     │                                │ <────────────────────────────│
     │  5. { status, body }           │                              │
     │ <──────────────────────────────│                              │
     │                                │                              │
     │  (token never returned to LLM) │                              │

Security: The plugin delegates all token management to AlterVault from @alter-ai/alter-sdk, which uses a dual-client architecture — one HTTP client talks to the Alter backend (with your API key), a separate client talks to external APIs (with only the OAuth token). Your API key is never sent to external services.

Common Recipes

Gmail — List recent messages

{
  "tool": "alter_api",
  "provider": "google",
  "method": "GET",
  "url": "https://www.googleapis.com/gmail/v1/users/me/messages",
  "query_params": "{\"maxResults\": \"10\"}"
}

GitHub — List repositories

{
  "tool": "alter_api",
  "provider": "github",
  "method": "GET",
  "url": "https://api.github.com/user/repos",
  "query_params": "{\"sort\": \"updated\", \"per_page\": \"10\"}"
}

Slack — Send a message

{
  "tool": "alter_api",
  "provider": "slack",
  "method": "POST",
  "url": "https://slack.com/api/chat.postMessage",
  "body": "{\"channel\": \"C01234567\", \"text\": \"Hello from OpenClaw!\"}"
}

Google Calendar — List upcoming events

{
  "tool": "alter_api",
  "provider": "google",
  "method": "GET",
  "url": "https://www.googleapis.com/calendar/v3/calendars/primary/events",
  "query_params": "{\"timeMin\": \"2024-01-01T00:00:00Z\", \"maxResults\": \"10\", \"singleEvents\": \"true\", \"orderBy\": \"startTime\"}"
}

Microsoft — List recent emails (Outlook)

{
  "tool": "alter_api",
  "provider": "microsoft",
  "method": "GET",
  "url": "https://graph.microsoft.com/v1.0/me/messages",
  "query_params": "{\"$top\": \"10\", \"$orderby\": \"receivedDateTime desc\"}"
}

Bundled Skill

The package includes a skill/SKILL.md file with API recipes that OpenClaw can use as context. See the SKILL.md for the full list.

Prerequisites

You need an Alter Vault account with:

1. An app created in the Developer Portal
2. An API key for that app
3. At least one OAuth provider configured (Google, GitHub, Slack, etc.)
4. A connected account (via Alter Connect or the alter_connect tool)

Documentation

• Full integration guide
• Alter Vault docs
• OpenClaw

License

MIT