​

Channel Setup

Loong keeps channel setup explicit so operators can tell what is actually shipped, 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.

​

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 runtime-backed or outbound-only
• setup should point to a concrete run command instead of a vague support claim

​

Common Rollout Shapes

​

Runtime-Backed Service Channels

These are the shipped reply-loop surfaces today.

​

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
• feishu-send and feishu-serve are both first-class shipped commands

​

Telegram

Telegram remains the simplest shipped bot lane:

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

​

Matrix

Matrix is a sync-loop surface:

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

​

WhatsApp

WhatsApp 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 whatsapp-send for proactive sends
• use whatsapp-serve for the reply loop
• keep webhook_bind and webhook_path explicit so the callback owner is legible

​

WeCom

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

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

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

​

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
• multi-channel-serve is the compatibility wrapper for the shipped runtime-backed subset
• 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 runtime-backed service channel if you need inbound or reply-loop behavior.
3. Add outbound-only surfaces when you need governed direct sends.
4. Reach for gateway and multi-channel-serve only after one channel already works cleanly.

​

Deep References

• Continue to Channel Guides for the full shipped 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.