# How to Install and Use Feishu Evolver Wrapper in OpenClaw

- Tool: OpenClaw
- Difficulty: Beginner
- Time required: 20 minutes
- Last updated: March 2026

## TL;DR

To use Feishu Evolver Wrapper in OpenClaw, run `clawhub install feishu-evolver-wrapper`, create a Feishu app with event subscription permissions at open.feishu.cn, configure your App ID, App Secret, and Evolver webhook settings in OpenClaw, and unlock advanced event-driven Feishu automation: multi-step bot workflows, message event triggers, and complex interaction patterns far beyond basic send/receive messaging.

## Advanced Feishu Automation with Evolver Middleware in OpenClaw

The feishu-bridge skill handles basic Feishu messaging — send a message here, receive one there. For many teams, that is enough. But when your automation needs become more complex — reacting to incoming messages, triggering workflows on specific events, managing multi-turn bot conversations, or chaining Feishu interactions with other tools — you need something more capable. That is what feishu-evolver-wrapper provides.

Evolver middleware sits between OpenClaw and the Feishu API, adding a stateful event layer. Instead of OpenClaw simply calling the Feishu API for one-shot operations, the Evolver layer subscribes to Feishu events (message received, user joined a group, reaction added, card button clicked) and fires corresponding OpenClaw workflows. This creates a genuine event-driven architecture: your Feishu workspace becomes an interactive surface that OpenClaw listens to and responds to intelligently, not just a passive notification target.

The practical difference from feishu-bridge is substantial. With feishu-bridge, you initiate all actions from OpenClaw chat. With feishu-evolver-wrapper, Feishu events can initiate OpenClaw actions — turning OpenClaw into a responsive bot that members of your Feishu workspace interact with on their own terms. Teams using Feishu for internal operations, customer support routing, or development workflows will find the Evolver layer essential for building genuinely interactive experiences rather than one-directional notification streams.

## Before you start

- OpenClaw installed and running (see openclaw.ai for installation instructions)
- ClawHub CLI available in your terminal (bundled with OpenClaw)
- A Feishu account with developer access to the Feishu Open Platform at open.feishu.cn
- Permission to configure event subscriptions in your Feishu app (requires app admin role)
- Familiarity with feishu-bridge basics is helpful but not required — this guide is self-contained

## Step-by-step guide

### 1. Install the Feishu Evolver Wrapper Skill via ClawHub

Open your terminal and run the clawhub install command below. The feishu-evolver-wrapper skill includes everything in feishu-bridge plus the Evolver middleware components — you do not need to install both skills separately. If you already have feishu-bridge installed, feishu-evolver-wrapper replaces it with a superset of functionality.

ClawHub downloads the skill package, verifies its signature, and registers it with your OpenClaw configuration. The installation takes 15-40 seconds. On completion, you will see a success message listing the installed version and the required configuration keys: FEISHU_APP_ID, FEISHU_APP_SECRET, and FEISHU_EVOLVER_VERIFICATION_TOKEN (for event subscription verification).

If you already have feishu-bridge installed, you can safely install feishu-evolver-wrapper alongside it — they are independent skills. However, for simplicity, most users choose to use one or the other rather than both simultaneously.

```
# Install feishu-evolver-wrapper
clawhub install feishu-evolver-wrapper

# Verify installation
clawhub list | grep feishu

# See all available config options
clawhub info feishu-evolver-wrapper
```

**Expected result:** Terminal shows 'feishu-evolver-wrapper@X.X.X installed successfully'. The skill appears in `clawhub list` output alongside any other installed skills.

### 2. Create and Configure a Feishu App with Event Subscriptions

Navigate to open.feishu.cn and log in. If you already created a Feishu app for feishu-bridge, you can extend that app with event subscription permissions. If starting fresh, click 'Create App' and follow the prompts to create a new In-House app.

In your app settings, navigate to 'Permissions & Scopes'. For the Evolver wrapper, you need a broader set of permissions than basic messaging: add `im:message` (read and send messages), `im:message.receive_v1` (receive message events), `im:chat` (manage chat membership), and `im:chat.member` (react to member join/leave events). Save your permission changes.

Next, go to 'Event Subscriptions' in your app settings. This is where you register the event types that Feishu will send to OpenClaw. Enable the event types relevant to your automation: `im.message.receive_v1` for incoming messages is the most common starting point. Feishu will ask for a 'Request URL' — this is the webhook endpoint where OpenClaw's Evolver middleware listens for events. For local OpenClaw instances, you will need a tunneling tool like ngrok to expose a public URL; for server-deployed OpenClaw, use your server's public URL.

