Connect OpenClaw to Feishu/Lark in 10 Minutes

What You'll Learn

This tutorial walks you through integrating OpenClaw—an open-source AI orchestration framework—with Feishu (or Lark, ByteDance's international collaboration platform) in under 10 minutes. You'll learn how to set up a serverless AI bot using WebSocket connections that bypasses the need for public IPs, port forwarding, or domain configuration. By the end, you'll have a fully functional AI assistant responding to messages in Feishu/Lark group chats and direct messages.

Prerequisites

• OpenClaw installed locally — requires Python 3.8+ and the OpenClaw CLI (install via pip install openclaw)
• Feishu/Lark workspace access — you'll need admin or developer permissions to create a custom app
• Basic CLI familiarity — you'll execute 3-4 command-line commands
• App ID and App Secret credentials — generated in the next section
• An AI model API key — OpenClaw supports OpenAI, Claude, Ollama, and 20+ other providers
• Network connectivity — outbound HTTPS access to Feishu's servers (no inbound ports required)

Why This Matters

Most Feishu bot integrations require webhooks, which demand publicly accessible endpoints. This creates deployment friction: you need a domain, SSL certificate, and network configuration. OpenClaw's built-in WebSocket plugin inverts this architecture—your local machine pulls messages instead of Feishu pushing them. This approach is production-grade (it handles ~90% of real-world use cases according to the OpenClaw community) while remaining trivial to deploy. You can run this on a laptop, in a Docker container, or on a $5/month VPS.

Step-by-Step Integration Guide

Step 1: Create a Feishu/Lark Custom App (2 minutes)

Navigate to the Feishu Developer Console (open.feishu.cn for China, open.larksuite.com for international Lark). If you don't see a Developer Console option, you likely need tenant admin permissions—request access from your workspace admin.

1. Click Create Custom App
2. Name it something descriptive like "OpenClaw AI Assistant"
3. In the resulting app dashboard, locate your App ID and App Secret under Credentials & Basic Info. Copy both—you'll need them in Step 5.

Checkpoint: You should have a string like cli_a1b2c3d4e5f6g7h8 (App ID) and J8h7G6f5E4d3C2b1A0z (App Secret).

Step 2: Enable Required Permissions (2 minutes)

OpenClaw's Feishu plugin needs explicit permission scopes. Rather than clicking individual toggles, Feishu offers a batch import option that's faster and error-resistant.

1. In your app dashboard, go to Permission Management
2. Find Batch Enable (usually a button or option in the Scopes section)
3. Paste this JSON block:

   {
     "scopes": [
       "im:message:send_as_bot",
       "im:message:receive",
       "im:message",
       "chat:read",
       "contact:user:readonly"
     ]
   }

4. Submit. Feishu will confirm all scopes are now enabled.

These five scopes cover message sending/receiving, basic user info access, and chat reading—everything OpenClaw needs for messaging and light context retrieval.

Step 3: Enable Bot Capabilities & Event Subscriptions (3 minutes)

This step is where most integrations fail silently. You need to explicitly enable the WebSocket event subscription, or users will see an empty input box when opening a chat with your bot.

1. Go to App Capabilities (or Features in some Feishu versions)
2. Toggle Bot to enabled
3. Under Bot Configuration, find Event Subscriptions and toggle it on
4. In Connection Mode, select Long Connection (WebSocket) — this is crucial. Do not select webhook/HTTP callback.
5. Under Event Types, add the event im.message.receive_v1 (required for receiving direct and group messages)
6. Optionally add im.message.receive_edited_v1 if you want to handle message edits

Why Step 3 is Critical: When users try to message your bot, Feishu checks if it has an active WebSocket connection. Without event subscriptions enabled, the connection never establishes, and Feishu hides the input box. Users see "App has not established a long connection"—a message that looks like an error on your end but is actually a Feishu UI response to a misconfigured app.

Step 4: Publish Your App Version (1 minute)

Feishu apps exist in draft status by default and won't actually work until published. For internal enterprise apps (apps only accessible to your tenant), approval is instant if you have admin rights.

1. Go to Version Management
2. Click Create Version (or Create Release)
3. Fill in a version number (e.g., "1.0.0") and release notes
4. Submit for Review
5. If you're the tenant admin or have approval rights, the status will change to Approved within seconds

If you're not the admin, the review may take 1-24 hours depending on your organization's review queue. Until this step is complete, OpenClaw won't be able to send messages (the bot will receive them but fail at response time).

Step 5: Configure OpenClaw with Feishu Credentials (2 minutes)

Now you'll tell OpenClaw about your Feishu app. There are two approaches: CLI or direct JSON editing. The CLI approach is safer because it validates your input.

Approach A: Using the CLI (recommended)

1. Open your terminal and run:

   openclaw channels add

2. When prompted, select feishu
3. Paste your App ID when asked
4. Paste your App Secret when asked
5. When asked for domain, enter feishu (or lark if using international Lark)
6. For connection mode, confirm websocket is selected
7. OpenClaw will validate the credentials immediately. If it succeeds, you'll see a confirmation.

Approach B: Manual JSON Configuration

If the CLI method fails or you prefer direct editing, edit ~/.openclaw/openclaw.json (or C:\Users\YourUser\.openclaw\openclaw.json on Windows) and add this block inside the channels object:

"feishu": 

Save the file. The streaming: true option enables real-time token streaming (messages appear as the AI generates them, not all at once)—set to false if your AI provider doesn't support streaming.

Step 6: Start OpenClaw and Approve the Pairing (2 minutes)

OpenClaw uses a pairing mechanism to confirm your bot is authorized. This is a safety feature that prevents accidental API key exposure.

1. In your terminal, start the OpenClaw gateway:

   openclaw gateway

2. Watch for output showing the Feishu channel is initializing. You should see a WebSocket connection status message.
3. In a new terminal, approve the pairing:

   openclaw pairing approve feishu

4. This generates a pairing code. OpenClaw will prompt you to send this code to the bot in Feishu or to approve it via CLI. Use the CLI option:

   openclaw pairing approve feishu --code YOUR_CODE

5. Once approved, the bot is live. Send a test message to your bot in Feishu—it should respond with a confirmation.

Checkpoint: Your terminal should show:
✓ Feishu channel connected (WebSocket)
✓ Bot pairing approved

Advanced Configuration: Group Chats & Multi-Agent Routing

How to Enable Group Chat Support

By default, OpenClaw responds to all messages. To fine-tune this, you can set a group policy. In your openclaw.json, add a bindings section under your Feishu account:

"bindings": 

groupPolicy: "open" means the bot responds to all groups it's added to. Set to "closed" if you want to whitelist specific groups. The requiresMention flag controls whether users must @mention the bot; agent routes the group to a different AI agent (useful if you have multiple agents configured in OpenClaw).

Enabling Streaming Responses

By default, the bot waits for the full AI response before sending. For long outputs, this can feel slow. Set "streaming": true to send tokens as they arrive (like ChatGPT's web UI). Your AI provider must support streaming—OpenAI, Claude, and Ollama all do.

Troubleshooting Common Issues

Problem: No Input Box Appears When Opening a Chat with the Bot

Cause: Event subscriptions not enabled, or the app is still in draft status.

Solution:

• Go back to Step 3 and verify im.message.receive_v1 is in your Event Types list
• Go to Step 4 and confirm your app version is Approved (not "In Review" or "Draft")
• Reload Feishu in your browser (Cmd+R or Ctrl+F5)

Problem: "App Has Not Established a Long Connection" Error

Cause: OpenClaw gateway isn't running or WebSocket connection is failing.

Solution:

• Verify openclaw gateway is running in a terminal (not backgrounded)
• Check your App ID and App Secret are correct (copy-paste from Feishu dashboard again)
• Restart the gateway: Ctrl+C to stop, then openclaw gateway to restart
• Check your firewall allows outbound HTTPS on port 443 (this is standard for almost all networks)
• Verify connectionMode is set to "websocket" in your config, not "webhook"

Problem: Bot Receives Messages but Doesn't Respond

Cause: Missing im:message:send_as_bot permission, or the app version isn't published.

Solution:

• Go to Step 2 and re-verify all five scopes are enabled. Feishu sometimes doesn't apply batch imports fully; toggle im:message:send_as_bot off and on manually.
• Ensure your app version is published (Step 4). Draft versions can receive messages but can't send them.
• Check OpenClaw's error logs: run openclaw gateway --debug and look for permission-related errors

Problem: Slow Response Times or Timeout Errors

Cause: AI model API latency or OpenClaw's timeout settings.

Solution:

• Check your AI provider's status page (OpenAI, Anthropic, etc.)
• If using a local LLM (Ollama), ensure it has enough resources (GPU/memory)
• Increase OpenClaw's timeout in openclaw.json:

  "feishu": {
    "timeout": 30,
    "streaming": true
  }

  (Default is 10 seconds; adjust based on your model's speed)

Problem: Bot Doesn't See Historical Messages or Context

Cause: OpenClaw's Feishu plugin (basic version) only processes real-time incoming messages, not history.

Solution: If you need full conversation history and access to Feishu's calendar, docs, and tasks, you'll need the official ByteDance Feishu plugin (more complex setup, but provides workspace-wide integrations). For typical AI chatbot use cases, real-time messaging is sufficient—the AI maintains conversation context within its token window during a single session.

Best Practices for Production Deployments

1. Run OpenClaw as a Persistent Service

Don't leave OpenClaw running in a terminal window. Use a process manager to keep it alive:

On Linux/Mac with systemd: Create /etc/systemd/system/openclaw.service:

[Unit]
Description=OpenClaw AI Gateway
After=network.target

[Service]
Type=simple
User=openclaw
ExecStart=/usr/local/bin/openclaw gateway
Restart=always
RestartSec=10
[Install]
WantedBy=multi-user.target

Then enable it: sudo systemctl enable openclaw && sudo systemctl start openclaw

On Windows: Use NSSM (Non-Sucking Service Manager) or Task Scheduler to run openclaw gateway at startup.

In Docker: Wrap OpenClaw in a Docker container with a restart policy:

docker run --restart always -v ~/.openclaw:/root/.openclaw openclaw:latest gateway

2. Rotate Credentials Periodically

Feishu lets you rotate App Secrets without downtime. Every 6-12 months, generate a new secret in the Feishu dashboard, update it in your OpenClaw config, and delete the old one. This limits the impact if credentials are ever exposed.

3. Monitor Gateway Logs

OpenClaw writes logs to ~/.openclaw/logs/. Monitor these for errors or disconnections:

tail -f ~/.openclaw/logs/feishu.log

Set up alerting if you're relying on the bot for production workflows.

4. Test with Dry Messages First

Before rolling out to production users, send 5-10 test messages covering:

• Simple factual questions (to test the AI integration)
• Multi-turn conversations (to verify context is maintained)
• Messages with special characters or emojis (rare but can cause issues)
• Very long prompts (to check if OpenClaw respects Feishu's message length limits, typically 4000 characters)

5. Set Clear User Expectations

Document for your users:

• Response time (typically 2-10 seconds depending on AI model)
• What the bot can and cannot do (it's an AI, not a database—don't expect it to retrieve confidential records)
• Privacy: which messages the bot sees and whether they're logged
• Rate limits: OpenClaw doesn't enforce them by default, but your AI provider might

Next Steps & Advanced Topics

Integrate Your Own Data

OpenClaw supports RAG (Retrieval-Augmented Generation) plugins. You can connect the bot to your knowledge base, documentation, or database so it can answer company-specific questions. See openclaw-rag-setup for a guide.

Use the Official Feishu Plugin for Workspace Access

If you need the bot to access Feishu Calendar, Docs, Sheets, or Tasks, the official ByteDance Feishu plugin provides deeper workspace integration. Setup is more involved (~30 minutes), but it unlocks use cases like "summarize all tasks assigned to me this week" or "find the meeting notes from yesterday's product meeting." See the official OpenClaw Feishu/Lark integration guide linked in the resources below.

Scale to Multiple Agents

OpenClaw supports running multiple AI agents simultaneously, each with different personalities or capabilities. You can route different groups or channels to different agents using the agent field in your config. This is useful for separating customer support from internal Q&A, or running a specialized agent for code questions.

Set Up Monitoring & Alerting

For production bots, integrate OpenClaw's metrics export into Prometheus or Datadog to monitor:
- Connection uptime
- Message latency
- Error rates
- API quota usage
See OpenClaw's observability documentation for integration steps.

Summary

You've successfully integrated an AI-powered bot into Feishu using OpenClaw. Here's what you accomplished:

• Created a Feishu custom app with proper permissions and WebSocket event subscriptions—the foundation of your bot
• Configured OpenClaw to connect via WebSocket, eliminating the need for public IPs, domain names, or port forwarding
• Deployed a fully functional AI assistant that responds to direct messages and group chats in real-time
• Learned production best practices for persistence, monitoring, and scaling

The entire process took under 10 minutes because OpenClaw abstracts away the infrastructure complexity. Your bot is now running outbound WebSocket connections (pulling messages from Feishu), which is inherently more reliable than webhook-based approaches that require inbound networking configuration.

From here, you can customize the bot's behavior by connecting it to RAG systems, scaling to multiple agents, or integrating with your company's internal tools. OpenClaw supports 50+ channels (Telegram, Discord, WhatsApp, Slack, Teams, etc.), so if you want to deploy the same bot across multiple platforms, you're one config change away.

Troubleshooting Reminder: If something breaks, the most common culprits are:
1. Event subscriptions not enabled (Step 3)
2. App version not published (Step 4)
3. Missing im:message:send_as_bot permission (Step 2)

Circle back to these three items before diving into logs or advanced debugging.

Resources:
openai-integration-openclaw
openclaw-discord-setup
Official OpenClaw Docs: https://docs.open-claw.me
Full Feishu Integration Guide: https://open-claw.me/en/blog/openclaw-feishu-integration-guide