> ## Documentation Index
> Fetch the complete documentation index at: https://docs.loongclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Channel Setup

> Practical setup guidance for gateway-supervised, standalone native-serve, plugin-backed, and outbound-only delivery surfaces.

# 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](/use-loong/channel-guides/index) for the exact per-surface contract, then keep [Channel Recipes](/use-loong/channel-recipes) for representative rollout patterns.
If you want the shared public config shape before the per-surface setup rules,
start with [Configuration Patterns](/use-loong/configuration-patterns).
If you specifically need the longer-lived owner model, foreground versus
headless supervision, or `--channel-account` selectors, continue to
[Gateway And Supervision](/use-loong/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

| If you need...                                                          | Start with...                                                                                                               |
| ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| a local assistant only                                                  | `onboard`, `ask`, `chat`, and `doctor`                                                                                      |
| inbound or reply-loop automation that should join `gateway run` later   | one shipped gateway-supervised service channel                                                                              |
| one built-in serve loop that should stay on its own command for now     | one standalone native-serve surface                                                                                         |
| a real channel contract whose login/runtime stays in an external bridge | one plugin-backed bridge surface                                                                                            |
| proactive delivery without a reply loop                                 | one outbound-only surface                                                                                                   |
| the shared account and selector config shape first                      | [Configuration Patterns](/use-loong/configuration-patterns)                                                                 |
| multiple reply-loop surfaces on one host                                | [Gateway And Supervision](/use-loong/gateway-and-supervision)                                                               |
| the full source-level field contract behind this page                   | the repository-native [Channel Setup](https://github.com/eastreams/loong/blob/dev/docs/product-specs/channel-setup.md) spec |

## 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

| Situation                                                                                              | Best first move                                                                                 | Why                                                                                                     |
| ------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| one Feishu or Lark app should own inbound automation                                                   | configure `feishu` and run `loong channels serve feishu`                                        | the Feishu family is the shipped runtime lane for both Feishu and Lark                                  |
| one Telegram bot should own a reply loop                                                               | configure `telegram` and run `loong channels serve telegram`                                    | this is the simplest runtime-backed bot lane                                                            |
| one Matrix bot should own a room sync loop                                                             | configure `matrix` and run `loong channels serve matrix`                                        | the homeserver, room ids, and sync boundary stay explicit                                               |
| one WhatsApp Cloud API business account should own a reply loop                                        | configure `whatsapp` and run `loong channels serve whatsapp`                                    | send and serve are both shipped on the verified webhook path                                            |
| one WeCom bot should own the official long connection                                                  | configure `wecom` and run `loong channels serve wecom`                                          | this matches the shipped AIBot contract                                                                 |
| one LINE or generic webhook lane should use a real built-in serve loop without gateway supervision yet | configure the standalone native-serve block and run `loong channels serve <surface> --bind ...` | the runtime is real, but the owner is still the direct grouped serve command                            |
| one WeChat / QQ / OneBot / personal WhatsApp bridge should stay external but visible                   | configure the plugin-backed channel block and run `loong doctor` plus `loong channels`          | bridge-owned surfaces are real but should not pretend the gateway already owns the upstream login stack |
| you need several accounts in one channel family                                                        | add `default_account` plus `accounts.<id>` before adding gateway selectors                      | stable account ids make later supervision and routing legible                                           |
| you only need governed direct sends                                                                    | configure one outbound-only surface and use `loong channels send <surface>`                     | this avoids pretending a reply loop already ships                                                       |

## Gateway-Supervised Service Channels

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

| Surface            | What you configure first                                           | Run loop                        |
| ------------------ | ------------------------------------------------------------------ | ------------------------------- |
| Feishu / Lark      | app credentials, trusted chats, and the selected inbound transport | `loong channels serve feishu`   |
| Telegram           | bot token and trusted chat ids                                     | `loong channels serve telegram` |
| Matrix             | homeserver base URL, access token, and trusted room ids            | `loong channels serve matrix`   |
| QQ Bot             | app id, client secret, and trusted peer ids                        | `loong channels serve qqbot`    |
| WhatsApp Cloud API | Cloud API credentials plus verified webhook material               | `loong channels serve whatsapp` |
| WeCom              | bot id, secret, and trusted conversation ids                       | `loong channels serve wecom`    |

## 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.

| Surface | What you configure first                                              | Run loop                                          |
| ------- | --------------------------------------------------------------------- | ------------------------------------------------- |
| LINE    | channel access token, channel secret, and a chosen local bind address | `loong channels serve line --bind <HOST:PORT>`    |
| Webhook | signing secret plus a chosen local bind address                       | `loong channels serve webhook --bind <HOST:PORT>` |

## 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.

| Surface           | What you configure first                                                     | Current operator path                                                                                                                                                               |
| ----------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Weixin            | `weixin.enabled`, `bridge_url`, `bridge_access_token`, `allowed_contact_ids` | `loong weixin onboard`, `loong doctor`, `loong channels`, `loong channels send weixin`, `loong channels serve weixin`, managed bridge discovery                                     |
| OneBot            | `onebot.enabled`, `websocket_url`, `access_token`, `allowed_group_ids`       | `loong doctor`, `loong channels`, `loong channels send onebot`, `loong channels serve onebot`, managed bridge discovery                                                             |
| WhatsApp Personal | `whatsapp_personal.enabled`, `bridge_url`, `auth_dir`, `allowed_chat_ids`    | `loong whatsapp-personal bridge run`, `loong doctor`, `loong channels`, `loong channels send whatsapp-personal`, `loong channels serve whatsapp-personal`, managed bridge discovery |

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](/use-loong/channel-guides/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.

| Surface family                         | Current examples                                                   | Primary command shape           |
| -------------------------------------- | ------------------------------------------------------------------ | ------------------------------- |
| chat and workplace platforms           | Discord, Slack, DingTalk, Microsoft Teams, Mattermost, Google Chat | `loong channels send <surface>` |
| messaging and communication bridges    | Signal, IRC, iMessage / BlueBubbles, Nostr                         | `loong channels send <surface>` |
| generic or self-hosted delivery        | Email, Nextcloud Talk, Synology Chat, Tlon                         | `loong channels send <surface>` |
| community-facing outbound integrations | Twitch and similar outbound-only integrations                      | `loong channels send <surface>` |

## 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](/use-loong/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](/use-loong/channel-guides/index) for the full actionable channel matrix.
* Continue to [Channel Recipes](/use-loong/channel-recipes) for tutorial-style demos built on top of this setup contract.
* Continue to [Channels](/use-loong/channels) for the conceptual public-surface model.
* Continue to [Gateway And Supervision](/use-loong/gateway-and-supervision)
  for the current runtime owner contract and multi-channel selection rules.
* Continue to [Use Loong](/use-loong/overview) for the broader operator-facing runtime contract.
* The repository still keeps the full field-level source spec in [Channel Setup](https://github.com/eastreams/loong/blob/dev/docs/product-specs/channel-setup.md).