Feishu's event subscription setup also generates an Encrypt Key and Verification Token — copy both, as you will need the Verification Token for OpenClaw configuration.

**Expected result:** Your Feishu app has event subscription permissions enabled. Feishu shows a 'Verification successful' status after you save the Request URL — this confirms Feishu can reach OpenClaw's Evolver webhook endpoint.

### 3. Configure Feishu and Evolver Credentials in OpenClaw

With your Feishu app credentials and Evolver Verification Token ready, configure all required values in OpenClaw. The feishu-evolver-wrapper needs three core variables: your Feishu App ID, your App Secret, and the Evolver Verification Token from the Event Subscriptions page.

Set all three using the `clawhub config set` command or by adding them to your `~/.openclaw/.env` file. The environment variable names must match exactly — incorrect names will cause silent failures where the skill installs but events do not trigger.

After setting all three values, run `clawhub reload` to apply the configuration. OpenClaw will start the Evolver middleware webhook listener on its configured port, which Feishu can now send events to. You can verify the webhook is running by checking OpenClaw's status output.

```
# Add to ~/.openclaw/.env
FEISHU_APP_ID=cli_your_app_id_here
FEISHU_APP_SECRET=your_app_secret_here
FEISHU_EVOLVER_VERIFICATION_TOKEN=your_verification_token_here

# Or set via clawhub config
clawhub config set FEISHU_APP_ID cli_your_app_id
clawhub config set FEISHU_APP_SECRET your_secret
clawhub config set FEISHU_EVOLVER_VERIFICATION_TOKEN your_token

# Apply and verify
clawhub reload
clawhub status feishu-evolver-wrapper
```

**Expected result:** `clawhub status feishu-evolver-wrapper` shows 'active' and 'webhook listening on port [N]'. All three config variables return masked values when queried.

### 4. Define and Test an Evolver Workflow from OpenClaw Chat

With the Evolver middleware running, you can now define event-triggered workflows directly from OpenClaw chat. The feishu-evolver-wrapper skill accepts workflow definitions in natural language and translates them into event subscription rules within the Evolver layer.

Start with a simple test: define a rule that responds to a specific message in a Feishu chat you have access to. Once the rule is defined, send the triggering message from your Feishu account and verify that OpenClaw responds through the Evolver middleware.

Evolver workflows support conditions, multi-step sequences, and state persistence within a conversation session. A 'conversation session' in Evolver terms is a series of message exchanges between one Feishu user and the OpenClaw bot within a time window — Evolver tracks context across these exchanges so your bot can ask follow-up questions, validate responses, and build up complex inputs before taking an action.

RapidDev can help configure complex Evolver workflow rules for enterprise teams building sophisticated Feishu automation — particularly useful for teams with conditional routing logic, integration with multiple back-end systems, and compliance requirements around message handling.

```
# Advanced Evolver skill configuration in ~/.openclaw/skills/feishu-evolver-wrapper.yaml
feishu-evolver-wrapper:
  webhook_port: 3100               # port for Feishu event webhook listener
  session_timeout_minutes: 10      # conversation session window for stateful workflows
  max_workflow_steps: 10           # max steps in a single triggered workflow
  default_response_format: "markdown"  # plain | markdown | card
  event_types:                     # event types to subscribe to
    - im.message.receive_v1
    - im.chat.member.user.added_v3
```

**Expected result:** Sending 'ping' to the OpenClaw bot in Feishu triggers an immediate 'pong' response from the bot within 2-5 seconds, confirming the Evolver middleware is receiving events and executing workflows.

### 5. Build a Multi-Step Workflow with Conditional Logic

Now that basic event triggering works, extend your automation to include multi-step logic with conditions. Evolver workflows can branch based on message content, user attributes, or time conditions — giving you the ability to build intelligent routing and response systems inside Feishu.

A common pattern is a triage bot: a team member mentions a keyword in a channel, the Evolver trigger fires, OpenClaw evaluates the message content to determine priority, and routes to a different response or escalation path based on the evaluation. This replaces manual triage work with an automated first pass that humans then review.

Define your conditional workflow in OpenClaw chat using natural language. Be explicit about the branching conditions — the more specific your description of the decision logic, the more accurately Evolver translates it into workflow rules. After defining the workflow, test each branch by sending messages that should trigger each path.

**Expected result:** Test messages routed to the correct channels based on their content. The 'bug' message appears in '#engineering-bugs', the 'feature request' in '#product-backlog', and the untagged message receives a clarification reply in the original channel.

