Skip to main content

​
Weixin

This is a shipped plugin-backed bridge surface. The channel contract is real and operator-visible, and Loong now ships a QR bootstrap flow for provisioning the sanctioned iLink bridge token and base URL. The long-lived listener still stays in an external bridge or managed plugin rather than a built-in Loong channels serve <surface> runtime. 
loong weixin onboard
What this does:
  • requests a fresh WeChat / iLink QR code
  • renders the QR directly in the terminal when possible
  • polls until iLink returns the bot_token, baseurl, and bound bot or user ids
  • writes weixin.bridge_url plus weixin.bridge_access_token into loong.toml
  • bootstraps allowed_contact_ids = ["<ilink_user_id>"] when that trust boundary is still empty
Use loong weixin onboard --account ops when you want the credentials written into weixin.accounts.ops.

​
At A Glance

FieldValue
Catalog idweixin
Config keyweixin
Implementation statusplugin_backed
Transportwechat_clawbot_ilink_bridge
Aliaseswechat, wx, wechat-clawbot
Default send target kindconversation
Runtime ownerexternal plugin

​
Minimal Config

[weixin]
enabled = true
bridge_url_env = "WEIXIN_BRIDGE_URL"
bridge_access_token_env = "WEIXIN_BRIDGE_ACCESS_TOKEN"
allowed_contact_ids = ["wxid_ops"]
If you already know which managed bridge plugin should own this surface, pin it explicitly: 
[weixin]
enabled = true
managed_bridge_plugin_id = "weixin-clawbot-bridge"
bridge_url_env = "WEIXIN_BRIDGE_URL"
bridge_access_token_env = "WEIXIN_BRIDGE_ACCESS_TOKEN"
allowed_contact_ids = ["wxid_ops"]

​
Smoke Test

loong weixin onboard
loong channels
loong channels --json
loong doctor
What success looks like:
  • loong channels lists Weixin [weixin] under the plugin-backed section
  • loong weixin onboard prints the saved bridge url plus the next channels serve weixin command
  • the managed bridge discovery line selects one compatible plugin or explains exactly why discovery is incomplete or ambiguous
  • loong doctor reports the bridge contract as ready, or gives a bounded remediation path

​
Current Command Surface

OperationCurrent pathUsage or status
QR bridge bootstrapweixin onboardprovisions bridge_url and bridge_access_token through the sanctioned iLink QR flow
managed bridge contract checkloong doctorcurrent readiness and remediation surface
inventory + discovery inspectionloong channelscurrent operator inventory surface
bridge-backed sendchannels send weixinexecutes through the selected managed bridge runtime; target contract stays weixin:<account>:contact:<id> or weixin:<account>:room:<id>
bridge-backed servechannels serve weixinstarts the selected managed bridge reply loop; upstream session ownership still stays in the external bridge

​
Required Fields For Bridge Send Contract

RequirementConfig pathsEnv pointer pathsDefault env
channel enabledweixin.enabled
weixin.accounts.<account>.enabled		nonenone
clawbot bridge urlweixin.bridge_url
weixin.accounts.<account>.bridge_url		weixin.bridge_url_env
weixin.accounts.<account>.bridge_url_env		WEIXIN_BRIDGE_URL
bridge access tokenweixin.bridge_access_token
weixin.accounts.<account>.bridge_access_token		weixin.bridge_access_token_env
weixin.accounts.<account>.bridge_access_token_env		WEIXIN_BRIDGE_ACCESS_TOKEN

​
Required Fields For Bridge Reply Contract

RequirementConfig pathsEnv pointer pathsDefault env
channel enabledweixin.enabled
weixin.accounts.<account>.enabled		nonenone
clawbot bridge urlweixin.bridge_url
weixin.accounts.<account>.bridge_url		weixin.bridge_url_env
weixin.accounts.<account>.bridge_url_env		WEIXIN_BRIDGE_URL
bridge access tokenweixin.bridge_access_token
weixin.accounts.<account>.bridge_access_token		weixin.bridge_access_token_env
weixin.accounts.<account>.bridge_access_token_env		WEIXIN_BRIDGE_ACCESS_TOKEN
allowed contact idsweixin.allowed_contact_ids
weixin.accounts.<account>.allowed_contact_ids		nonenone

​
Stable Target Templates

Use these templates when you need one bridge implementation and later tooling to converge on the same route semantics.
TargetMeaning
weixin:<account>:contact:<id>direct contact conversation
weixin:<account>:room:<id>group room conversation

​
Managed Bridge Discovery Notes

  • Loong scans the configured managed install root for compatible bridge manifests.
  • Managed bridge execution also requires [runtime_plugins].enabled = true plus one or more runtime_plugins.roots.
  • If exactly one compatible bridge is found, loong doctor and loong channels can surface it as the selected plugin.
  • If several compatible bridges are found, set managed_bridge_plugin_id to make the selection explicit.
  • If discovery is incomplete, Loong keeps the bridge-owned surface visible and reports the missing fields instead of pretending the channel is ready.

​
Gateway And Ownership

This surface does not join gateway run or gateway run today. The upstream Weixin listener and login flow remain owned by the external bridge. Use Loong here for:
  • the stable channel id and target contract
  • config validation
  • managed bridge discovery
  • bounded operator diagnostics and remediation

​
Operator Notes

  • Keep allowed_contact_ids tight. Treat it as the trust boundary, not a convenience list.
  • loong weixin onboard is the recommended first-run path because it provisions the sanctioned bridge_url and bridge_access_token pair without asking operators to copy the raw iLink response by hand.
  • Loong validates allowed_contact_ids locally before forwarding a contact send through the managed bridge runtime.
  • If allowed_contact_ids is still empty during QR onboarding, Loong bootstraps it with the scanned ilink_user_id so the onboarding account can validate the lane immediately.
  • channels serve weixin retries transient managed bridge runtime failures with bounded backoff; repeated failures still surface as a hard error so the bridge can be inspected.
  • channels serve weixin --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 weixin --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.
  • QR onboarding does not install the bridge plugin for you. Managed bridge execution still needs [runtime_plugins].enabled = true, one or more runtime_plugins.roots, and either one compatible bridge or an explicit managed_bridge_plugin_id.
  • Prefer one explicit managed bridge per environment. If discovery is ambiguous, fix the ambiguity instead of relying on accidental selection.
  • If you need multiple bridge identities, move to default_account plus accounts.<id> before inventing ad-hoc routes.
  • Continue to QQ Bot or OneBot if your Tencent or personal-account bridge lane uses a different upstream contract.
  • Continue to Channel Guides for the full actionable matrix.
  • Continue to Channels for the surface model.
  • Continue to Channel Setup for the shared public setup contract.