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

# Feishu/Lark

> Configure the Feishu/Lark channel surface in Loong.

# Feishu/Lark

This is a shipped runtime-backed surface: direct sends are implemented, the serve loop is implemented, and the channel can join `gateway run` or `gateway run`.

## At A Glance

| Field                    | Value                                 |
| ------------------------ | ------------------------------------- |
| Catalog id               | `feishu`                              |
| Config key               | `feishu`                              |
| Implementation status    | `runtime_backed`                      |
| Transport                | `feishu_openapi_webhook_or_websocket` |
| Aliases                  | `lark`                                |
| Default send target kind | `receive_id`, `message_reply`         |

## Minimal Config

Preferred setup path:

```bash theme={null}
loong feishu onboard
```

This starts the official Feishu/Lark QR registration flow in the terminal, saves the generated `app_id` and `app_secret` into `loong.toml`, and defaults the channel to `mode = "websocket"`. Manual credential handoff remains available with `loong feishu onboard --manual --app-id ... --app-secret ...`.

```toml theme={null}
[feishu]
enabled = true
domain = "lark"
mode = "websocket"
receive_id_type = "chat_id"
app_id_env = "FEISHU_APP_ID"
app_secret_env = "FEISHU_APP_SECRET"
allowed_chat_ids = ["oc_ops_room"]
require_mention = true
```

## Smoke Test

```bash theme={null}
loong channels send feishu --target "ou_xxxxxxxxxxxxx" --text "hello from loong"
loong channels serve feishu
```

## Command Surface

| Operation             | Command                 | Usage or status                                                                |
| --------------------- | ----------------------- | ------------------------------------------------------------------------------ |
| direct send           | `channels send feishu`  | Usage: loong channels send feishu \[OPTIONS] --target \<TARGET> --text \<TEXT> |
| inbound reply service | `channels serve feishu` | Usage: loong channels serve feishu \[OPTIONS]                                  |

## Required Fields For Send

| Requirement     | Config paths                                                    | Env pointer paths                                                       | Default env         |
| --------------- | --------------------------------------------------------------- | ----------------------------------------------------------------------- | ------------------- |
| channel enabled | `feishu.enabled`<br />`feishu.accounts.<account>.enabled`       | none                                                                    | none                |
| app id          | `feishu.app_id`<br />`feishu.accounts.<account>.app_id`         | `feishu.app_id_env`<br />`feishu.accounts.<account>.app_id_env`         | `FEISHU_APP_ID`     |
| app secret      | `feishu.app_secret`<br />`feishu.accounts.<account>.app_secret` | `feishu.app_secret_env`<br />`feishu.accounts.<account>.app_secret_env` | `FEISHU_APP_SECRET` |

## Required Fields For Serve

| Requirement                            | Config paths                                                                    | Env pointer paths                                                                       | Default env                 |
| -------------------------------------- | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | --------------------------- |
| channel enabled                        | `feishu.enabled`<br />`feishu.accounts.<account>.enabled`                       | none                                                                                    | none                        |
| app id                                 | `feishu.app_id`<br />`feishu.accounts.<account>.app_id`                         | `feishu.app_id_env`<br />`feishu.accounts.<account>.app_id_env`                         | `FEISHU_APP_ID`             |
| app secret                             | `feishu.app_secret`<br />`feishu.accounts.<account>.app_secret`                 | `feishu.app_secret_env`<br />`feishu.accounts.<account>.app_secret_env`                 | `FEISHU_APP_SECRET`         |
| serve mode                             | `feishu.mode`<br />`feishu.accounts.<account>.mode`                             | none                                                                                    | none                        |
| allowed chat ids                       | `feishu.allowed_chat_ids`<br />`feishu.accounts.<account>.allowed_chat_ids`     | none                                                                                    | none                        |
| verification token (webhook mode only) | `feishu.verification_token`<br />`feishu.accounts.<account>.verification_token` | `feishu.verification_token_env`<br />`feishu.accounts.<account>.verification_token_env` | `FEISHU_VERIFICATION_TOKEN` |
| encrypt key (webhook mode only)        | `feishu.encrypt_key`<br />`feishu.accounts.<account>.encrypt_key`               | `feishu.encrypt_key_env`<br />`feishu.accounts.<account>.encrypt_key_env`               | `FEISHU_ENCRYPT_KEY`        |

## Gateway And Ownership

This surface can run directly through `channels serve feishu`, or under [Gateway And Supervision](/use-loong/gateway-and-supervision) through `gateway run`.

## Operator Notes

* `loong feishu onboard` is the recommended first-run path for both Feishu and Lark. Use `--domain lark` to start on the international lane, or keep the default Feishu lane and let the registration poll switch to Lark when the scanned tenant reports `tenant_brand = "lark"`.
* `loong channels send feishu` and `loong channels serve feishu` stay aligned with the same canonical grouped channel contract used by other shipped channels.
* Keep Feishu-specific richer payload modes such as `--post-json`, `--image-key` / `--image-path`, and `--file-key` / `--file-path` / `--file-type` on the dedicated `loong feishu send` and `loong feishu reply` surfaces instead of widening the shared grouped contract.
* Webhook mode additionally needs `verification_token` and `encrypt_key`; websocket mode does not.
* Set `require_mention = true` when multiple bots share the same group and you only want Loong to react when this bot is explicitly @-mentioned. P2P chats still bypass that gate.
* QR onboarding only provisions `app_id` and `app_secret`, so it currently targets websocket mode. Use `loong feishu onboard --manual --mode webhook ...` when you need webhook callback credentials.
* When QR onboarding receives the configuring user's `open_id` and no Feishu inbound allowlists are already configured, Loong bootstraps `allowed_chat_ids = ["*"]` plus `allowed_sender_ids = [owner_open_id]` so that same user can immediately start a direct chat with the bot after setup.
* Use `allowed_chat_ids` as the trust boundary instead of treating it as a convenience filter.
* Keep `domain = "lark"` for the Lark lane and `domain = "feishu"` for the Feishu lane; the runtime contract is the same family.

## Related Docs

* Continue to [Channel Guides](/use-loong/channel-guides/index) for the full shipped channel matrix.
* Continue to [Channels](/use-loong/channels) for the conceptual surface model.
* Continue to [Channel Setup](/use-loong/channel-setup) for the shared public setup contract.
* Continue to [Gateway And Supervision](/use-loong/gateway-and-supervision) when this surface needs longer-lived runtime ownership.