Purpose & Significance

Feishu-OpenClaw is a standalone bridge that connects Feishu (Lark) messaging platform to OpenClaw AI agents without requiring a public server, domain name, or reverse tunneling tools like ngrok. It uses Feishu's WebSocket long-connection API to establish persistent, secure communication between your local machine and Feishu's cloud infrastructure. This eliminates the complexity of network exposure while maintaining stable, production-ready message and media handling.

Key Features

Zero infrastructure setup — No public IP, domain, HTTPS certificate, or ngrok/frp tunneling required
WebSocket-based connectivity — Uses Feishu's long-connection event API for reliable, bidirectional messaging
Full media support — Automatically downloads and forwards images, videos, and files to AI models; returns generated images to Feishu
Process isolation — Runs as independent service separate from OpenClaw Gateway, improving stability and fault tolerance
Automatic keepalive — Integrates with macOS launchd for background persistence, auto-restart on crash, and automatic log management
Smart group chat behavior — "Low-disturbance" mode; responds only when @mentioned, asked questions, or given explicit commands
Thinking status indicator — Shows "thinking…" message for responses exceeding 2.5 seconds, then auto-replaces with final answer
Enhanced debugging — FEISHU_BRIDGE_DEBUG=1 mode provides detailed download and forwarding logs for troubleshooting
Whitelist-based file security — Only allows media from ~/.clawdbot/media, system temp directories, and /tmp by default
5-minute setup — Streamlined configuration requiring only App ID, App Secret, and a single npm install

Architecture Overview

The bridge operates as a three-tier relay: Feishu user sends message → Feishu cloud → bridge script (your machine) → OpenClaw Gateway (local WebSocket) → AI agent generates response → bridge forwards reply back to Feishu. Unlike webhook-based approaches, the bridge initiates the connection outbound, eliminating inbound firewall and DNS complexity.

Plugin vs. Standalone Bridge

Two installation options exist:

Plugin mode (openclaw-feishu): Single process, easier setup, but shares OpenClaw Gateway process—crashes affect both components
Standalone bridge (this project): Two independent processes, production-grade isolation, superior media handling, requires separate process management

Recommendation: Start with plugin for testing, upgrade to bridge for production or media-heavy workflows.

Getting Started in 5 Minutes

Prerequisites

macOS with Node.js ≥ 18
OpenClaw/Clawdbot already installed and running
Gateway active (clawdbot gateway status)
Access to Feishu Open Platform

Step 1: Create Feishu Bot

Log into Feishu Open Platform
Create a custom app; add Bot capability
In Permissions, enable: im:message, im:message.send_as_bot, im:message.group_at_msg, im:message.p2p_msg, im:resource (critical for media)
In Events & Callbacks, configure: Subscribe to im.message.receive_v1 using long-connection mode
Publish/release the app; copy App ID and App Secret

Step 2–5: Local Setup & Service Registration

cd /path/to/feishu-openclaw && npm install
Store secret securely: mkdir -p ~/.clawdbot/secrets && echo "YOUR_SECRET" > ~/.clawdbot/secrets/feishu_app_secret && chmod 600 ~/.clawdbot/secrets/feishu_app_secret
Test: FEISHU_APP_ID=cli_xxx node bridge.mjs (send a message in Feishu to verify)
Enable auto-start: node setup-service.mjs && launchctl load ~/Library/LaunchAgents/com.clawdbot.feishu-bridge.plist
Verify: launchctl list | grep feishu

Recent Updates (v2.2, Feb 2026)

Major stability release addressing media workflows:

Image-to-AI: Automatically downloads Feishu image_keys and feeds them as attachments to models
Video/file receipt: Bridge downloads and passes file:// paths to AI (file-reading depends on agent implementation)
AI-to-image: Generated images and mediaUrl outputs automatically post to Feishu
Format repair: Auto-fixes Feishu list formatting edge cases
Debug mode: FEISHU_BRIDGE_DEBUG=1 enables detailed media handling logs

Who This Is For

OpenClaw/Clawdbot users seeking production-grade Feishu integration without infrastructure overhead
Organizations using Feishu (Lark) internally requiring AI assistant access without public server exposure
Developers prioritizing media handling reliability (images, videos, file download/upload) in bot workflows
Privacy-conscious teams preferring local-first message processing over cloud-based webhook middleware
Mac-based deployments or anyone comfortable with process-level service management

Troubleshooting Checklist

Messages sent, but none received Verify event subscription uses "long-connection mode"; confirm im.message.receive_v1 event registered; ensure app is published; check bot added to conversation. Images sent, AI doesn't see them Verify im:resource permission enabled; enable debug mode (FEISHU_BRIDGE_DEBUG=1) and check logs at ~/.clawdbot/logs/feishu-bridge.err.log. AI generates image, Feishu doesn't receive it Generated image path must be in whitelist (~/.clawdbot/media, /tmp, or system temp); confirm file is readable and under size limits; check debug logs. Video/file downloaded but AI ignores it Bridge passes file:// path to AI—actual parsing depends on agent configuration and tool availability. Manual PDF/document parsing requires custom extension.

Configuration & Advanced Options

Clawdbot config path: Defaults to ~/.clawdbot/clawdbot.json; override with CLAWDBOT_CONFIG_PATH=/custom/path.

Agent selection: Defaults to main agent; switch with CLAWDBOT_AGENT_ID=your_agent_id.

App Secret location: Defaults to ~/.clawdbot/secrets/feishu_app_secret; override with FEISHU_APP_SECRET_PATH=/path/to/secret.

Debug logging: Set FEISHU_BRIDGE_DEBUG=1 in .env for verbose media and event handling output.

Important Limitations

Local-only Gateway: Bridge connects only to 127.0.0.1; cross-machine deployment requires code modification or additional relay layer
macOS focus: Tested on macOS with launchd; Windows/Linux versions require alternative process managers
File parsing: Large files and complex formats (PDF, Word, Excel) are passed as paths only; AI understanding depends on agent tooling
Offline downtime: Bot goes offline when machine shuts down; for 24/7 availability, deploy to persistent hardware (NAS, VPS, Raspberry Pi)

Links & Resources

GitHub Repository — Source code, releases, issue tracker
Releases — Version history and upgrade guides
Plugin alternative — Integrated OpenClaw/Clawdbot plugin version openclaw-feishu
Feishu Open Platform — Bot creation and app management
SKILL.md — Detailed capability reference in repo

Source: AlexAnys/feishu-openclaw GitHub repository; 256 stars, 30 forks, JavaScript. Last updated February 6, 2026.

Read original