npm package: @soundwisdomai/clawdbot-nex-bridge
Description: NEX Bridge channel plugin for OpenClaw - Mobile AI Agent management via Tether
Latest version: 0.2.1

# clawdbot-ngx-bridge

NGX Bridge channel plugin for Clawdbot - Connect your local AI agent to Tether mobile app for remote management.

## Quick Start (One Command Setup)

```bash
cd clawdbot-ngx-bridge
npm install
npm run setup
```

The setup script will:
1. Ask for your API Key (from Tether mobile app)
2. Automatically configure Clawdbot
3. Build the plugin

Then just run:
```bash
clawdbot gateway start
```

That's it! Open Tether app and start chatting with your local AI agent.

---

## Overview

This plugin enables bi-directional communication between your local Clawdbot AI agent and the Tether mobile app through the NGX cloud server. Users can send messages from their mobile devices and receive AI responses in real-time with streaming support.

```
Mobile App <--> Tether Cloud Server <--> clawdbot-ngx-bridge <--> Clawdbot AI Agent
```

## Installation

### Local Installation (Recommended for Development)

1. Clone or copy this directory to your machine
2. Install dependencies:
   ```bash
   cd clawdbot-ngx-bridge
   npm install
   npm run build
   ```

3. Add to your Clawdbot config (`~/.config/clawdbot/config.json5`):
   ```json5
   {
     plugins: {
       load: {
         paths: ["/path/to/clawdbot-ngx-bridge"]
       }
     },
     channels: {
       ngx: {
         enabled: true,
         apiKey: "gw_xxxxxxxxxxxx"  // Get this from Tether app
       }
     }
   }
   ```

### NPM Installation (When Published)

```bash
clawdbot plugin install @anthropic/clawdbot-ngx-bridge
```

## Configuration

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `enabled` | boolean | `true` | Enable/disable the NGX channel |
| `apiKey` | string | **required** | Gateway API key from Tether mobile app |
| `serverUrl` | string | `wss://china.swgameai.com/ws` | WebSocket server URL |
| `reconnectInterval` | number | `5000` | Reconnect interval in ms |
| `heartbeatInterval` | number | `30000` | Heartbeat interval in ms |
| `dmPolicy` | string | `"open"` | DM access policy: `open`, `pairing`, `allowlist` |
| `allowFrom` | string[] | `[]` | Allowed user IDs (when dmPolicy is allowlist) |
| `textChunkLimit` | number | `4000` | Max characters per message chunk |

### Getting Your API Key

1. Open the Tether mobile app
2. Go to **Settings** > **Gateway**
3. Create a new gateway or select existing one
4. Copy the **API Key** (starts with `gw_`)

## Usage

Once configured, start the Clawdbot gateway:

```bash
clawdbot gateway start
```

The plugin will:
1. Connect to the NGX cloud server
2. Authenticate with your API key
3. Listen for messages from your mobile app
4. Route messages to your configured AI agent
5. Stream responses back to the mobile app

## Features

- **Auto-reconnect**: Automatically reconnects on connection loss
- **Heartbeat**: Keeps connection alive with periodic pings
- **Streaming**: Real-time streaming of AI responses to mobile
- **Full integration**: Works with Clawdbot's routing, sessions, and agents

## Development

```bash
# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run dev

# Clean
npm run clean
```

## WebSocket Protocol

The plugin communicates with the server using JSON messages:

| Direction | Type | Description |
|-----------|------|-------------|
| C→S | `auth` | Authentication with API key |
| S→C | `auth.success` | Authentication successful |
| S→C | `message.send` | Message from mobile app |
| C→S | `message.reply` | Reply to message |
| C→S | `message.stream.start` | Start streaming response |
| C→S | `message.stream.chunk` | Stream chunk |
| C→S | `message.stream.end` | End streaming |
| C↔S | `ping`/`pong` | Heartbeat |

## License

MIT