open-index/open-npm huggingface dataset:
npm package: @spikelabs/lobster-shell-plugin
Description: Connect your OpenClaw agent to Lobster Shell cloud
Latest version: 0.3.8

# @spikelabs/lobster-shell-plugin

Connect your OpenClaw agent to [Lobster Shell](https://www.lobstershell.ai) — give your bot a face, voice, and video presence.

## Install

```bash
npm install @spikelabs/lobster-shell-plugin
```

OpenClaw discovers the plugin automatically via its `openclaw.plugin.json` manifest.

## Setup

1. Start your OpenClaw gateway
2. Visit **http://localhost:18789/lobster/setup** in your browser
3. Click **Connect to Lobster Shell**
4. Sign in (or create an account) on lobstershell.ai
5. You'll be redirected back — the setup page should show "Connected!"

No API keys needed. The plugin uses OAuth 2.1 with PKCE to securely link your gateway to your Lobster Shell account.

## How it works

Once connected, the plugin:

- **Relays messages** between your OpenClaw agent and the Lobster Shell avatar renderer via an Ably real-time bridge
- **Publishes events** (`message_received`, `agent_thinking`, `agent_response`) so the avatar reacts in real time
- **Supports Shell Live** — real-time voice/video conversations through LiveKit

## Configuration

The plugin works with zero configuration. Optional settings:

| Variable | Default | Description |
|---|---|---|
| `OPENCLAW_GATEWAY_TOKEN` | `dev-token-1234` | Gateway WebSocket auth token (set this if you changed the default) |

You can also override the cloud URL via the plugin config in OpenClaw if you're running a custom Lobster Shell instance:

```json
{
  "pluginConfig": {
    "lobster-shell": {
      "cloudUrl": "https://your-custom-instance.com"
    }
  }
}
```

## Diagnostics

Use the `/lobster-status` command in your OpenClaw chat to check connection status:

```
/lobster-status
```

This shows plugin version, gateway port, cloud bridge status, and channel info.

## Development

```bash
pnpm install
pnpm build          # Build once
pnpm dev            # Watch mode
pnpm lint           # Type-check
```

To test with a local OpenClaw Docker container, copy the built plugin:

```bash
pnpm build
cp dist/* .openclaw-dev/config/extensions/lobster-shell/dist/
docker compose restart
```

## License

MIT