专栏定位：OpenClaw 从入门到精通（第 09 章）
适读人群：开发者、技术爱好者、AI应用创业者

摘要

飞书（Feishu）是字节跳动推出的企业协作平台，在国内企业中有大量用户。OpenClaw 原生支持飞书集成，让你可以把 AI 助手直接接入飞书——在群聊中 @它、在私聊中与它对话、让它帮你操作飞书文档和管理多维表格。本章将深入探讨飞书 Bot 的创建与配置、feishu_doc、feishu_bitable、feishu_wiki 等 Skills 的详细用法，以及如何构建一个自动推送日报的实战案例。

SEO 摘要

OpenClaw 飞书集成详解：飞书 Bot 创建与配置、feishu_doc 文档操作、feishu_bitable 多维表格、feishu_wiki 知识库、自动推送日报实战案例。

目录

• 飞书集成概述
• 飞书 Bot 创建与配置
• feishu_doc 文档操作
• feishu_bitable 多维表格
• feishu_wiki 知识库
• 飞书消息与卡片
• 实战：自动推送日报
• 常见错误与避坑指南
• 术语注释
• 面试高频问答
• 深度扩展
• 附录
• 系列总结（第 01-09 章）
• 版权声明

开篇

想象这样的场景：

周一早上 9 点，你的团队飞书群里准时出现了一条 Bot 消息：

【团队周报】📊
📅 周期：2026-03-23 ~ 2026-03-29

🏆 本周完成
- 张三：完成用户认证模块
- 李四：修复 3 个 Bug
- 王五：优化数据库查询，性能提升 40%

📋 下周计划
- 张三：开始支付模块
- 李四：单元测试覆盖率提升到 80%
- ...

📌 需要关注
- 测试环境数据库即将满，需要清理

🤖 由 OpenClaw AI 助手自动生成

这条消息不是人发的，而是 OpenClaw 自动从 Jira、Confluence 等系统抓取数据，整理后通过飞书 Bot 发送的。这就是飞书集成在企业场景中的威力。

核心知识点

1. 飞书集成概述

1.1 飞书 Open Platform

飞书提供了开放的 Open Platform，允许第三方应用通过 API 操作飞书的各种功能：

• 消息：发送/接收消息、@ 机器人
• 文档：读写飞书云文档
• 多维表格：操作 Bitable 数据
• 知识库：管理 Wiki 文档
• 日历：创建/查询会议
• 通讯录：获取用户/部门信息

OpenClaw 通过飞书 SDK（lark-oapi）封装了这些能力，通过 Skills 的方式提供使用。

1.2 集成架构

OpenClaw
    ↓ feishu_doc / feishu_bitable / feishu_wiki / message
飞书 Skills
    ↓ HTTP API
飞书 Open Platform
    ↓
飞书用户 / 飞书文档 / 飞书群

1.3 需要开通的权限

在开始之前，你需要在飞书开放平台开通以下权限：

权限名称	权限标识	用途
获取与发送单聊、群组消息	im:message	发送消息
读取消息	im:message:readonly	读取消息内容
获取与编辑云文档	docx:document	操作云文档
获取与编辑多维表格	bitable:app	操作多维表格
获取与编辑知识库	wiki:space	操作知识库

2. 飞书 Bot 创建与配置

2.1 创建飞书应用

1. 访问 https://open.feishu.cn/app
2. 点击「创建企业自建应用」
3. 填写应用信息：
   • 应用名称：OpenClaw Assistant
   • 应用描述：AI 助手
   • 应用图标：上传图标（可选）
4. 创建完成后，进入应用详情页

2.2 获取凭证

在「凭证与基础信息」页面获取：

# 应用凭证
App ID: cli_xxxxxxxxxxxxxxxx
App Secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

2.3 配置机器人能力

1. 在应用详情页，点击「添加应用能力」
2. 找到「机器人」，点击启用
3. 添加后，在「机器人」设置中配置：
   • 机器人名称：OpenClaw
   • 机器人描述：AI 助手

2.4 配置事件订阅

