Feishu AI Bot Setup: Ultimate OpenClaw Group Chat Integration Guide

高效码农

3 hours ago

How to Set Up an AI Bot in Feishu Group Chat Using OpenClaw: A Complete Configuration Guide

“

This guide is based on a real configuration process, covering every step from creating a Feishu application to getting your AI bot to respond to group messages — including complete solutions to the most common errors.

Who Is This Guide For?

If you’re trying to connect an AI assistant to a Feishu (Lark) group chat so that team members can mention the bot directly in conversations, this article is worth reading from start to finish.

The tool used in this guide is OpenClaw — an open-source AI gateway — version 2026.3.8, integrated with Feishu using a self-built application. The overall setup isn’t overly complicated, but there are several places where things can easily go wrong. This guide addresses each one in detail.

Before You Begin: Getting OpenClaw Up and Running

What to Do When OpenClaw Throws an Error on Startup

After installing OpenClaw, you might run into the following error when executing a command:

Failed to start CLI: Error: Cannot find native binding.
npm has a bug related to optional dependencies.
Please try `npm i` again after removing both package-lock.json and node_modules directory.
    at Object.<anonymous> (/Users/kb/nodejs/lib/node_modules/openclaw/node_modules/@snazzah/davey/index.js:500:11)

This is a known npm bug. Here’s how to fix it:

Step 1 — Navigate to the OpenClaw global installation directory:

cd /Users/your-username/nodejs/lib/node_modules/openclaw

Step 2 — Remove the existing dependency folders:

rm -rf node_modules package-lock.json

Step 3 — Reinstall dependencies:

npm install

If that still doesn’t work, try a force install or switch to Yarn:

npm install --force
# or
yarn install

For the most thorough fix, completely uninstall and reinstall OpenClaw:

npm uninstall -g openclaw
npm install -g openclaw

Root Cause: npm occasionally skips the installation of optional dependencies that contain native bindings. Reinstalling from scratch usually resolves the issue.

Part 1: Creating a Feishu Application on the Developer Console

Step 1 — Create a Self-Built Application

Go to the Feishu Open Platform and click “Create Self-Built App”. Fill in the app name and description.

Once created, navigate to “Credentials & Basic Info” to find two critical pieces of information:

◉

App ID (format: cli_a93e9c50d978dcbd)
◉

App Secret

You’ll need both of these when configuring OpenClaw. Copy them somewhere safe.

Step 2 — Enable Bot Capability

In the application detail page, go to “App Capabilities” → “Bot” and toggle the switch on.

This step is frequently overlooked, but it’s a prerequisite for the bot to receive any messages at all.

Step 3 — Configure Permissions

Under “Permission Management”, add the following permissions:

Permission	Description
`im:message`	Basic messaging permission
`im:message.group_at_msg:readonly`	Receive group @ mention messages
`im:message.p2p_msg:readonly`	Receive direct messages
`im:message:send_as_bot`	Send messages as a bot
`im:chat.members:bot_access`	Allow bot to join group chats
`im:resource`	Access resources

Step 4 — Configure Event Subscriptions (Persistent Connection Method)

This is the single most important step in the entire setup. Most failed configurations trace back to this.

In your application’s “Events & Callbacks” section:

Select “Use Persistent Connection to Receive Events” — you don’t need to fill in a callback URL, and you don’t need a public IP address
Click “Add Event”, search for and subscribe to: im.message.receive_v1

“

Why use a persistent connection? OpenClaw’s Gateway defaults to listening only on localhost (loopback interface) and has no public-facing address. A WebSocket persistent connection allows Feishu’s servers to push messages to your local gateway without needing an exposed endpoint.

Step 5 — Publish the Application

After completing the configuration, go to “Version Management & Release”, create a new version, and submit for publication. Enterprise internal apps are usually approved quickly.

Part 2: Configuring OpenClaw

Where Is the Configuration File?

OpenClaw’s configuration file is located at:

~/.openclaw/openclaw.json

The Complete, Verified Configuration

Below is a complete configuration file that has been tested and confirmed to work correctly:

