Telegram Bot 上线配置技能

技能 ID: telegram-bot-setup
版本: 1.0 (2026-03-11)
用途: 指导用户完成 Telegram Bot 配置与上线

📋 技能描述

本技能提供 Telegram Bot 配置的完整指导，支持：

单 Bot 添加 — 一个 Bot 对应一个 Agent
多 Bot 添加 — 多个 Bot 对应多个 Agent
群组添加 — 支持群组消息和 Topics

🎯 使用场景

场景	说明
新 Agent 上线 Telegram	配置 Bot Token 和消息绑定
多 Agent 多 Bot	配置 accounts 和 bindings
群组消息支持	配置群组 ID 和提及策略
Topic 支持	配置 Topic 级别消息路由

📝 前置准备

用户需要准备的

Telegram Bot Token
- 在 Telegram 中联系 @BotFather
- 发送 /newbot 创建新 Bot
- 设置 Bot 名称和用户名
- 复制 Bot Token（格式：123456789:ABCdef...）
Group ID（如需群组支持）
- 在群组中添加 @MissRose_bot
- 发送 /id 命令
- 获取 Group ID 和 Topic ID
Agent ID
- 确认要绑定的 Agent ID（如 main, leader, tool-architect 等）

🔧 配置流程（问答式）

Q1: 你需要配置哪种场景？

