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. The canonical public docs story uses grouped shells first: loong channels serve <surface> for single-surface runtime loops and loong gateway ... for persisted ownership.

​
Choose The Right Owner Shape

NeedBest commandWhy
keep one service channel in the foreground while you verify itloong channels serve <surface>simplest single-surface loop; no cross-channel supervisor yet
keep several gateway-supervised runtime-backed channels attached to one foreground shellloong gateway run --session <name>one visible attached owner shell with a named concurrent CLI host
claim the persisted owner slot and manage it from another processloong gateway runexplicit persisted owner contract with status and stop
claim gateway ownership and also attach a named CLI hostloong gateway run --session <name>same owner contract, but attached to an explicit interactive host session

​
Current Public Ownership Model

  • gateway run, gateway status, and gateway stop are the current explicit owner contract for longer-lived gateway-supervised delivery.
  • gateway run --session <name> is the explicit attached foreground owner workflow for rollout.
  • bare gateway run is the persisted owner workflow when another process should inspect or stop it later.
  • This ownership model is for gateway-supervised service channels. Some of those surfaces still keep implementation_status=plugin_backed in the catalog because their setup and transport contracts preserve managed-bridge-capable or externally bridged history. 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:
  • Standalone native-serve surfaces: LINE and Webhook
  • Outbound-only surfaces: Email, Slack, Discord, Teams, Google Chat, Mattermost, Nextcloud Talk, Synology Chat, DingTalk, Signal, IRC, iMessage / BlueBubbles, Nostr, Tlon, Twitch, and similar direct-send integrations
If a surface is standalone native-serve or outbound-only, it should stay documented that way instead of being described as if it joins the same reply-loop supervisor. The supervision grouping describes current runtime ownership, not every catalog implementation-status nuance.

​
Channel-Account Selectors

Use repeatable --channel-account <CHANNEL=ACCOUNT> selectors when you want to pin a specific account for a gateway-supervised 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 gateway run \
  --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 gateway-supervised surface with its own loong channels serve <surface> loop before you introduce supervision.
  3. Add default_account plus accounts.<id> before you rely on multi-account supervision.
  4. Use gateway run --session <name> 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
loong status --json
That combination answers four 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
  • loong status --json provides the broader operator summary across gateway, ACP, and work-unit surfaces
If the runtime still does not start cleanly:
  • confirm that the selected surface is actually gateway-supervised, not a standalone native-serve channels serve <surface> lane or outbound-only lane
  • 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 the gateway-supervised versus standalone native-serve 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.