OpenClaw 对 Telegram 提供了生产级支持，通过 grammY 实现 Bot API 接入。默认使用长轮询模式，也可选 Webhook 模式。本文涵盖从快速配置到高级访问控制的全部内容。
快速配置步骤
第 1 步：创建 Telegram Bot
- 在 Telegram 中找到 @BotFather
- 发送
/newbot创建新 Bot - 按提示设置 Bot 名称和用户名
- 保存获得的 Bot Token
第 2 步：配置 openclaw.json
json
{
"channels": {
"telegram": {
"enabled": true,
"botToken": "你的Bot Token",
"dmPolicy": "pairing"
}
}
}第 3 步：重启 Gateway
bash
openclaw gateway restart访问控制策略
私聊（DM）策略
channels.telegram.dmPolicy 控制私聊访问权限：
| 策略值 | 说明 |
|---|---|
pairing（默认） | 需要配对审批才能与 Bot 交互 |
allowlist | 只允许 allowFrom 列表中的用户 |
open | 允许所有人（需在 allowFrom 中添加 "*"） |
disabled | 禁用私聊功能 |
找到你的 Telegram 用户 ID
推荐方式（无需第三方 Bot）：
- 给你的 Bot 发一条消息
- 运行
openclaw logs --follow - 查看日志中的
from.id字段
官方 API 方式：
bash
curl "https://api.telegram.org/bot<bot_token>/getUpdates"配置白名单
json
{
"channels": {
"telegram": {
"dmPolicy": "allowlist",
"allowFrom": ["123456789", "987654321"]
}
}
}群组管理
群组访问由两个控制层共同决定：
- 允许哪些群组 (
channels.telegram.groups) - 允许群组中的哪些成员 (
channels.telegram.groupPolicy)
群组策略
json
{
"channels": {
"telegram": {
"groupPolicy": "allowlist",
"groupAllowFrom": ["123456789"],
"groups": {
"-1001234567890": {
"groupPolicy": "open",
"requireMention": false
}
}
}
}
}全局开放群组（任何成员均可使用）
json
{
"channels": {
"telegram": {
"groups": {
"*": { "requireMention": false }
}
}
}
}获取群组 Chat ID
- 将群消息转发给
@userinfobot或@getidsbot - 或运行
openclaw logs --follow查看chat.id - 或通过 Bot API 的
getUpdates接口获取
@提及行为
群组中默认需要 @提及 Bot 才会触发响应。提及方式：
- 原生 Telegram
@botusername提及 - 在配置中设置自定义提及模式：
json
{
"messages": {
"groupChat": {
"mentionPatterns": ["@openclaw", "小爪"]
}
}
}高级配置选项
消息流式输出
json
{
"channels": {
"telegram": {
"streaming": "partial"
}
}
}流式模式：off（默认）| partial | block | progress
Webhook 模式（替代长轮询）
json
{
"channels": {
"telegram": {
"webhookUrl": "https://yourdomain.com/webhook",
"webhookSecret": "your-secret-key"
}
}
}代理配置
json
{
"channels": {
"telegram": {
"proxy": "socks5://127.0.0.1:1080"
}
}
}内联按钮
json
{
"channels": {
"telegram": {
"capabilities": {
"inlineButtons": "all"
}
}
}
}可选值：off | dm | group | all | allowlist（默认）
运行时行为说明
- Telegram 由 Gateway 进程管理，路由是确定性的
- 入站消息统一规范化为共享频道信封格式
- 群组会话按群组 ID 隔离；论坛话题额外附加
:topic:<threadId> - 长轮询使用 grammY runner，按聊天/话题顺序处理消息
常用配置速查
| 配置项 | 说明 |
|---|---|
botToken | BotFather 给的 Token |
dmPolicy | 私聊策略 |
allowFrom | 私聊白名单用户 ID |
groupPolicy | 群组策略 |
groupAllowFrom | 群组白名单用户 ID |
streaming | 流式输出模式 |
textChunkLimit | 消息分块大小（字符数） |
mediaMaxMb | 媒体文件大小上限 |
原文：Telegram - OpenClaw | 来源：OpenClaw 官方文档