A. 单 Bot 单 Agent → 跳转到 [场景 A](#场景 a-单 bot 单 agent)

B. 多 Bot 多 Agent → 跳转到 [场景 B](#场景 b-多 bot 多 agent)

C. 群组消息支持 → 跳转到 [场景 C](#场景 c-群组消息支持)

场景 A: 单 Bot 单 Agent

适用: 一个 Bot 对应一个 Agent

Step 1: 添加 Bot Token

编辑 ~/.openclaw/.env:

TELEGRAM_BOT_TOKEN=你的_Bot_Token

Step 2: 配置 openclaw.json

编辑 ~/.openclaw/openclaw.json:

{
  "channels": {
    "telegram": {
      "enabled": true,
      "dmPolicy": "pairing",
      "botToken": "你的_Bot_Token",
      "groupPolicy": "allowlist",
      "allowFrom": ["你的 Telegram ID"],
      "streaming": "partial"
    }
  },
  "bindings": [
    {
      "agentId": "你的 Agent ID",
      "match": {
        "channel": "telegram",
        "accountId": "default"
      }
    }
  ]
}

Step 3: 重启 Gateway

openclaw gateway restart

Step 4: 测试

在 Telegram 中:

找到你的 Bot
发送 /start
确认收到回复

场景 B: 多 Bot 多 Agent

适用: 多个 Bot 对应多个 Agent

Step 1: 添加所有 Bot Token

编辑 ~/.openclaw/.env:

# Bot 1
TELEGRAM_BOT_TOKEN_BOT1=Bot1_Token

# Bot 2
TELEGRAM_BOT_TOKEN_BOT2=Bot2_Token

Step 2: 配置 accounts

编辑 ~/.openclaw/openclaw.json:

{
  "channels": {
    "telegram": {
      "enabled": true,
      "dmPolicy": "pairing",
      "groupPolicy": "allowlist",
      "allowFrom": ["你的 Telegram ID"],
      "streaming": "partial",
      "accounts": {
        "bot1": {
          "enabled": true,
          "botToken": "Bot1_Token"
        },
        "bot2": {
          "enabled": true,
          "botToken": "Bot2_Token"
        }
      }
    }
  }
}

Step 3: 配置 bindings

编辑 ~/.openclaw/openclaw.json:

{
  "bindings": [
    {
      "agentId": "agent1_id",
      "match": {
        "channel": "telegram",
        "accountId": "bot1"
      }
    },
    {
      "agentId": "agent2_id",
      "match": {
        "channel": "telegram",
        "accountId": "bot2"
      }
    }
  ]
}

Step 4: 重启 Gateway

openclaw gateway restart

Step 5: 测试

在 Telegram 中:

分别给每个 Bot 发送 /start
确认对应 Agent 回复

场景 C: 群组消息支持

适用: Bot 需要响应群组消息

Step 1: 获取 Group ID

在 Telegram 群组中:

添加 @MissRose_bot 到群组
发送 /id 命令

记录返回的 ID:

Group ID: -1003793956861
Topic ID: 1 (如果有 Topics)

Step 2: 配置群组

编辑 ~/.openclaw/openclaw.json:

{
  "channels": {
    "telegram": {
      "enabled": true,
      "groups": {
        "-1003793956861": {
          "requireMention": true,
          "groupPolicy": "open",
          "topics": {
            "1": {
              "requireMention": true,
              "groupPolicy": "open"
            },
            "2": {
              "requireMention": false,
              "groupPolicy": "open"
            }
          }
        }
      }
    }
  }
}

配置说明:

参数	值	说明
`requireMention`	`true/false`	是否需要 @Bot 提及
`groupPolicy`	`open/allowlist`	开放或白名单
`topics`	`{}`	Topic 级别配置（可选）

Step 3: 配置群组消息绑定

编辑 ~/.openclaw/openclaw.json:

{
  "bindings": [
    {
      "agentId": "你的 Agent ID",
      "match": {
        "channel": "telegram",
        "accountId": "你的 Bot 账号",
        "peer": {
          "kind": "group",
          "id": "-1003793956861"
        }
      }
    }
  ]
}

Step 4: 重启 Gateway

openclaw gateway restart

Step 5: 测试

在群组中:

发送 @Bot 用户名你好
确认 Bot 回复

🔍 常见问题排查

Q1: Bot 不回复消息

检查清单:

Bot Token 是否正确
Gateway 是否重启
bindings 配置是否匹配
群组消息是否需要 @提及

日志检查:

cat /tmp/openclaw/openclaw-*.log | grep telegram | tail -20

常见错误:

错误	原因	解决
`unknown channel id`	使用了自定义 channel ID	使用 `accounts` 配置
`token mismatch`	Token 配置错误	检查 .env 和 openclaw.json
`no-mention`	群组要求提及	发送时 @Bot

Q2: 群组消息收不到

检查清单:

Group ID 是否正确（包含 -100 前缀）
是否配置了 bindings 群组绑定
peer.kind 是否为 "group"
Bot 是否在群组中

配置示例:

{
  "bindings": [
    {
      "agentId": "main",
      "match": {
        "channel": "telegram",
        "accountId": "bigbro",
        "peer": {
          "kind": "group",
          "id": "-1003793956861"
        }
      }
    }
  ]
}

Q3: Topic 消息不响应

检查清单:

Topic ID 是否正确（数字，如 1, 2, 3）
Topics 配置是否在 groups 下
Topic 的 requireMention 设置

配置示例:

{
  "groups": {
    "-1003793956861": {
      "topics": {
        "1": {
          "requireMention": true,
          "groupPolicy": "open"
        }
      }
    }
  }
}

Q4: Gateway 重启失败

解决方案:

方式 A: 热重载（推荐）

# 配置会自动重载，无需手动操作

方式 B: 手动重启

# 容器内
kill <gateway_pid> && openclaw gateway

# 或宿主机
docker restart <容器名>

方式 C: 修复配置

openclaw doctor --fix
openclaw gateway restart

📋 完整配置示例

多 Bot + 群组 + Topics

{
  "channels": {
    "telegram": {
      "enabled": true,
      "dmPolicy": "pairing",
      "groupPolicy": "allowlist",
      "allowFrom": ["8732266812"],
      "streaming": "partial",
      "accounts": {
        "leader": {
          "enabled": true,
          "botToken": "8400278364:AAHXNoE6ql3dBjwnhXo-lMiE6kROicVxC8o"
        },
        "bigbro": {
          "enabled": true,
          "botToken": "8532367214:AAH5xW_dnGykVSIcktHaIliQvIz95ZTXmM4"
        }
      },
      "groups": {
        "-1003793956861": {
          "requireMention": true,
          "groupPolicy": "open",
          "topics": {
            "1": {
              "requireMention": true,
              "groupPolicy": "open"
            },
            "2": {
              "requireMention": false,
              "groupPolicy": "open"
            }
          }
        }
      }
    }
  },
  "bindings": [
    {
      "agentId": "leader",
      "match": {
        "channel": "telegram",
        "accountId": "leader"
      }
    },
    {
      "agentId": "main",
      "match": {
        "channel": "telegram",
        "accountId": "bigbro",
        "peer": {
          "kind": "group",
          "id": "-1003793956861"
        }
      }
    }
  ]
}

🎯 快速参考

配置位置

配置项	文件	说明
Bot Token	`~/.openclaw/.env`	环境变量
Channel 配置	`~/.openclaw/openclaw.json`	channels.telegram
Bindings	`~/.openclaw/openclaw.json`	bindings 数组

命令速查

# 重启 Gateway
openclaw gateway restart

# 修复配置
openclaw doctor --fix

# 查看日志
cat /tmp/openclaw/openclaw-*.log | grep telegram | tail -20

# 获取 Group ID
# 在 Telegram 群组中 @MissRose_bot 发送 /id

测试清单

Bot Token 已写入 .env
accounts 配置正确
bindings 配置正确
Gateway 已重启
个人消息测试通过
群组消息测试通过
Topics 测试通过（如使用）

📚 相关文档

OpenClaw 文档：https://docs.openclaw.ai
Telegram Bot API: https://core.telegram.org/bots/api
BotFather: https://t.me/BotFather

技能版本: 1.0
最后更新: 2026-03-11
维护者: yaer (main agent)
基于: Telegram 配置实战经验（2026-03-11）

Telegram Bot 上线配置技能

📋 技能描述

🎯 使用场景

📝 前置准备

用户需要准备的

🔧 配置流程（问答式）

Q1: 你需要配置哪种场景？

场景 A: 单 Bot 单 Agent

Step 1: 添加 Bot Token

Step 2: 配置 openclaw.json

Step 3: 重启 Gateway

Step 4: 测试

场景 B: 多 Bot 多 Agent

Step 1: 添加所有 Bot Token

Step 2: 配置 accounts

Step 3: 配置 bindings

Step 4: 重启 Gateway

Step 5: 测试

场景 C: 群组消息支持

Step 1: 获取 Group ID

Step 2: 配置群组

Step 3: 配置群组消息绑定

Step 4: 重启 Gateway

Step 5: 测试

🔍 常见问题排查

Q1: Bot 不回复消息

Q2: 群组消息收不到

Q3: Topic 消息不响应

Q4: Gateway 重启失败

📋 完整配置示例

多 Bot + 群组 + Topics

🎯 快速参考

配置位置

命令速查

测试清单

📚 相关文档

Trust Score

Attestations