​

Channel Setup

Loong keeps channel setup explicit so operators can tell what is actually shipped, what is gateway-supervised, what stays on a standalone native serve loop, what is bridge-owned, what is outbound-only, and what still depends on future runtime work. Use this page when you want the practical setup contract. If you want step-by-step smoke tests and worked examples instead, start with Channel Guides for the exact per-surface contract, then keep Channel Recipes for representative rollout patterns. If you want the shared public config shape before the per-surface setup rules, start with Configuration Patterns. If you specifically need the longer-lived owner model, foreground versus headless supervision, or --channel-account selectors, continue to Gateway And Supervision.

​

Canonical Channel Command Story

Public docs now use grouped channel shells first:

• generic sends: loong channels send <surface> ...
• generic serve loops: loong channels serve <surface> ...
• richer family namespaces stay first-class when they expose more than thin wrappers, but the canonical channel contract still uses loong channels send <surface> and loong channels serve <surface>

​

Start With The Right Question

​

Readiness Rules

Before any channel is really ready:

• the base CLI path should already work locally
• provider credentials should already be healthy
• channel-specific credentials should already resolve
• the surface should be described truthfully as gateway-supervised, standalone native-serve, plugin-backed, or outbound-only
• setup should point to a concrete operator path instead of a vague support claim

​

Common Rollout Shapes

​

Gateway-Supervised Service Channels

These are the shipped reply-loop surfaces that can join gateway run or gateway run today.

​

Standalone Native-Serve Surfaces

These surfaces ship real built-in serve loops, but the runtime still stays on the direct channels serve <surface> command instead of gateway supervision.

​

Plugin-Backed Bridge Surfaces

These surfaces are shipped as real channel contracts, but the listener, login, and upstream session lifecycle stay in an external bridge or managed plugin. Operational rule:

• these surfaces are actionable and operator-visible today
• they do not join gateway run or gateway run because their runtime owner is still the external bridge
• the important setup milestone is a passing contract + discovery result, not a native runtime loop that does not exist yet
• managed bridge command execution also requires [runtime_plugins].enabled = true plus one or more runtime_plugins.roots
• grouped channels serve <surface> flows retry transient managed bridge runtime failures locally with bounded backoff before surfacing a hard failure
• retry/failure metadata is surfaced through loong doctor and loong channels, so operators can see when a bridge is actively retrying instead of guessing from stderr

​

Multi-Account Rule

• use default_account when one account should be the normal default lane
• use accounts.<id> when one config should hold prod, backup, or environment-specific credentials
• keep shared defaults at the top level and override only account-specific secrets or allowlists
• feishu is the canonical config block for the Feishu family, while lark remains an accepted operator-facing alias in selectors and references
• gateway selectors should target those configured accounts.<id> values rather than ad-hoc names invented at command time

​

Feishu / Lark

Feishu supports two inbound transport shapes:

• webhook mode
• websocket mode

Publicly that means:

• both modes need the base app credentials and trusted-chat boundary
• webhook mode also needs the webhook verification material
• websocket mode should not be documented as if webhook-only secrets are mandatory
• loong channels send feishu and loong channels serve feishu are the canonical first-class shipped channel commands

​

Telegram

Telegram remains the simplest shipped bot lane:

• enable the channel
• provide one bot token
• allowlist trusted chat ids
• use loong channels serve telegram for reply-loop automation
• use loong channels send telegram for direct proactive sends

​

Matrix

Matrix is a sync-loop surface:

• configure the homeserver URL and access token
• allowlist trusted room ids
• use loong channels send matrix for direct room delivery
• use loong channels serve matrix for the reply loop

​

WhatsApp Cloud API

The current WhatsApp business lane is a Cloud API plus verified webhook runtime surface:

• configure access_token and phone_number_id for direct sends
• configure verify_token and app_secret for the webhook-backed serve path
• use loong channels send whatsapp for proactive sends
• use loong channels serve whatsapp for the reply loop
• keep webhook_bind and webhook_path explicit so the callback owner is legible
• keep this Cloud API credential flow separate from the QR-linked WhatsApp Personal path so operators can tell whether they need Meta business credentials or a scan-to-link setup

​

WeCom

WeCom is documented as the official AIBot long-connection lane:

• configure bot_id and secret
• allowlist trusted conversation ids
• use loong channels serve wecom for the long-lived reply loop
• use loong channels send wecom for proactive sends

Loong should not describe a WeCom webhook callback mode as if it were the same shipped contract.

