OpenClaw对接飞书完整教程

OpenClaw对接飞书完整教程

前言

想在飞书里部署一个既聪明又能干的AI助手吗？OpenClaw正是一个能够实现这个目标的强大框架。不同于一些复杂的方案，它可以通过WebSocket长连接与企业协作平台无缝对接，稳定又便捷。接下来的内容，就手把手带你走通整个配置流程。

准备工作

磨刀不误砍柴工，在正式动手之前，得先确认手头这几样“家伙事儿”是否齐全：

首先，你得有一个飞书企业账号，并且拥有创建应用的权限。这是基础入场券。

其次，OpenClaw的主程序需要提前安装好，确保核心引擎就位。

最后，网络环境要通畅，能够顺利访问飞书开放平台，毕竟所有配置都在那里完成。

第一步：创建飞书企业应用

1.1 访问飞书开放平台

打开浏览器，直奔飞书开放平台，用你的企业管理员账号登录进去。这就是我们后续所有操作的“控制台”。

1.2 创建新应用

登录后，找到并点击“创建企业应用”按钮。在弹出的表单里，需要填写几项基本信息：

应用名称：这里可以起个一目了然的名字，比如“OpenClaw AI 助手”。

应用描述：简单说明一下，例如“智能AI助手，支持对话交互和任务执行”。

应用图标：可以上传一个OpenClaw的专属图标，让它在飞书里更有辨识度，暂时没有用默认的也行。

1.3 获取应用凭证

应用创建成功后，会进入应用的管理页面。在左侧导航栏找到“凭证与基础信息”并进入，这里有两条最关键的信息需要复制保存：

App ID：格式通常是 cli_xxx 这样的一串字符。

App Secret：这是应用密钥，非常重要！务必妥善保管，不要泄露，它相当于机器人的“密码”。

第二步：配置应用权限和能力

2.1 添加机器人能力

光有应用还不够，得让它具备“机器人”的能力。在管理页面左侧，选择“应用能力”，点击“添加能力”，然后从列表里选中“机器人”并添加。这一步是赋予应用智能交互的核心身份。

2.2 配置权限

机器人有了，还得告诉飞书它能在什么范围内活动，这就是权限管理。进入“权限管理”页面，建议批量导入以下几个关键权限：

im:message：这是消息的读写权限，是对话的基础。

im:message:send_as_bot：允许以机器人身份发送消息，必不可少。

im:chat：获取群组信息的权限，如果你需要机器人在群里工作，就需要它。

2.3 设置事件订阅

为了让机器人能实时收到用户消息，需要配置事件订阅。进入“事件订阅”页面，注意两个关键操作：

在连接方式上，选择“使用长连接”（也就是WebSocket模式），这是实现稳定、实时通信的关键。

然后，添加一个关键事件：im.message.receive_v1。添加后，务必确保该事件的状态显示为“已启用”。

2.4 发布应用

所有配置在“沙箱”里完成后，必须发布才能生效。进入“版本管理与发布”页面，创建一个新版本并提交审核。只有应用审核通过并发布后，才能正常接收和处理消息。

第三步：安装飞书插件

现在回到OpenClaw这边。我们需要安装一个专门用于连接飞书的适配器插件。打开终端，执行下面这条命令：

openclaw plugins install @openclaw/feishu

第四步：配置 OpenClaw 连接

4.1 命令行向导配置（推荐）

对于大多数用户，最推荐使用交互式命令行向导来配置，不容易出错。在终端中执行：

openclaw channels add

接下来，只需跟着提示一步步操作：

渠道类型选择 feishu。

粘贴第一步获取的 App ID 和 App Secret。

Endpoint type 选择 im。

根据你的飞书是国内版还是国际版，选择对应的环境。

4.2 手动配置文件方式

如果你更习惯直接编辑配置文件，可以手动修改 ~/.openclaw/openclaw.json 文件，在对应位置添加以下配置（记得替换掉示例中的占位符）：

{"plugins": {"entries": {"feishu": {"enabled": true}}}, "channels": {"feishu": {"enabled": true, "dmPolicy": "pairing", "appId": "cli_your_app_id", "appSecret": "your_app_secret", "domain": "feishu"}}}

4.3 环境变量配置

在容器化部署或某些自动化场景下，使用环境变量会更方便。可以通过如下命令设置：

export FEISHU_APP_ID="cli_your_app_id" export FEISHU_APP_SECRET="your_app_secret"

第五步：启动服务并测试

5.1 启动 Gateway 服务

