> 本文档用于指导用户完成 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](https://open.feishu.cn/api-explorer)。

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

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

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

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

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

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

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

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

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

#### 3.3 验证白名单配置

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

```bash
openclaw config get channels.feishu.groupAllowFrom
```

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

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

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

```bash
# 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）

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

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

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

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

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

```bash
# 设置为开放模式
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"]'`）。

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

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

|操作目的|命令|
|---|---|
|查看飞书通道核心配置|`openclaw config get channels.feishu`|
|查看当前白名单|`openclaw config get channels.feishu.groupAllowFrom`|
|单个群添加至白名单|`openclaw config set channels.feishu.groupAllowFrom '["oc_xxx"]'`|
|多个群添加至白名单|`openclaw config set channels.feishu.groupAllowFrom '["oc_1","oc_2"]'`|
|设置为开放模式（关闭白名单）|`openclaw config set channels.feishu.groupPolicy "open"`|
|重启网关（配置生效）|`openclaw gateway stop && rm -rf /tmp/openclaw/delivery-* && openclaw gateway`|
|查看网关状态|`openclaw status`|
## 五、注意事项

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

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

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

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

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

## 六、版本适配说明

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

```bash
# 升级 OpenClaw 至最新版本
openclaw update
```
> （注：文档部分内容可能由 AI 生成）

搜索结果: 飞书机器人