Tools
Mail Feishu
By OpenClaw plugin: Gmail real-time notifications to Feishu/Lark via Google Pub/Sub
Install
npm install &&README
# openclaw-mail-feishu
OpenClaw plugin for real-time Gmail notifications to Feishu/Lark.
Uses Google Pub/Sub for instant delivery — no polling, no delay.
## For AI Agents
Copy the prompt below and send it to your AI agent to set up this plugin automatically.
```
Set up the openclaw-mail-feishu plugin. This plugin delivers real-time Gmail notifications to Feishu/Lark via Google Pub/Sub.
Before starting, ask me for: (1) my Gmail address, (2) my Feishu/Lark webhook URL — if I don't have one, guide me to create it: Feishu group → Settings → Bots → Add Bot → Custom Bot → copy webhook URL, (3) my Google Cloud project ID — if I don't have one, guide me to create one at https://console.cloud.google.com, (4) optionally an LLM API key for smart email filtering.
Then follow these steps in order:
Step 1 — Check prerequisites:
- gog CLI installed: run "which gog && gog --version". If missing, download from https://github.com/openclaw/gogcli/releases for the correct platform.
- gog Gmail auth: run "gog auth list". If no account, guide me through OAuth: I need a Google Cloud project with OAuth credentials (Desktop app type), then run "gog auth credentials /path/to/client_secret.json" and "gog auth add USER@gmail.com --services gmail".
- OpenClaw running: run "openclaw status".
Step 2 — Enable Google Cloud APIs. Send me these two links to open in browser and click Enable:
- Gmail API: https://console.cloud.google.com/apis/library/gmail.googleapis.com?project=PROJECT_ID
- Pub/Sub API: https://console.cloud.google.com/apis/library/pubsub.googleapis.com?project=PROJECT_ID
Wait for me to confirm before proceeding.
Step 3 — Create Pub/Sub topic and subscription. If gcloud is available, run:
gcloud pubsub topics create gmail-notifications
gcloud pubsub subscriptions create gmail-notifications-sub --topic=gmail-notifications
gcloud pubsub topics add-iam-policy-binding gmail-notifications --member="serviceAccount:gmail-api-push@system.gserviceaccount.com" --role="roles/pubsub.publisher"
If gcloud is NOT available, use REST API with an OAuth token that has pubsub scope:
curl -X PUT "https://pubsub.googleapis.com/v1/projects/PROJECT_ID/topics/gmail-notifications" -H "Authorization: Bearer ACCESS_TOKEN" -H "Content-Type: application/json"
curl -X PUT "https://pubsub.googleapis.com/v1/projects/PROJECT_ID/subscriptions/gmail-notifications-sub" -H "Authorization: Bearer ACCESS_TOKEN" -H "Content-Type: application/json" -d '{"topic":"projects/PROJECT_ID/topics/gmail-notifications","ackDeadlineSeconds":60}'
curl -X POST "https://pubsub.googleapis.com/v1/projects/PROJECT_ID/topics/gmail-notifications:setIamPolicy" -H "Authorization: Bearer ACCESS_TOKEN" -H "Content-Type: application/json" -d '{"policy":{"bindings":[{"role":"roles/pubsub.publisher","members":["serviceAccount:gmail-api-push@system.gserviceaccount.com"]}]}}'
Step 4 — Install and configure the plugin:
git clone https://github.com/larry-xue/openclaw-mail-feishu.git /tmp/openclaw-mail-feishu
cd /tmp/openclaw-mail-feishu && npm install && npm run build
openclaw plugins install /tmp/openclaw-mail-feishu
openclaw plugins config mail-feishu --set gcpProject=PROJECT_ID
openclaw plugins config mail-feishu --set pubsubSubscription=gmail-notifications-sub
openclaw plugins config mail-feishu --set pubsubTopic=gmail-notifications
openclaw plugins config mail-feishu --set feishuWebhook=WEBHOOK_URL
If LLM key was provided, also run:
openclaw plugins config mail-feishu --set llmApiKey=KEY
openclaw plugins config mail-feishu --set llmModel=gpt-4o-mini
Step 5 — Restart and verify:
openclaw gateway restart
sleep 3
openclaw gateway logs | grep mail-feishu
Expected: "mail-feishu: watch registered" and "mail-feishu: watching inbox → feishu"
Step 6 — Test: ask me to send myself a test email. Within 30 seconds a Feishu card notification should appear.
Troubleshooting:
- "watch registration failed" → Gmail API not enabled or wrong project ID
- "subscription error" → Pub/Sub API not enabled or subscription name mismatch
- "feishu send failed" → webhook URL incorrect or bot removed from group
- No logs at all → plugin not loaded, check "openclaw plugins list"
```
---
## For Humans
[中文文档](README_CN.md)
## How It Works
```
Gmail inbox → Google Pub/Sub → OpenClaw plugin → LLM classification → Feishu/Lark webhook
```
1. Gmail pushes new email events to a Pub/Sub topic in real time
2. The plugin listens on the subscription and fetches email details
3. (Optional) LLM classifies urgency: 🔴 Critical / 🟠 Important / 🟡 Normal / 🟢 Low
4. Important emails are sent to Feishu/Lark as interactive card messages
## Features
- **Real-time** — Pub/Sub push, not IMAP polling
- **Feishu + Lark** — supports both `open.feishu.cn` and `open.larksuite.com` webhooks
- **Smart filtering** — optional LLM classification skips newsletters and spam
- **Rich cards** — sender, subject, summary, urgency tag in one card
- **Auto-renew** — Gmail watch is re-registered every 6 days automatically
- **Multilingual** — zh / en / ja notification and classification
## Prerequisites
- [OpenClaw](https://openclaw.ai) installed and running
- [gog CLI](https://github.com/openclaw/gogcli) with Gmail OAuth configured
- Google Cloud project with **Gmail API** and **Pub/Sub API** enabled
- Feishu/Lark group with a webhook bot
## Quick Start
### 1. Set up Google Cloud
```bash
# Create Pub/Sub topic and subscription
gcloud pubsub topics create gmail-notifications
gcloud pubsub subscriptions create gmail-notifications-sub \
--topic=gmail-notifications
# Grant Gmail permission to publish
gcloud pubsub topics add-iam-policy-binding gmail-notifications \
--member="serviceAccount:gmail-api-push@system.gserviceaccount.com" \
--role="roles/pubsub.publisher"
```
Or do it via REST API / Google Cloud Console — see [Setup Guide](docs/setup.md).
### 2. Create Feishu Webhook
1. Open a Feishu group → Settings → Bots → Add Bot → Custom Bot
2. Copy the webhook URL (`https://open.feishu.cn/open-apis/bot/v2/hook/xxx`)
3. (Optional) Enable signature verification, note the secret
### 3. Install Plugin
```bash
# From source
git clone https://github.com/larry-xue/openclaw-mail-feishu.git
cd openclaw-mail-feishu
npm install && npm run build
openclaw plugins install .
# Or run the setup script
./scripts/setup.sh
```
### 4. Configure
```bash
openclaw plugins config mail-feishu --set gcpProject=YOUR_PROJECT_ID
openclaw plugins config mail-feishu --set pubsubSubscription=gmail-notifications-sub
openclaw plugins config mail-feishu --set feishuWebhook=https://open.feishu.cn/open-apis/bot/v2/hook/xxx
# Optional: webhook signature
openclaw plugins config mail-feishu --set feishuWebhookSecret=YOUR_SECRET
# Optional: LLM classification (without this, all inbox emails are forwarded)
openclaw plugins config mail-feishu --set llmApiKey=sk-xxx
openclaw plugins config mail-feishu --set llmModel=gpt-4o-mini
```
### 5. Restart & Verify
```bash
openclaw gateway restart
openclaw gateway logs | grep mail-feishu
# Expected: mail-feishu: watch registered, historyId=...
# Expected: mail-feishu: watching inbox → feishu
```
Send yourself a test email and wait a few seconds — you should see a Feishu card.
## Configuration Reference
| Key | Required | Default | Description |
|-----|----------|---------|-------------|
| `feishuWebhook` | ✅ | — | Feishu/Lark webhook URL |
| `feishuWebhookSecret` | — | — | Webhook signature secret |
| `gcpProject` | ✅ | — | Google Cloud project ID |
| `pubsubSubscription` | ✅ | `gmail-notifications-sub` | Pub/Sub subscription name |
| `pubsubTopic` | — | `gmail-notifications` | Pub/Sub topic name |
| `gogAccount` | — | gog default | Gmail account to watch |
| `credentialsPath` | — | ADC | Path to Google credentials JSON |
| `llmApiKey` | — | — | API key for classification LLM |
| `llmBaseUrl` | — | `https://api.openai.com/v1` | LLM API base URL |
| `llmModel` | — | `gpt-4o-mini` | LLM model name |
| `locale` | — | `zh` | Notification language (zh/en/ja) |
## Notification Card Preview
```
┌─────────────────────────────────┐
│ 📬 新邮件 — 🟠 重要 │
├─────────────────────────────────┤
│ 发件人 时间 │
│ Alice Chen 2026-05-29 14:30 │
│ │
│ 主题 │
│ Q3 预算审批需要你签字 │
│ ─────────────────────────────── │
│ 摘要 │
│ Alice 请你在周五前审批 Q3 预算 │
└─────────────────────────────────┘
```
## License
MIT
tools
Comments
Sign in to leave a comment