飞书群聊接入 AI 机器人完整指南：OpenClaw 配置全流程踩坑记录
“
本文基于真实配置过程整理，覆盖从创建飞书应用到机器人正常响应群消息的每一个步骤，包含常见报错的完整解决方案。
这篇文章适合谁？
如果你正在尝试把 AI 助手接入飞书群聊，让团队成员可以直接在群里 @ 机器人提问，那这篇文章值得从头读完。
本文使用的工具是 OpenClaw（一个开源的 AI 网关工具），版本为 2026.3.8，飞书端使用自建应用方式接入。整个配置过程并不复杂，但有几个容易踩坑的地方，本文会逐一说明。
准备工作：先把 OpenClaw 装好
安装后报错怎么办？
OpenClaw 安装完成后，有时候执行命令会遇到这个错误：
Failed to start CLI: Error: Cannot find native binding.
npm has a bug related to optional dependencies.
Please try `npm i` again after removing both package-lock.json and node_modules directory.
这是 npm 的一个已知问题，处理方式如下：
第一步：进入 OpenClaw 的全局安装目录
cd /Users/你的用户名/nodejs/lib/node_modules/openclaw
第二步：删除旧的依赖
rm -rf node_modules package-lock.json
第三步：重新安装
npm install
如果上面的方法还是不行，尝试强制安装或换用 yarn：
npm install --force
# 或者
yarn install
最彻底的方案是完全重装：
npm uninstall -g openclaw
npm install -g openclaw
根本原因：npm 在处理含有原生绑定（native bindings）的可选依赖时，有时会跳过安装步骤，重新安装通常能解决。
第一部分：在飞书开放平台创建应用
1. 新建自建应用
打开 飞书开放平台，点击「创建自建应用」，填写名称和描述即可。
创建完成后，在「凭证与基础信息」页面可以看到两个重要信息：
-
App ID（格式类似 cli_a93e9c50d978dcbd） -
App Secret
这两个信息后面配置 OpenClaw 时要用到，先复制保存好。
2. 开启机器人能力
在应用详情页，找到「应用能力」→「机器人」，打开开关。这一步经常被忽略，是机器人能收到消息的前提条件。
3. 配置权限
在「权限管理」中添加以下权限：
| 权限名称 | 说明 |
|---|---|
im:message |
基础消息权限 |
im:message.group_at_msg:readonly |
接收群 @ 消息 |
im:message.p2p_msg:readonly |
接收私聊消息 |
im:message:send_as_bot |
机器人发送消息 |
im:chat.members:bot_access |
机器人加入群聊 |
im:resource |
资源访问 |
4. 配置事件订阅（长连接方式）
这是整个配置过程中最关键的一步，很多人在这里卡住。
在应用的「事件与回调」页面：
-
订阅方式选择「使用长连接接收事件」（不需要填回调 URL，不需要公网 IP） -
添加事件：搜索并订阅 im.message.receive_v1
“
为什么选长连接？ OpenClaw 的 Gateway 默认只监听本机（loopback），没有公网地址，所以只能用长连接（WebSocket）方式让飞书主动推送消息过来。
5. 发布应用
配置完成后，在「版本管理与发布」中创建版本并提交发布。企业内部应用通常审批很快。
第二部分：配置 OpenClaw
配置文件位置
OpenClaw 的配置文件在：
~/.openclaw/openclaw.json
正确的完整配置
下面是一份经过验证、能正常工作的完整配置文件：
{
"meta": {
"lastTouchedVersion": "2026.3.8",
"lastTouchedAt": "2026-03-13T14:39:07.080Z"
},
"wizard": {
"lastRunAt": "2026-03-13T14:39:07.064Z",
"lastRunVersion": "2026.3.8",
"lastRunCommand": "configure",
"lastRunMode": "local"
},
"auth": {
"profiles": {
"minimax-portal:default": {
"provider": "minimax-portal",
"mode": "oauth"
}
}
},
"models": {
"providers": {
"minimax-portal": {
"baseUrl": "https://api.minimaxi.com/anthropic",
"apiKey": "minimax-oauth",
"api": "anthropic-messages",
"models": [
{
"id": "MiniMax-M2.5",
"name": "MiniMax M2.5",
"reasoning": false,
"input": ["text"],
"cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
"contextWindow": 200000,
"maxTokens": 8192
}
]
}
}
},
"agents": {
"defaults": {
"model": {
"primary": "minimax-portal/MiniMax-M2.5"
},
"workspace": "/Users/kb/.openclaw/workspace",
"compaction": {
"mode": "safeguard"
}
}
},
"tools": {
"profile": "full"
},
"commands": {
"native": "auto",
"nativeSkills": "auto",
"restart": true,
"ownerDisplay": "raw"
},
"session": {
"dmScope": "per-channel-peer"
},
"channels": {
"feishu": {
"enabled": true,
"groupPolicy": "open",
"accounts": {
"main": {
"appId": "cli_a93e9c50d978dcbd",
"appSecret": "cB4hiYEMv0rKpUpoYP7Sqh5hOmE2jzBj",
"dmPolicy": "pairing"
}
}
}
},
"gateway": {
"port": 18789,
"mode": "local",
"bind": "loopback",
"auth": {
"mode": "token",
"token": "你的token"
},
"tailscale": {
"mode": "off",
"resetOnExit": false
}
},
"plugins": {
"entries": {
"minimax-portal-auth": {
"enabled": true
},
"feishu": {
"enabled": true
}
}
}
}
关键配置说明
groupPolicy 控制机器人如何响应群消息，有三个取值：
| 取值 | 说明 |
|---|---|
"open" |
允许所有群触发机器人（推荐） |
"allowlist" |
只允许指定的群 |
"disabled" |
完全禁用群消息 |
dmPolicy 控制私聊行为，"pairing" 表示需要配对才能私聊。
“
⚠️ 常见错误：很多人把
dmPolicy放在单独的default账号里，而不是放在main账号内。这会导致 Dashboard 显示not configured，机器人无法连接飞书。
第三部分：把机器人加入飞书群
内部群添加步骤
-
打开飞书，进入目标群聊 -
点击右上角「···」 -
选择「设置」 -
点击「群机器人」 -
点击右上角「添加机器人」 -
搜索你的应用名称，点击添加
“
一个群最多可添加 99 个机器人。
关于外部群（跨企业群）
如果需要在外部群中使用机器人，需要额外开启对外共享：
-
在飞书开放平台的「版本管理与发布」中，创建版本时找到「对外共享」选项并开启 -
或者在「用户管理 → 可用范围」中开启外部用户开关
“
注意：对外共享需要走审批流程，且需要企业管理员权限，部分企业账号普通开发者看不到该入口。如果只是内部群使用，完全不需要这个步骤。
第四部分：排查机器人不回复的问题
配置完成后，在群里 @ 机器人没有反应——这是最常见的问题。按以下步骤逐一排查。
Step 1：查看实时日志
openclaw logs --follow
在群里 @ 机器人，同时观察日志输出。
正常情况应该看到类似：
Approved feishu sender oc_xxxxxxxxxx
注意前缀：oc_ 开头是群聊 ID，ou_ 开头是用户（私聊）ID。如果只看到 ou_ 开头，说明机器人收到的是私聊消息，不是群消息。
Step 2：检查 Gateway 连接状态
打开浏览器访问：
http://127.0.0.1:18789/
在 Dashboard 中找到 Feishu 频道，检查 main 账号的状态：
| 字段 | 期望值 | 含义 |
|---|---|---|
| Running | Yes | Gateway 进程在运行 |
| Configured | Yes | App ID/Secret 已配置 |
| Connected | Yes / n/a → 应为 connected | 长连接是否建立 |
如果 Connected 显示 n/a，说明飞书长连接没有建立成功，消息根本无法传入。
Step 3：检查 Gateway 运行状态
openclaw gateway status
正常输出应包含：
Runtime: running (pid xxxxx)
RPC probe: ok
Step 4：确认飞书事件订阅
回到飞书开放平台，再次确认：
-
「事件与回调」→ 订阅方式是长连接（不是 HTTP 回调） -
已添加 im.message.receive_v1事件 -
应用已重新发布（改完配置不发布不生效）
Step 5：重启 Gateway
openclaw gateway restart
重启后观察日志，正常应看到飞书频道重新连接的信息。
第五部分：如何获取群 ID
有些高级配置需要指定具体的群 ID（oc_ 开头）。获取方式：
-
启动日志监听： openclaw logs --follow -
在目标群里 @ 机器人发一条消息 -
在日志中找到 Approved feishu sender oc_xxxxxx这行，oc_后面的就是群 ID
获取到群 ID 后，可以在配置中针对特定群进行细化设置，例如关闭 @ 要求：
"channels": {
"feishu": {
"groups": {
"oc_你的群ID": {
"requireMention": false
}
}
}
}
requireMention 默认为 true，即必须 @ 机器人才触发回复。设为 false 后，群里任何消息都会触发机器人，请谨慎使用。
第六部分：如何删除机器人
从群聊移除
-
进入群聊 → 右上角「···」→「设置」→「群机器人」 -
找到机器人 → 点击右侧「···」→「删除」
从好友/会话中移除
在消息列表找到与机器人的对话，右键选择「删除会话」。如需从通讯录彻底移除，进入「通讯录」找到机器人，右键「删除联系人」。
在开发者后台关闭机器人能力
飞书不支持单独删除机器人，只能关闭能力或删除整个应用：
-
关闭机器人能力：「应用能力」→「机器人」→ 关闭开关 → 重新发布版本 -
删除整个应用：应用需处于未发布或已停用状态，才能在详情页底部找到「删除应用」选项
“
如果只是想重新配置，不需要删除应用，直接修改配置重新发布即可。
常见问题 FAQ
Q：机器人加入群后完全没有反应，日志也没有任何输出怎么办？
A：最可能的原因是飞书事件订阅没有配置。检查飞书开放平台的「事件与回调」，确认已选择「长连接」方式并订阅了 im.message.receive_v1 事件，且应用已重新发布。
Q：日志只看到 ou_ 开头的 ID，没有 oc_ 开头的，是什么问题？
A：ou_ 是用户 ID，代表收到的是私聊消息。oc_ 才是群 ID。说明机器人目前只能接收私聊，群消息没有传入。检查 groupPolicy 是否设置为 "open"，以及飞书事件订阅是否正确。
Q：Dashboard 显示 Connected: n/a，长连接没有建立怎么办？
A：检查配置文件中是否有多余的 default 账号（显示 not configured），将其删除，确保只保留配置完整的 main 账号，然后重启 Gateway。
Q：bindings 配置出现 Invalid input 报错怎么办？
A：OpenClaw 的 bindings 格式有版本差异，如果遇到校验报错，先去掉 bindings 配置，改用 groupPolicy: "open" 来允许所有群消息，功能上是等效的。
Q：tools.profile 报 unknown entries 警告正常吗？
A：正常，这只是 warn 级别的提示，说明 allowlist 中配置了当前版本尚未启用的工具名（如 apply_patch），不影响正常使用。
Q：fts unavailable: no such module: fts5 是什么意思？
A：这是 SQLite 全文搜索模块未启用的提示，影响记忆搜索功能，但不影响基本的群聊对话功能。
总结
整个配置流程可以归纳为三个核心步骤：
-
飞书端：创建应用 → 开启机器人能力 → 配置权限 → 开启长连接事件订阅 → 发布 -
OpenClaw 端：正确填写 appId和appSecret到main账号，设置groupPolicy: "open"，删除多余的default账号 -
验证：通过 Dashboard 和日志确认 Connected状态，群里 @ 机器人测试
最容易出问题的两个地方：一是飞书没有选择长连接订阅方式，二是 OpenClaw 配置里 dmPolicy 放错了位置导致账号状态异常。按照本文的配置结构来写，可以避免这两个坑。
本文基于 OpenClaw 2026.3.8 版本、飞书开放平台实际配置过程整理，配置细节以官方文档为准。