1. 进入「事件订阅」页面
2. 订阅以下事件：
   • im.message.receive_v1（接收消息）
3. 配置请求地址（等你部署好 OpenClaw 后填写）

2.5 安装应用到飞书

1. 在「版本管理与发布」页面
2. 创建版本并发布
3. 将应用添加到需要的飞书群或私聊

2.6 OpenClaw 配置

在 .env 中配置：

# 飞书应用凭证
FEISHU_APP_ID=cli_xxxxxxxxxxxxxxxx
FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxxxxxxxx

# 飞书消息配置
FEISHU_MESSAGE_WEBHOOK=   # 如使用 Webhook 方式
FEISHU_BOT_NAME=OpenClaw

在 AGENTS.md 中启用飞书 Channel：

## Channels

### 飞书
- **Status:** enabled
- **App ID:** cli_xxxxxxxxxxxxxxxx
- **Allowed Actions:**
  - Read messages where bot is mentioned
  - Send messages to channels
  - Read/write Feishu docs
  - Read/write Bitable

3. feishu_doc 文档操作

3.1 功能概述

feishu_doc Skill 让你可以读取、创建、写入飞书云文档。

3.2 读取文档

# 读取飞书文档
feishu_doc(action="read", doc_token="xxxxxxxxxxxx")

返回文档内容（Markdown 格式）。

3.3 创建文档

# 在指定文件夹创建新文档
feishu_doc(
    action="create",
    title="项目周报 - 2026-03-30",
    folder_token="xxxxxxxxxxxx"
)

返回新创建的文档 token。

3.4 写入文档

# 覆盖写入文档内容
feishu_doc(
    action="write",
    doc_token="xxxxxxxxxxxx",
    content="# 项目周报\n\n## 本周进展\n\n..."
)

3.5 追加内容

# 在文档末尾追加内容
feishu_doc(
    action="append",
    doc_token="xxxxxxxxxxxx",
    content="\n\n## 下周计划\n\n- 继续开发支付模块"
)

3.6 插入内容到指定位置

# 在指定 block 后插入内容
feishu_doc(
    action="insert",
    doc_token="xxxxxxxxxxxx",
    after_block_id="block_xxx",
    content="# 新章节\n\n内容..."
)

3.7 获取文档块结构

# 获取文档的块结构（用于精确定位）
feishu_doc(action="list_blocks", doc_token="xxxxxxxxxxxx")

返回文档的完整块树，可用于定位要修改的块。

4. feishu_bitable 多维表格

4.1 功能概述

feishu_bitable Skill 让你可以操作飞书多维表格（Bitable）。

4.2 解析 Bitable URL

收到一个 Bitable 链接时，先解析获取信息：

# 解析 Bitable URL
feishu_bitable_get_meta(url="https://xxx.feishu.cn/base/xxxxxxxxxxxx?table=yyyyyyyy")

返回：

{
  "app_token": "xxxxxxxxxxxx",
  "table_id": "yyyyyyyy",
  "name": "任务管理表"
}

4.3 列出记录

# 列出所有记录
feishu_bitable_list_records(
    app_token="xxxxxxxxxxxx",
    table_id="yyyyyyyy",
    page_size=100
)

4.4 查询记录

# 使用过滤条件查询
feishu_bitable_list_records(
    app_token="xxxxxxxxxxxx",
    table_id="yyyyyyyy",
    filter="AND(状态=\"进行中\", 负责人=\"张三\")"
)

4.5 创建记录

# 创建新记录
feishu_bitable_create_record(
    app_token="xxxxxxxxxxxx",
    table_id="yyyyyyyy",
    fields={
        "任务名称": "完成用户认证",
        "负责人": "张三",
        "状态": "已完成",
        "截止日期": "2026-03-30"
    }
)

4.6 更新记录

# 更新指定记录
feishu_bitable_update_record(
    app_token="xxxxxxxxxxxx",
    table_id="yyyyyyyy",
    record_id="xxxxxxxxxxxx",
    fields={
        "状态": "已完成"
    }
)

