OpenClaw v2026 飞书机器人群聊白名单配置指南

本文档用于指导用户完成 OpenClaw 机器人在飞书群聊中的白名单配置，解决群内 @机器人无响应的核心问题，适用于 OpenClaw 2026.2.26 及以上版本，操作流程清晰可落地，兼顾新手友好性与专业准确性。

一、前置说明

1.1 适用场景

当 OpenClaw 机器人配置为 groupPolicy=allowlist（白名单模式）时，仅白名单内的飞书群可触发机器人响应，未添加至白名单的群聊中，机器人将无法接收或回复消息。本文档核心解决“白名单模式下机器人不回复”的问题。

1.2 前置条件

• 已部署 OpenClaw 机器人，且版本为 2026.2.26 及以上（可通过 openclaw --version 命令验证）。

• 已在飞书开放平台创建应用，并完成机器人能力配置（获取 appId 和 appSecret）。

• 飞书应用已开通群聊消息收发核心权限（im:message.group_at_msg:readonly、im:message:send_as_bot），且已发布应用版本。

• 机器人已加入目标飞书群聊（群设置 → 群机器人 → 添加对应应用机器人）。

1.3 核心概念

• groupPolicy：OpenClaw 飞书通道的群聊策略，取值为allowlist（白名单模式）或 open（开放模式），默认值为 allowlist。

• groupAllowFrom：白名单配置项，存储可触发机器人的飞书群 ID 列表，群 ID 格式为 oc_xxx 或 ou_xxx（两种格式均有效）。

• 飞书群 ID（chat_id）：飞书群的唯一标识，用于 OpenClaw 识别目标群聊，是配置白名单的核心参数。

二、操作流程（完整步骤）

步骤1：确认当前群聊策略配置

首先通过命令行确认 OpenClaw 飞书通道的群聊策略，确保当前为白名单模式，避免配置无效。

1. 登录部署 OpenClaw 机器人的服务器，打开终端。

2. 执行以下命令，查看飞书通道核心配置： openclaw config get channels.feishu

3. 查看输出结果，重点确认 groupPolicy 字段：

   • 若 groupPolicy: "allowlist"：当前为白名单模式，需继续配置groupAllowFrom。

   • 若 groupPolicy: "open"：当前为开放模式，无需配置白名单，机器人可响应所有群聊消息（不推荐生产环境使用）。

步骤2：获取飞书群 ID（chat_id）

飞书群 ID 是配置白名单的关键，提供 3 种获取方式，优先推荐方法1（最准确，适配所有场景）。

方法1：从 OpenClaw 网关日志获取（推荐）

1. 启动 OpenClaw 网关（若已启动可跳过）： openclaw gateway

2. 打开目标飞书群，@机器人发送任意测试消息（例如：@OpenClaw 测试群ID获取）。

3. 回到服务器终端，查看网关日志，搜索关键词 chat_id，找到类似如下内容： [feishu] receive message: chat_id=oc_cbf89dcaf14e87d8b32ac1d600a1b4ad, sender_id=xxx...

4. 复制 oc_ 或 ou_ 开头的整串字符，即为该群的群 ID（例如：oc_cbf89dcaf14e87d8b32ac1d600a1b4ad）。

方法2：从飞书客户端获取（简单快捷）

1. 打开飞书客户端，进入目标群聊。

2. 点击群聊右上角的「···」（更多选项），进入群设置页面。

3. 下拉页面至最底部，找到「群ID」选项，点击即可复制（需飞书客户端版本 7.60 及以上）。

4. 复制的群 ID 格式为 oc_xxx，直接用于后续配置。

方法3：从飞书开放平台 API 调试台获取（备用）

1. 登录飞书开放平台 API 调试台：https://open.feishu.cn/api-explorer。

2. 在调试台顶部选择已创建的飞书应用（需与 OpenClaw 配置的 appId 一致）。

3. 搜索接口「获取群信息」或「搜索群列表」，填写群名等查询条件，点击「调试运行」。

4. 在接口返回结果中，找到 chat_id 字段，取值即为群 ID（格式：oc_xxx）。

步骤3：添加群 ID 到 OpenClaw 白名单

根据实际需求，可添加单个群或多个群至白名单，配置后需重启网关使配置生效。

3.1 单个群添加（常用场景）