配置完成后，需要启动核心的Gateway服务来建立连接。在终端执行：

openclaw gateway restart

5.2 配对验证

服务启动后，就可以进行配对了：

在飞书里搜索你刚刚创建的机器人应用名称，找到它。

向它发送任意一条消息，比如“开始配对”。这时，机器人会回复一个配对码。

回到终端，执行以下命令来批准这次配对：

openclaw pairing approve feishu <配对码>

5.3 测试对话

配对成功后，真正的测试来了。在飞书里给机器人发一句“你好”，如果它能迅速且正常地回复你，那么恭喜，对接大功告成！

高级配置选项

私聊策略配置

OpenClaw提供了灵活的私聊访问控制，支持四种策略：

pairing（默认）：需要先进行配对验证，安全性高。

allowlist：只允许特定用户ID列表中的用户访问。

open：任何人无需验证都可以发起私聊。

disabled：完全关闭私聊功能。

例如，配置白名单模式如下：

"feishu": {"dmPolicy": "allowlist", "allowFrom": ["ou_user_id_1", "ou_user_id_2"]}

多账号配置

一套OpenClaw系统可以同时服务多个飞书机器人账号，例如区分技术支持、人事等不同职能。配置示例：

"feishu": {"enabled": true, "accounts": {"support": {"appId": "cli_support", "appSecret": "secret_support", "botName": "技术支持助手"}, "hr": {"appId": "cli_hr", "appSecret": "secret_hr", "botName": "人事助手"}}}

群组配置

对于群聊，同样可以精细控制。可以设置哪些群可以拉机器人进去：

"feishu": {"groupPolicy": "open", "groupAllowFrom": ["oc_group_id_1"]}

常用管理命令

日常运维时，这几个命令会非常实用：

# 查看Gateway状态 openclaw gateway status # 重启Gateway服务 openclaw gateway restart # 查看实时日志 openclaw logs --follow # 列出配对请求 openclaw pairing list feishu # 批准配对 openclaw pairing approve feishu <配对码> # 拒绝配对 openclaw pairing reject feishu <配对码>

常见问题解决

问题 1：无法接收消息

排查思路：

首先，回想一下应用是否真的完成了“发布并审批通过”，而不仅是保存了配置。

其次，去飞书开放平台检查“事件订阅”里的im.message.receive_v1事件是否确认为“已启用”状态。

再次，检查服务器或本地网络能否正常访问外网。

最后，查看Gateway的日志输出，通常错误信息会给出明确提示。

问题 2：配对码不显示

排查思路：

确认OpenClaw的Gateway服务是否正在运行（用openclaw gateway status命令检查）。

核对飞书应用后台的“事件订阅”配置，确保长连接和消息接收事件都已开启。

双重检查配置文件中或向导里填写的App ID和App Secret是否正确无误，一个字母都不能错。

问题 3：机器人无法回复消息

排查思路：

回到飞书开放平台，检查“权限管理”页面，确认所需的权限是否都已添加并生效。

确认“应用能力”中的“机器人”能力已经添加成功。

查看飞书开放平台的应用总状态，是否存在异常或禁用情况。

问题 4：WebSocket 连接不稳定

检查部署OpenClaw的服务器的网络环境，是否存在波动或防火墙限制。

确保服务器的防火墙规则允许向飞书服务器发起出站WebSocket连接。

可以尝试在配置中通过环境变量调整连接超时、重试等参数，以适应特殊网络环境。

安全注意事项

在享受便利的同时，安全这根弦一定得绷紧：

App Secret 保护：像保护密码一样保护它。切勿提交到Git等版本控制系统。生产环境强烈建议使用环境变量或密钥管理服务来配置。

权限最小化：只申请业务真正需要的权限，避免过度授权，这是安全的基本原则。

访问控制：除非有特殊需求，否则不要使用open策略。配对机制或白名单能有效控制访问范围。

定期更新：关注OpenClaw和飞书插件的版本更新，及时升级以修复已知的安全漏洞。

日志监控：养成定期查看Gateway日志的习惯，便于及时发现异常的登录或访问行为。

总结

跟着教程走下来，从创建飞书应用、配置权限，到安装插件、连接测试，再到高级功能和安全设置，一套完整的OpenClaw对接飞书流程就清晰了。

如今，你的飞书里已经有了一个随时待命的AI助手。它借助WebSocket长连接，无需复杂的公网IP暴露或内网穿透，就能实现稳定、低延迟的通信，特别适合作为企业内部的智能化升级方案。接下来，就基于它去探索更多的自动化可能吧。

来源：互联网