{
  "meta": {
    "lastTouchedVersion": "2026.3.8",
    "lastTouchedAt": "2026-03-13T14:39:07.080Z"
  },
  "wizard": {
    "lastRunAt": "2026-03-13T14:39:07.064Z",
    "lastRunVersion": "2026.3.8",
    "lastRunCommand": "configure",
    "lastRunMode": "local"
  },
  "auth": {
    "profiles": {
      "minimax-portal:default": {
        "provider": "minimax-portal",
        "mode": "oauth"
      }
    }
  },
  "models": {
    "providers": {
      "minimax-portal": {
        "baseUrl": "https://api.minimaxi.com/anthropic",
        "apiKey": "minimax-oauth",
        "api": "anthropic-messages",
        "models": [
          {
            "id": "MiniMax-M2.5",
            "name": "MiniMax M2.5",
            "reasoning": false,
            "input": ["text"],
            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
            "contextWindow": 200000,
            "maxTokens": 8192
          },
          {
            "id": "MiniMax-M2.5-highspeed",
            "name": "MiniMax M2.5 Highspeed",
            "reasoning": true,
            "input": ["text"],
            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
            "contextWindow": 200000,
            "maxTokens": 8192
          },
          {
            "id": "MiniMax-M2.5-Lightning",
            "name": "MiniMax M2.5 Lightning",
            "reasoning": true,
            "input": ["text"],
            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
            "contextWindow": 200000,
            "maxTokens": 8192
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "minimax-portal/MiniMax-M2.5"
      },
      "models": {
        "minimax-portal/MiniMax-M2.5": {
          "alias": "minimax-m2.5"
        }
      },
      "workspace": "/Users/kb/.openclaw/workspace",
      "compaction": {
        "mode": "safeguard"
      }
    }
  },
  "tools": {
    "profile": "full"
  },
  "commands": {
    "native": "auto",
    "nativeSkills": "auto",
    "restart": true,
    "ownerDisplay": "raw"
  },
  "session": {
    "dmScope": "per-channel-peer"
  },
  "channels": {
    "feishu": {
      "enabled": true,
      "groupPolicy": "open",
      "accounts": {
        "main": {
          "appId": "cli_a93e9c50d978dcbd",
          "appSecret": "your-app-secret-here",
          "dmPolicy": "pairing"
        }
      }
    }
  },
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "loopback",
    "auth": {
      "mode": "token",
      "token": "your-gateway-token"
    },
    "tailscale": {
      "mode": "off",
      "resetOnExit": false
    }
  },
  "plugins": {
    "entries": {
      "minimax-portal-auth": {
        "enabled": true
      },
      "feishu": {
        "enabled": true
      }
    }
  }
}

Understanding the Key Configuration Fields

groupPolicy controls how the bot responds to group messages. It accepts three values:

Value	Behavior
`"open"`	Allows all groups to trigger the bot (recommended)
`"allowlist"`	Only allows groups explicitly listed in `groupAllowFrom`
`"disabled"`	Completely disables group message handling

dmPolicy controls direct message behavior. Setting it to "pairing" means the bot requires pairing before accepting DMs.

“

⚠️ A very common mistake: Many users place dmPolicy inside a separate default account entry rather than inside the main account. This causes the Dashboard to display not configured for that account, and the bot will fail to connect to Feishu. Always put dmPolicy inside main.

Part 3: Adding the Bot to a Feishu Group Chat

Adding the Bot to an Internal Group

Open Feishu and navigate to your target group chat
Click the “···” icon in the top-right corner
Select “Settings”
Click “Group Bots”
Click “Add Bot” in the top-right corner of the panel
Search for your application name and click to add it

A single group supports up to 99 bots.

What About External Groups (Cross-Organization)?

If you need the bot to work in external groups (groups that include members from outside your organization), you’ll need to enable the “Open to External” sharing option:

◉

During publication in “Version Management & Release”, find and enable the “External Sharing” toggle
◉

Alternatively, go to “User Management → Available Scope” and enable the external user switch

“

Important note: Enabling external sharing requires an approval process and typically requires administrator-level permissions. Some developer accounts within an enterprise may not see this option at all. If you’re only using the bot in internal groups, you don’t need this step at all — skip it entirely.

Part 4: Troubleshooting — When the Bot Doesn’t Respond

You’ve set everything up, added the bot to the group, sent a message mentioning it — and nothing happens. This is the most common issue people run into. Work through the following steps in order.

Step 1 — Watch the Real-Time Log

Open a terminal and run:

openclaw logs --follow

Then go to the Feishu group and @ mention the bot. Watch the log output at the same time.

What you should see if things are working:

Approved feishu sender oc_xxxxxxxxxxxxxxxxxx

Pay close attention to the ID prefix:

◉

oc_ prefix = group chat ID ✅
◉

ou_ prefix = user ID (direct message) ❌

If you only see ou_ IDs in the log, it means the bot is receiving direct messages but not group messages. The group message pipeline isn’t connected.

Step 2 — Check the Gateway Dashboard

Open a browser and navigate to:

http://127.0.0.1:18789/

This is the OpenClaw Gateway Dashboard. Find the Feishu channel section and check the main account status:

Field	Expected Value	What It Means
Running	Yes	The Gateway process is active
Configured	Yes	App ID and App Secret are set
Connected	Yes (not n/a)	The persistent WebSocket connection is established

If Connected shows n/a, the persistent connection to Feishu has not been established. This means no messages can flow into OpenClaw at all, regardless of what you do in the group chat.

Step 3 — Verify Gateway Status from the CLI

openclaw gateway status

A healthy output looks like this:

Service: LaunchAgent (loaded)
Runtime: running (pid 58207)
RPC probe: ok
Listening: 127.0.0.1:18789

Step 4 — Re-verify Feishu Event Subscription Settings

Return to the Feishu Open Platform and double-check:

Under “Events & Callbacks”, the subscription method is set to “Persistent Connection” (NOT HTTP callback URL)
The event im.message.receive_v1 is in the subscribed events list
You’ve published a new version of the application after making any changes (configuration changes don’t take effect until the app is republished)

Step 5 — Restart the Gateway

openclaw gateway restart

After restarting, immediately watch the log:

openclaw logs --follow

You should see the Feishu channel reconnecting. If you see any error entries or repeated reconnecting messages, copy those log lines and use them to identify the specific issue.

Part 5: How to Find Your Group Chat ID

Some advanced configuration options require specifying a particular group’s ID (which starts with oc_). Here’s the most reliable way to get it:

Start log monitoring: openclaw logs --follow
Go to the target group in Feishu and @ mention the bot
Look in the log output for a line like: Approved feishu sender oc_xxxxxxxxxxxxxx
The full string starting with oc_ is your group chat ID

Using the Group ID for Fine-Grained Control

Once you have the group ID, you can apply specific settings to individual groups. For example, disabling the mention requirement:

"channels": {
  "feishu": {
    "groupPolicy": "open",
    "groups": {
      "oc_your_group_id_here": {
        "requireMention": false
      }
    },
    "accounts": {
      "main": {
        "appId": "cli_a93e9c50d978dcbd",
        "appSecret": "your-app-secret",
        "dmPolicy": "pairing"
      }
    }
  }
}

By default, requireMention is true, meaning the bot only responds when directly mentioned with @. Setting it to false means the bot will respond to every message in that group — use this setting with care, as it can become disruptive in active channels.

Part 6: Handling the `bindings` Configuration Error

When trying to add a bindings section to route group messages to a specific agent, you might encounter this error:

Failed to start CLI: Error: Invalid config at /Users/kb/.openclaw/openclaw.json:
- bindings.0: Invalid input

This happens because the bindings schema has version-specific requirements, and the format for matching group peers may not align with the current version’s validation rules.

The practical solution: Remove the bindings section entirely and rely on groupPolicy: "open" instead. For most use cases, this achieves the same result — the bot responds to all groups it has been added to — without requiring a manually crafted bindings configuration.

If you do need per-group routing (routing different groups to different agents), wait until you have successfully confirmed the basic setup is working, then consult the latest OpenClaw documentation for the correct bindings syntax for your version.

Part 7: Removing the Bot

Remove the Bot from a Group Chat

Open the group chat in Feishu
Click “···” in the top-right corner
Go to “Settings”
Click “Group Bots”
Find your bot, click the “···” button next to it
Select “Remove” and confirm

Remove the Bot from Your Contacts / DM List

In your message list, find the conversation with the bot, right-click and select “Delete Conversation”. To remove it entirely from your contacts, go to your Address Book, find the bot, right-click and select “Delete Contact”.

Disable Bot Capability in the Developer Console

Feishu doesn’t allow deleting just the bot — you can either disable the bot capability or delete the entire application:

To disable the bot capability:

Go to the Feishu Open Platform → your application
Navigate to “App Capabilities” → “Bot”
Toggle the switch off
Create and publish a new version for the change to take effect

To delete the entire application:
The application must be in an unpublished or deactivated state. Once it is, you’ll find a “Delete App” button at the bottom of the application detail page.

“

If you’re simply reconfiguring the bot, you don’t need to delete the application. Just update your settings, publish a new version, and the changes will take effect.

Frequently Asked Questions

Q: The bot was added to the group but there’s absolutely no response, and nothing shows up in the logs. What’s wrong?

The most likely cause is that Feishu event subscriptions aren’t configured. Go back to the Feishu Open Platform → your app → “Events & Callbacks”. Make sure you’ve selected Persistent Connection (not HTTP callback), that im.message.receive_v1 is in your subscribed events list, and that you’ve published a new version of the app after making these changes. Configuration changes in the developer console don’t take effect until you publish.

Q: The log shows ou_ IDs but no oc_ IDs. What does that mean?

ou_ is a user ID — it indicates a direct message. oc_ is a group chat ID. If you’re only seeing ou_ entries, the bot is receiving DMs but group messages aren’t reaching OpenClaw. Check that groupPolicy is set to "open" in your configuration and that the Feishu event subscription is correctly configured to handle group messages.

Q: The Dashboard shows Connected: n/a. How do I fix the persistent connection?

First, check whether there’s a default account entry in your channels.feishu.accounts configuration that shows not configured. A misconfigured account in the same channel can interfere with the connection. Remove the default account entirely, ensure only the properly configured main account remains, then restart the Gateway with openclaw gateway restart.

Q: I get an Invalid input error when using bindings configuration. How do I resolve this?

Remove the bindings section from your configuration. Use groupPolicy: "open" in the Feishu channel configuration instead. This allows the bot to respond in any group it’s been added to, which achieves the same end result for most standard setups. The bindings validation schema varies between versions, and an invalid format will prevent OpenClaw from starting.

Q: I see a warning about tools.profile containing unknown entries like apply_patch. Should I be concerned?

No. This is a warn-level log entry, not an error. It simply means your tools allowlist references tool names (apply_patch, cron, etc.) that haven’t been enabled as plugins in your current setup. The warning doesn’t affect normal bot operation or group message handling.

Q: What does fts unavailable: no such module: fts5 mean?

This warning means SQLite’s full-text search (FTS5) module is not available on your system. This affects OpenClaw’s memory and search features but does not impact basic group chat bot functionality. You can safely ignore it while getting the bot set up.

Q: Can the bot respond to everyone’s messages in the group, or only to @ mentions?

By default, the bot only responds when directly mentioned with @. This is controlled by the requireMention setting, which defaults to true. You can set it to false for specific groups using the group ID configuration shown in Part 5. Keep in mind that disabling the mention requirement means the bot will attempt to respond to every single message in that group.

Q: How many bots can be added to a single Feishu group?

A single Feishu group supports a maximum of 99 bots.

Q: I changed the App ID and App Secret in the config file. Do I need to restart the Gateway?

No — OpenClaw supports hot reloading for certain configuration changes, including App ID and App Secret updates. When you save the config file, the Gateway detects the change and automatically restarts the Feishu channel. You’ll see log entries like restarting feishu channel confirming this happened. A full Gateway restart isn’t required.

Summary: The Complete Setup Checklist

Here’s a condensed checklist of everything you need to do, in order:

On the Feishu Open Platform:

◉

[ ] Create a self-built application
◉

[ ] Enable the Bot capability under App Capabilities
◉

[ ] Add all required im:* permissions
◉

[ ] Subscribe to im.message.receive_v1 using Persistent Connection method
◉

[ ] Publish the application

In OpenClaw configuration (~/.openclaw/openclaw.json):

◉

[ ] Set appId and appSecret inside the main account (not in a default account)
◉

[ ] Set dmPolicy: "pairing" inside the main account
◉

[ ] Set groupPolicy: "open" in the Feishu channel config
◉

[ ] Remove any default account entry with no App ID/Secret
◉

[ ] Do not include bindings unless you’ve verified the correct format for your version

Verification:

◉

[ ] Run openclaw gateway status and confirm Runtime: running and RPC probe: ok
◉

[ ] Check the Dashboard at http://127.0.0.1:18789/ and confirm Connected: Yes for the main account
◉

[ ] Add the bot to a Feishu group
◉

[ ] Run openclaw logs --follow, @ mention the bot in the group, and confirm an oc_ ID appears in the log

The two places where configurations most commonly fail are: (1) Feishu’s event subscription not being set to persistent connection, and (2) the dmPolicy field being placed in the wrong account entry in the OpenClaw config. Follow the structure in this guide and both of those issues are avoided from the start.

This guide is based on a real configuration process using OpenClaw version 2026.3.8 and the Feishu Open Platform as of early 2026. For the most current configuration options, always refer to the official OpenClaw documentation at https://docs.openclaw.ai and the Feishu Open Platform documentation at https://open.feishu.cn/document/home/index.