Skip to main content

​
OneBot

This is a shipped plugin-backed bridge surface. Loong owns the stable OneBot-facing channel contract, but the active websocket listener and upstream bridge runtime stay external.

​
At A Glance

FieldValue
Catalog idonebot
Config keyonebot
Implementation statusplugin_backed
Transportonebot_v11_bridge
Aliasesonebot-v11, napcat, llonebot
Default send target kindconversation
Runtime ownerexternal plugin

​
Minimal Config

[onebot]
enabled = true
websocket_url_env = "ONEBOT_WEBSOCKET_URL"
access_token_env = "ONEBOT_ACCESS_TOKEN"
allowed_group_ids = ["123456789"]
Optional explicit selection when several compatible managed bridges are installed: 
[onebot]
enabled = true
managed_bridge_plugin_id = "onebot-managed-bridge"
websocket_url_env = "ONEBOT_WEBSOCKET_URL"
access_token_env = "ONEBOT_ACCESS_TOKEN"
allowed_group_ids = ["123456789"]

​
Smoke Test

loong channels
loong channels --json
loong doctor
What success looks like:
  • OneBot [onebot] appears in the plugin-backed section
  • discovery keeps the selected compatible bridge visible when one exists
  • doctor reports a bridge-ready contract instead of falling back to generic channel-placeholder wording

​
Current Command Surface

OperationCurrent pathUsage or status
managed bridge contract checkloong doctorcurrent readiness and remediation surface
inventory + discovery inspectionloong channelscurrent operator inventory surface
bridge-backed sendchannels send onebotexecutes through the selected managed bridge runtime; target contract stays onebot:<account>:private:<user_id> or onebot:<account>:group:<group_id>
bridge-backed servechannels serve onebotstarts the selected managed bridge reply loop; upstream event-loop ownership still stays in the external bridge

​
Required Fields For Bridge Send Contract

RequirementConfig pathsEnv pointer pathsDefault env
channel enabledonebot.enabled
onebot.accounts.<account>.enabled		nonenone
onebot websocket urlonebot.websocket_url
onebot.accounts.<account>.websocket_url		onebot.websocket_url_env
onebot.accounts.<account>.websocket_url_env		ONEBOT_WEBSOCKET_URL
onebot access tokenonebot.access_token
onebot.accounts.<account>.access_token		onebot.access_token_env
onebot.accounts.<account>.access_token_env		ONEBOT_ACCESS_TOKEN

​
Required Fields For Bridge Event Contract

RequirementConfig pathsEnv pointer pathsDefault env
channel enabledonebot.enabled
onebot.accounts.<account>.enabled		nonenone
onebot websocket urlonebot.websocket_url
onebot.accounts.<account>.websocket_url		onebot.websocket_url_env
onebot.accounts.<account>.websocket_url_env		ONEBOT_WEBSOCKET_URL
onebot access tokenonebot.access_token
onebot.accounts.<account>.access_token		onebot.access_token_env
onebot.accounts.<account>.access_token_env		ONEBOT_ACCESS_TOKEN
allowed group idsonebot.allowed_group_ids
onebot.accounts.<account>.allowed_group_ids		nonenone

​
Stable Target Templates

TargetMeaning
onebot:<account>:private:<user_id>private conversation user id
onebot:<account>:group:<group_id>group conversation id

​
Account Scope Note

Keep <account> stable so personal-account bridge routes stay unambiguous across bridge replacements or reconnects.

​
Managed Bridge Discovery Notes

  • OneBot is the right Loong surface when the upstream bridge already speaks OneBot v11 and you want a stable protocol contract inside Loong.
  • Managed bridge execution also requires [runtime_plugins].enabled = true plus one or more runtime_plugins.roots.
  • Discovery ambiguity should be resolved explicitly with managed_bridge_plugin_id rather than by relying on whichever plugin happens to be found first.
  • Bridge setup docs and missing-field guidance flow through loong doctor when the compatible plugin advertises them.

​
Gateway And Ownership

This surface does not join gateway run or gateway run today. The upstream OneBot-compatible bridge remains the runtime owner.

​
Operator Notes

  • Keep allowed_group_ids explicit.
  • Loong validates allowed_group_ids locally before forwarding a managed bridge group send, so disallowed groups fail before the external bridge sees the request.
  • channels serve onebot retries transient managed bridge runtime failures with bounded backoff; repeated failures still terminate loudly so the upstream bridge can be checked.
  • channels serve onebot --stop requests a cooperative shutdown for the currently selected managed bridge runtime owner.
  • When duplicate runtime owners appear, Loong automatically keeps the preferred live runtime owner and requests cooperative shutdown for the older duplicates when the winner is clear.
  • channels serve onebot --stop-duplicates remains the operator fallback when duplicate runtime owners persist and you want Loong to keep the preferred live runtime owner while draining the others.
  • While it is retrying, loong doctor and loong channels surface the current failure count and last bridge error.
  • Treat the OneBot websocket URL as part of the trust boundary; do not point it at a vague shared relay unless you intend to widen that boundary.
  • Prefer stable account ids before layering more than one bridge identity into the same config.
  • Continue to QQ Bot for the Tencent official-bot lane.
  • Continue to Weixin for the ClawBot / iLink-style WeChat lane.
  • Continue to Channel Setup for the shared public setup contract.