4.7 创建字段

# 创建新字段
feishu_bitable_create_field(
    app_token="xxxxxxxxxxxx",
    table_id="yyyyyyyy",
    field_name="优先级",
    field_type=3,  # 3 = SingleSelect
    property={
        "options": [
            {"name": "高"},
            {"name": "中"},
            {"name": "低"}
        ]
    }
)

常用 field_type：

类型 ID	类型名称	说明
1	Text	文本
2	Number	数字
3	SingleSelect	单选
4	MultiSelect	多选
5	DateTime	日期时间
7	Checkbox	复选框
11	User	用户
15	URL	链接
17	Attachment	附件

5. feishu_wiki 知识库

5.1 功能概述

feishu_wiki Skill 让你可以操作飞书知识库。

5.2 列出知识库空间

# 获取用户可访问的知识库空间列表
feishu_wiki(action="spaces")

5.3 列出节点

# 获取指定知识库空间下的节点
feishu_wiki(action="nodes", space_id="xxxxxxxxxxxx")

5.4 创建知识库节点

# 创建新的知识库文档
feishu_wiki(
    action="create",
    space_id="xxxxxxxxxxxx",
    parent_node_token="xxxxxxxxxxxx",  # 可选，父节点
    title="AI 助手使用指南",
    obj_type="docx"
)

5.5 移动节点

# 移动文档到新位置
feishu_wiki(
    action="move",
    node_token="xxxxxxxxxxxx",
    target_space_id="yyyyyyyyyyyy",
    target_parent_token="zzzzzzzzzzzz"
)

5.6 重命名节点

# 重命名知识库节点
feishu_wiki(
    action="rename",
    node_token="xxxxxxxxxxxx",
    title="新标题"
)

6. 飞书消息与卡片

6.1 发送普通消息

# 发送文本消息到群
message(
    action="send",
    channel="feishu",
    target="oc_xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    message="Hello from OpenClaw!"
)

# 发送文本消息到私聊
message(
    action="send",
    channel="feishu",
    target="ou_xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    message="这是一条私聊消息"
)

6.2 发送富文本消息

# 发送带格式的消息
message(
    action="send",
    channel="feishu",
    target="oc_xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    message="**粗体** 和 *斜体*\n- 列表项1\n- 列表项2\n> 引用文本"
)

飞书支持以下 Markdown 格式：

• **粗体**
• *斜体*
• - 列表
• 1. 有序列表
• > 引用
• `代码`

6.3 发送卡片消息

# 发送交互卡片
message(
    action="send",
    channel="feishu",
    target="oc_xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    effectId="interactive",
    content={
        "type": "card",
        "data": {
            "header": {
                "title": {"tag": "plain_text", "content": "项目更新"},
                "template": "blue"
            },
            "elements": [
                {
                    "tag": "markdown",
                    "content": "**本周进展**\n- 认证模块 ✅\n- 支付模块 🔄"
                },
                {"tag": "hr"},
                {
                    "tag": "action",
                    "actions": [
                        {
                            "tag": "button",
                            "text": {"tag": "plain_text", "content": "查看详情"},
                            "type": "primary"
                        }
                    ]
                }
            ]
        }
    }
)

6.4 卡片模板

常用的卡片模板类型：

模板	适用场景
blue	通用通知
red	紧急/错误
yellow	警告
green	成功
purple	信息
grey	灰色（低调）

7. 实战：自动推送日报

7.1 需求

每天早上 9:00，自动从 Jira 抓取昨日完成的任务，整理成日报，发送到飞书群。

7.2 系统架构

Cron (每天 9:00)
    ↓
OpenClaw 主会话
    ↓
Step 1: 从 Jira API 获取昨日任务
Step 2: 整理数据
Step 3: 使用 feishu_bitable 记录
Step 4: 生成卡片消息
Step 5: 使用 message 发送到飞书群

7.3 完整配置

第一步：配置 Jira API（假设有 REST API）

