将 Clawdbot AI 助手连接到 Telegram，实现智能机器人自动化、智能消息和 AI 驱动的 Telegram 对话。

Clawdbot Telegram 集成概述

Clawdbot Telegram 集成让您可以通过 grammY 使用 Bot API 将个人 AI 助手连接到 Telegram。这是生产就绪的，支持机器人私聊和群组，默认使用长轮询，可选 webhook 支持。

为什么选择 Clawdbot Telegram？

Telegram 提供强大的机器人 API 和隐私功能。将 Clawdbot 与 Telegram 集成可获得：

功能	Clawdbot Telegram 优势
Bot API 集成	Clawdbot Telegram 通过 grammY 使用原生 Telegram Bot API
内联模式	Clawdbot Telegram 支持内联查询
群组支持	私聊共享主会话；群组保持隔离
草稿流式传输	在 Telegram 私聊中流式传输部分回复
隐私优先	Clawdbot 本地运行，您的 Telegram 数据保持私密

快速设置（初学者）

使用 @BotFather 创建机器人（直接链接）
确认句柄正是 @BotFather，然后复制 token
通过环境变量（TELEGRAM_BOT_TOKEN=...）或配置（channels.telegram.botToken）设置 token
启动网关
私聊访问默认为配对模式；首次联系时批准配对码

最小配置：

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "123:abc",
      "dmPolicy": "pairing"
    }
  }
}

设置 Clawdbot Telegram

前置条件

在将 Clawdbot 连接到 Telegram 之前，请确保您已具备：

设备上已安装 Clawdbot
一个 Telegram 账户
从 @BotFather 获取的 Telegram Bot Token

步骤 1：创建 Telegram 机器人

通过 Telegram 的 BotFather 创建机器人：

打开 Telegram 并与 @BotFather 聊天（直接链接）
确认句柄正是 @BotFather
运行 /newbot，然后按照提示操作（名称 + 以 bot 结尾的用户名）
复制 token 并安全保存

可选 BotFather 设置：

/setjoingroups — 允许/禁止将机器人添加到群组
/setprivacy — 控制机器人是否能看到所有群组消息

步骤 2：配置 Token

通过环境变量或配置设置 token：

环境变量：

TELEGRAM_BOT_TOKEN=123:abc

配置文件（~/.clawdbot/clawdbot.json）：

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "123:abc",
      "dmPolicy": "pairing",
      "groups": {
        "*": { "requireMention": true }
      }
    }
  }
}

如果同时设置了环境变量和配置，配置优先。

步骤 3：启动网关

clawdbot gateway --port 18789

当 token 解析成功时（配置优先，环境变量备选），Telegram 启动。

步骤 4：验证连接

检查您的 Clawdbot Telegram 状态：

clawdbot channels status telegram

Token + 隐私 + 权限

Token 创建（BotFather）

/newbot 创建机器人并返回 token（保密）
如果 token 泄露，通过 @BotFather 撤销/重新生成并更新配置

群组消息可见性（隐私模式）

Telegram 机器人默认为隐私模式，限制它们接收哪些群组消息。选项：

使用 /setprivacy 禁用隐私模式
将机器人添加为群组管理员（管理员机器人接收所有消息）

注意：切换隐私模式时，Telegram 要求从每个群组中移除并重新添加机器人才能生效。

群组权限（管理员权限）

管理员状态在群组内设置（Telegram UI）。管理员机器人始终接收所有群组消息。

Clawdbot Telegram 功能特性

工作原理

入站消息被规范化为共享频道信封，包含回复上下文和媒体占位符
群组回复默认需要提及（原生 @提及或配置的模式）
回复始终路由回同一个 Telegram 聊天
长轮询使用 grammY runner，按聊天排序

草稿流式传输

Clawdbot 可以使用 sendMessageDraft 在 Telegram 私聊中流式传输部分回复。

要求：

在 @BotFather 中为机器人启用线程模式（论坛主题模式）
仅限私聊线程
channels.telegram.streamMode 未设置为 "off"

草稿流式传输仅限私聊；Telegram 不支持在群组或频道中使用。

格式化（Telegram HTML）

出站 Telegram 文本使用 parse_mode: "HTML"
类 Markdown 输入被渲染为 Telegram 安全的 HTML
来自模型的原始 HTML 被转义以避免 Telegram 解析错误

命令

Clawdbot Telegram 支持自定义命令：

命令	Clawdbot Telegram 动作
`/start`	Clawdbot 欢迎消息
`/help`	Clawdbot Telegram 帮助菜单
`/ask`	直接向 Clawdbot 提问

Clawdbot Telegram 配置

完整配置示例

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "123:abc",
      "dmPolicy": "pairing",
      "groups": {
        "*": { "requireMention": true }
      }
    }
  }
}

访问控制（私聊 + 群组）

私聊访问：

dmPolicy: "pairing" — 未知发送者获得配对码；通过 CLI 批准
dmPolicy: "allowlist" — 仅响应白名单中的用户
dmPolicy: "open" — 响应所有人（不推荐）

群组访问：

设置 channels.telegram.groups，按群组 id 或 "*" 表示所有群组
使用 requireMention: true 仅在被提及时响应

查找您的 Telegram 用户 ID

使用 @userinfobot 或类似机器人获取您的数字 Telegram 用户 ID。

Clawdbot Telegram 凭证存储

Clawdbot 安全存储 Telegram 凭证：

~/.clawdbot/credentials/telegram/bot_token
~/.clawdbot/credentials/telegram/session.json

您的 Clawdbot Telegram 数据保留在本地机器上。

Clawdbot Telegram 故障排除

机器人无响应

如果您的 Clawdbot Telegram 机器人不响应：

验证 token：clawdbot channels verify telegram
通过 @BotFather 检查机器人状态
查看日志：cat /tmp/clawdbot/telegram.log

群组激活

在群组中激活 Clawdbot：

通过配置（推荐）：

{
  "channels": {
    "telegram": {
      "groups": {
        "<group_id>": { "requireMention": true }
      }
    }
  }
}

通过命令（会话级别）： 在群聊中使用 /activate。

获取群组聊天 ID

将群组中的消息转发给 @userinfobot 或使用 Telegram API。

Clawdbot Telegram 最佳实践

使用配对模式：默认使用配对码确保安全
设置隐私模式：根据需要在 @BotFather 中配置
处理速率限制：实现适当的速率限制
监控使用情况：跟踪 Clawdbot Telegram 机器人分析数据

下一步

Clawdbot WhatsApp 集成 - 将 Clawdbot 连接到 WhatsApp
Clawdbot Discord 集成 - 在 Discord 上设置 Clawdbot
Clawdbot 设置指南 - 完整安装指南

Clawdbot Telegram 集成指南