OpenClaw 的 Telegram 集成基于 Bot API（grammY 库），默认长轮询模式，支持 DM、群组、论坛主题、多账号多 Agent。本文覆盖核心访问控制与高级配置。
DM 访问控制（dmPolicy）
json
{
"channels": {
"telegram": {
"dmPolicy": "allowlist",
"allowFrom": ["123456789", "987654321"]
}
}
}| 策略 | 说明 |
|---|---|
pairing（默认） | 需要配对审批 |
allowlist | 仅允许 allowFrom 中的用户 ID |
open | allowFrom 包含 "*" 时开放 |
disabled | 拒绝所有 DM |
单人使用的 Bot 推荐
dmPolicy: "allowlist"+ 明确的数字 ID，比依赖配对记录更稳定。
获取你的 Telegram 用户 ID
方法一（安全，不需要第三方）：
- 向你的 Bot 发一条消息
- 运行
openclaw logs --follow - 查看日志中的
from.id字段
方法二（官方 API）：
bash
curl "https://api.telegram.org/bot<token>/getUpdates"群组权限配置
两个控制维度：哪些群组可以访问 + 群组内哪些成员可以发言
开放特定群组
json
{
"channels": {
"telegram": {
"groups": {
"-1001234567890": {
"groupPolicy": "open",
"requireMention": false
}
}
}
}
}群组内限定特定成员
json
{
"channels": {
"telegram": {
"groups": {
"-1001234567890": {
"requireMention": true,
"allowFrom": ["8734062810", "745123456"]
}
}
}
}
}所有群组默认不需要 @ 提及
json
{
"channels": {
"telegram": {
"groups": {
"*": { "requireMention": false }
}
}
}
}获取群组 ID
- 将群组消息转发给
@userinfobot或@getidsbot - 或查看
openclaw logs --follow中的chat.id - 群组 ID 通常是负数（如
-1001234567890）
论坛主题（Forum Topic）路由
不同主题路由到不同 Agent：
json
{
"channels": {
"telegram": {
"groups": {
"-1001234567890": {
"topics": {
"123": {
"agentId": "coding",
"groupPolicy": "open"
},
"456": {
"agentId": "assistant",
"requireMention": false
}
}
}
}
}
}
}多账号配置
多个 Bot Token 对应多个 Agent：
json
{
"channels": {
"telegram": {
"defaultAccount": "main",
"accounts": {
"main": {
"botToken": "123456:ABC...",
"dmPolicy": "pairing"
},
"alerts": {
"botToken": "987654:XYZ...",
"dmPolicy": "allowlist",
"allowFrom": ["123456789"]
}
}
}
}
}Exec 命令审批（通过 Telegram 审批）
json
{
"channels": {
"telegram": {
"execApprovals": {
"enabled": true,
"approvers": ["123456789"],
"target": "dm"
}
}
}
}target 选项：dm（私信）、channel（频道）、both
Webhook 模式配置
默认是长轮询。切换到 Webhook 模式（更低延迟）：
json
{
"channels": {
"telegram": {
"webhookUrl": "https://your-domain.com/telegram-webhook",
"webhookSecret": "your-secret-token",
"webhookPath": "/telegram-webhook",
"webhookHost": "127.0.0.1",
"webhookPort": 8787
}
}
}常用功能配置
流式回复预览
json
{
"channels": {
"telegram": {
"streaming": "partial"
}
}
}可选：off、partial（默认）、block
回复模式
json
{
"channels": {
"telegram": {
"replyToMode": "first"
}
}
}可选：off（默认）、first（仅回复第一条）、all
内联按钮
json
{
"channels": {
"telegram": {
"capabilities": {
"inlineButtons": "all"
}
}
}
}代理配置（中国区常用）
json
{
"channels": {
"telegram": {
"proxy": "socks5://127.0.0.1:1080"
}
}
}消息分块
json
{
"channels": {
"telegram": {
"textChunkLimit": 4000,
"chunkMode": "newline"
}
}
}chunkMode: "newline" 在段落边界分割，更自然。
反应（Reactions）配置
json
{
"channels": {
"telegram": {
"reactionLevel": "minimal",
"reactionNotifications": "own"
}
}
}reactionLevel：off、ack、minimal（默认）、extensive
故障排查
Bot 没有响应：
- 检查
botToken是否正确 - 确认
dmPolicy和allowFrom配置 - 运行
openclaw logs --follow查看实时日志
用户 ID 无效：
openclaw doctor --fix可以将旧版@username自动转换为数字 ID
群组访问被拒绝：
- 检查
groupPolicy是否为allowlist且未配置groups - 群组 ID 需要包含负号（如
-1001234567890）
原文：Telegram - OpenClaw | 来源：OpenClaw 官方文档