playbooks

home / skills / xiaomingx / moltbot-connector-feishu-dingtalk / feishu-connection

feishu-connection skill

/skills/feishu-connection

This skill helps you connect Feishu bot to Clawdbot via WebSocket, manage bridge startup, logs, and group chat behavior.

npx playbooks add skill xiaomingx/moltbot-connector-feishu-dingtalk --skill feishu-connection

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

Files (6)
SKILL.md
2.5 KB
---
name: feishu-connection
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.py (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-connection
uv sync
FEISHU_APP_ID=cli_xxx uv run python bridge.py
```

### 4. Auto-start (macOS)

```bash
FEISHU_APP_ID=cli_xxx uv run python setup_service.py
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.py` → `should_respond_in_group()`.

## 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 Feishu bot creation, credential management, bridge startup, macOS launchd auto-restart, and group chat response tuning. Sessions are mapped per Feishu chat and the bridge authenticates to the gateway using your existing gateway token.

How this skill works

The local bridge runs a Feishu SDK client that maintains an outbound WebSocket to Feishu and a second WebSocket to the Clawdbot Gateway. Incoming Feishu events are translated to Clawdbot sessions (feishu:<chatId>) and forwarded; gateway responses are sent back into the original Feishu chat. Group chat reply rules and response thresholds are configurable in the bridge code and environment variables.

When to use it

  • Enable Feishu/Lark as a channel for Clawdbot without opening inbound ports or deploying a public server.
  • Set up a new Feishu bot and wire its events into Clawdbot using WebSocket long-connection.
  • Troubleshoot connectivity between Feishu and Clawdbot or review bridge logs.
  • Run the bridge on a local machine or server and use macOS launchd for auto-restart.
  • Adjust group chat reply behavior to avoid noisy or undesired bot replies.

Best practices

  • Store the Feishu App Secret in ~/.clawdbot/secrets with strict file permissions (600).
  • Set FEISHU_APP_ID environment variable before launching the bridge for predictable startup.
  • Use the provided launchd setup on macOS to auto-restart the bridge and capture stderr logs.
  • Tune should_respond_in_group() to match your organization’s mention and command patterns.
  • Monitor logs (~/.clawdbot/logs/feishu-bridge.err.log) and test approving the app version in Feishu Open Platform.

Example use cases

  • Connect an internal Feishu workspace to Clawdbot so employees can query an AI agent from group and 1:1 chats.
  • Deploy the bridge on a developer laptop or private server with no public IP and push messages securely to the gateway.
  • Adjust group reply rules so the bot only responds when explicitly asked or mentioned in project channels.
  • Automate bridge startup on macOS using launchd to ensure high availability for critical teams.

FAQ

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

No. The Feishu SDK uses an outbound WebSocket long-connection, so no public inbound port or ngrok is required.

How do I stop or check the bridge service on macOS?

Use launchctl: load/unload the ~/Library/LaunchAgents/com.clawdbot.feishu-bridge.plist and view logs with tail -f ~/.clawdbot/logs/feishu-bridge.err.log.