DEV Community

sunyifu
sunyifu

Posted on

How I Connected an OpenClaw to Feishu/Lark in 10 Minutes (No Public IP Needed)

#ai #feishu #openclaw #tutorial

blog： https://open-claw.me/en/blog/openclaw-feishu-integration-guide

If you're using Feishu (or Lark, its international counterpart), here's how to connect an AI assistant using OpenClaw — without needing a public IP, domain, or any port forwarding.

OpenClaw's built-in Feishu plugin uses WebSocket by default. Your machine connects outbound to Feishu's servers, so NATs and firewalls aren't a problem.

Two Integration Options

Built-in Plugin Official Plugin
Maintained by OpenClaw community ByteDance (Feishu team)
Capabilities Messaging, basic doc reading Full workspace: docs, calendar, tasks, sheets, wiki
Complexity Moderate Higher
Best for Quick messaging setup Teams needing deep workspace access

This guide covers the built-in plugin, which handles ~90% of use cases.

Setup in 6 Steps

1. Create a Feishu/Lark App

Go to open.feishu.cn (or open.larksuite.com for Lark) → Developer Console → Create Custom App → grab your App ID and App Secret.

2. Configure Permissions

Use batch import — paste this JSON under Permission Management → Batch Enable:

{
  "scopes": {
    "tenant": [
      "im:chat", "im:message", "im:message:send_as_bot",
      "im:message.p2p_msg:readonly", "im:message.group_at_msg:readonly",
      "im:message.group_msg", "im:message:readonly", "im:resource",
      "im:chat.members:bot_access",
      "contact:user.employee_id:readonly",
      "docs:document.content:read", "sheets:spreadsheet",
      "wiki:wiki:readonly"
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

3. Enable Bot & Event Subscriptions

  • App Capabilities → Bot → Enable
  • Events & Callbacks → Event Subscriptions → select Long Connection (WebSocket)
  • Add event: im.message.receive_v1 (required)

⚠️ Without event subscriptions, the chat input box won't appear when users open a conversation with the bot. This is the #1 cause of "app has not established a long connection" errors.

4. Publish the App

Version Management → Create Version → Submit for Review. For internal enterprise apps, approval is usually instant if you're a tenant admin.

5. Configure OpenClaw 

openclaw channels add    # Select Feishu, paste credentials
openclaw gateway restart
Enter fullscreen mode Exit fullscreen mode

Or edit ~/.openclaw/openclaw.json directly:

{
  channels: {
    feishu: {
      enabled: true,
      domain: "feishu",        // "lark" for international
      connectionMode: "websocket",
      streaming: true,
      accounts: {
        main: {
          appId: "cli_xxx",
          appSecret: "your-secret",
          botName: "AI Assistant"
        }
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

6. Start & Pair 

openclaw gateway
openclaw pairing approve feishu <CODE>
Enter fullscreen mode Exit fullscreen mode

Send a message to the bot in Feishu → approve the pairing code → done.

Group Chat Support

Groups work out of the box with groupPolicy: "open". You can restrict to specific groups, control @mention requirements per group, and even route different groups to different AI agents:

{
  bindings: [
    { agentId: "main", match: { channel: "feishu", peer: { kind: "direct" } } },
    { agentId: "team-helper", match: { channel: "feishu", peer: { kind: "group", id: "oc_xxx" } } }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Common Issues

Problem Fix
No input box in chat Add im.message.receive_v1 event subscription
"App has not established a long connection" Restart gateway, verify App ID/Secret
Bot doesn't respond Publish the app (drafts don't work), check im:message:send_as_bot permission
Slow responses Enable streaming: true

Full Guide

For the complete walkthrough including webhook mode, the official Feishu plugin (full workspace access), multi-agent routing, and detailed troubleshooting:

👉 OpenClaw Feishu/Lark Integration Guide

OpenClaw supports 50+ channels — Feishu, Telegram, Discord, WhatsApp, Slack, and more. Check out the full channel list.

Top comments (0)