koishi-plugin-server-onebot

A lightweight OneBot v11 server implementation for Koishi.

This project is under active development.

Use adapter-satori + server-onebot + server-satori to call functions across Koishi instances.

• Koishi A enables adapter-satori and server-onebot; the OneBot client connects to A.
• Koishi B enables server-satori; A's adapter-satori connects to B's server-satori.

Result: Koishi B can call all functions exposed by the OneBot client as if the client were connected directly to Koishi B.

Message format conversion

The plugin converts messages between Satori and OneBot formats.

Satori to OneBot

[
  { type: 'text', attrs: { content: 'Hello ' } },
  { type: 'at', attrs: { id: '123456', name: 'user' } },
  { type: 'image', attrs: { src: 'https://example.com/image.jpg' } }
]


[
  { type: 'text', data: { text: 'Hello ' } },
  { type: 'at', data: { qq: '123456', name: 'user' } },
  { type: 'image', data: { file: 'https://example.com/image.jpg' } }
]

OneBot to Satori

[
  { type: 'text', data: { text: 'Hello ' } },
  { type: 'at', data: { qq: 'all' } },
  { type: 'face', data: { id: '123' } }
]


[
  h.text('Hello '),
  h('at', { type: 'all' }),
  h('face', { id: '123' })
]

License

MIT

Extending OneBot actions

When enabled, server-onebot is a complete OneBot v11 implementation. It starts the configured WebSocket server and/or reverse WebSocket clients, registers built-in actions, converts Koishi events into OneBot events, and dispatches incoming OneBot requests.

The implementation is exposed as the onebot Koishi service. Other plugins can inject it and add protocol extensions:

import { Context } from 'koishi'
import { OneBotActionError } from 'koishi-plugin-server-onebot'

export const inject = {
  required: ['onebot'],
}

export function apply(ctx: Context) {
  ctx.onebot.registerAction('get_custom_status', async (params, client, request) => {
    return {
      self_id: request?.endpoint.selfId,
      status: 'ready',
    }
  })

  ctx.onebot.useAction('get_group_info', async (request, next) => {
    const response = await next()
    if (response.status === 'failed') {
      throw new OneBotActionError('group info is unavailable', 1404)
    }
    return response
  })
}

registerAction() returns an unregister function. Existing actions are protected by default; pass { override: true } only when intentionally replacing a built-in action. invoke() uses the same action registry without WebSocket transport:

const status = await ctx.onebot.invoke('get_custom_status')

Forward WebSocket connections and reverse WebSocket connections use the same action registry and dispatcher. Handlers receive the original request, connection state, and endpoint metadata.