# OpenClaw 接入 Telegram 群组实战指南

> **摘要**：记录将 OpenClaw AI 助手接入 Telegram 群组的完整过程，包括常见陷阱排查、关键配置字段解析以及最终解决方案。适用于希望在群聊中部署 AI 助手的开发者。

---

## 背景

目标：将运行在 OpenClaw 框架下的 AI 助手（Bot）接入指定的 Telegram 群组，实现群内消息的接收与回复。

环境信息：

- **OpenClaw 版本**：2026.2.26

- **部署环境**：Windows 11 (Scheduled Task)

- **Telegram Bot**：@xxx_bot

- **目标群组 ID**：`-51xxx`

---

## 第一阶段：初步尝试与问题暴露

### 1.1 初步配置

最初，我尝试将群组 ID 直接添加到用户的白名单 `allowFrom` 中，认为这样可以允许该群组的消息进入：

```json

{

  "channels": {

    "telegram": {

      "accounts": {

        "magic": {

          "allowFrom": ["56xxxx", "-51xxx"],

          "groupPolicy": "allowlist"

        }

      }

    }

  }

}

```

**现象**：

- ✅ Bot 可以成功向群组发送消息（证明 Bot 在群内且网络通畅）。

- ❌ Bot **无法接收**群组的任何消息（包括 @ 提及）。

- ❌ OpenClaw 会话列表中未生成任何群组会话（如 `agent:...:group:...`）。

### 1.2 排查过程

尝试了以下常见修复手段，均**无效**：

1. **尝试完整群组 ID**：添加 `-10051xxx`（超级群组格式）到 `allowFrom`。

2. **修改群组策略**：尝试将 `groupPolicy` 改为 `"public"` 或 `"all"`，但配置校验失败（不支持的值）。

3. **尝试新字段**：猜测是否存在 `allowGroups` 字段，配置校验同样失败。

**结论**：`allowFrom` 字段可能仅用于**私聊用户**的白名单，不适用于群组。

---

## 第二阶段：关键转折 - Telegram 隐私模式

在确认 Bot 已加入群组且配置看似无误后，问题指向了 Telegram 的机制。

### 2.1 隐私模式 (Privacy Mode)

Telegram Bot 默认开启隐私模式，在此模式下：

- Bot **看不到**群里的普通消息。

- Bot **只能看到**：

  - @ 提及它的消息。

  - 回复它的消息。

  - 或者 Bot 被设为管理员。

**操作**：

1. 访问 @BotFather。

2. 输入 `/mybots` 选择目标 Bot。

3. 进入 `Bot Settings` -> `Group Privacy`。

4. 设置为 **Disabled**（关闭隐私模式）。

5. **关键一步**：将 Bot **移出群组**，然后**重新拉入**，使设置生效。

**结果**：问题依旧。说明即使关闭隐私模式，OpenClaw 的配置逻辑仍有门槛。

---

## 第三阶段：定位核心问题 - 配置字段错误

查阅 OpenClaw 官方文档后，发现了关键信息：

> **群组访问由 `*.groupPolicy` + 允许列表（`*.groups`、`*.groupAllowFrom`）控制。**

> **私信访问由 `*.allowFrom` 控制。**

**核心发现**：

- ❌ `allowFrom`：仅用于**私聊用户**的白名单（User ID）。

- ✅ `groups`：用于定义**允许的群组列表**（Group ID）。

之前的配置一直错误地将群组 ID 放入 `allowFrom`，导致 OpenClaw 在解析时直接忽略了群组消息。

---

## 第四阶段：正确配置与验证

### 4.1 修正后的配置

根据文档，正确的配置结构应该是在 `channels.telegram` 层级添加 `groups` 对象：

```json

{

  "channels": {

    "telegram": {

      "groupPolicy": "allowlist",

      "groups": {

        "-51xxx": {

          "requireMention": true

        },

        "-10051xxx": {

          "requireMention": true

        }

      },

      "accounts": {

        "magic": {

          "allowFrom": ["56xxxx"],

          "groupPolicy": "allowlist"

        }

      }

    }

  }

}

```

**配置说明**：

- `groupPolicy: "allowlist"`：启用群组白名单模式。

- `groups`：定义允许的群组列表。

  - 键为群组 ID（支持短 ID 和带 `-100` 的完整 ID，建议都加上以防万一）。

  - `requireMention: true`：在群内需要 @Bot 才能触发回复（默认行为，避免骚扰）。

- `allowFrom`：保持仅包含用户 ID，用于控制哪些人可以在私聊中触发 Bot。

### 4.2 应用配置

