{
  "title": "Feishu bot",
  "content": "Feishu (Lark) is a team chat platform used by companies for messaging and collaboration. This plugin connects OpenClaw to a Feishu/Lark bot using the platform’s WebSocket event subscription so messages can be received without exposing a public webhook URL.\n\nInstall the Feishu plugin:\n\nLocal checkout (when running from a git repo):\n\nThere are two ways to add the Feishu channel:\n\n### Method 1: onboarding wizard (recommended)\n\nIf you just installed OpenClaw, run the wizard:\n\nThe wizard guides you through:\n\n1. Creating a Feishu app and collecting credentials\n2. Configuring app credentials in OpenClaw\n3. Starting the gateway\n\n✅ **After configuration**, check gateway status:\n\n* `openclaw gateway status`\n* `openclaw logs --follow`\n\n### Method 2: CLI setup\n\nIf you already completed initial install, add the channel via CLI:\n\nChoose **Feishu**, then enter the App ID and App Secret.\n\n✅ **After configuration**, manage the gateway:\n\n* `openclaw gateway status`\n* `openclaw gateway restart`\n* `openclaw logs --follow`\n\n## Step 1: Create a Feishu app\n\n### 1. Open Feishu Open Platform\n\nVisit [Feishu Open Platform](https://open.feishu.cn/app) and sign in.\n\nLark (global) tenants should use [https://open.larksuite.com/app](https://open.larksuite.com/app) and set `domain: \"lark\"` in the Feishu config.\n\n1. Click **Create enterprise app**\n2. Fill in the app name + description\n3. Choose an app icon\n\n<img alt=\"Create enterprise app\" />\n\n### 3. Copy credentials\n\nFrom **Credentials & Basic Info**, copy:\n\n* **App ID** (format: `cli_xxx`)\n* **App Secret**\n\n❗ **Important:** keep the App Secret private.\n\n<img alt=\"Get credentials\" />\n\n### 4. Configure permissions\n\nOn **Permissions**, click **Batch import** and paste:\n\n<img alt=\"Configure permissions\" />\n\n### 5. Enable bot capability\n\nIn **App Capability** > **Bot**:\n\n1. Enable bot capability\n2. Set the bot name\n\n<img alt=\"Enable bot capability\" />\n\n### 6. Configure event subscription\n\n⚠️ **Important:** before setting event subscription, make sure:\n\n1. You already ran `openclaw channels add` for Feishu\n2. The gateway is running (`openclaw gateway status`)\n\nIn **Event Subscription**:\n\n1. Choose **Use long connection to receive events** (WebSocket)\n2. Add the event: `im.message.receive_v1`\n\n⚠️ If the gateway is not running, the long-connection setup may fail to save.\n\n<img alt=\"Configure event subscription\" />\n\n### 7. Publish the app\n\n1. Create a version in **Version Management & Release**\n2. Submit for review and publish\n3. Wait for admin approval (enterprise apps usually auto-approve)\n\n## Step 2: Configure OpenClaw\n\n### Configure with the wizard (recommended)\n\nChoose **Feishu** and paste your App ID + App Secret.\n\n### Configure via config file\n\nEdit `~/.openclaw/openclaw.json`:\n\n### Configure via environment variables\n\n### Lark (global) domain\n\nIf your tenant is on Lark (international), set the domain to `lark` (or a full domain string). You can set it at `channels.feishu.domain` or per account (`channels.feishu.accounts.<id>.domain`).\n\n## Step 3: Start + test\n\n### 1. Start the gateway\n\n### 2. Send a test message\n\nIn Feishu, find your bot and send a message.\n\n### 3. Approve pairing\n\nBy default, the bot replies with a pairing code. Approve it:\n\nAfter approval, you can chat normally.\n\n* **Feishu bot channel**: Feishu bot managed by the gateway\n* **Deterministic routing**: replies always return to Feishu\n* **Session isolation**: DMs share a main session; groups are isolated\n* **WebSocket connection**: long connection via Feishu SDK, no public URL needed\n\n* **Default**: `dmPolicy: \"pairing\"` (unknown users get a pairing code)\n* **Approve pairing**:\n  \n* **Allowlist mode**: set `channels.feishu.allowFrom` with allowed Open IDs\n\n**1. Group policy** (`channels.feishu.groupPolicy`):\n\n* `\"open\"` = allow everyone in groups (default)\n* `\"allowlist\"` = only allow `groupAllowFrom`\n* `\"disabled\"` = disable group messages\n\n**2. Mention requirement** (`channels.feishu.groups.<chat_id>.requireMention`):\n\n* `true` = require @mention (default)\n* `false` = respond without mentions\n\n## Group configuration examples\n\n### Allow all groups, require @mention (default)\n\n### Allow all groups, no @mention required\n\n### Allow specific users in groups only\n\n## Get group/user IDs\n\n### Group IDs (chat\\_id)\n\nGroup IDs look like `oc_xxx`.\n\n**Method 1 (recommended)**\n\n1. Start the gateway and @mention the bot in the group\n2. Run `openclaw logs --follow` and look for `chat_id`\n\nUse the Feishu API debugger to list group chats.\n\n### User IDs (open\\_id)\n\nUser IDs look like `ou_xxx`.\n\n**Method 1 (recommended)**\n\n1. Start the gateway and DM the bot\n2. Run `openclaw logs --follow` and look for `open_id`\n\nCheck pairing requests for user Open IDs:\n\n| Command   | Description       |\n| --------- | ----------------- |\n| `/status` | Show bot status   |\n| `/reset`  | Reset the session |\n| `/model`  | Show/switch model |\n\n> Note: Feishu does not support native command menus yet, so commands must be sent as text.\n\n## Gateway management commands\n\n| Command                    | Description                   |\n| -------------------------- | ----------------------------- |\n| `openclaw gateway status`  | Show gateway status           |\n| `openclaw gateway install` | Install/start gateway service |\n| `openclaw gateway stop`    | Stop gateway service          |\n| `openclaw gateway restart` | Restart gateway service       |\n| `openclaw logs --follow`   | Tail gateway logs             |\n\n### Bot does not respond in group chats\n\n1. Ensure the bot is added to the group\n2. Ensure you @mention the bot (default behavior)\n3. Check `groupPolicy` is not set to `\"disabled\"`\n4. Check logs: `openclaw logs --follow`\n\n### Bot does not receive messages\n\n1. Ensure the app is published and approved\n2. Ensure event subscription includes `im.message.receive_v1`\n3. Ensure **long connection** is enabled\n4. Ensure app permissions are complete\n5. Ensure the gateway is running: `openclaw gateway status`\n6. Check logs: `openclaw logs --follow`\n\n1. Reset the App Secret in Feishu Open Platform\n2. Update the App Secret in your config\n3. Restart the gateway\n\n### Message send failures\n\n1. Ensure the app has `im:message:send_as_bot` permission\n2. Ensure the app is published\n3. Check logs for detailed errors\n\n## Advanced configuration\n\n### Multiple accounts\n\n* `textChunkLimit`: outbound text chunk size (default: 2000 chars)\n* `mediaMaxMb`: media upload/download limit (default: 30MB)\n\nFeishu does not support message editing, so block streaming is enabled by default (`blockStreaming: true`). The bot waits for the full reply before sending.\n\n## Configuration reference\n\nFull configuration: [Gateway configuration](/gateway/configuration)\n\n| Setting                                           | Description                     | Default   |\n| ------------------------------------------------- | ------------------------------- | --------- |\n| `channels.feishu.enabled`                         | Enable/disable channel          | `true`    |\n| `channels.feishu.domain`                          | API domain (`feishu` or `lark`) | `feishu`  |\n| `channels.feishu.accounts.<id>.appId`             | App ID                          | -         |\n| `channels.feishu.accounts.<id>.appSecret`         | App Secret                      | -         |\n| `channels.feishu.accounts.<id>.domain`            | Per-account API domain override | `feishu`  |\n| `channels.feishu.dmPolicy`                        | DM policy                       | `pairing` |\n| `channels.feishu.allowFrom`                       | DM allowlist (open\\_id list)    | -         |\n| `channels.feishu.groupPolicy`                     | Group policy                    | `open`    |\n| `channels.feishu.groupAllowFrom`                  | Group allowlist                 | -         |\n| `channels.feishu.groups.<chat_id>.requireMention` | Require @mention                | `true`    |\n| `channels.feishu.groups.<chat_id>.enabled`        | Enable group                    | `true`    |\n| `channels.feishu.textChunkLimit`                  | Message chunk size              | `2000`    |\n| `channels.feishu.mediaMaxMb`                      | Media size limit                | `30`      |\n| `channels.feishu.blockStreaming`                  | Disable streaming               | `true`    |\n\n## dmPolicy reference\n\n| Value         | Behavior                                                        |\n| ------------- | --------------------------------------------------------------- |\n| `\"pairing\"`   | **Default.** Unknown users get a pairing code; must be approved |\n| `\"allowlist\"` | Only users in `allowFrom` can chat                              |\n| `\"open\"`      | Allow all users (requires `\"*\"` in allowFrom)                   |\n| `\"disabled\"`  | Disable DMs                                                     |\n\n## Supported message types\n\n* ✅ Text\n* ✅ Images\n* ✅ Files\n* ✅ Audio\n* ✅ Video\n* ✅ Stickers\n\n* ✅ Text\n* ✅ Images\n* ✅ Files\n* ✅ Audio\n* ⚠️ Rich text (partial support)",
  "code_samples": [
    {
      "code": "Local checkout (when running from a git repo):",
      "language": "unknown"
    },
    {
      "code": "***\n\n## Quickstart\n\nThere are two ways to add the Feishu channel:\n\n### Method 1: onboarding wizard (recommended)\n\nIf you just installed OpenClaw, run the wizard:",
      "language": "unknown"
    },
    {
      "code": "The wizard guides you through:\n\n1. Creating a Feishu app and collecting credentials\n2. Configuring app credentials in OpenClaw\n3. Starting the gateway\n\n✅ **After configuration**, check gateway status:\n\n* `openclaw gateway status`\n* `openclaw logs --follow`\n\n### Method 2: CLI setup\n\nIf you already completed initial install, add the channel via CLI:",
      "language": "unknown"
    },
    {
      "code": "Choose **Feishu**, then enter the App ID and App Secret.\n\n✅ **After configuration**, manage the gateway:\n\n* `openclaw gateway status`\n* `openclaw gateway restart`\n* `openclaw logs --follow`\n\n***\n\n## Step 1: Create a Feishu app\n\n### 1. Open Feishu Open Platform\n\nVisit [Feishu Open Platform](https://open.feishu.cn/app) and sign in.\n\nLark (global) tenants should use [https://open.larksuite.com/app](https://open.larksuite.com/app) and set `domain: \"lark\"` in the Feishu config.\n\n### 2. Create an app\n\n1. Click **Create enterprise app**\n2. Fill in the app name + description\n3. Choose an app icon\n\n<img alt=\"Create enterprise app\" />\n\n### 3. Copy credentials\n\nFrom **Credentials & Basic Info**, copy:\n\n* **App ID** (format: `cli_xxx`)\n* **App Secret**\n\n❗ **Important:** keep the App Secret private.\n\n<img alt=\"Get credentials\" />\n\n### 4. Configure permissions\n\nOn **Permissions**, click **Batch import** and paste:",
      "language": "unknown"
    },
    {
      "code": "<img alt=\"Configure permissions\" />\n\n### 5. Enable bot capability\n\nIn **App Capability** > **Bot**:\n\n1. Enable bot capability\n2. Set the bot name\n\n<img alt=\"Enable bot capability\" />\n\n### 6. Configure event subscription\n\n⚠️ **Important:** before setting event subscription, make sure:\n\n1. You already ran `openclaw channels add` for Feishu\n2. The gateway is running (`openclaw gateway status`)\n\nIn **Event Subscription**:\n\n1. Choose **Use long connection to receive events** (WebSocket)\n2. Add the event: `im.message.receive_v1`\n\n⚠️ If the gateway is not running, the long-connection setup may fail to save.\n\n<img alt=\"Configure event subscription\" />\n\n### 7. Publish the app\n\n1. Create a version in **Version Management & Release**\n2. Submit for review and publish\n3. Wait for admin approval (enterprise apps usually auto-approve)\n\n***\n\n## Step 2: Configure OpenClaw\n\n### Configure with the wizard (recommended)",
      "language": "unknown"
    },
    {
      "code": "Choose **Feishu** and paste your App ID + App Secret.\n\n### Configure via config file\n\nEdit `~/.openclaw/openclaw.json`:",
      "language": "unknown"
    },
    {
      "code": "### Configure via environment variables",
      "language": "unknown"
    },
    {
      "code": "### Lark (global) domain\n\nIf your tenant is on Lark (international), set the domain to `lark` (or a full domain string). You can set it at `channels.feishu.domain` or per account (`channels.feishu.accounts.<id>.domain`).",
      "language": "unknown"
    },
    {
      "code": "***\n\n## Step 3: Start + test\n\n### 1. Start the gateway",
      "language": "unknown"
    },
    {
      "code": "### 2. Send a test message\n\nIn Feishu, find your bot and send a message.\n\n### 3. Approve pairing\n\nBy default, the bot replies with a pairing code. Approve it:",
      "language": "unknown"
    },
    {
      "code": "After approval, you can chat normally.\n\n***\n\n## Overview\n\n* **Feishu bot channel**: Feishu bot managed by the gateway\n* **Deterministic routing**: replies always return to Feishu\n* **Session isolation**: DMs share a main session; groups are isolated\n* **WebSocket connection**: long connection via Feishu SDK, no public URL needed\n\n***\n\n## Access control\n\n### Direct messages\n\n* **Default**: `dmPolicy: \"pairing\"` (unknown users get a pairing code)\n* **Approve pairing**:",
      "language": "unknown"
    },
    {
      "code": "* **Allowlist mode**: set `channels.feishu.allowFrom` with allowed Open IDs\n\n### Group chats\n\n**1. Group policy** (`channels.feishu.groupPolicy`):\n\n* `\"open\"` = allow everyone in groups (default)\n* `\"allowlist\"` = only allow `groupAllowFrom`\n* `\"disabled\"` = disable group messages\n\n**2. Mention requirement** (`channels.feishu.groups.<chat_id>.requireMention`):\n\n* `true` = require @mention (default)\n* `false` = respond without mentions\n\n***\n\n## Group configuration examples\n\n### Allow all groups, require @mention (default)",
      "language": "unknown"
    },
    {
      "code": "### Allow all groups, no @mention required",
      "language": "unknown"
    },
    {
      "code": "### Allow specific users in groups only",
      "language": "unknown"
    },
    {
      "code": "***\n\n## Get group/user IDs\n\n### Group IDs (chat\\_id)\n\nGroup IDs look like `oc_xxx`.\n\n**Method 1 (recommended)**\n\n1. Start the gateway and @mention the bot in the group\n2. Run `openclaw logs --follow` and look for `chat_id`\n\n**Method 2**\n\nUse the Feishu API debugger to list group chats.\n\n### User IDs (open\\_id)\n\nUser IDs look like `ou_xxx`.\n\n**Method 1 (recommended)**\n\n1. Start the gateway and DM the bot\n2. Run `openclaw logs --follow` and look for `open_id`\n\n**Method 2**\n\nCheck pairing requests for user Open IDs:",
      "language": "unknown"
    },
    {
      "code": "***\n\n## Common commands\n\n| Command   | Description       |\n| --------- | ----------------- |\n| `/status` | Show bot status   |\n| `/reset`  | Reset the session |\n| `/model`  | Show/switch model |\n\n> Note: Feishu does not support native command menus yet, so commands must be sent as text.\n\n## Gateway management commands\n\n| Command                    | Description                   |\n| -------------------------- | ----------------------------- |\n| `openclaw gateway status`  | Show gateway status           |\n| `openclaw gateway install` | Install/start gateway service |\n| `openclaw gateway stop`    | Stop gateway service          |\n| `openclaw gateway restart` | Restart gateway service       |\n| `openclaw logs --follow`   | Tail gateway logs             |\n\n***\n\n## Troubleshooting\n\n### Bot does not respond in group chats\n\n1. Ensure the bot is added to the group\n2. Ensure you @mention the bot (default behavior)\n3. Check `groupPolicy` is not set to `\"disabled\"`\n4. Check logs: `openclaw logs --follow`\n\n### Bot does not receive messages\n\n1. Ensure the app is published and approved\n2. Ensure event subscription includes `im.message.receive_v1`\n3. Ensure **long connection** is enabled\n4. Ensure app permissions are complete\n5. Ensure the gateway is running: `openclaw gateway status`\n6. Check logs: `openclaw logs --follow`\n\n### App Secret leak\n\n1. Reset the App Secret in Feishu Open Platform\n2. Update the App Secret in your config\n3. Restart the gateway\n\n### Message send failures\n\n1. Ensure the app has `im:message:send_as_bot` permission\n2. Ensure the app is published\n3. Check logs for detailed errors\n\n***\n\n## Advanced configuration\n\n### Multiple accounts",
      "language": "unknown"
    }
  ],
  "headings": [
    {
      "level": "h2",
      "text": "Plugin required",
      "id": "plugin-required"
    },
    {
      "level": "h2",
      "text": "Quickstart",
      "id": "quickstart"
    },
    {
      "level": "h3",
      "text": "Method 1: onboarding wizard (recommended)",
      "id": "method-1:-onboarding-wizard-(recommended)"
    },
    {
      "level": "h3",
      "text": "Method 2: CLI setup",
      "id": "method-2:-cli-setup"
    },
    {
      "level": "h2",
      "text": "Step 1: Create a Feishu app",
      "id": "step-1:-create-a-feishu-app"
    },
    {
      "level": "h3",
      "text": "1. Open Feishu Open Platform",
      "id": "1.-open-feishu-open-platform"
    },
    {
      "level": "h3",
      "text": "2. Create an app",
      "id": "2.-create-an-app"
    },
    {
      "level": "h3",
      "text": "3. Copy credentials",
      "id": "3.-copy-credentials"
    },
    {
      "level": "h3",
      "text": "4. Configure permissions",
      "id": "4.-configure-permissions"
    },
    {
      "level": "h3",
      "text": "5. Enable bot capability",
      "id": "5.-enable-bot-capability"
    },
    {
      "level": "h3",
      "text": "6. Configure event subscription",
      "id": "6.-configure-event-subscription"
    },
    {
      "level": "h3",
      "text": "7. Publish the app",
      "id": "7.-publish-the-app"
    },
    {
      "level": "h2",
      "text": "Step 2: Configure OpenClaw",
      "id": "step-2:-configure-openclaw"
    },
    {
      "level": "h3",
      "text": "Configure with the wizard (recommended)",
      "id": "configure-with-the-wizard-(recommended)"
    },
    {
      "level": "h3",
      "text": "Configure via config file",
      "id": "configure-via-config-file"
    },
    {
      "level": "h3",
      "text": "Configure via environment variables",
      "id": "configure-via-environment-variables"
    },
    {
      "level": "h3",
      "text": "Lark (global) domain",
      "id": "lark-(global)-domain"
    },
    {
      "level": "h2",
      "text": "Step 3: Start + test",
      "id": "step-3:-start-+-test"
    },
    {
      "level": "h3",
      "text": "1. Start the gateway",
      "id": "1.-start-the-gateway"
    },
    {
      "level": "h3",
      "text": "2. Send a test message",
      "id": "2.-send-a-test-message"
    },
    {
      "level": "h3",
      "text": "3. Approve pairing",
      "id": "3.-approve-pairing"
    },
    {
      "level": "h2",
      "text": "Overview",
      "id": "overview"
    },
    {
      "level": "h2",
      "text": "Access control",
      "id": "access-control"
    },
    {
      "level": "h3",
      "text": "Direct messages",
      "id": "direct-messages"
    },
    {
      "level": "h3",
      "text": "Group chats",
      "id": "group-chats"
    },
    {
      "level": "h2",
      "text": "Group configuration examples",
      "id": "group-configuration-examples"
    },
    {
      "level": "h3",
      "text": "Allow all groups, require @mention (default)",
      "id": "allow-all-groups,-require-@mention-(default)"
    },
    {
      "level": "h3",
      "text": "Allow all groups, no @mention required",
      "id": "allow-all-groups,-no-@mention-required"
    },
    {
      "level": "h3",
      "text": "Allow specific users in groups only",
      "id": "allow-specific-users-in-groups-only"
    },
    {
      "level": "h2",
      "text": "Get group/user IDs",
      "id": "get-group/user-ids"
    },
    {
      "level": "h3",
      "text": "Group IDs (chat\\_id)",
      "id": "group-ids-(chat\\_id)"
    },
    {
      "level": "h3",
      "text": "User IDs (open\\_id)",
      "id": "user-ids-(open\\_id)"
    },
    {
      "level": "h2",
      "text": "Common commands",
      "id": "common-commands"
    },
    {
      "level": "h2",
      "text": "Gateway management commands",
      "id": "gateway-management-commands"
    },
    {
      "level": "h2",
      "text": "Troubleshooting",
      "id": "troubleshooting"
    },
    {
      "level": "h3",
      "text": "Bot does not respond in group chats",
      "id": "bot-does-not-respond-in-group-chats"
    },
    {
      "level": "h3",
      "text": "Bot does not receive messages",
      "id": "bot-does-not-receive-messages"
    },
    {
      "level": "h3",
      "text": "App Secret leak",
      "id": "app-secret-leak"
    },
    {
      "level": "h3",
      "text": "Message send failures",
      "id": "message-send-failures"
    },
    {
      "level": "h2",
      "text": "Advanced configuration",
      "id": "advanced-configuration"
    },
    {
      "level": "h3",
      "text": "Multiple accounts",
      "id": "multiple-accounts"
    },
    {
      "level": "h3",
      "text": "Message limits",
      "id": "message-limits"
    },
    {
      "level": "h3",
      "text": "Streaming",
      "id": "streaming"
    },
    {
      "level": "h2",
      "text": "Configuration reference",
      "id": "configuration-reference"
    },
    {
      "level": "h2",
      "text": "dmPolicy reference",
      "id": "dmpolicy-reference"
    },
    {
      "level": "h2",
      "text": "Supported message types",
      "id": "supported-message-types"
    },
    {
      "level": "h3",
      "text": "Receive",
      "id": "receive"
    },
    {
      "level": "h3",
      "text": "Send",
      "id": "send"
    }
  ],
  "url": "llms-txt#feishu-bot",
  "links": []
}