Skip to main content

​
Gateway And Supervision

Use this page when one service channel already works and you need to decide how Loong should own longer-lived delivery. If you still need initial channel setup or smoke tests, start with Channel Guides for the exact one-surface contract and keep Channel Recipes for the representative rollout path. This page is about runtime ownership, supervision, and account selection after the basic lane is already healthy. If you first need the shared default_account, accounts.<id>, or outbound trust config shape, start with Configuration Patterns.

​
Choose The Right Owner Shape

NeedBest commandWhy
keep one service channel in the foreground while you verify itloong <surface>-servesimplest single-surface loop; no cross-channel supervisor yet
keep several runtime-backed channels attached to one foreground shellloong multi-channel-serve --session <name>compatibility wrapper for operators who want one visible CLI-first session
claim the persisted owner slot and manage it from another processloong gateway runexplicit owner contract with status and stop
claim gateway ownership and also attach a named CLI hostloong gateway run --session <name>same owner contract, plus an attached concurrent CLI session

​
Current Public Ownership Model

  • gateway run, gateway status, and gateway stop are the current explicit owner contract for longer-lived runtime-backed delivery.
  • multi-channel-serve uses the same ownership model while preserving the attached foreground workflow many operators want during rollout.
  • multi-channel-serve is still the compatibility wrapper, not the long-term product noun.
  • This ownership model is for runtime-backed service channels. It is not the umbrella story for every outbound integration in the catalog.

​
What Gateway Supervision Includes Today

Included in runtime supervision today:
  • Feishu / Lark
  • Telegram
  • Matrix
  • WhatsApp
  • WeCom
Not part of runtime supervision today:
  • Webhook and Email
  • Slack, Discord, Teams, Google Chat, Mattermost, Nextcloud Talk, and Synology Chat
  • LINE, DingTalk, Signal, IRC, iMessage / BlueBubbles, Nostr, Tlon, Twitch, and similar outbound-only surfaces
If a surface is outbound-only, it should stay documented as outbound-only instead of being described as if it joins the same reply-loop supervisor.

​
Channel-Account Selectors

Use repeatable --channel-account <CHANNEL=ACCOUNT> selectors when you want to pin a specific account for a runtime-backed channel family. Rules that matter:
  • feishu=work is valid, and lark=work is the accepted alias for the same Feishu family.
  • selectors should target configured account ids such as work, alerts, bot_123456, or bridge-sync
  • one channel family can appear only once in the selector list; duplicate overrides are rejected
  • malformed selectors such as telegrambot123 fail because the syntax must be CHANNEL=ACCOUNT
  • when a channel family has several configured accounts, setting default_account explicitly keeps fallback routing from becoming accidental
Foreground wrapper example: 
loong multi-channel-serve \
  --session cli-supervisor \
  --channel-account lark=work \
  --channel-account wecom=alerts \
  --channel-account telegram=bot_123456 \
  --channel-account matrix=bridge-sync
Gateway-owned example: 
loong gateway run \
  --channel-account feishu=work \
  --channel-account wecom=work \
  --channel-account telegram=bot_123456
Attached gateway example: 
loong gateway run \
  --session daemon-gateway \
  --channel-account lark=work \
  --channel-account matrix=bridge-sync
Control loop: 
loong gateway status
loong gateway status --json
loong gateway stop

​
Rollout Order

  1. Get onboard, ask or chat, and doctor healthy first.
  2. Bring up one runtime-backed surface with its own loong <surface>-serve loop before you introduce supervision.
  3. Add default_account plus accounts.<id> before you rely on multi-account supervision.
  4. Use multi-channel-serve when you want one attached foreground session.
  5. Use gateway run when you want a persisted owner that another process can inspect or stop.

​
Recovery And Inspection

When startup or supervision is unclear, use the shortest diagnostic loop first: 
loong doctor
loong channels
loong gateway status --json
That combination answers three different questions:
  • doctor checks provider and channel readiness
  • channels shows how Loong currently classifies each surface
  • gateway status --json is the quickest way to inspect current ownership from another CLI process
If the runtime still does not start cleanly:
  • confirm that the selected surface is actually runtime-backed, not outbound-only
  • confirm that the selected account id exists under accounts.<id>
  • rerun with explicit --channel-account selectors when a channel family has more than one configured account
  • check duplicate selectors first if startup fails immediately

​
Continue Reading

  • Continue to Gateway Rollout when you want the owner contract turned into a rollout sequence.
  • Continue to Common Setups when you want provider, channel, and gateway choices combined into one setup path.
  • Continue to Configuration Patterns for the shared public account, selector, and trust-toggle config shapes.
  • Go back to Channels for the surface model and runtime-backed versus outbound-only boundary.
  • Continue to Channel Guides for the exact built-in contract of one shipped channel surface.
  • Continue to Channel Setup for the practical public setup contract.
  • Continue to Channel Recipes for smoke tests, worked examples, and rollout walkthroughs.
  • The field-level public source spec remains in the repository’s Channel Setup markdown.