# .env
JIRA_URL=https://your-company.atlassian.net
JIRA_EMAIL=your-email@company.com
JIRA_API_TOKEN=your-jira-api-token
FEISHU_APP_ID=cli_xxxxxxxxxxxxxxxx
FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxxxxxxxx
FEISHU_CHAT_ID=oc_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

第二步：创建日报收集脚本

创建 scripts/fetch_jira_tasks.py：

#!/usr/bin/env python3
"""
从 Jira 获取昨日完成的任务
"""

import sys
import json
import urllib.request
import urllib.parse
from datetime import datetime, timedelta

def fetch_yesterday_tasks():
    yesterday = (datetime.now() - timedelta(days=1)).strftime("%Y-%m-%d")
    
    # Jira JQL 查询
    jql = urllib.parse.quote(
        f'project = "YourProject" AND status = Done '
        f'AND resolutiondate >= {yesterday}'
    )
    
    url = (
        f"{JIRA_URL}/rest/api/3/search"
        f"?jql={jql}"
        f"&fields=summary,assignee,status,resolutiondate"
    )
    
    req = urllib.request.Request(url)
    req.add_header("Authorization", f"Bearer {JIRA_API_TOKEN}")
    req.add_header("Accept", "application/json")
    
    with urllib.request.urlopen(req) as response:
        data = json.loads(response.read().decode())
        
        tasks = []
        for issue in data.get("issues", []):
            tasks.append({
                "key": issue["key"],
                "summary": issue["fields"]["summary"],
                "assignee": issue["fields"]["assignee"]["displayName"],
                "status": issue["fields"]["status"]["name"]
            })
        
        return tasks

if __name__ == "__main__":
    tasks = fetch_yesterday_tasks()
    print(json.dumps(tasks, ensure_ascii=False))

第三步：创建 HEARTBEAT.md 或 Cron 任务

# 添加每日日报 cron 任务
openclaw cron add "0 9 * * *" --name "每日日报推送" --prompt "
执行以下步骤生成和发送日报：

1. 执行 scripts/fetch_jira_tasks.py 获取昨日完成的任务

2. 整理数据，格式化为：
   - 按人分组
   - 每人的任务列表

3. 使用 feishu_bitable_create_record 记录到周报 Bitable：
   - 日期
   - 提交人
   - 任务内容

4. 生成飞书卡片消息：
   - 标题：【团队日报】+ 日期
   - 内容：按人分组的任务列表
   
5. 使用 message 发送到飞书群 FEISHU_CHAT_ID

卡片格式示例：
{
  "type": "card",
  "data": {
    "header": {
      "title": {"tag": "plain_text", "content": "【团队日报】2026-03-30"},
      "template": "blue"
    },
    "elements": [...]
  }
}
"

第四步：验证

# 查看 cron 任务
openclaw cron list

# 手动触发测试
openclaw cron run cron_1

# 查看日志
openclaw logs --tail 50

7.4 完整脚本：generate_daily_report.py

#!/usr/bin/env python3
"""
生成每日团队日报并发送到飞书
"""

import json
import sys
from datetime import datetime, timedelta
from scripts.fetch_jira_tasks import fetch_yesterday_tasks

def generate_report_card(tasks):
    """生成飞书卡片消息"""
    yesterday = (datetime.now() - timedelta(days=1)).strftime("%Y-%m-%d")
    
    # 按人分组
    by_person = {}
    for task in tasks:
        assignee = task.get("assignee", "未知")
        if assignee not in by_person:
            by_person[assignee] = []
        by_person[assignee].append(task)
    
    # 构建卡片元素
    elements = []
    
    if by_person:
        elements.append({
            "tag": "markdown",
            "content": f"**📅 日期：** {yesterday}\n\n**🏆 昨日完成（{len(tasks)} 项）**"
        })
        
        for person, person_tasks in by_person.items():
            task_list = "\n".join([
                f"- [{t['key']}] {t['summary']}"
                for t in person_tasks
            ])
            elements.append({
                "tag": "markdown",
                "content": f"**{person}**\n{task_list}"
            })
    else:
        elements.append({
            "tag": "markdown",
            "content": f"**📅 日期：** {yesterday}\n\n暂无完成任务 ✅"
        })
    
    elements.append({
        "tag": "note",
        "elements": [
            {"tag": "plain_text", "content": "🤖 由 OpenClaw AI 助手自动生成"}
        ]
    })
    
    card = {
        "type": "card",
        "data": {
            "header": {
                "title": {
                    "tag": "plain_text",
                    "content": f"【团队日报】{yesterday}"
                },
                "template": "blue"
            },
            "elements": elements
        }
    }
    
    return card