使用 `gateway` 工具应用配置：

```bash

openclaw gateway config.patch --raw '{"channels": {"telegram": {"groupPolicy": "allowlist", "groups": {"-51xxx": {"requireMention": true}, "-10051xxx": {"requireMention": true}}}}}'

```

OpenClaw 会自动重启 Gateway 以应用新配置。

### 4.3 验证测试

1. 在群组中发送：`@xxx_bot 测试成功了吗？`

2. **观察**：

   - ✅ Bot 在群内回复了消息。

   - ✅ OpenClaw 会话列表中出现新会话：`agent:magic:telegram:group:-51xxx`。

**成功！**

---

## 关键知识点总结

### 1. 字段区分

| 字段 | 作用域 | 示例值 | 说明 |

|------|--------|--------|------|

| `allowFrom` | 私聊 (DM) | `"56xxxx"` | 允许触发 Bot 的用户 ID |

| `groups` | 群组 (Group) | `"-51xxx"` | 允许 Bot 响应的群组 ID |

| `groupPolicy` | 群组策略 | `"allowlist"` / `"open"` / `"disabled"` | 控制群组消息处理策略 |

| `groupAllowFrom` | 群组内用户 | `"56xxxx"` | (可选) 限制群内哪些人可以触发 Bot |

### 2. 群组 ID 格式

- **普通群组**：负数，如 `-51xxx`。

- **超级群组 (Supergroup)**：通常以 `-100` 开头，如 `-10051xxx`。

- **建议**：在 `groups` 中同时配置短 ID 和完整 ID，确保兼容性。

### 3. 提及限制 (`requireMention`)

- `true`（默认）：群内消息需 @Bot 才响应。

- `false`：群内所有消息都会触发 Bot（慎用，可能造成骚扰）。

### 4. 隐私模式 (Privacy Mode)

即使配置正确，如果未关闭 Telegram Bot 的隐私模式且未将 Bot 设为管理员，Bot 仍可能收不到消息。

**推荐操作**：

1. 在 @BotFather 关闭 Privacy Mode。

2. 将 Bot 移出群组再重新拉入。

---

## 完整配置示例

以下是 `openclaw.json` 中 Telegram 部分的完整配置示例：

```json

{

  "channels": {

    "telegram": {

      "enabled": true,

      "groupPolicy": "allowlist",

      "groups": {

        "-51xxx": {

          "requireMention": true

        },

        "-10051xxx": {

          "requireMention": true

        }

      },

      "accounts": {

        "magic": {

          "enabled": true,

          "botToken": "YOUR_BOT_TOKEN",

          "allowFrom": ["56xxxx"],

          "dmPolicy": "allowlist",

          "groupPolicy": "allowlist",

          "streaming": "partial"

        }

      }

    }

  }

}

```

---

## 常见问题 FAQ

### Q: 配置后仍然收不到群消息？

**A**: 按顺序检查：

1. Bot 是否在群内？（发送测试消息确认）

2. `groupPolicy` 是否为 `"allowlist"` 或 `"open"`？

3. `groups` 对象中是否包含正确的群组 ID？

4. 是否关闭了 Privacy Mode 并重启了 Bot 在群内的连接？

5. 消息是否包含 @ 提及（如果 `requireMention: true`）？

### Q: 如何获取群组 ID？

**A**:

- 方法 1：在群内发送消息，查看 Bot 日志中的 `chat.id`。

- 方法 2：使用 @getidsbot 等工具 Bot 查询。

- 方法 3：通过 Telegram API `getUpdates` 接口获取。

### Q: 如何让 Bot 在群内免 @ 响应？

**A**: 将对应群组的 `requireMention` 设置为 `false`：

```json

"-51xxx": {

  "requireMention": false

}

```

---

## 结语

接入 Telegram 群组的关键在于理解 OpenClaw 对**私聊**和**群聊**的区分处理机制：

- **私聊**：通过 `allowFrom` 控制用户白名单。

- **群聊**：通过 `groups` 对象控制群组白名单。

避免将群组 ID 误填入 `allowFrom`，是成功的关键。

希望这篇实战记录能帮助你少走弯路，快速将 AI 助手部署到 Telegram 群组中！

---

**参考资料**：

- [OpenClaw 官方文档 - 群组](https://docs.openclaw.ai/zh-CN/channels/groups)

- [Telegram Bot API - Privacy Mode](https://core.telegram.org/bots/features#privacy-mode)

---

*作者：包打听*

*日期：2026-03-01*

*标签：#OpenClaw #Telegram #Bot #AI #教程*