feishu-bridge

# 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...

# 飞书 × Clawdbot 桥接器

> 让你的 Clawdbot 智能体直接在飞书里对话——无需公网服务器、无需域名、无需备案。

---

## 它是怎么工作的？

想象三个角色：

```
飞书用户 ←→ 飞书云端 ←→ 桥接脚本（你的电脑上） ←→ Clawdbot 智能体
```

### 通俗解释

1. **飞书那边**：你在飞书开发者后台创建一个"自建应用"（机器人），飞书会给你一个 App ID 和 App Secret——这就像是机器人的"身份证"。

2. **桥接脚本**：一个运行在你电脑上的小程序。它用飞书提供的 **WebSocket 长连接**（而不是传统的 Webhook）来接收消息——这意味着：
   - ✅ 不需要公网 IP / 域名
   - ✅ 不需要 ngrok / frp 等内网穿透
   - ✅ 不需要 HTTPS 证书
   - 就像微信一样，你的客户端主动连上去，消息就推过来了

3. **Clawdbot**：桥接脚本收到飞书消息后，通过本地 WebSocket 转发给 Clawdbot Gateway。Clawdbot 调用 AI 模型生成回复，桥接脚本再把回复发回飞书。

### 保活机制

脚本通过 macOS 的 **launchd**（系统服务管理器）运行：
- 开机自动启动
- 崩溃自动重启
- 日志自动写入文件

就像把一个程序设成了"开机启动项"，但更可靠。

---

## 5 分钟上手

### 前提

- macOS（已安装 Clawdbot 并正常运行）
- Node.js ≥ 18
- Clawdbot Gateway 已启动（`clawdbot gateway status` 检查）

### 第一步：创建飞书机器人

1. 打开 [飞书开放平台](https://open.feishu.cn/app)，登录
2. 点击 **创建自建应用**
3. 填写应用名称（随意，比如 "My AI Assistant"）
4. 进入应用 → **添加应用能力** → 选择 **机器人**
5. 进入 **权限管理**，开通以下权限：
   - `im:message` — 获取与发送单聊、群聊消息
   - `im:message.group_at_msg` — 接收群聊中 @ 机器人的消息
   - `im:message.p2p_msg` — 接收机器人单聊消息
6. 进入 **事件与回调** → **事件配置**：
   - 添加事件：`接收消息 im.message.receive_v1`
   - 请求方式选择：**使用长连接接收事件**（这是关键！）
7. 发布应用（创建版本 → 申请上线）
8. 记下 **App ID** 和 **App Secret**（在"凭证与基础信息"页面）

### 第二步：安装依赖

```bash
cd feishu-bridge
npm install
```

### 第三步：配置凭证

把你的飞书 App Secret 保存到安全位置：

```bash
# 创建 secrets 目录
mkdir -p ~/.clawdbot/secrets

# 写入 secret（替换成你自己的）
echo "你的AppSecret" > ~/.clawdbot/secrets/feishu_...