# 替换命令中的 oc_xxx 为实际获取的群 ID
openclaw config set channels.feishu.groupAllowFrom '["oc_xxx"]'

3.2 多个群添加（多群使用场景）

# 多个群 ID 用英文逗号分隔，均包裹在中括号内
openclaw config set channels.feishu.groupAllowFrom '["oc_xxx1","oc_xxx2","oc_xxx3"]'

3.3 验证白名单配置

执行以下命令，确认群 ID 已成功添加至白名单：

openclaw config get channels.feishu.groupAllowFrom

正常输出应为：["oc_xxx1","oc_xxx2"]（与配置的群 ID 一致）。

步骤4：重启网关，使配置生效

OpenClaw 配置修改后，必须重启网关才能加载新的白名单配置，同时清理历史投递缓存，避免出现 open_id cross app 报错。

# 1. 停止当前运行的网关
openclaw gateway stop

# 2. 清理历史消息投递缓存（避免旧报错残留）
rm -rf /tmp/openclaw/delivery-*

# 3. 重新启动网关
openclaw gateway

网关启动成功后，终端日志会显示[feishu] feishu[default]: WebSocket client started 和 [ws] ws client ready，表示飞书长连接正常，白名单配置已生效。

步骤5：验证配置效果

1. 打开已添加至白名单的飞书群，@机器人发送测试消息（例如：@OpenClaw 测试白名单配置）。

2. 查看服务器终端的网关日志，若出现以下内容，说明配置生效：

   • [feishu] receive message: ...：机器人成功接收群消息。

   • [feishu] send message: ...：机器人成功回复群消息。

3. 飞书群内看到机器人的回复，即为配置成功。

三、常见问题排查

3.1 配置白名单后，机器人仍不回复

• 检查群 ID 是否正确：确认添加的群 ID 与目标群的 chat_id 完全一致，无多余空格或字符。

• 检查群聊策略：确认 groupPolicy 为 allowlist，而非 open。

• 检查网关是否重启：配置修改后未重启网关，新配置不会生效，需执行步骤4的重启命令。

• 检查飞书权限：确认飞书应用已开通 im:message.group_at_msg:readonly 和 im:message:send_as_bot权限，且已发布新版本。

• 检查机器人是否入群：确认机器人已加入目标群聊，未入群则无法接收消息。

3.2 网关启动时报错：open_id cross app（错误码 99992361）

核心原因：历史消息投递缓存残留，导致网关启动时重试发送无效消息，与白名单配置无关，但会影响日志整洁度。

解决方案：执行以下命令清理缓存并重启网关：

openclaw gateway stop
rm -rf /tmp/openclaw/delivery-*
openclaw gateway

3.3 如何关闭白名单模式（开放所有群聊）

若需让机器人响应所有群聊消息，可将群聊策略改为开放模式，无需配置白名单：

# 设置为开放模式
openclaw config set channels.feishu.groupPolicy "open"

# 重启网关生效
openclaw gateway stop && openclaw gateway

3.4 如何修改白名单（添加/删除群 ID）

• 添加新群：重新执行步骤3的配置命令，将新群 ID 加入数组（例如：['oc_旧ID1','oc_旧ID2','oc_新ID']）。

• 删除群：执行配置命令，仅保留需要保留的群 ID（例如：删除 oc_xxx2，命令为 openclaw config set channels.feishu.groupAllowFrom '["oc_xxx1"]'）。

• 修改后需重启网关，配置才能生效。

四、常用命令汇总（快速参考）

五、注意事项

• 群 ID 区分大小写，复制时需完整复制，避免遗漏或多输字符。

• 每次修改白名单配置后，必须重启网关，否则配置不生效。

• 白名单模式适用于生产环境，可有效控制机器人的响应范围，避免无关群聊触发机器人。

• 若飞书应用的可用范围发生变更，需重新发布应用版本，否则机器人可能无法正常收发消息。

• 清理 /tmp/openclaw/delivery-* 仅删除历史消息投递缓存，不会影响机器人的核心配置和正常运行。

六、版本适配说明

本文档适用于 OpenClaw 2026.2.26 及以上版本，若使用低版本 OpenClaw，部分命令可能存在差异，建议先升级至最新版本后再执行配置操作：

# 升级 OpenClaw 至最新版本
openclaw update

（注：文档部分内容可能由 AI 生成）