playbooks

home / skills / openclaw / skills / feishu-bridge

feishu-bridge skill

/skills/alexanys/feishu-bridge

This skill helps you connect a Feishu bot to Clawdbot via WebSocket, manage startup, and troubleshoot the bridge end-to-end.

npx playbooks add skill openclaw/skills --skill feishu-bridge

Review the files below or copy the command above to add this skill to your agents.

Files (6)
SKILL.md
2.4 KB
---
name: feishu-bridge
description: Connect a Feishu (Lark) bot to Clawdbot via WebSocket long-connection. No public server, domain, or ngrok required. Use when setting up Feishu/Lark as a messaging channel, troubleshooting the Feishu bridge, or managing the bridge service (start/stop/logs). Covers bot creation on Feishu Open Platform, credential setup, bridge startup, macOS launchd auto-restart, and group chat behavior tuning.
---

# Feishu Bridge

Bridge Feishu bot messages to Clawdbot Gateway over local WebSocket.

## Architecture

```
Feishu user → Feishu cloud ←WS→ bridge.mjs (local) ←WS→ Clawdbot Gateway → AI agent
```

- Feishu SDK connects outbound (no inbound port / public IP needed)
- Bridge authenticates to Gateway using the existing gateway token
- Each Feishu chat maps to a Clawdbot session (`feishu:<chatId>`)

## Setup

### 1. Create Feishu bot

1. Go to [open.feishu.cn/app](https://open.feishu.cn/app) → Create self-built app → Add **Bot** capability
2. Enable permissions: `im:message`, `im:message.group_at_msg`, `im:message.p2p_msg`
3. Events: add `im.message.receive_v1`, set delivery to **WebSocket long-connection**
4. Publish the app (create version → request approval)
5. Note the **App ID** and **App Secret**

### 2. Store secret

```bash
mkdir -p ~/.clawdbot/secrets
echo "YOUR_APP_SECRET" > ~/.clawdbot/secrets/feishu_app_secret
chmod 600 ~/.clawdbot/secrets/feishu_app_secret
```

### 3. Install & run

```bash
cd <skill-dir>/feishu-bridge
npm install
FEISHU_APP_ID=cli_xxx node bridge.mjs
```

### 4. Auto-start (macOS)

```bash
FEISHU_APP_ID=cli_xxx node setup-service.mjs
launchctl load ~/Library/LaunchAgents/com.clawdbot.feishu-bridge.plist
```

## Diagnostics

```bash
# Check service
launchctl list | grep feishu

# Logs
tail -f ~/.clawdbot/logs/feishu-bridge.err.log

# Stop
launchctl unload ~/Library/LaunchAgents/com.clawdbot.feishu-bridge.plist
```

## Group chat behavior

Bridge replies only when: user @-mentions the bot, message ends with `?`/`？`, contains request verbs (帮/请/分析/总结…), or calls the bot by name. Customize the name list in `bridge.mjs` → `shouldRespondInGroup()`.

## Environment variables

| Variable | Required | Default |
|---|---|---|
| `FEISHU_APP_ID` | ✅ | — |
| `FEISHU_APP_SECRET_PATH` | — | `~/.clawdbot/secrets/feishu_app_secret` |
| `CLAWDBOT_CONFIG_PATH` | — | `~/.clawdbot/clawdbot.json` |
| `CLAWDBOT_AGENT_ID` | — | `main` |
| `FEISHU_THINKING_THRESHOLD_MS` | — | `2500` |

Overview

This skill connects a Feishu (Lark) bot to Clawdbot via a local WebSocket long-connection so you can use Feishu as a messaging channel without exposing a public server or using ngrok. It handles bot authentication, maps Feishu chats to Clawdbot sessions, and supports macOS auto-restart and logging for reliable bridge operation. The skill focuses on practical setup, diagnostics, and tuning group chat response behavior.

How this skill works

The bridge runs locally and maintains an outbound WebSocket link to Feishu cloud and a separate WebSocket to the Clawdbot Gateway. Each Feishu chat is translated to a Clawdbot session ID (feishu:<chatId>) and messages are proxied both ways. The bridge authenticates to Feishu using App ID and stored App Secret and uses the gateway token to authenticate to Clawdbot.

When to use it

  • Set up Feishu/Lark as a messaging channel for Clawdbot without opening inbound ports.
  • Troubleshoot connectivity, message delivery, or group chat response behavior between Feishu and Clawdbot.
  • Run Clawdbot interactions on a local machine or private network where public hosting isn’t available.
  • Configure automatic restart on macOS and inspect logs for operational issues.
  • Adjust group chat trigger rules to reduce noise or improve responsiveness.

Best practices

  • Keep the Feishu App Secret in a file with strict permissions (~/.clawdbot/secrets/feishu_app_secret, chmod 600).
  • Use the CL AWDBOT gateway token already in your environment so the bridge can authenticate without extra public exposure.
  • Run the bridge as a background service (launchd on macOS) for automatic restarts and stable long connections.
  • Monitor logs at ~/.clawdbot/logs/feishu-bridge.err.log and use launchctl list to check service status.
  • Tune group chat triggers in shouldRespondInGroup() to avoid unwanted replies and to match your team's language patterns.

Example use cases

  • Run Clawdbot on a laptop and connect a Feishu bot so teammates can message the AI without a public server.
  • Enable a helpdesk bot in a Feishu group that only responds when explicitly @-mentioned or when queries end with a question mark.
  • Deploy the bridge on macOS with launchd to guarantee automatic restart after reboots or crashes.
  • Debug message loss or authentication errors using the stored secret path and log output.
  • Customize group reply heuristics to respond to specific verbs or bot name calls in multilingual teams.

FAQ

Do I need a public IP or domain to run the bridge?

No. The bridge uses outbound WebSocket long-connections to Feishu and Clawdbot, so no inbound ports, public IP, or ngrok are required.

Where should I store the Feishu App Secret?

Store it at ~/.clawdbot/secrets/feishu_app_secret with file permissions set to 600 to keep it secure.

How do I make the bridge restart automatically on macOS?

Use the provided setup script to create a launchd plist, then load it with launchctl so the bridge restarts on logout/login or failure.

feishu-bridge skill by openclaw/skills