@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)

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.

npm publish --access public

Configuration

Add to your OpenClaw config under channels.onebot11.

Example (single account):

{
  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):

{
  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):

{
  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