def main():
    # 获取任务
    tasks = fetch_yesterday_tasks()
    
    # 生成卡片
    card = generate_report_card(tasks)
    
    # 输出 JSON（供 OpenClaw 读取）
    print(json.dumps(card, ensure_ascii=False))

if __name__ == "__main__":
    main()

常见错误与避坑指南

错误 1：飞书应用没有开通 Bot 能力

症状： 发送消息时报错 bot is not enabled

解决：

1. 进入飞书开放平台的应用页面
2. 点击「添加应用能力」
3. 启用「机器人」能力
4. 重新发布应用

错误 2：多维表格权限不足

症状： 报错 app permission denied

原因： 应用没有访问该多维表格的权限

解决：

1. 打开多维表格
2. 点击右上角「…」→「设置」
3. 在「权限管理」中添加应用
4. 授予编辑权限

错误 3：消息发送成功但群里看不到

排查：

1. 确认 Bot 已被添加到群中
2. 确认发送到了正确的 chat_id
3. 检查是否触发了飞书的反垃圾机制（短时间内发送太多消息）

错误 4：文档 token 无效

症状： 报错 document token invalid

原因： 文档 token 有两种（docx 和 doc），需要区分

解决：

• 云文档（新版）：token 格式类似 xxxxxxxxxxxx，用于 feishu_doc
• 旧版文档：token 格式类似 docx_xxxxxxxxxxxx

错误 5：消息卡片显示不完整

原因： 卡片元素超过限制

飞书卡片限制：

• 最多 20 个元素
• 每个元素内容不超过 2000 字符
• header + elements 总大小不超过 30KB

术语注释

术语	英文	解释
App Token	应用凭证	飞书应用的唯一标识
Chat ID	会话 ID	飞书群或私聊的唯一标识
Bitable	多维表格	飞书的在线表格/数据库
Wiki	知识库	飞书的文档知识库
Block	块	飞书文档的基本元素
Card	卡片	飞书的富文本消息格式

面试高频问答

Q1：飞书 Bot 和普通用户有什么区别？

回答：飞书 Bot 是一个特殊的「用户」，但有几个关键区别。第一，Bot 不能主动发起私聊（需要用户先发消息，或者通过 Webhook）；第二，Bot 发送消息会显示「机器人」标识；第三，Bot 有权限限制，不能做所有用户能做的事（比如加入群需要管理员操作）。但在消息能力上，Bot 可以发送富文本卡片、@人、回复消息等。

Q2：如何处理飞书 API 的限流？

回答：飞书 API 有调用频率限制（通常是 1000 次/分钟/应用）。处理方式有几种。第一是请求合并：不是逐条操作 Bitable，而是批量操作。第二是添加延迟：使用 time.sleep() 在请求之间加间隔。第三是错误重试：限流会返回 429 错误，应该实现指数退避重试。第四是缓存：不频繁读取同一份文档。

Q3：飞书文档和飞书多维表格有什么区别？

回答：飞书文档（docx）是富文本编辑，适合内容创作；飞书多维表格（bitable）是数据库式的表格，适合数据管理。文档的内容是块（block）的树状结构，可以包含文字、图片、表格等。多维表格则是行列数据结构，每行是一条记录，每列是一个字段（支持文本、数字、日期、用户等多种类型）。简单说：文档是「写」的，多维表格是「管」的。

深度扩展

深度 1：飞书消息的完整生命周期

理解飞书消息的完整流程，有助于调试：

