MMClaw 接入飞书实战：权限、长连接等设置（也适用于OpenClaw）

前言

在部署多模态 Agent 时，飞书是一个理想的落地端。但很多开发者在接入时会遇到权限配置不全的问题，导致机器人无法正常接收消息或发送回复。

虽然 OpenClaw (Node.js) 是同类项目的代表，但如果你更倾向于 Python 生态，MMClaw 提供了更轻量的实现，并且原生支持 WebSocket 长连接 模式。本文的飞书后台权限配置逻辑对两者通用，旨在帮助开发者快速打通链路。

项目 GitHub：https://github.com/CrawlScript/MMClaw

一、安装及快速开始

在终端直接通过 pip 安装即可开始使用：

1. 安装程序：在终端执行 pip install mmclaw。
2. 进入配置向导：执行 mmclaw（如果您之前已经配置过其他模式，请执行 mmclaw config）。
3. 选择接入模式：在交互引导中选择 Feishu (飞书) Mode。

此时，终端会弹出一系列关于飞书接入的详细步骤说明。为了确保您能顺利打通链路，本教程提供了对应的图文详解，帮助您快速完成每一步设置。

二、开启飞书机器人能力

1. 访问飞书开放平台：登录官方地址 https://open.feishu.cn/app
2. 创建企业自建应用：点击“创建企业自建应用”，填写应用基本信息。
3. 激活机器人模块：在应用详情页左侧菜单栏进入 “添加应用能力”，找到 “机器人” 模块并点击添加。

三、获取凭证 (App ID / Secret)

在进行任何权限或代码配置前，请先记录应用身份凭证。

获取路径：在左侧菜单栏选择 “凭证与基础信息”。
记录信息：复制并保存 App ID 和 App Secret。这两个 ID 是 MMClaw 识别并登录你机器人的唯一凭证。

四、核心权限配置：批量导入 JSON

为了避免手动逐项勾选权限导致遗漏，建议直接使用“批量导入”功能。

1. 进入权限管理：在左侧菜单选择“权限管理”。
2. 批量导入：点击页面上的 “批量导入/导出权限” 按钮。

3. 粘贴 JSON：在弹出的窗口中粘贴以下权限配置后，点击“下一步，确认新增权限”，然后点击“申请开通”，最后点击“确认”。

	{
	  "scopes": {
	    "tenant": [
	      "contact:user.base:readonly",
	      "im:chat",
	      "im:chat:read",
	      "im:chat:update",
	      "im:message",
	      "im:message.group_at_msg:readonly",
	      "im:message.p2p_msg:readonly",
	      "im:message:send_as_bot",
	      "im:resource"
	    ],
	    "user": []
	  }
	}

五、激活飞书长连接状态 (Python 脚本)

在飞书后台开启“长连接”开关前，必须确保本地有一个活跃的连接进程，否则飞书后台会校验失败。

1. 准备激活脚本：新建一个 activate_ws.py 文件，并写入以下代码（请替换您的凭证）：

import lark_oapi as lark

# ==========================================
# 1. 请在此处替换为您在飞书开放平台获取的凭证
# ==========================================
APP_ID = '你的_飞书_APP_ID'
APP_SECRET = '你的_飞书_APP_SECRET'

def activate():
    # 初始化事件处理器
    h = lark.EventDispatcherHandler.builder('', '').build()

    # 建立 WebSocket 长连接客户端
    c = lark.ws.Client(
        app_id=APP_ID, 
        app_secret=APP_SECRET, 
        event_handler=h
    )

    print("[*] 正在启动飞书长连接激活脚本...")
    print("[*] 脚本运行期间，请前往飞书后台开启“使用长连接接收事件”开关。")
    c.start()

if __name__ == "__main__":
    activate()

2. 安装依赖库：在终端执行 pip install lark-oapi（如果您之前已执行过 pip install mmclaw，此步可忽略）。
3. 运行激活脚本：在终端执行 python activate_ws.py。
4. 飞书后台切换：保持上述脚本运行不要关闭，回到飞书后台 “事件与回调” 页面，将订阅方式切换为 “使用长连接接收事件” 并点击保存。
5. 添加订阅事件：在同一页面点击“添加事件”，搜索并添加 “接收消息 (im.message.receive_v1)”。

六、发布版本（使配置生效）

在完成权限导入和长连接设置后，必须发布一个应用版本，否则机器人将无法识别新权限。

1. 进入发布页面：在左侧菜单栏选择 “版本管理与发布”，点击右上角的 “创建版本”。
2. 详情配置：
- 版本号：填入 1.0.0（或根据您的习惯递增）。
- 更新说明：简单填写如“初始化配置”或“新增权限”。
3. 确认发布：点击底部的 “保存”，随后点击 “确认发布”。

七、身份绑定与验证

在 MMClaw 的 Feishu（飞书）配置引导中，除了要求输入 App ID 和 App Secret，最重要的安全性步骤就是接下来的身份绑定（Identity Binding）。这是为了防止任何知道你机器人名字的人都能随意调用你的 AI 资源：

根据你的操作路径，启动方式分为以下两种情况：

情况 A：如果你是通过 mmclaw 命令首次启动并配置 在配置完所有信息并完成飞书后台的“长连接”激活后，程序会自动继续运行。
情况 B：如果你是通过 mmclaw config 手动修改配置 配置完成后程序会自动回到命令行终端。此时，你需要再次输入 mmclaw 启动程序。