本文记录 OpenClaw 接入飞书时，群聊与私聊两种场景的配置思路、操作步骤、命令示例，以及排查时需要重点关注的几个配置点。
适合用于从零接入，或在“群里能收消息、私聊不生效”这类问题出现时对照检查。
一、接入目标
接入完成后，通常希望实现两类能力：
- 群聊接入
- 在飞书群内
@机器人后，OpenClaw 能收到事件并回复 - 私聊接入
- 指定用户可直接与机器人私聊
- 可通过白名单限制允许私聊的用户范围
二、前置准备
在开始之前，先确认以下条件已经具备：
- 已创建并配置好飞书应用
- 已拿到飞书应用的基础凭据
- OpenClaw 所在环境可以访问公网，或已正确配置反向代理 / 公网地址
- 已安装并可正常运行 OpenClaw Gateway
建议先检查 OpenClaw 当前状态：
bashCopyCopied!
openclaw status
openclaw gateway status
如果 Gateway 未运行，可先启动：
bashCopyCopied!
openclaw gateway start
三、飞书应用侧准备
在飞书开发者后台，需要先完成应用本身的基础设置。
1）创建应用并启用机器人能力
在飞书开放平台中创建企业自建应用，并为应用开启机器人相关能力。
重点确认：
- 已启用机器人
- 已配置事件订阅
- 已为机器人添加必要权限
- 已将机器人添加到目标群聊中
2）配置事件订阅
需要在飞书后台为应用开启事件订阅，并填写 OpenClaw 对应的回调地址。
你需要确认的不是“有没有填”，而是这几个点是否一致：
- 回调地址是否为当前实际生效地址
- 网关是否可从飞书侧访问
- 若走反向代理，路径转发是否正确
- 修改地址后是否已经重新保存并生效
3）开通所需权限
至少要保证飞书应用拥有与消息、群聊、文档相关的必要权限。
如果后续还要支持飞书文档、群成员查询、知识库等能力，则需要额外补齐对应 scope。
如果你不确定当前权限情况，可以在 OpenClaw 中直接检查：
bashCopyCopied!
# 如果通过聊天内工具排查，可查看 Feishu app 当前 scopes
# 用于确认消息、群聊、文档等权限是否已授予
排查重点：
- 机器人收消息相关权限
- 群聊信息读取权限
- 用户信息读取权限
- 私聊场景所需的用户事件权限
四、OpenClaw 侧基础配置
飞书接入的关键，在于 渠道配置、回调可达性、白名单策略 三件事。
建议先查看当前相关配置结构，再修改：
bashCopyCopied!
openclaw gateway --help
如果是通过 OpenClaw 配置文件管理，则重点关注：
channels.feishuplugins.entries.device-pair.config.publicUrl（如果公网地址依赖这里）- Gateway 对外监听地址
- 事件回调绑定地址
五、群聊接入步骤
群聊接入的目标是：机器人被拉入群后，在群里 @机器人 能触发 OpenClaw 收到消息事件。
步骤 1：将机器人加入目标群
先把飞书应用对应的机器人加入目标群聊。
如果机器人根本不在群里，后面配置再全也收不到群内消息。
步骤 2：在群内 @机器人 测试一次
在目标群发一条消息并 @机器人，例如：
textCopyCopied!
@机器人 在吗
此时要看 OpenClaw 是否收到了对应事件。
步骤 3：确认群 chat_id
排查群聊是否接通时，chat_id 很重要。
实际操作里，可以从本地 session / jsonl 日志中的 conversation_label 或相关事件上下文中捞到群 ID。
排查到的结果建议记录下来，例如：
textCopyCopied!
oc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
这样后面做 allowlist、路由确认或问题复盘时会方便很多。
步骤 4：确认群消息事件是否成功进入 OpenClaw
如果群里 @ 了机器人，但没有收到事件，优先检查：
- 飞书后台事件订阅是否已成功送达
- OpenClaw Gateway 是否在线
- 公网地址 / 反向代理是否可访问
- 机器人是否真的在该群里
- 群消息是否属于当前应用可见范围
六、私聊接入步骤
私聊接入的目标是：允许指定用户直接给机器人发消息，并由 OpenClaw 正常处理。
步骤 1：确认私聊策略
如果希望只有特定用户能私聊机器人，建议使用白名单模式。
例如将私聊策略设置为：
yamlCopyCopied!
dmPolicy: allowlist
这意味着：只有在 allowFrom 中列出的用户，私聊事件才会被放行。
步骤 2：配置 allowFrom 白名单
allowFrom 中填写的必须是实际发消息用户对应的正确 open_id。
这里最容易踩坑：填成了错误的用户 ID、历史 ID，或者从别的上下文抄错了。
错误示例的典型表现是：
- 群里 @机器人 没问题
- 用户私聊机器人后，看起来“发出去了”
- 但 OpenClaw 侧始终收不到私聊事件
步骤 3：从最近事件中核对 sender/open_id
不要只凭印象填白名单。
最稳妥的做法，是从最近一次真实事件上下文中核对发送者 ID，确认：
sender_idopen_id- 当前白名单中的 ID
三者是否一致。
如果不一致，私聊白名单就不会命中。
步骤 4：更新配置并重启 Gateway
当你修正了 dmPolicy 或 allowFrom 后，需要让配置重新生效。
常见做法是重启 Gateway：
bashCopyCopied!
openclaw gateway restart
如果只是查看状态，可用：
bashCopyCopied!
openclaw gateway status
步骤 5：重新发起私聊测试
配置更新后，让白名单内用户再次私聊机器人，观察：
- 飞书侧是否成功投递事件
- OpenClaw 是否收到私聊消息
- 是否能正常回包
如果仍不生效，优先重新核对 allowFrom 中的 open_id。
七、一个典型排错思路
实际接入里，最常见的情况不是“全都不通”，而是：
- 群聊正常
- 私聊不通
这种情况下，优先按下面顺序排查：
1）先判断是不是白名单问题
若群聊正常，说明：
- 飞书应用基本可用
- 事件订阅大概率没大问题
- OpenClaw Gateway 大概率在线
这时更应该怀疑的是：
dmPolicyallowFrom- open_id 填写错误
2）核对最近真实 sender_id
不要直接复用旧配置。
应从最近一次真实触发的飞书事件里，核对实际 sender/open_id，再回填到配置中。
3）更新后重启，再测试
bashCopyCopied!
openclaw gateway restart
然后重新做一次私聊验证，而不是只看旧日志下结论。
八、推荐排查命令
下面这些命令适合作为基础排查入口：
查看 OpenClaw 状态
bashCopyCopied!
openclaw status
查看 Gateway 状态
bashCopyCopied!
openclaw gateway status
启动 Gateway
bashCopyCopied!
openclaw gateway start
重启 Gateway
bashCopyCopied!
openclaw gateway restart
停止 Gateway
bashCopyCopied!
openclaw gateway stop
如果不确定命令参数或当前版本支持情况，可查看帮助：
bashCopyCopied!
openclaw help
openclaw gateway --help
九、注意事项
1）群 chat_id 与用户 open_id 不是一回事
排查群聊时，重点是 chat_id。
排查私聊时，重点是用户的 open_id / sender_id。
这两个概念不要混用。
2）私聊 allowlist 最容易因为 ID 填错失效
即使只差一个字符，白名单也不会命中。
所以一定要基于最近一次真实事件来核对，不要靠手填记忆。
3）配置改了不等于已经生效
很多问题不是“没改对”，而是“改了但没重启 / 没重新加载”。
修改私聊策略后，记得重启 Gateway，并重新做一次真实测试。
4）先打通群聊，再打通私聊
如果是从零开始接入，建议顺序是：
- 先完成飞书应用基础配置
- 先验证群聊
@机器人可用 - 再处理私聊白名单
- 最后补文档、群成员、知识库等扩展能力
这样排查路径最短，也最不容易把问题搅在一起。
十、结论
飞书接入 OpenClaw 时，群聊与私聊虽然都依赖同一套飞书应用与 Gateway，但实际排障关注点不同：
- 群聊重点看：机器人是否在群里、事件是否送达、chat_id 是否确认
- 私聊重点看：dmPolicy、allowFrom、open_id 是否正确
如果出现“群聊正常、私聊不通”，优先怀疑白名单配置，而不是先怀疑整套接入链路。