​

Weixin

Weixin is a bridge-first surface:

• start with loong weixin onboard when you want Loong to request the iLink QR code and save the resulting bridge_url plus bridge_access_token for you
• configure bridge_url plus bridge_access_token
• keep allowed_contact_ids explicit because the bridge contract should stay narrow
• optional managed_bridge_plugin_id is the tie-breaker when several compatible managed bridges are installed
• use loong doctor to verify the configured contract and the selected managed bridge
• use loong channels or loong channels --json to inspect stable targets and discovery state
• use loong channels send weixin --target contact:<id> or loong channels send weixin --target weixin:<account>:room:<id> for proactive sends
• use loong channels serve weixin to run the selected managed bridge reply loop under Loong supervision
• use loong channels serve weixin --stop to request cooperative shutdown for the selected managed bridge runtime owner
• Loong automatically asks older duplicate owners to stop when it can identify one clear preferred runtime owner
• use loong channels serve weixin --stop-duplicates as the operator fallback when duplicate live owners persist and you want Loong to keep the preferred runtime owner while requesting cooperative shutdown for the older duplicates

​

QQ Bot

QQ Bot is the explicit Tencent gateway runtime lane:

• configure app_id plus client_secret
• use allowed_peer_ids to keep the trusted conversation boundary explicit
• keep openids and account ids stable so direct, group, and guild routes do not drift between bridge implementations
• use loong channels send qqbot --target c2c:<openid>, group:<openid>, or channel:<id> for proactive sends
• use loong channels serve qqbot to run the native QQ gateway reply loop under Loong supervision

​

OneBot

OneBot is the protocol-level bridge lane:

• configure websocket_url plus access_token
• keep allowed_group_ids explicit so the bridge contract stays narrow
• use it when the upstream bridge already speaks OneBot v11 and you want Loong to own the stable surface id and target contract
• verify bridge discovery through loong doctor before you treat the surface as ready
• use loong channels send onebot --target private:<user_id> or loong channels send onebot --target group:<group_id> for proactive sends
• use loong channels serve onebot to run the selected managed bridge reply loop under Loong supervision
• use loong channels serve onebot --stop to request cooperative shutdown for the selected managed bridge runtime owner
• Loong automatically asks older duplicate owners to stop when it can identify one clear preferred runtime owner
• use loong channels serve onebot --stop-duplicates as the operator fallback to clean up duplicate live runtime owners without fully draining the preferred owner

​

Outbound-Only Surfaces

These surfaces ship direct-send behavior, config validation, and inventory metadata without claiming a full reply-loop runtime.

​

Outbound HTTP Trust Rules

For HTTP-backed outbound delivery:

• URLs should use http or https
• credentials should not be embedded in the URL itself
• private or special-use hosts are blocked by default
• redirects are not followed automatically

If an operator intentionally targets a private bridge or self-hosted endpoint, the runtime can widen that boundary explicitly instead of silently assuming it.

​

Gateway And Multi-Channel Ownership

When you move beyond one local surface:

• gateway run, gateway status, and gateway stop are the explicit owner contract
• gateway run is the compatibility wrapper for the shipped gateway-supervised subset
• standalone native-serve surfaces use their own channels serve <surface> loop instead of joining the same reply-loop runtime contract
• plugin-backed surfaces are inspected through doctor and channels, not supervised through the same reply-loop runtime contract
• outbound-only surfaces should not be described as if they are supervised by the same reply-loop runtime contract
• the detailed command model, selector syntax, and recovery loop live in Gateway And Supervision

​

Recommended Progression

1. Get the local assistant path healthy first.
2. Add one gateway-supervised service channel if you need the shortest path into gateway run or gateway run.
3. Add one standalone native-serve surface when you need a real built-in channels serve <surface> loop without gateway supervision yet.
4. Add one plugin-backed bridge surface when the ecosystem is real but the runtime owner should stay external.
5. Add outbound-only surfaces when you need governed direct sends.
6. Reach for gateway and gateway run only after one gateway-supervised channel already works cleanly.

​

Deep References

• Continue to Channel Guides for the full actionable channel matrix.
• Continue to Channel Recipes for tutorial-style demos built on top of this setup contract.
• Continue to Channels for the conceptual public-surface model.
• Continue to Gateway And Supervision for the current runtime owner contract and multi-channel selection rules.
• Continue to Use Loong for the broader operator-facing runtime contract.
• The repository still keeps the full field-level source spec in Channel Setup.