@avatarium/openclaw-plugin

OpenClaw channel plugin for Avatarium - video call your AI avatar.

Overview

This plugin enables two integration modes:

1. OpenClaw → Avatar: Send messages from OpenClaw to your Avatarium avatar
2. Avatar → OpenClaw (External Brain): Your avatar uses OpenClaw as its AI brain

Installation

In OpenClaw

openclaw plugins install @avatarium/openclaw-plugin

Or link locally:

openclaw plugins install ./path/to/avatarium/packages/openclaw-plugin

Configuration

Option 1: OpenClaw as a Channel (Send to Avatar)

Add to your OpenClaw config:

// openclaw.config.ts
export default {
  channels: {
    avatarium: {
      enabled: true,
      shortId: "your-avatar-short-id",  // From avatarium.ai dashboard
      apiUrl: "https://api.avatarium.ai",
    },
  },
};

Then send messages:

openclaw message send --channel avatarium "Hello, avatar!"

Option 2: Avatar Uses OpenClaw Brain (Video Call Mode) 🎥

This is the "video call your AI bot" setup. Your avatar becomes a visual frontend for OpenClaw.

Step 1: Create Avatar with External Brain

1. Go to dashboard.avatarium.ai
2. Create or edit an avatar
3. In Settings → External Brain:
   • Enable "External Brain Mode"
   • URL: https://your-openclaw-gateway.com/api/brain
   • Token: Your OpenClaw API token (optional)

Step 2: Set Up OpenClaw Brain Endpoint

Add this to your OpenClaw config to expose a brain endpoint:

// openclaw.config.ts
export default {
  api: {
    enabled: true,
    endpoints: {
      brain: {
        enabled: true,
        path: "/api/brain",
        // Optional: restrict to specific avatar IPs/tokens
      },
    },
  },
};

Or use the built-in sessions API:

// The avatar can POST to:
// POST /api/sessions/send
// { "message": "user's question", "sessionKey": "avatar-session" }

Step 3: Test the Flow

1. Open your avatar's consumer page: https://avatarium.ai/a/your-short-id
2. Speak to the avatar
3. Avatar sends your message to OpenClaw
4. OpenClaw responds
5. Avatar speaks the response

How It Works

┌─────────────────────────────────────────────────────────────┐
│                    Video Call Flow                          │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  User speaks    Avatar STT    External Brain    Avatar TTS  │
│      │              │              │                │       │
│      ▼              ▼              ▼                ▼       │
│  ┌──────┐      ┌──────┐      ┌──────────┐      ┌──────┐    │
│  │ 🎤   │ ───► │ 📝   │ ───► │ OpenClaw │ ───► │ 🔊   │    │
│  │ Mic  │      │ STT  │      │  Brain   │      │ TTS  │    │
│  └──────┘      └──────┘      └──────────┘      └──────┘    │
│                                                             │
│  Browser              Avatarium API           Browser       │
└─────────────────────────────────────────────────────────────┘

Avatar Configuration

For the External Brain to work, your avatar needs these fields set:

| Field | Description | |-------|-------------| | externalBrainEnabled | true to use external brain | | externalBrainUrl | OpenClaw endpoint URL | | externalBrainToken | Auth token (optional) |

These can be set in the Avatarium dashboard under Avatar Settings.

API Reference

External Brain Request (Avatar → OpenClaw)

POST /api/brain
Content-Type: application/json

{
  "message": "What's the weather like?",
  "history": [
    { "role": "user", "content": "Hi" },
    { "role": "assistant", "content": "Hello! How can I help?" }
  ],
  "context": {
    "avatarName": "Luna",
    "systemPrompt": "You are a helpful assistant"
  }
}

External Brain Response

{
  "response": "I don't have real-time weather data, but I can help you find a weather service!"
}

Channel Send (OpenClaw → Avatar)

POST https://api.avatarium.ai/v1/public/avatar/{shortId}/chat
Content-Type: application/json

{
  "message": "Hello from OpenClaw!"
}

Development

# Install dependencies
pnpm install

# Build
pnpm build

# Watch mode
pnpm dev

# Type check
pnpm typecheck

Troubleshooting

Avatar not responding

1. Check External Brain is enabled in avatar settings
2. Verify the OpenClaw endpoint URL is correct
3. Check OpenClaw logs for incoming requests

CORS errors

If testing locally, ensure OpenClaw allows requests from avatarium.ai:

api: {
  cors: {
    origins: ["https://avatarium.ai", "https://dashboard.avatarium.ai"],
  },
}

Authentication errors

If using a token, ensure it matches between avatar config and OpenClaw.

License

MIT