@maxesisn/openclaw-channel-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

$3

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

$3

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

$3

This package is published to npm as @maxesisn/openclaw-channel-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: "",


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://:3002/onebot/v11/ws
- Headers/Auth: Authorization: Bearer

(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