1. 用户发送消息 → 飞书服务器接收
2. 飞书服务器 → POST 到 OpenClaw 的 Webhook 地址
3. OpenClaw → 解析消息，提取内容
4. OpenClaw → 路由到合适的处理逻辑
5. 处理完成 → 调用飞书 API 发送响应
6. 飞书服务器 → 将响应消息投递到群/私聊

如果消息没有收到，检查顺序：

• 飞书开放平台的事件订阅配置
• OpenClaw 的 Webhook 是否可达
• 消息是否被飞书反垃圾策略拦截

深度 2：飞书卡片与小程序

飞书支持更复杂的卡片交互，比如点击按钮触发回调：

# 带按钮交互的卡片
card = {
    "type": "card",
    "data": {
        "header": {...},
        "elements": [
            {...},
            {
                "tag": "action",
                "actions": [
                    {
                        "tag": "button",
                        "text": {"tag": "plain_text", "content": "批准"},
                        "type": "primary",
                        "value": {"record_id": "xxx", "action": "approve"}
                    },
                    {
                        "tag": "button",
                        "text": {"tag": "plain_text", "content": "拒绝"},
                        "type": "danger",
                        "value": {"record_id": "xxx", "action": "reject"}
                    }
                ]
            }
        ]
    }
}

用户点击按钮后，OpenClaw 会收到回调，可以处理审批流程。

深度 3：多语言国际化支持

飞书支持多语言，消息内容可以指定语言：

{
    "zh_cn": {
        "title": "项目更新",
        "content": "..."
    },
    "en_us": {
        "title": "Project Update",
        "content": "..."
    }
}

可以在消息中根据用户的语言设置选择合适的语言。

附录

A.1 飞书 Skill 工具速查

工具	功能	关键参数
feishu_doc(action=“read”)	读取文档	doc_token
feishu_doc(action=“write”)	写入文档	doc_token, content
feishu_doc(action=“create”)	创建文档	title, folder_token
feishu_bitable_get_meta	解析 URL	url
feishu_bitable_list_records	列出记录	app_token, table_id
feishu_bitable_create_record	创建记录	app_token, table_id, fields
feishu_bitable_update_record	更新记录	app_token, table_id, record_id, fields
feishu_wiki(action=“create”)	创建节点	space_id, title
feishu_wiki(action=“move”)	移动节点	node_token, target_parent_token
message(action=“send”)	发送消息	channel, target, message

A.2 飞书卡片模板速查

# header template 选项
"blue"    # 蓝色（通用）
"red"     # 红色（紧急）
"yellow"  # 黄色（警告）
"green"   # 绿色（成功）
"purple"  # 紫色
"grey"    # 灰色

# 常用 element tags
"markdown"   # Markdown 格式文本
"plain_text" # 纯文本
"divider"    # 分隔线（hr）
"note"      # 备注
"image"     # 图片
"action"    # 按钮组
"column_set" # 多列布局

A.3 飞书权限速查

权限	权限标识	用途
获取与发送单聊、群组消息	im:message	发消息
读取消息	im:message:readonly	收消息
获取与编辑云文档	docx:document	操作文档
获取与编辑多维表格	bitable:app	操作表格
获取与编辑知识库	wiki:space	操作 Wiki
获取用户 ID	contact:user.base:readonly	获取用户信息

系列总结（第 01-09 章）

通过前九章的学习，我们已经掌握了 OpenClaw 的完整能力体系：

第 01-06 章： 基础认知、配置体系、人格设计、记忆系统、Skills 架构、核心工具集
第 07-08 章： 编程 Agent 集成、多模型智能路由

第 09 章： 飞书集成，企业级 AI 助手

现在你已经能够把 OpenClaw 与飞书深度集成，实现企业级的 AI 自动化。下一章我们将学习定时任务与 Heartbeat 机制，让 OpenClaw 能够主动工作、自动执行定期任务。读完第 10 章，你将能够构建一个完全自动化运行的 AI 助手。

版权声明

本文为原创技术实践文章，禁止未经授权的全文转载；引用请注明出处与本文链接。