Tools
Feishu Suite
By Custom Feishu/Lark plugins for OpenClaw — calendar, tasks, spreadsheets, messaging, contacts, enhanced documents with table support, and more
Configuration Example
{
"plugins": {
"allow": [
"feishu-bitable",
"feishu-calendar",
"feishu-contacts",
"feishu-doc-enhanced",
"feishu-messaging",
"feishu-sheets",
"feishu-task",
"anthropic-auth",
"feishu"
]
}
}README
# OpenClaw Feishu Suite
让 [OpenClaw](https://github.com/nicepkg/openclaw) 像员工一样使用飞书——日历、任务、表格、文档、消息、通讯录，全场景覆盖。
[English](#english)
---
## 这是什么？
OpenClaw 自带了基础的飞书插件（文档读写、群聊查询、知识库、云盘、权限管理、多维表格基础操作）。但要让 AI 像一个真正的飞书员工一样工作，还缺很多能力。
这个项目补齐了这些能力：
| 插件 | 动作数 | 能力 |
|------|--------|------|
| **feishu-bitable** | 21 | 多维表格：搜索、批量增删改、字段管理、视图管理、附件上传/复制 |
| **feishu-calendar** | 7 | 日历：创建/修改/删除日程、查看空闲忙碌、管理参会人 |
| **feishu-sheets** | 7 | 电子表格：读写单元格、追加行、自动列宽 |
| **feishu-doc-enhanced** | 6 | 增强文档：创建带**完整表格**的文档（内置插件会丢弃表格） |
| **feishu-messaging** | 5 | 消息：主动发消息、发卡片、回复消息、列出群组和成员 |
| **feishu-task** | 7 | 任务：创建/更新/完成任务、指派负责人、设置截止日期 |
| **feishu-contacts** | 3 | 通讯录：按邮箱/手机号查人、获取用户详情、搜索企业通讯录 |
| **anthropic-auth** | - | Anthropic Claude Pro/Max 的 OAuth 认证提供者 |
### 为什么不直接用内置插件？
| 能力 | 内置飞书插件 | 本项目 |
|------|-------------|--------|
| 多维表格 | 基础增删改查（8个工具，无搜索/批量/删除） | 完整能力（21个动作） |
| 文档含表格 | 会丢弃表格块（type 31/32） | 完整表格支持 |
| 主动发消息 | 不支持（只能查群信息和成员） | 支持文本、卡片、回复 |
| 日历 | 无 | 完整增删改查 + 空闲忙碌 |
| 电子表格 | 无 | 读写/追加/列宽 |
| 任务管理 | 无 | 完整增删改查 + 指派 |
| 按邮箱/手机查人 | 无（只能从配置列表查） | 支持，含通讯录搜索 |
| 文档权限 | 有（设置 `tools.perm: true`） | 用内置的即可 |
## 快速开始
### 场景一：已有 OpenClaw，只需添加插件
> 适用于已经部署好 OpenClaw + 飞书的用户，只需要扩展飞书能力。
**1. 克隆本项目**
```bash
git clone https://github.com/zixixr/openclaw-feishu-suite.git
cd openclaw-feishu-suite
```
**2. 配置目标服务器**
```bash
export OPENCLAW_VM="your-user@your-vm-ip"
```
**3. 一键部署**
```bash
./deploy.sh
```
这会：上传所有插件到 VM 的 `~/.openclaw/extensions/` → 应用容器补丁 → 重启 gateway。
**4. 在 OpenClaw 配置中允许插件**
编辑 VM 上的 `~/.openclaw/openclaw.json`，在 `plugins.allow` 中添加插件 ID：
```json
{
"plugins": {
"allow": [
"feishu-bitable",
"feishu-calendar",
"feishu-contacts",
"feishu-doc-enhanced",
"feishu-messaging",
"feishu-sheets",
"feishu-task",
"anthropic-auth",
"feishu"
]
}
}
```
**5. 建议同时开启内置权限工具**
在飞书账号配置中启用 `tools.perm`，这样就不需要额外的权限插件：
```json
{
"channels": {
"feishu": {
"accounts": {
"main": {
"tools": { "perm": true }
}
}
}
}
}
```
**6. 验证**
```bash
ssh $OPENCLAW_VM "docker logs --tail 20 openclaw-gateway 2>&1 | grep 'Registered'"
```
应该看到每个插件都注册了 dispatcher tool。
### 场景二：从零开始部署 OpenClaw + 飞书
> 适用于还没有 OpenClaw 的用户，从头搭建完整环境。
**1. 准备一台 Linux 服务器**
推荐 Ubuntu 22.04/24.04，至少 2 核 4GB 内存。可以是云服务器（Azure、AWS、阿里云等）或本地机器。
**2. 安装 Docker**
```bash
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
# 重新登录以生效
```
**3. 安装 OpenClaw**
参考 [OpenClaw 官方文档](https://github.com/nicepkg/openclaw) 完成安装和初始化：
```bash
# 拉取镜像
docker pull nicepkg/openclaw:latest
# 初始化（按提示完成配置）
docker run --rm -it -v ~/.openclaw:/home/node/.openclaw \
nicepkg/openclaw:latest node dist/index.js onboard
```
**4. 创建飞书自建应用**
1. 前往 [飞书开放平台](https://open.feishu.cn) 创建企业自建应用
2. 获取 App ID 和 App Secret
3. 开通以下权限（按需选择）：
- 多维表格：`bitable:app`、`bitable:app:readonly`
- 文档：`docx:document`、`docx:document:readonly`、`wiki:wiki`、`wiki:wiki:readonly`
- 消息：`im:message`、`im:message:send_as_bot`、`im:chat`、`im:chat:readonly`
- 日历：`calendar:calendar`、`calendar:calendar:readonly`
- 任务：`task:task`、`task:task:readonly`
- 通讯录：`contact:user.base:readonly`、`search:user`
- 云盘：`drive:drive`、`drive:drive:readonly`
4. 在"事件与回调"中选择"使用长连接接收事件"
5. 发布应用
**5. 配置 OpenClaw 飞书通道**
编辑 `~/.openclaw/openclaw.json`：
```json
{
"channels": {
"feishu": {
"enabled": true,
"domain": "feishu",
"streaming": true,
"accounts": {
"main": {
"appId": "cli_xxxxxx",
"appSecret": "your-app-secret",
"botName": "你的机器人名称",
"dmPolicy": "open",
"groupPolicy": "open",
"allowFrom": ["*"],
"tools": { "perm": true }
}
}
}
}
}
```
**6. 启动 Gateway**
```bash
docker run -d --name openclaw-gateway --restart unless-stopped --network host \
-v ~/.openclaw:/home/node/.openclaw \
-e HOME=/home/node -e TERM=xterm-256color \
--init nicepkg/openclaw:latest node dist/index.js gateway --bind loopback --port 18789
```
**7. 部署本项目插件**
```bash
git clone https://github.com/zixixr/openclaw-feishu-suite.git
cd openclaw-feishu-suite
export OPENCLAW_VM="your-user@your-vm-ip" # 如果是本机可以跳过，手动复制
./deploy.sh
```
然后按场景一的步骤 4-6 完成配置。
## 项目结构
```
plugins/
feishu-bitable/ # 多维表格操作
feishu-calendar/ # 日历管理
feishu-sheets/ # 电子表格操作
feishu-doc-enhanced/ # 增强文档（支持表格）
feishu-messaging/ # 主动消息发送
feishu-task/ # 任务管理
feishu-contacts/ # 通讯录查询
anthropic-auth/ # Anthropic OAuth 提供者
patches/
bot-media-path.py # 修复：媒体文件路径被吞掉的问题
docs/
custom-plugin-guide.md # 插件开发指南
deploy.sh # 一键部署脚本
```
每个插件包含：
- `index.ts` — 插件实现（TypeScript，运行时由 jiti 加载）
- `openclaw.plugin.json` — 插件清单（id、configSchema）
- `package.json` — 包元数据，声明 `openclaw.extensions` 入口
- `skills/<name>/SKILL.md` — AI 使用指南（教模型何时、如何使用工具）
## 技术细节
### Dispatcher 模式
为避免工具定义过多导致超出模型上下文窗口，每个插件只注册**一个工具**，通过 `action` 参数分发到不同功能：
```typescript
// 一个插件 = 一个工具 = 多个 action
feishu_bitable({ action: "search_records", params: { ... } })
feishu_bitable({ action: "batch_create", params: { ... } })
```
### 凭据管理
插件从 OpenClaw 运行时配置（`channels.feishu.accounts`）读取飞书凭据，不硬编码任何密钥。
### Skills（AI 指南）
每个插件附带一个 `SKILL.md`，用 YAML frontmatter + Markdown 编写，告诉 AI 模型：
- **何时**激活该插件（触发关键词）
- **有哪些**工具和动作
- **如何**调用（参数格式、示例）
Skills 由 OpenClaw 自动加载并在相关时注入 AI 上下文。
### 容器补丁
`patches/` 目录中的 Python 脚本会修改运行中的 Docker 容器内的代码：
| 补丁 | 作用 |
|------|------|
| `bot-media-path.py` | 修复 Media Understanding 吞掉入站媒体文件路径的问题 |
补丁在 `docker restart` 后仍然有效，但 `docker run`（重建容器）后会丢失。重建后需重新运行 `./deploy.sh patches`。
## 开发新插件
参见 [docs/custom-plugin-guide.md](docs/custom-plugin-guide.md)（中文）。
## 许可证
MIT
---
<a name="english"></a>
## English
Custom plugins for [OpenClaw](https://github.com/nicepkg/openclaw) that extend its Feishu/Lark integration — making OpenClaw work like a real employee in your Feishu workspace.
### Plugins
| Plugin | Actions | Description |
|--------|---------|-------------|
| **feishu-bitable** | 21 | Multi-dimensional table: search, batch CRUD, field/view management, attachments |
| **feishu-calendar** | 7 | Calendar event CRUD, free/busy checking, attendee management |
| **feishu-sheets** | 7 | Spreadsheet read/write, append rows, auto-fit column widths |
| **feishu-doc-enhanced** | 6 | Document creation with **full table support** (bundled plugin strips tables) |
| **feishu-messaging** | 5 | Send messages/cards, reply, list chats and members |
| **feishu-task** | 7 | Task CRUD with assignees and due dates |
| **feishu-contacts** | 3 | User lookup by email/phone, profile retrieval, directory search |
| **anthropic-auth** | - | OAuth provider for Anthropic Claude Pro/Max subscriptions |
### Quick Start (Existing OpenClaw)
```bash
git clone https://github.com/zixixr/openclaw-feishu-suite.git
cd openclaw-feishu-suite
export OPENCLAW_VM="your-user@your-vm-ip"
./deploy.sh
```
Then add plugin IDs to `plugins.allow` in `~/.openclaw/openclaw.json` and restart.
### Quick Start (From Scratch)
1. Set up a Linux server with Docker
2. Install OpenClaw following [official docs](https://github.com/nicepkg/openclaw)
3. Create a Feishu self-built app with required permissions
4. Configure the Feishu channel in `~/.openclaw/openclaw.json`
5. Start the gateway container
6. Deploy this suite's plugins with `./deploy.sh`
See the Chinese section above for detailed step-by-step instructions.
### Development
See [docs/custom-plugin-guide.md](docs/custom-plugin-guide.md) for the plugin development guide.
### License
MIT
tools
Comments
Sign in to leave a comment