## Best practices

- Start with a simple ping-pong test workflow before building complex multi-step automation — verifying the Evolver webhook is working end-to-end saves hours of debugging later.
- Store all three credentials (FEISHU_APP_ID, FEISHU_APP_SECRET, FEISHU_EVOLVER_VERIFICATION_TOKEN) only in your OpenClaw `.env` file or via `clawhub config set` — never in chat history or version-controlled files.
- Configure the minimal set of Feishu event subscription types your workflows actually need — subscribing to unnecessary events creates noise and increases the load on the Evolver middleware.
- Test each branch of conditional workflows explicitly before deploying — edge cases in message content evaluation can produce unexpected routing behavior.
- Use feishu-bridge for simple one-shot send/receive needs and feishu-evolver-wrapper only when you genuinely need event-driven or stateful automation — the simpler skill is faster to configure and easier to debug.
- Keep Evolver session timeouts reasonable (10-15 minutes) for interactive conversation workflows to balance responsiveness with memory usage.
- For production deployments, run OpenClaw on a server rather than a local machine to ensure the Evolver webhook endpoint is consistently available for incoming Feishu events.
- Log Evolver workflow executions during initial setup by enabling verbose logging in the skill config — this makes it much easier to trace why a specific event did or did not trigger the expected workflow.

## Use cases

### Keyword-Triggered Workflow Automation

Configure the Evolver middleware to watch for specific keywords or phrases in Feishu messages. When a trigger phrase is detected — such as '@openclaw summarize' or '/ticket create' — the Evolver layer fires an OpenClaw workflow that processes the message context and sends back an intelligent response, all without manual intervention.

Prompt example:

```
Set up an Evolver trigger: whenever anyone posts a message in the 'Support' Feishu channel containing the phrase 'urgent issue', send an alert to the on-call engineer's direct messages with the original message content, the sender's name, and a timestamp.
```

### Multi-Step Interactive Bot Conversations

Build Feishu bot conversations that span multiple message turns, maintaining state between each exchange. For example, a bot that asks a series of qualification questions and routes the person to the right team based on their answers — not possible with basic one-shot messaging, but straightforward with Evolver's stateful workflow management.

Prompt example:

```
Create an Evolver workflow that starts when someone sends 'start onboarding' to the OpenClaw bot in Feishu. The bot should ask for their name, their role, and their team, wait for each response, then send a personalized welcome message with the relevant onboarding resources based on their role.
```

### Event-Driven Cross-Tool Automation

React to Feishu events by triggering actions in other systems connected to OpenClaw. When a project status message is posted in Feishu, automatically update a data record, send a confirmation to a different channel, and log the event — all triggered by a single Feishu message event.

Prompt example:

```
Configure an Evolver rule: when a message is posted in the 'Project Updates' Feishu channel with the tag #shipped, extract the product name and version number from the message and send a formatted release notification to the 'Announcements' channel and the 'Customer Success' channel.
```

## Troubleshooting

### Feishu events are not triggering OpenClaw workflows — the Evolver webhook shows no activity

Cause: Feishu's event subscription may not be able to reach OpenClaw's Evolver webhook endpoint. This usually means the Request URL in the Feishu Open Platform is incorrect, the port is blocked, or the webhook listener is not running.

Solution: Run `clawhub status feishu-evolver-wrapper` to confirm the webhook listener is active. Verify the Request URL in the Feishu Open Platform matches your OpenClaw instance's public address and port. If running locally, confirm your ngrok tunnel is still active and update the Feishu Request URL if the tunnel URL changed.

```
# Check webhook status
clawhub status feishu-evolver-wrapper

# Restart the Evolver middleware listener
clawhub reload feishu-evolver-wrapper
```

### 'feishu-evolver-wrapper: authentication failed' or credential errors despite correct App ID and Secret

Cause: The Feishu app may be in draft/unpublished state, missing required event subscription permissions, or the FEISHU_EVOLVER_VERIFICATION_TOKEN value is incorrect or missing.

Solution: Confirm all three config values are set: FEISHU_APP_ID, FEISHU_APP_SECRET, and FEISHU_EVOLVER_VERIFICATION_TOKEN. Verify the app is published in the Feishu Open Platform (not just saved as draft). Check that event subscription permissions (`im:message.receive_v1`) are granted and saved in the app's permission settings.

