OpenClaw 接入飞书：完整配置指南

七夜zippoe2026-03-26 8:43

目 录

    • 摘要
    • [1. 引言](#1. 引言)
    • [2. 飞书开放平台介绍](#2. 飞书开放平台介绍)
      • [2.1 平台概述](#2.1 平台概述)
      • [2.2 应用类型](#2.2 应用类型)
      • [2.3 核心概念](#2.3 核心概念)
    • [3. 创建企业自建应用](#3. 创建企业自建应用)
      • [3.1 进入开放平台](#3.1 进入开放平台)
      • [3.2 创建应用步骤](#3.2 创建应用步骤)
      • [3.3 获取凭证信息](#3.3 获取凭证信息)
    • [4. 配置应用权限](#4. 配置应用权限)
      • [4.1 权限模型](#4.1 权限模型)
      • [4.2 OpenClaw 必需权限](#4.2 OpenClaw 必需权限)
      • [4.3 权限配置步骤](#4.3 权限配置步骤)
    • [5. OpenClaw 飞书渠道配置](#5. OpenClaw 飞书渠道配置)
      • [5.1 配置文件结构](#5.1 配置文件结构)
      • [5.2 核心配置项详解](#5.2 核心配置项详解)
      • [5.3 配置验证](#5.3 配置验证)
    • [6. 私聊与群聊策略](#6. 私聊与群聊策略)
      • [6.1 私聊策略](#6.1 私聊策略)
      • [6.2 群聊策略](#6.2 群聊策略)
      • [6.3 策略对比](#6.3 策略对比)
      • [6.4 消息处理流程](#6.4 消息处理流程)
    • [7. 消息格式与卡片](#7. 消息格式与卡片)
      • [7.1 文本消息](#7.1 文本消息)
      • [7.2 富文本消息](#7.2 富文本消息)
      • [7.3 卡片消息](#7.3 卡片消息)
      • [7.4 消息类型对比](#7.4 消息类型对比)
    • [8. 事件订阅配置](#8. 事件订阅配置)
      • [8.1 事件订阅原理](#8.1 事件订阅原理)
      • [8.2 配置事件订阅](#8.2 配置事件订阅)
      • [8.3 事件处理示例](#8.3 事件处理示例)
      • [8.4 事件订阅架构](#8.4 事件订阅架构)
    • [9. 常见问题与解决方案](#9. 常见问题与解决方案)
      • [9.1 消息无法接收](#9.1 消息无法接收)
      • [9.2 消息发送失败](#9.2 消息发送失败)
      • [9.3 群聊无响应](#9.3 群聊无响应)
      • [9.4 Token 过期问题](#9.4 Token 过期问题)
      • [9.5 消息加密验证失败](#9.5 消息加密验证失败)
    • [10. 高级配置](#10. 高级配置)
      • [10.1 多机器人支持](#10.1 多机器人支持)
      • [10.2 消息中间件](#10.2 消息中间件)
      • [10.3 自定义 Skill 集成](#10.3 自定义 Skill 集成)
    • [11. 部署与运维](#11. 部署与运维)
      • [11.1 生产环境部署](#11.1 生产环境部署)
      • [11.2 监控与告警](#11.2 监控与告警)
      • [11.3 日志管理](#11.3 日志管理)
    • [12. 总结](#12. 总结)
    • 参考资料

摘要

本文详细介绍了如何将 OpenClaw AI 助手框架接入飞书平台，实现企业级智能对话服务。文章从飞书开放平台的基础概念入手，逐步讲解创建企业自建应用、配置应用权限、设置事件订阅等核心步骤，并深入分析 OpenClaw 的飞书渠道配置细节。通过私聊与群聊策略的对比，帮助读者理解不同场景下的最佳实践。同时，本文还涵盖了消息格式、卡片消息、常见问题解决方案等实用内容。无论你是初次接触飞书开发的入门者，还是希望将现有 AI 助手接入飞书的开发者，都能从本文中获得完整的实施指南。

1. 引言

在企业数字化转型的浪潮中，即时通讯工具已成为团队协作的核心载体。飞书作为字节跳动旗下的企业协作平台，凭借其强大的开放能力和丰富的 API 接口，为企业构建智能化办公场景提供了坚实基础。而 OpenClaw 作为一款开源的 AI 助手框架，支持多渠道接入、本地部署、技能扩展等特性，是构建企业智能助手的理想选择。

将 OpenClaw 接入飞书，可以让 AI 助手无缝融入企业日常工作流程。员工可以通过私聊或群聊的方式与 AI 助手交互，获取信息查询、任务执行、文档处理等服务。这种集成不仅提升了工作效率，还为企业构建专属的智能办公生态奠定了基础。

本文将从零开始，手把手教你完成 OpenClaw 与飞书的对接。内容涵盖飞书开放平台介绍、应用创建与配置、权限管理、事件订阅、消息处理等核心环节，并提供详细的代码示例和配置说明。通过本文的学习，你将能够独立完成一个功能完整的飞书 AI 助手部署。

2. 飞书开放平台介绍

2.1 平台概述

飞书开放平台是飞书为开发者提供的统一接入入口，通过开放 API、SDK、Webhook 等方式，让第三方应用能够与飞书深度集成。平台支持多种应用类型，包括企业自建应用、商店应用、小程序等，满足不同场景的开发需求。

飞书开放平台的核心能力包括：

  • 消息与群组：发送消息、管理群组、处理消息事件
  • 通讯录管理：获取用户信息、部门结构、组织架构
  • 日历与会议：创建日程、管理会议室、发起会议
  • 文档协作：读写文档、管理知识库、处理表格
  • 审批与流程：创建审批流程、处理审批任务
  • 机器人能力：自定义机器人、消息卡片、交互式组件

2.2 应用类型

飞书开放平台支持多种应用类型，开发者可根据实际需求选择：

应用类型 适用场景 审核要求 分发范围
企业自建应用 企业内部使用，定制化需求 无需审核 仅本企业
商店应用 面向所有飞书用户，SaaS 服务 需通过审核 全平台用户
小程序 轻量级应用，快速启动 需通过审核 全平台用户
企业小程序 企业内部轻量应用 无需审核 仅本企业

对于 OpenClaw 接入场景，推荐使用企业自建应用。这种方式无需审核流程，配置灵活，适合企业内部 AI 助手的快速部署。

2.3 核心概念

在开始配置之前，需要理解几个核心概念：

App ID 与 App Secret

每个飞书应用都有唯一的 App ID 和 App Secret，用于身份验证和 API 调用。App ID 是公开的标识符，而 App Secret 需要妥善保管，类似于密码。

tenant_access_token

租户访问令牌是调用飞书 API 的关键凭证。通过 App ID 和 App Secret 获取，有效期 2 小时。OpenClaw 会自动管理令牌的获取和刷新。

事件订阅

飞书通过事件订阅机制将消息、审批等事件推送到开发者服务器。需要配置一个公网可访问的 HTTP 端点来接收事件。

3. 创建企业自建应用

3.1 进入开放平台

首先，访问飞书开放平台官网（https://open.feishu.cn），使用飞书账号登录。如果你是企业管理员，可以直接进入开发者后台；如果不是，需要联系管理员添加开发者权限。

登录后，点击右上角的「开发者后台」进入应用管理界面。这里可以看到企业已有的所有应用，以及创建新应用的入口。

3.2 创建应用步骤

点击「创建企业自建应用」按钮，进入应用创建流程：

  1. 填写基本信息

    • 应用名称：建议使用有辨识度的名称，如「AI 助手」或「智能客服」
    • 应用描述：简要说明应用功能，如「基于 OpenClaw 的企业智能助手」
    • 应用图标：上传一个 512×512 像素的图标，建议使用简洁的设计风格

  2. 选择应用能力

    • 根据需求勾选需要的能力，OpenClaw 接入通常需要：
      • 机器人能力（必选）
      • 消息能力（必选）
      • 通讯录能力（可选，用于获取用户信息）

  3. 提交创建

    • 确认信息无误后，点击「创建」按钮
    • 创建成功后，系统会自动跳转到应用详情页

3.3 获取凭证信息

创建完成后，在应用详情页的「凭证与基础信息」栏目中，可以看到：

  • App ID ：应用的唯一标识，格式如 cli_xxxxxxxxxxxx
  • App Secret：应用的密钥，点击「查看」后显示

这两个值是 OpenClaw 配置的关键参数，需要记录下来。建议使用密码管理器保存 App Secret，避免泄露。

yaml 复制代码 
# OpenClaw 飞书渠道配置示例
channels:
  feishu:
    enabled: true
    app_id: "cli_xxxxxxxxxxxxxxxx"      # 替换为你的 App ID
    app_secret: "xxxxxxxxxxxxxxxxxxxx"   # 替换为你的 App Secret
    encrypt_key: ""                      # 消息加密密钥（可选）
    verification_token: ""               # 验证令牌（可选）

上述配置展示了 OpenClaw 中飞书渠道的基本配置结构。app_id 和 app_secret 是必填项，从飞书开放平台获取。encrypt_key 和 verification_token 用于消息加密验证，可在飞书开放平台的「事件订阅」页面配置。在生产环境中，建议启用消息加密以增强安全性。

4. 配置应用权限

4.1 权限模型

飞书采用细粒度的权限控制模型，应用需要申请相应的权限才能调用 API 或接收事件。权限分为以下几类：

权限类型 说明 示例
通讯录权限 获取用户、部门、群组信息 contact:user.base:readonly
消息权限 发送消息、获取消息内容 im:message, im:message:send_as_bot
群组权限 创建群、管理群成员 im:chat, im:chat:readonly
文档权限 读写文档、表格、知识库 docs:doc:readonly, wiki:wiki:readonly
日历权限 管理日程、会议室 calendar:calendar:readonly

4.2 OpenClaw 必需权限

对于 OpenClaw 的基本功能，需要配置以下权限：

消息相关权限

  • im:message - 获取消息内容
  • im:message:send_as_bot - 以机器人身份发送消息
  • im:message:receive_as_bot - 接收发送给机器人的消息
  • im:chat - 获取群组信息
  • im:chat:readonly - 读取群组列表

通讯录权限（可选）

  • contact:user.base:readonly - 获取用户基本信息
  • contact:user.department_id:readonly - 获取用户部门信息

4.3 权限配置步骤

在飞书开放平台的应用详情页，进入「权限管理」栏目：

  1. 搜索权限

    • 在搜索框中输入权限名称或关键词
    • 例如搜索「message」可找到所有消息相关权限

  2. 申请权限

    • 点击权限右侧的「申请权限」按钮
    • 对于敏感权限，需要填写申请理由
    • 部分权限需要管理员审批

  3. 发布版本

    • 权限配置完成后，需要发布新版本才能生效
    • 点击「版本管理与发布」→「创建版本」
    • 填写版本号和更新说明，提交发布
yaml 复制代码 
# OpenClaw 权限配置建议
permissions:
  required:
    - im:message                    # 基础消息能力
    - im:message:send_as_bot        # 发送消息
    - im:message:receive_as_bot     # 接收消息
    - im:chat                       # 群组管理
    - im:chat:readonly              # 读取群组信息
  
  optional:
    - contact:user.base:readonly    # 用户信息（用于个性化）
    - contact:user.department_id:readonly  # 部门信息
    - docs:doc:readonly             # 文档读取（如需处理文档）
    - wiki:wiki:readonly            # 知识库读取

上述配置以 YAML 格式列出了 OpenClaw 接入飞书所需的权限。required 部分是必选权限，缺少这些权限将导致核心功能无法使用。optional 部分是可选权限，根据实际需求选择配置。在申请权限时，建议遵循最小权限原则，只申请必要的权限，以降低安全风险。

5. OpenClaw 飞书渠道配置

5.1 配置文件结构

OpenClaw 采用 YAML 格式的配置文件，飞书渠道的配置位于 channels.feishu 节点下。完整的配置结构如下：

yaml 复制代码 
# OpenClaw 飞书渠道完整配置
channels:
  feishu:
    # 基础配置
    enabled: true
    app_id: "cli_xxxxxxxxxxxxxxxx"
    app_secret: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    
    # 消息加密配置（推荐开启）
    encrypt_key: "your-encrypt-key-32-chars"
    verification_token: "your-verification-token"
    
    # 事件订阅配置
    event_callback:
      enabled: true
      endpoint: "/feishu/webhook"
    
    # 消息处理配置
    message:
      # 私聊策略
      private_chat:
        enabled: true
        prefix: ""                    # 触发前缀，留空表示所有消息都响应
        mention_required: false       # 是否需要 @ 机器人
      
      # 群聊策略
      group_chat:
        enabled: true
        mention_required: true        # 群聊需要 @ 机器人
        prefix: ""                    # 可选的前缀触发
    
    # 机器人信息
    bot:
      name: "AI助手"
      avatar: "https://example.com/avatar.png"

5.2 核心配置项详解

基础凭证配置

app_id 和 app_secret 是飞书应用的凭证，从飞书开放平台获取。这两个参数是必填项，缺少将无法完成身份验证。

消息加密配置

encrypt_key 和 verification_token 用于消息加密和验证。开启后，飞书推送的消息会经过加密，OpenClaw 需要使用相同的密钥解密。建议在生产环境中开启此功能。

事件订阅配置

event_callback 定义了事件回调的配置。endpoint 是接收事件的 HTTP 端点，需要与飞书开放平台中配置的 URL 一致。

消息处理配置

private_chat 和 group_chat 分别定义私聊和群聊的处理策略。mention_required 控制是否需要 @ 机器人才触发响应，prefix 定义触发前缀。

5.3 配置验证

完成配置后，可以通过以下命令验证配置是否正确：

bash 复制代码 
# 验证 OpenClaw 飞书配置
openclaw config validate --channel feishu

# 测试飞书 API 连接
openclaw test feishu --action ping

# 查看当前配置
openclaw config show --channel feishu

上述命令用于验证 OpenClaw 的飞书渠道配置。第一条命令检查配置文件的语法和必填项是否正确。第二条命令测试与飞书 API 的连接是否正常。第三条命令显示当前的飞书渠道配置，方便排查问题。如果配置有误，命令会输出具体的错误信息，指导用户修正。

6. 私聊与群聊策略

6.1 私聊策略

私聊场景下，用户与机器人是一对一的关系，消息处理相对简单。OpenClaw 默认会响应私聊中的所有消息，但也可以通过配置进行调整。

触发机制

私聊场景下，用户发送的每条消息都会触发机器人响应。如果设置了 prefix，则只有以指定前缀开头的消息才会被处理。

yaml 复制代码 
# 私聊配置示例
private_chat:
  enabled: true
  prefix: ""              # 留空：所有消息都响应
  mention_required: false # 私聊不需要 @
  # prefix: "ai"          # 设置前缀：只有 "ai 你好" 才响应

上下文管理

私聊场景下，OpenClaw 会自动维护对话上下文。用户可以连续发送多条消息，机器人会记住之前的对话内容。上下文存储在工作空间的 memory 目录中。

权限控制

可以通过配置限制哪些用户可以使用机器人：

yaml 复制代码 
# 私聊权限配置
private_chat:
  # 白名单模式：只允许指定用户
  whitelist:
    enabled: true
    users:
      - "ou_xxxxxxxxxx"   # 用户 Open ID
      - "ou_yyyyyyyyyy"
  
  # 黑名单模式：禁止指定用户
  blacklist:
    enabled: false
    users: []

6.2 群聊策略

群聊场景下，机器人需要处理更复杂的交互逻辑。默认情况下，OpenClaw 只响应 @ 机器人的消息，避免在群聊中产生过多噪音。

触发机制

yaml 复制代码 
# 群聊配置示例
group_chat:
  enabled: true
  mention_required: true   # 默认：需要 @ 机器人
  prefix: ""
  
  # 可选：响应所有消息（谨慎使用）
  # mention_required: false
  # respond_to_all: true

群组白名单

可以限制机器人只在特定群组中工作：

yaml 复制代码 
# 群组白名单配置
group_chat:
  whitelist:
    enabled: true
    groups:
      - "oc_xxxxxxxxxx"   # 群组 Chat ID
      - "oc_yyyyyyyyyy"

6.3 策略对比

特性 私聊 群聊
默认触发 所有消息 需要 @ 机器人
上下文 自动维护 自动维护（按群组隔离）
权限控制 用户白名单/黑名单 群组白名单
消息可见性 仅双方可见 群内所有成员可见
响应速度 即时响应 即时响应
适用场景 个人助手、隐私对话 团队协作、信息共享

6.4 消息处理流程

私聊
群聊
是
否
匹配
不匹配
是
否
通过
不通过
收到消息
消息类型
是否设置前缀
是否 @ 机器人
消息是否匹配前缀
处理消息
忽略消息
权限检查
调用 AI 模型
返回权限错误
生成回复
发送消息

上述流程图展示了 OpenClaw 处理飞书消息的完整流程。收到消息后，首先判断是私聊还是群聊。私聊消息根据前缀配置决定是否处理，群聊消息需要检查是否 @ 了机器人。通过检查后，进行权限验证，最后调用 AI 模型生成回复并发送。

7. 消息格式与卡片

7.1 文本消息

最基础的消息格式是纯文本消息。OpenClaw 支持发送富文本消息，包括加粗、斜体、链接等格式。

python 复制代码 
# OpenClaw 发送文本消息示例
async def send_text_message(chat_id: str, text: str):
    """
    发送文本消息到飞书
    
    Args:
        chat_id: 会话 ID，可以是用户 ID 或群组 ID
        text: 消息文本内容
    """
    message = {
        "receive_id": chat_id,
        "msg_type": "text",
        "content": json.dumps({
            "text": text
        })
    }
    
    response = await feishu_client.send_message(message)
    return response

上述代码展示了如何使用 OpenClaw 发送简单的文本消息。receive_id 是目标会话的标识，可以是用户的 Open ID（私聊）或群组的 Chat ID（群聊）。msg_type 指定消息类型为文本，content 包含具体的消息内容。这个函数封装了飞书消息发送 API，可以在 Skills 中直接调用。

7.2 富文本消息

飞书支持富文本消息，可以包含多种格式元素：

python 复制代码 
# OpenClaw 发送富文本消息示例
async def send_rich_text_message(chat_id: str):
    """
    发送富文本消息
    
    富文本支持多种格式：
    - 文本加粗、斜体、下划线
    - 超链接
    - @ 用户
    - 代码块
    """
    content = {
        "zh_cn": {
            "title": "任务完成通知",
            "content": [
                [
                    {"tag": "text", "text": "任务 "},
                    {"tag": "text", "text": "代码审查", "style": ["bold"]},
                    {"tag": "text", "text": " 已完成"}
                ],
                [
                    {"tag": "text", "text": "执行时间："},
                    {"tag": "text", "text": "2024-01-15 14:30", "style": ["italic"]}
                ],
                [
                    {"tag": "a", "text": "查看详情", "href": "https://example.com/task/123"}
                ]
            ]
        }
    }
    
    message = {
        "receive_id": chat_id,
        "msg_type": "post",
        "content": json.dumps(content)
    }
    
    return await feishu_client.send_message(message)

上述代码展示了如何发送富文本消息。富文本消息使用 post 类型，内容是一个结构化的 JSON 对象。content 数组中的每个元素代表一个段落，段落中的元素可以是文本、链接、@ 提及等。通过 style 属性可以设置文本样式，如 bold（加粗）、italic（斜体）等。

7.3 卡片消息

卡片消息是飞书的高级消息格式，支持丰富的交互组件：

python 复制代码 
# OpenClaw 发送卡片消息示例
async def send_card_message(chat_id: str):
    """
    发送交互式卡片消息
    
    卡片消息支持：
    - 标题、正文、图片
    - 按钮、选择器
    - 表单输入
    - 回调交互
    """
    card = {
        "type": "template",
        "data": {
            "template_id": "AAqk8J8J",  # 使用模板 ID
            "template_variable": {
                "title": "代码审查请求",
                "content": "请审查以下代码变更",
                "files": ["main.py", "utils.py"],
                "author": "张三"
            }
        }
    }
    
    # 或者直接定义卡片内容
    card_direct = {
        "config": {
            "wide_screen_mode": True
        },
        "elements": [
            {
                "tag": "div",
                "text": {
                    "content": "**代码审查请求**\n请审查以下变更",
                    "tag": "lark_md"
                }
            },
            {
                "tag": "action",
                "actions": [
                    {
                        "tag": "button",
                        "text": {"content": "批准", "tag": "plain_text"},
                        "type": "primary",
                        "value": {"action": "approve"}
                    },
                    {
                        "tag": "button",
                        "text": {"content": "拒绝", "tag": "plain_text"},
                        "type": "danger",
                        "value": {"action": "reject"}
                    }
                ]
            }
        ]
    }
    
    message = {
        "receive_id": chat_id,
        "msg_type": "interactive",
        "card": json.dumps(card_direct)
    }
    
    return await feishu_client.send_message(message)

上述代码展示了两种创建卡片消息的方式。第一种使用预定义的模板 ID，通过 template_variable 传递变量值。第二种直接定义卡片结构，包含文本元素和交互按钮。卡片消息非常适合需要用户交互的场景，如审批流程、问卷调查、任务确认等。

7.4 消息类型对比

消息类型 适用场景 交互能力 开发复杂度
文本消息 简单通知、对话回复 无 低
富文本消息 格式化内容、带链接的通知 链接跳转 中
卡片消息 表单、审批、复杂交互 按钮、选择器、回调 高
图片消息 图表、截图、视觉内容 无 低
文件消息 文档分享、报告发送 下载 低

8. 事件订阅配置

8.1 事件订阅原理

飞书通过事件订阅机制将应用相关的事件推送到开发者服务器。当用户发送消息、加入群组、修改文档等操作时，飞书会将事件数据 POST 到配置的回调 URL。
AI 模型 OpenClaw Gateway 飞书服务器 用户 AI 模型 OpenClaw Gateway 飞书服务器 用户 发送消息给机器人 POST 事件到回调 URL 验证签名 解析事件内容 发送消息内容 返回 AI 回复 调用 API 发送消息 推送机器人回复

上述时序图展示了飞书事件订阅的完整流程。用户发送消息后，飞书服务器将事件推送到 OpenClaw Gateway。Gateway 验证签名并解析事件，然后调用 AI 模型生成回复，最后通过飞书 API 将回复发送给用户。

8.2 配置事件订阅

在飞书开放平台配置事件订阅：

  1. 设置回调 URL

    • 进入应用详情页 → 「事件订阅」
    • 填写回调 URL，格式如 https://your-domain.com/feishu/webhook
    • URL 必须是 HTTPS 协议，且公网可访问

  2. 选择订阅事件

    • 在事件列表中勾选需要订阅的事件
    • OpenClaw 常用事件：
      • im.message.receive_v1 - 接收消息
      • im.chat.member_added_v1 - 群成员增加
      • im.chat.member_deleted_v1 - 群成员减少

  3. 配置加密

    • 点击「加密策略」开启消息加密
    • 设置 Encrypt Key 和 Verification Token
    • 将这两个值配置到 OpenClaw 的配置文件中

8.3 事件处理示例

python 复制代码 
# OpenClaw 飞书事件处理器示例
from openclaw.channels.feishu import FeishuEventHandler

class MessageHandler(FeishuEventHandler):
    """飞书消息事件处理器"""
    
    async def on_message_receive(self, event):
        """
        处理接收到的消息事件
        
        Args:
            event: 飞书推送的事件对象，包含：
                - event_type: 事件类型
                - event: 事件内容
                - event_id: 事件 ID
        """
        # 解析消息内容
        message = event.get("event", {}).get("message", {})
        chat_id = message.get("chat_id")
        content = json.loads(message.get("content", "{}"))
        msg_type = message.get("message_type")
        
        # 根据消息类型处理
        if msg_type == "text":
            text = content.get("text", "")
            # 调用 AI 模型处理
            response = await self.ai_model.chat(text, chat_id)
            # 发送回复
            await self.send_text_message(chat_id, response)
        
        elif msg_type == "image":
            # 处理图片消息
            image_key = content.get("image_key")
            await self.handle_image(chat_id, image_key)
        
        return {"success": True}
    
    async def on_chat_member_added(self, event):
        """处理群成员增加事件"""
        chat_info = event.get("event", {}).get("chat", {})
        chat_id = chat_info.get("chat_id")
        
        # 发送欢迎消息
        await self.send_text_message(
            chat_id, 
            "欢迎加入群聊！我是 AI 助手，有什么可以帮助你的吗？"
        )

上述代码展示了 OpenClaw 中飞书事件处理器的实现方式。MessageHandler 继承自 FeishuEventHandler，重写了 on_message_receive 方法来处理消息事件。根据消息类型（文本、图片等）进行不同的处理逻辑。对于文本消息，调用 AI 模型生成回复；对于图片消息，可以调用图片识别服务。这个处理器框架可以轻松扩展，支持更多事件类型。

8.4 事件订阅架构

AI 服务
开发者服务器
飞书云端
HTTP POST
API 调用
飞书服务器
事件队列
OpenClaw Gateway
事件分发器
消息处理器
群组处理器
其他处理器
AI 模型

上述架构图展示了飞书事件订阅的整体架构。飞书服务器将事件推送到 OpenClaw Gateway，Gateway 中的事件分发器根据事件类型将事件路由到不同的处理器。处理器可以调用 AI 模型或其他服务，最后通过飞书 API 发送响应。

9. 常见问题与解决方案

9.1 消息无法接收

问题描述：配置完成后，机器人无法接收用户发送的消息。

排查步骤：

  1. 检查事件订阅是否正确配置

    • 确认回调 URL 可公网访问
    • 确认已订阅 im.message.receive_v1 事件

  2. 检查应用权限

    • 确认已申请 im:message:receive_as_bot 权限
    • 确认权限已发布生效

  3. 检查网络连接

    • 确认服务器防火墙允许飞书 IP 访问
    • 确认 SSL 证书配置正确
bash 复制代码 
# 测试回调 URL 是否可访问
curl -X POST https://your-domain.com/feishu/webhook \
  -H "Content-Type: application/json" \
  -d '{"challenge":"test"}'

# 查看 OpenClaw 日志
openclaw logs --channel feishu --tail 100

9.2 消息发送失败

问题描述：机器人可以接收消息，但无法发送回复。

常见原因：

错误码 原因 解决方案
99991663 权限不足 申请 im:message:send_as_bot 权限
99991661 会话不存在 检查 chat_id 是否正确
99991400 参数错误 检查消息格式是否正确
99991600 token 过期 检查 token 刷新逻辑

解决方案：

python 复制代码 
# OpenClaw 消息发送错误处理示例
async def send_message_safe(chat_id: str, content: dict):
    """带错误处理的消息发送"""
    try:
        response = await feishu_client.send_message({
            "receive_id": chat_id,
            "msg_type": content["type"],
            "content": json.dumps(content["data"])
        })
        return response
    except FeishuAPIError as e:
        if e.code == 99991663:
            logger.error("权限不足，请检查应用权限配置")
        elif e.code == 99991661:
            logger.error(f"会话不存在: {chat_id}")
        elif e.code == 99991400:
            logger.error(f"消息格式错误: {content}")
        raise

9.3 群聊无响应

问题描述：机器人在群聊中不响应消息。

排查步骤：

  1. 确认机器人已加入群聊
  2. 确认消息是否 @ 了机器人
  3. 检查群聊配置中的 mention_required 设置
yaml 复制代码 
# 群聊配置检查
group_chat:
  enabled: true
  mention_required: true  # 确认此设置
  
  # 如果希望响应所有消息（不推荐）
  # mention_required: false
  # respond_to_all: true

9.4 Token 过期问题

问题描述：运行一段时间后，API 调用返回 token 过期错误。

原因分析：飞书的 tenant_access_token 有效期为 2 小时，需要定期刷新。

解决方案：OpenClaw 内置了 token 自动刷新机制，但如果遇到问题，可以手动刷新：

python 复制代码 
# OpenClaw token 管理示例
class FeishuTokenManager:
    """飞书 Token 管理器"""
    
    def __init__(self, app_id: str, app_secret: str):
        self.app_id = app_id
        self.app_secret = app_secret
        self._token = None
        self._expire_time = 0
    
    async def get_token(self) -> str:
        """获取有效的 token，自动刷新"""
        import time
        current_time = time.time()
        
        # 提前 5 分钟刷新
        if self._token and current_time < self._expire_time - 300:
            return self._token
        
        # 获取新 token
        response = await self._request_token()
        self._token = response["tenant_access_token"]
        self._expire_time = current_time + response["expire"]
        
        return self._token
    
    async def _request_token(self) -> dict:
        """向飞书请求 token"""
        url = "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal"
        data = {
            "app_id": self.app_id,
            "app_secret": self.app_secret
        }
        async with aiohttp.ClientSession() as session:
            async with session.post(url, json=data) as resp:
                return await resp.json()

上述代码展示了 OpenClaw 中飞书 token 管理器的实现。get_token 方法会检查当前 token 是否有效，如果即将过期则自动刷新。通过提前 5 分钟刷新的策略，避免了 token 在使用过程中过期的问题。这个管理器被 OpenClaw 内部使用，开发者通常不需要直接操作。

9.5 消息加密验证失败

问题描述：开启消息加密后，收到签名验证失败的错误。

解决方案：

  1. 确认 Encrypt Key 配置正确
  2. 确认 Verification Token 配置正确
  3. 检查时间戳是否在有效期内（默认 5 分钟）
python 复制代码 
# OpenClaw 消息签名验证示例
import hmac
import hashlib
import time

def verify_signature(timestamp: str, nonce: str, body: str, 
                     signature: str, encrypt_key: str) -> bool:
    """
    验证飞书消息签名
    
    Args:
        timestamp: 请求时间戳
        nonce: 随机字符串
        body: 请求体
        signature: 签名值
        encrypt_key: 加密密钥
    
    Returns:
        签名是否有效
    """
    # 检查时间戳是否在有效期内
    if abs(time.time() - int(timestamp)) > 300:  # 5 分钟
        return False
    
    # 计算签名
    sign_base = timestamp + nonce + encrypt_key + body
    expected_signature = hashlib.sha256(
        sign_base.encode()
    ).hexdigest()
    
    return hmac.compare_digest(signature, expected_signature)

10. 高级配置

10.1 多机器人支持

OpenClaw 支持配置多个飞书机器人，适用于不同业务场景：

yaml 复制代码 
# 多机器人配置示例
channels:
  feishu:
    bots:
      - name: "客服机器人"
        app_id: "cli_xxxxxxxxxx1"
        app_secret: "secret1"
        skills: ["customer-service", "faq"]
      
      - name: "开发助手"
        app_id: "cli_xxxxxxxxxx2"
        app_secret: "secret2"
        skills: ["code-review", "ci-cd"]

10.2 消息中间件

可以通过中间件扩展消息处理逻辑：

python 复制代码 
# OpenClaw 消息中间件示例
class RateLimitMiddleware:
    """消息频率限制中间件"""
    
    def __init__(self, max_requests: int = 10, window: int = 60):
        self.max_requests = max_requests
        self.window = window
        self.request_counts = {}
    
    async def process(self, message, next_handler):
        user_id = message.get("sender", {}).get("user_id")
        
        # 检查请求频率
        if self._is_rate_limited(user_id):
            return {
                "text": "您的请求过于频繁，请稍后再试"
            }
        
        # 记录请求
        self._record_request(user_id)
        
        # 继续处理
        return await next_handler(message)

10.3 自定义 Skill 集成

为飞书机器人添加自定义技能：

yaml 复制代码 
# 技能配置示例
skills:
  - name: "weather"
    enabled: true
    triggers:
      - "天气"
      - "weather"
  
  - name: "calendar"
    enabled: true
    triggers:
      - "日程"
      - "日历"
  
  - name: "code-review"
    enabled: true
    triggers:
      - "代码审查"
      - "code review"

11. 部署与运维

11.1 生产环境部署

是
否
是
否
开发环境
测试环境
测试通过?
生产环境
监控运行
发现问题?
修复问题

11.2 监控与告警

yaml 复制代码 
# OpenClaw 监控配置
monitoring:
  enabled: true
  
  # 健康检查
  health_check:
    endpoint: "/health"
    interval: 30  # 秒
  
  # 告警配置
  alerts:
    - type: "error_rate"
      threshold: 0.05  # 5% 错误率
      channels: ["feishu", "email"]
    
    - type: "response_time"
      threshold: 5000  # 5 秒
      channels: ["feishu"]

11.3 日志管理

bash 复制代码 
# OpenClaw 日志配置
openclaw config set logging.level info
openclaw config set logging.format json
openclaw config set logging.output /var/log/openclaw/app.log

# 日志轮转配置
openclaw config set logging.rotation.max_size 100MB
openclaw config set logging.rotation.max_files 10

12. 总结

本文从飞书开放平台的基础概念入手，详细介绍了将 OpenClaw AI 助手接入飞书的完整流程。通过企业自建应用的创建、权限配置、事件订阅设置，我们构建了一个功能完整的飞书机器人。文章还深入探讨了私聊与群聊的不同策略、消息格式与卡片消息的使用、常见问题的解决方案等内容。

核心要点总结如下：

  1. 应用配置是基础：正确创建企业自建应用并配置权限是接入的第一步，需要特别注意消息相关权限的申请。

  2. 事件订阅是核心：飞书通过事件订阅推送消息，需要配置公网可访问的回调 URL，并正确处理各类事件。

  3. 策略配置要合理：私聊和群聊有不同的触发机制，需要根据实际场景选择合适的策略，避免在群聊中产生过多噪音。

  4. 消息格式要丰富：飞书支持文本、富文本、卡片等多种消息格式，合理使用卡片消息可以提升用户体验。

  5. 错误处理要完善：生产环境中需要考虑 token 刷新、签名验证、频率限制等边界情况，确保服务稳定运行。

通过本文的学习，你已经掌握了 OpenClaw 接入飞书的核心技能。接下来，你可以根据企业实际需求，开发更多自定义功能，如知识库问答、工单系统对接、自动化工作流等，让 AI 助手真正成为企业效率提升的利器。

参考资料

相关推荐
一次旅行3 小时前
OpenClaw命令速查指南（二）
linux·网络·人工智能·windows
智算菩萨3 小时前
OpenCV图像算术运算全栈实战：基于Python 3.13的图像算术运算（加、减、混合、位运算、遮罩）的底层原理与工程实现
人工智能·python·opencv
Thomas.Sir3 小时前
AI 真的可以取代人类吗？
人工智能·ai·工作流
AI英德西牛仔3 小时前
ChatGPT和Gemini导出word排版
人工智能·ai·chatgpt·word·deepseek·ds随心转
咕噜签名-铁蛋3 小时前
鲲鹏CCA赋能OpenClaw，筑牢AI安全防线，开启AI智能体安全新纪元
人工智能·安全·ai编程
带娃的IT创业者3 小时前
WeClaw-TTS 语音合成实战：pyttsx3 本地引擎与 Edge-TTS 云服务的混合架构.md
前端·tts·ai智能体·openclaw·weclaw
人工智能AI技术3 小时前
C# Runner+OpenClaw，用C#打造工业级AI智能体
人工智能·c#
西红市杰出青年3 小时前
AI 调用 MCP 的全流程教程（基于 Streamable HTTP）
人工智能·网络协议·http
风象南3 小时前
我写了个公众号历史数据一键抓取脚本
人工智能
热门推荐
01GitHub 镜像站点02Qwen3.5 开源全解析：从 0.8B 到 397B，代际升级 + 全场景选型指南03围棋-html版本04班级宠物园部署指南05小黑课堂计算机二级WPSoffice题库软件下载安装教程（2026年3月最新版）06UV安装并设置国内源07OpenClaw 使用和管理 MCP 完全指南08“wsl --install -d Ubuntu-22.04”下载慢，中国地区离线安装 Ubuntu 22.04 WSL方法（亲测2025年5月6日）09机器学习深度学习二——GAN网络10OpenClaw Control UI安全上下文访问配置