npm package: @maxesisn-openclaw/onebot11
Description: OpenClaw OneBot v11 channel plugin (Reverse WebSocket, DM-only)
Latest version: 0.1.2

# @maxesisn-openclaw/onebot11

A minimal, **DM-only** OneBot v11 channel plugin for OpenClaw (Reverse WebSocket).

This project intentionally focuses on the “small & safe by default” subset:
- **Reverse WS** (OneBot v11-compatible client connects as client)
- **Private messages only** (no groups)
- Token auth (`Authorization: Bearer ...`)
- Quote/reply support (fetch original via `get_msg` and include in context)
- Inbound images (attach up to N URLs to context)
- Outbound: split long text + light markdown downgrade

If you need **group chats / commands / triggers / broader QQ features**, use a more feature-complete integration such as community projects like `openclaw_qq`.

## Scope (by design)

- ✅ OneBot v11 **Reverse WebSocket**
- ✅ **DM-only** (private messages)
- ✅ Token auth (Bearer)
- ✅ Multi-account (configure multiple OpenClaw channel accounts; typically use different ports)
- ✅ Inbound images (attach up to N URLs to context)
- ✅ Reply/quote support (fetch original via `get_msg` and include in context)
- ✅ Outbound: split long text + light markdown downgrade
- ✅ Outbound images via `base64://` (file:// gets converted)

- ❌ Group chats / trigger modes / guilds / admin commands (intentionally out of scope)

## Installation

### Option A: install from npm (recommended)

```bash
openclaw plugins install @maxesisn-openclaw/onebot11
openclaw gateway restart
```

### Option B: local development

Clone this repo on the OpenClaw host, then install it from the local path (or link it) while iterating.

### Publishing (maintainers)

This package is published to npm as `@maxesisn-openclaw/onebot11`.

```bash
npm publish --access public
```

## Configuration

Add to your OpenClaw config under `channels.onebot11`.

Example (single account):

```json5
{
  channels: {
    onebot11: {
      enabled: true,
      listenHost: "0.0.0.0",
      listenPort: 3002,
      wsPath: "/onebot/v11/ws",
      accessToken: "<YOUR_TOKEN>",


      includeReplyOriginal: true,
      replyMaxChars: 1200,

      maxMessageLength: 3500,
      rateLimitMs: 800,
      markdownToText: true,
      sendReplySegment: false,

      maxInboundImages: 3
    }
  }
}
```

Multi-account example (two ports):

```json5
{
  channels: {
    onebot11: {
      enabled: true,
      // default account
      listenPort: 3002,
      accessToken: "token-a",
      accounts: {
        work: {
          name: "Work QQ",
          listenPort: 3003,
          accessToken: "token-b"
        }
      }
    }
  }
}
```

## Reverse WS client configuration

Configure your OneBot v11 client (Reverse WebSocket / Universal) to connect:

- URL: `ws://<openclaw-host>:3002/onebot/v11/ws`
- Headers/Auth: `Authorization: Bearer <YOUR_TOKEN>`

(Exact UI names vary by client implementation.)

## Slash commands (/status, /model, ...)

Text slash commands are handled by the OpenClaw Gateway and require the sender to be authorized.

Make sure your `channels.onebot11.allowFrom` includes your user id (either plain or channel-prefixed):

```json5
{
  channels: {
    onebot11: {
      allowFrom: ["onebot11:1763471048", "1763471048"]
    }
  }
}
```

## Debug logging

Set `ONEBOT11_DEBUG=1` in the gateway environment to enable extra OneBot11 plugin logs.

## Notes

- This plugin expects OneBot messages preferably in **array segment format**.
- If your OneBot implementation does not provide direct image URLs, you may need to enable that in the protocol-side settings.

## License

MIT