feishu-connection

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Feishu Bridge

Feishu桥接

Bridge Feishu bot messages to Clawdbot Gateway over local WebSocket.

通过本地WebSocket将Feishu机器人消息桥接到Clawdbot网关。

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>
```
)

Feishu用户 → Feishu云 ←WS→ bridge.py（本地） ←WS→ Clawdbot网关 → AI Agent

Feishu SDK采用outbound连接（无需入站端口/公网IP）
桥接服务使用现有网关令牌向网关进行身份验证
每个Feishu聊天对应一个Clawdbot会话（
```
feishu:<chatId>
```
）

Setup

配置步骤

1. Create Feishu bot

1. 创建Feishu机器人

Go to open.feishu.cn/app → Create self-built app → Add Bot capability

Enable permissions:

im:message

im:message.group_at_msg

im:message.p2p_msg

Events: add
```
im.message.receive_v1
```
, set delivery to WebSocket long-connection
Publish the app (create version → request approval)
Note the App ID and App Secret

访问open.feishu.cn/app → 创建自建应用 → 添加机器人能力

启用权限：

im:message

im:message.group_at_msg

im:message.p2p_msg

事件：添加
```
im.message.receive_v1
```
，设置投递方式为WebSocket长连接
发布应用（创建版本 → 申请审批）
记录App ID和App Secret

2. Store secret

2. 存储密钥

bash

mkdir -p ~/.clawdbot/secrets
echo "YOUR_APP_SECRET" > ~/.clawdbot/secrets/feishu_app_secret
chmod 600 ~/.clawdbot/secrets/feishu_app_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

3. 安装并运行

bash

cd <skill-dir>/feishu-connection
uv sync
FEISHU_APP_ID=cli_xxx uv run python bridge.py

bash

cd <skill-dir>/feishu-connection
uv sync
FEISHU_APP_ID=cli_xxx uv run python bridge.py

4. Auto-start (macOS)

4. 自动启动（macOS）

bash

FEISHU_APP_ID=cli_xxx uv run python setup_service.py
launchctl load ~/Library/LaunchAgents/com.clawdbot.feishu-bridge.plist

bash

FEISHU_APP_ID=cli_xxx uv run python setup_service.py
launchctl load ~/Library/LaunchAgents/com.clawdbot.feishu-bridge.plist

Diagnostics

诊断

bash

undefined

bash

undefined

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

undefined

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

undefined

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()

桥接服务仅在以下情况回复：用户@提及机器人、消息以

？

结尾、包含请求类动词（帮/请/分析/总结…）或呼叫机器人名称。可在

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`

变量名	是否必填	默认值
`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`