```
# Verify all required config values
clawhub config get FEISHU_APP_ID
clawhub config get FEISHU_APP_SECRET
clawhub config get FEISHU_EVOLVER_VERIFICATION_TOKEN
```

### `clawhub install feishu-evolver-wrapper` fails with a version conflict mentioning feishu-bridge

Cause: If feishu-bridge is installed and flagged as conflicting with feishu-evolver-wrapper, ClawHub may block installation to prevent configuration conflicts.

Solution: Uninstall feishu-bridge first if you intend to replace it: `clawhub uninstall feishu-bridge`. Then install feishu-evolver-wrapper. Note that feishu-evolver-wrapper is a superset — it provides all the basic messaging that feishu-bridge does plus the Evolver automation layer.

```
# Remove feishu-bridge if it conflicts
clawhub uninstall feishu-bridge

# Then install the wrapper
clawhub install feishu-evolver-wrapper
```

### Evolver workflows trigger correctly but Feishu API rate limit errors appear during high-activity periods

Cause: Feishu's Open Platform API has per-app rate limits. High-frequency event-driven workflows that send many messages in response to rapid incoming events can exceed these limits.

Solution: Add a minimum delay between successive API calls in your skill configuration using the `rate_limit_delay_ms` setting. For workflows that handle bursts of events, consider batching responses or adding conditional deduplication to avoid processing the same event multiple times.

```
# Add rate limiting in skill config
feishu-evolver-wrapper:
  rate_limit_delay_ms: 500   # minimum delay between API calls (ms)
```

## Frequently asked questions

### What is the difference between feishu-bridge and feishu-evolver-wrapper in OpenClaw?

feishu-bridge provides basic messaging: OpenClaw can send and receive Feishu messages on demand. feishu-evolver-wrapper adds Evolver middleware that makes OpenClaw react to Feishu events automatically — when someone sends a specific message or triggers an event in Feishu, OpenClaw runs a workflow without you needing to manually issue a command. Use feishu-bridge for simple notifications; use feishu-evolver-wrapper for event-driven automation.

### How do I install feishu-evolver-wrapper in OpenClaw?

Run `clawhub install feishu-evolver-wrapper` in your terminal. Then create a Feishu app at open.feishu.cn, enable event subscriptions, and configure FEISHU_APP_ID, FEISHU_APP_SECRET, and FEISHU_EVOLVER_VERIFICATION_TOKEN in OpenClaw using `clawhub config set`. Run `clawhub reload` to start the Evolver webhook listener.

### What is the OpenClaw evolver setting and what does it do?

The Evolver setting in OpenClaw refers to the Evolver middleware layer provided by feishu-evolver-wrapper. It is an event subscription and workflow state management system that sits between OpenClaw and the Feishu API. It listens for Feishu events (incoming messages, user actions, reactions) and triggers corresponding OpenClaw workflows automatically based on rules you define.

### Do I need both feishu-bridge and feishu-evolver-wrapper installed?

No — feishu-evolver-wrapper is a superset of feishu-bridge and includes all basic messaging functionality. If you install feishu-evolver-wrapper, you do not also need feishu-bridge. You can uninstall feishu-bridge if you have both installed and find them conflicting.

### Why are my Feishu events not triggering OpenClaw workflows after setup?

The most common cause is that Feishu cannot reach OpenClaw's Evolver webhook URL. Verify the Request URL in your Feishu app's Event Subscriptions settings is correct and publicly accessible. If running OpenClaw locally, ensure your ngrok or equivalent tunnel is active. Also confirm FEISHU_EVOLVER_VERIFICATION_TOKEN is set correctly — a wrong token causes Feishu to reject the webhook silently.

### Can RapidDev help configure Feishu Evolver Wrapper for enterprise automation?

Yes — RapidDev specializes in configuring OpenClaw skills for complex team workflows, and feishu-evolver-wrapper is one of the more involved setups due to the event subscription and webhook configuration requirements. Teams building multi-stage Feishu automation pipelines are welcome to reach out to RapidDev for hands-on configuration support.

### Does feishu-evolver-wrapper work with Lark (the international Feishu edition)?

Yes — set `FEISHU_API_BASE=https://open.larksuite.com` in your OpenClaw config alongside your App ID, App Secret, and Verification Token. The Evolver middleware supports both the Feishu (feishu.cn) and Lark (larksuite.com) API endpoints with the same skill configuration structure.

---

Source: https://www.rapidevelopers.com/openclaw-integrations/feishu-evolver-wrapper
© RapidDev — https://www.rapidevelopers.com/openclaw-integrations/feishu-evolver-wrapper