Zhin.js

English

简体中文

English

简体中文

Appearance

Documentation Sync

This page is auto-generated from plugins/adapters/onebot12/README.md. Please edit the in-package README and then run pnpm sync:adapter-docs.

@zhin.js/adapter-onebot12 ​

Zhin.js OneBot 12 adapter (Plugin Runtime). Default is forward WebSocket client (connection: ws); also supports HTTP Webhook and reverse WS (routes registered via httpHostToken).

Features ​

  • OneBot 12 Standard compatible (events + actions)
  • Convention-based defineAdapter / definePlugin (no usePlugin needed)
  • Forward WebSocket (connection: ws): the application connects to the OneBot implementation's WS server
  • access_token authentication (Bearer + query)
  • Inbound via messageGatewayToken; outbound send({ target, payload })

Installation ​

bash
pnpm add @zhin.js/adapter-onebot12

Plugin Runtime ​

  • @zhin.js/adapter — convention-based adapters/onebot12.ts (defineAdapter)
  • @zhin.js/core — messageGatewayToken inbound/outbound
  • @zhin.js/plugin-runtime — plugin.ts (definePlugin)
  • Configuration goes to plugins.<instanceKey> via the plugin's schema.json

Inbound: gateway.receive({ adapter, target: "private:uid"| "group:gid"|..., content, sender, metadata }) Outbound: send({ target, payload }) -> WS send_message (payload is rendered by gateway/core; no segment-mapper)

Minimal Configuration ​

yaml
# zhin.config.yml (Plugin Runtime)
plugins:
  onebot12:
    connection: ws
    reconnect_interval: 5000
    heartbeat_interval: 30000
    endpoints:
      - name: ob12-bot
        url: "ws://127.0.0.1:6700"
        access_token: "${ONEBOT12_ACCESS_TOKEN}"

The root plugin zhin.plugins (or project graph) must reference @zhin.js/adapter-onebot12 (instanceKey: onebot12).

Connection Modes ​

connectionStatus
wsImplemented (recommended)
webhookImplemented: POST inbound + api_url HTTP outbound
wssImplemented: reverse WS (httpHostToken)

Authentication ​

  • Bearer: Authorization: Bearer <access_token>
  • Forward WS attaches request headers during Upgrade and includes access_token in the URL query

Actions and Events ​

  • Events: type (meta/message/notice/request), detail_type, message, etc. See Events.
  • Actions: send_message, delete_message, get_status, etc. See Action Requests.

AI Tools ​

See agent/skills/onebot12.md for skill documentation.

License ​

MIT License