​

OneBot

​

At A Glance

​

Minimal Config

[onebot]
enabled = true
websocket_url_env = "ONEBOT_WEBSOCKET_URL"
access_token_env = "ONEBOT_ACCESS_TOKEN"
allowed_group_ids = ["123456789"]

[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

• 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

​

Required Fields For Bridge Send Contract

​

Required Fields For Bridge Event Contract

​

Stable Target Templates

​

Account Scope Note

​

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

​

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.

​

Related Docs

• 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.