{"skill":{"slug":"lark-integration","displayName":"Lark Integration","summary":"Connect Lark (Feishu) messaging to OpenClaw via webhook bridge. Supports text, rich text (post), and image messages bidirectionally. Use when setting up Lark/Feishu as a messaging channel, receiving messages with images, sending replies back to Lark, reading Lark documents/wikis/bitables, or troubleshooting Lark integration issues. Covers both Lark International (larksuite.com) and China Feishu (feishu.cn).","description":"---\nname: lark-integration\ndescription: Connect Lark (Feishu) messaging to OpenClaw via webhook bridge. Supports text, rich text (post), and image messages bidirectionally. Use when setting up Lark/Feishu as a messaging channel, receiving messages with images, sending replies back to Lark, reading Lark documents/wikis/bitables, or troubleshooting Lark integration issues. Covers both Lark International (larksuite.com) and China Feishu (feishu.cn).\n---\n\n# Lark Integration\n\nConnect Lark (Feishu) to OpenClaw for bidirectional messaging with full rich content support.\n\n## Quick Start\n\n```bash\n# 1. Set credentials\necho \"FEISHU_APP_ID=cli_xxx\" >> ~/.openclaw/workspace/.env\nmkdir -p ~/.openclaw/secrets\necho \"your_app_secret\" > ~/.openclaw/secrets/feishu_app_secret\n\n# 2. Start bridge\ncd skills/lark-integration/scripts\nnode bridge-webhook.mjs\n\n# 3. Configure Lark webhook URL in developer console\n# https://open.larksuite.com → Your App → Event Subscriptions\n# URL: http://YOUR_SERVER_IP:3000/webhook\n```\n\n## Architecture\n\n```\nLark App ──webhook──► Bridge (port 3000) ──WebSocket──► OpenClaw Gateway\n                           │                                   │\n                           ◄────────── Reply ──────────────────┘\n```\n\n## Supported Message Types\n\n| Type | Direction | Format |\n|------|-----------|--------|\n| `text` | ↔ Both | Plain text |\n| `post` | → Receive | Rich text with images, links |\n| `image` | → Receive | Single image |\n| Reply | ← Send | Text (cards via feishu-card skill) |\n\n## Platform Detection\n\nThe bridge auto-detects platform from URLs:\n- `*.larksuite.com` → `https://open.larksuite.com` (International)\n- `*.feishu.cn` → `https://open.feishu.cn` (China)\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `FEISHU_APP_ID` | Yes | App ID from Lark Developer Console |\n| `FEISHU_APP_SECRET_PATH` | No | Path to secret file (default: `~/.openclaw/secrets/feishu_app_secret`) |\n| `WEBHOOK_PORT` | No | Webhook listen port (default: 3000) |\n| `FEISHU_THINKING_THRESHOLD_MS` | No | Delay before \"Thinking...\" placeholder (default: 2500) |\n| `FEISHU_ENCRYPT_KEY` | No | Encryption key if enabled in Lark |\n| `OPENCLAW_AGENT_ID` | No | Agent to route messages to (default: main) |\n\n### Lark App Permissions\n\nEnable these scopes in Lark Developer Console → Permissions & Scopes:\n\n**Messaging:**\n- `im:message` - Send and receive messages\n- `im:message:send_as_bot` - Send messages as bot\n- `im:resource` - Download message resources (images)\n\n**Documents (optional):**\n- `docx:document:readonly` - Read documents\n- `wiki:wiki:readonly` - Read wiki spaces\n- `sheets:spreadsheet:readonly` - Read spreadsheets\n- `bitable:bitable:readonly` - Read bitables\n- `drive:drive:readonly` - Access drive files\n\n## Scripts\n\n### bridge-webhook.mjs\n\nMain webhook bridge. Receives Lark events, forwards to OpenClaw, sends replies.\n\n```bash\nFEISHU_APP_ID=cli_xxx node scripts/bridge-webhook.mjs\n```\n\n### setup-service.mjs\n\nInstall as systemd service for auto-start:\n\n```bash\nnode scripts/setup-service.mjs\n# Creates /etc/systemd/system/lark-bridge.service\n```\n\n## Image Handling\n\nImages in messages are:\n1. Detected from `post` content or `image` message type\n2. Downloaded via Lark API using `message_id` and `image_key`\n3. Converted to base64\n4. Sent to OpenClaw Gateway as `attachments` parameter\n\n```javascript\nattachments: [{ mimeType: \"image/png\", content: \"<base64>\" }]\n```\n\n## Group Chat Behavior\n\nIn group chats, the bridge responds when:\n- Bot is @mentioned\n- Message ends with `?` or `？`\n- Message contains trigger words: help, please, why, how, what, 帮, 请, 分析, etc.\n- Message starts with bot name\n\nOtherwise, messages are ignored to avoid noise.\n\n## Reading Documents\n\nUse the `feishu-doc` skill to read Lark documents:\n\n```bash\nnode skills/feishu-doc/index.js fetch \"https://xxx.larksuite.com/docx/TOKEN\"\n```\n\nSupported URL types:\n- `/docx/` - New documents\n- `/wiki/` - Wiki pages (auto-resolves to underlying doc)\n- `/sheets/` - Spreadsheets\n- `/base/` - Bitables (multi-dimensional tables)\n\n**Permission Note:** Documents must be shared with the bot, or the bot must have tenant-wide read permission.\n\n## Troubleshooting\n\n### \"forBidden\" error when reading docs\n- Document not shared with bot → Add bot as collaborator\n- Missing scope → Enable `docx:document:readonly` in console\n\n### No messages received\n- Check webhook URL is accessible: `curl http://YOUR_IP:3000/health`\n- Verify webhook in Lark console shows \"Verified\"\n- Check bridge logs: `journalctl -u lark-bridge -f`\n\n### \"must be string\" error\n- Old bridge version → Update to use `attachments` for images\n\n### Images not received\n- Missing `im:resource` scope → Enable in Lark console\n- Token expired → Bridge auto-refreshes, restart if stuck\n\n## Service Management\n\n```bash\n# Check status\nsystemctl status lark-bridge\n\n# View logs\njournalctl -u lark-bridge -f\n\n# Restart\nsystemctl restart lark-bridge\n```\n\n## References\n\n- [Lark Developer Console](https://open.larksuite.com/) (International)\n- [Feishu Developer Console](https://open.feishu.cn/) (China)\n- See `references/api-formats.md` for message format details\n- See `references/setup-guide.md` for step-by-step setup\n","tags":{"latest":"1.0.0"},"stats":{"comments":0,"downloads":5243,"installsAllTime":16,"installsCurrent":15,"stars":2,"versions":1},"createdAt":1769979378161,"updatedAt":1779076573210},"latestVersion":{"version":"1.0.0","createdAt":1769979378161,"changelog":"Initial release: Full Lark/Feishu integration with text, rich text, and image support","license":null},"metadata":null,"owner":{"handle":"boyangwang","userId":"s17eb68n9bz06qppj7nxdd6zf5884p1e","displayName":"boyangwang","image":"https://avatars.githubusercontent.com/u/2408273?v=4"},"moderation":{"isSuspicious":true,"isMalwareBlocked":false,"verdict":"suspicious","reasonCodes":["suspicious.llm_suspicious"],"summary":"Detected: suspicious.llm_suspicious","engineVersion":"v2.4.24","updatedAt":1779076573210}}