openclaw/docs/channels/feishu.md

summary	read_when
Feishu (Lark) bot support, capabilities, and configuration	Working on Feishu features or webhooks Integrating with Chinese enterprise messaging

Feishu (飞书/Lark)

Status: experimental. Supports direct messages and groups via Bot API.

Plugin required

Feishu ships as a plugin and is not bundled with the core install.

• Install via CLI: clawdbot plugins install @clawdbot/feishu
• Or select Feishu during onboarding and confirm the install prompt
• Details: Plugins

Quick setup (beginner)

1. Install the Feishu plugin:
   • From a source checkout: clawdbot plugins install ./extensions/feishu
   • From npm (if published): clawdbot plugins install @clawdbot/feishu
   • Or pick Feishu in onboarding and confirm the install prompt
2. Create an app in Feishu Open Platform and get App ID + App Secret
3. Set the credentials:
   • Env: FEISHU_APP_ID=... and FEISHU_APP_SECRET=...
   • Or config: channels.feishu.appId and channels.feishu.appSecret
4. Configure event subscription in Feishu console with your webhook URL
5. Restart the gateway (or finish onboarding)
6. DM access is pairing by default; approve the pairing code on first contact

Minimal config:

{
  channels: {
    feishu: {
      enabled: true,
      appId: "cli_xxxxxxxxxx",
      appSecret: "xxxxxxxxxxxxxxxxxxxxxxxx",
      verificationToken: "xxxxxxxxxxxxxxxxxxxxxxxx",
      webhookPath: "/feishu/callback",
      dmPolicy: "pairing"
    }
  }
}

What it is

Feishu (飞书) is an enterprise collaboration platform by ByteDance, also known as Lark internationally. Its Bot API allows the Gateway to run a bot for 1:1 conversations and group chats.

• A Feishu Bot API channel owned by the Gateway
• Deterministic routing: replies go back to Feishu; the model never chooses channels
• DMs share the agent's main session
• Groups require @mention by default

Setup (fast path)

1) Create an app in Feishu Open Platform

1. Go to https://open.feishu.cn/app and sign in
2. Click "Create App" and choose "Enterprise Self-built App"
3. Fill in the basic information (name, description, icon)
4. Add Bot capability in "Add Application Capabilities"
5. Go to "Credentials and Basic Info" to get your App ID and App Secret

2) Configure permissions

1. Go to "Permission Management" in your app
2. Add at least these permissions:
   • im:message - Send messages
   • im:message.receive_v1 - Receive messages (event subscription)
   • im:chat - Access chat information
   • contact:user.id:readonly - Read user info (optional, for name display)
3. Request approval if required by your organization

3) Configure event subscription

1. Go to "Events and Callbacks" page
2. Choose "Request URL Mode" (webhook)
3. Enter your webhook URL: https://your-gateway-host/feishu/callback
4. Copy the Verification Token and optionally the Encrypt Key
5. Add event subscription: im.message.receive_v1 (Receive messages)
6. Click Save

4) Configure the token (env or config)

Example:

{
  channels: {
    feishu: {
      enabled: true,
      appId: "cli_xxxxxxxxxx",
      appSecret: "xxxxxxxxxxxxxxxxxxxxxxxx",
      verificationToken: "xxxxxxxxxxxxxxxxxxxxxxxx",
      encryptKey: "xxxxxxxxxxxxxxxxxxxxxxxx",  // optional, for encrypted events
      webhookPath: "/feishu/callback",
      dmPolicy: "pairing"
    }
  }
}

Env option (works for the default account only):

• FEISHU_APP_ID=cli_xxxxxxxxxx
• FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxxxxxxxx
• FEISHU_VERIFICATION_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxx
• FEISHU_ENCRYPT_KEY=xxxxxxxxxxxxxxxxxxxxxxxx

Multi-account support: use channels.feishu.accounts with per-account credentials and optional name.

5) Publish the app

1. Go to "Version Management and Release"
2. Create a new version
3. Submit for review (or use within your organization if no review required)
4. Once approved, the bot is ready to use

6) Start the gateway

Restart the gateway. Feishu starts when credentials are resolved. DM access defaults to pairing. Approve the code when the bot is first contacted.

How it works (behavior)

• Inbound messages arrive via webhook (Feishu sends HTTP POST to your configured path)
• The gateway verifies the request using the verification token
• Messages are normalized into the shared channel envelope
• Replies always route back to the same Feishu chat
• Long responses are chunked to 4000 characters (Feishu API limit)

Limits

• Outbound text is chunked to 4000 characters (Feishu API limit)
• Media downloads/uploads are capped by channels.feishu.mediaMaxMb (default 20)
• Streaming is blocked by default due to webhook-based architecture
• Rate limits apply per the Feishu API documentation

Access control (DMs)

DM access

• Default: channels.feishu.dmPolicy = "pairing". Unknown senders receive a pairing code; messages are ignored until approved (codes expire after 1 hour)
• Approve via:
  • clawdbot pairing list feishu
  • clawdbot pairing approve feishu <CODE>
• Pairing is the default token exchange. Details: Pairing
• channels.feishu.allowFrom accepts Feishu user IDs (open_id like ou_xxx or user_id)

Group access

• Default: channels.feishu.groupPolicy = "allowlist". Only groups in the allowlist receive responses
• Configure allowed groups via channels.feishu.groupAllowFrom or channels.feishu.groups
• Groups require @mention by default; configure per-group via channels.feishu.groups.<chat_id>.requireMention

Webhook verification

Feishu uses two verification mechanisms:

1. URL Verification: When you first configure the webhook, Feishu sends a challenge request. The gateway responds automatically.
2. Event Verification: Each event includes a token field that must match your verification token.

Optional encryption:

• If you enable encryption in Feishu console, set channels.feishu.encryptKey
• Events are encrypted with AES-256-CBC; the gateway decrypts them automatically

Supported message types

• Text messages: Full support with 4000 character chunking
• Image messages: Logged but media upload requires image_key (planned)
• Rich text (post): Planned support
• Interactive cards: Planned support

Capabilities

Feature	Status
Direct messages	Supported
Groups	Supported
Media (images)	Partial (text only for now)
Reactions	Not supported
Threads	Not supported
Polls	Not supported
Native commands	Not supported
Streaming	Blocked (webhook-based)
Rich cards	Planned

Delivery targets (CLI/cron)

• Use an open_id, user_id, or chat_id as the target
• Example: clawdbot message send --channel feishu --target ou_xxxxxxxxxx --message "hi"
• For groups: clawdbot message send --channel feishu --target oc_xxxxxxxxxx --message "hi"

Troubleshooting

Bot does not respond:

• Check that the app credentials are valid: clawdbot channels status --probe
• Verify the webhook URL is correctly configured in Feishu console
• Check that the verification token matches
• Verify the sender is approved (pairing or allowFrom)
• Check gateway logs: clawdbot logs --follow

Webhook verification fails:

• Ensure your gateway is publicly accessible at the configured webhook path
• Check that channels.feishu.verificationToken matches the token in Feishu console
• If using encryption, verify channels.feishu.encryptKey is correct

Permission errors:

• Ensure the app has required permissions (im:message, im:message.receive_v1)
• Check if permissions need admin approval in your organization
• Verify the app is published and active

Cannot send messages:

• Check that the bot has been added to the chat (for groups)
• Verify the target ID format (open_id starts with ou_, chat_id starts with oc_)
• Check API quota limits

Configuration reference (Feishu)

Full configuration: Configuration

Provider options:

• channels.feishu.enabled: enable/disable channel startup
• channels.feishu.appId: App ID from Feishu Open Platform
• channels.feishu.appSecret: App Secret from Feishu Open Platform
• channels.feishu.appSecretFile: read app secret from file path
• channels.feishu.verificationToken: verification token for webhook validation
• channels.feishu.encryptKey: encrypt key for event decryption (optional)
• channels.feishu.webhookPath: webhook path on the gateway HTTP server (default: /feishu/callback)
• channels.feishu.dmPolicy: pairing | allowlist | open | disabled (default: pairing)
• channels.feishu.allowFrom: DM allowlist (open_id or user_id). open requires "*"
• channels.feishu.groupPolicy: open | allowlist (default: allowlist)
• channels.feishu.groupAllowFrom: group allowlist (chat_id)
• channels.feishu.groups: per-group configuration
• channels.feishu.mediaMaxMb: inbound/outbound media cap (MB, default 20)

Multi-account options:

• channels.feishu.accounts.<id>.appId: per-account App ID
• channels.feishu.accounts.<id>.appSecret: per-account App Secret
• channels.feishu.accounts.<id>.appSecretFile: per-account secret file
• channels.feishu.accounts.<id>.name: display name
• channels.feishu.accounts.<id>.enabled: enable/disable account
• channels.feishu.accounts.<id>.dmPolicy: per-account DM policy
• channels.feishu.accounts.<id>.allowFrom: per-account allowlist
• channels.feishu.accounts.<id>.verificationToken: per-account verification token
• channels.feishu.accounts.<id>.encryptKey: per-account encrypt key
• channels.feishu.accounts.<id>.webhookPath: per-account webhook path

International users (Lark)

For Lark (international version), use the same configuration. The API endpoints are compatible. Consider using lark or fs as channel aliases in CLI commands:

• clawdbot message send --channel lark --target ou_xxx --message "hi"