LobeHub
LobeHub

将 LobeHub 连接到 Telegram

通过将 Telegram 渠道连接到您的 LobeHub 代理,用户可以通过 Telegram 私聊和群组对话与 AI 助手互动。

前置条件

  • 一个拥有有效订阅的 LobeHub 账户
  • 一个 Telegram 账户

第一步:创建 Telegram 机器人

打开 BotFather

打开 Telegram 并搜索 @BotFather —— 这是用于管理机器人的官方 Telegram 机器人。开始对话并发送 /newbot 命令。

设置机器人名称和用户名

BotFather 会要求您:

  1. 为您的机器人选择一个 显示名称(例如,“LobeHub 助手”)
  2. 选择一个 用户名 —— 必须以 bot 结尾(例如,lobehub_assistant_bot)

复制机器人令牌

创建机器人后,BotFather 会发送给您一个 API 令牌(格式:123456789:ABCdefGhIjKlmNoPQRsTuVwXyZ)。复制并保存此令牌。

重要提示: 您的机器人令牌是一个机密凭证,请勿公开分享。

第二步:在 LobeHub 中配置 Telegram

打开渠道设置

在 LobeHub 中,导航到您的代理设置,然后选择 渠道 标签页。从平台列表中点击 Telegram。

输入机器人令牌

将您从 BotFather 收到的机器人令牌粘贴到 机器人令牌 字段中。

可选:设置 Webhook 密钥

您可以选择输入一个 Webhook 密钥令牌 以增加安全性。此密钥用于验证来自 Telegram 的入站 Webhook 请求。

保存配置

点击 保存配置。LobeHub 将自动向 Telegram 注册 Webhook URL,无需手动复制 URL。

您的令牌将被加密并安全存储。

第三步:测试连接

在 LobeHub 的渠道设置中点击 测试连接 以验证集成。然后打开 Telegram,搜索您的机器人用户名并发送消息。机器人应通过您的 LobeHub 代理进行响应。

填写你的平台身份(推荐)

高级设置里有一个可选字段影响日常使用体验,建议一开始就填好。

你的平台用户 ID

也就是你自己的 Telegram 数字用户 ID,用于:

  • 配对审批 — 当 私信策略 为 配对审批 时为必填项,/approve <code> 是属主命令,runtime 会用这个 ID 校验发起人。
  • AI 工具主动推送 — 让 Agent 能主动联系你(提醒、通知),把内部用户引用映射到你的 Telegram 账号。
  • 防自锁 — 自动被 允许的用户 信任,给好友收紧 bot 时不会把自己挡在外面。

获取方式:打开 Telegram,私信 @userinfobot,它会把你的数字用户 ID 回给你。粘贴到 LobeHub 高级设置的 你的平台用户 ID 字段。

Telegram 没有 "默认服务器" 的概念(每个会话各自独立),因此 Telegram 渠道不展示 默认服务器 字段。

将机器人添加到群组聊天

要在 Telegram 群组中使用机器人:

  1. 将机器人添加为群组成员
  2. 默认情况下,机器人在被 @your_bot_username 提及时会响应
  3. 发送一条提及机器人的消息以开始互动

关于隐私模式(Group Privacy): Telegram 机器人默认启用隐私模式,仅接收群组中 @提及、回复机器人的消息以及 / 命令。如果您在创建机器人后更改了隐私模式设置,必须将机器人从群组中移除后重新加入,新的设置才会对该群组生效。

Guest Mode(无需入群即可召唤)

Telegram Guest Mode 允许用户在任意群组或私聊中 @mention 你的机器人,不必把机器人加为成员。机器人只能看到这条召唤消息(以及它所回复的那条,如果有),并且只能回复一次。

  1. 打开 @BotFather 的 Mini App → 选择你的机器人 → 开启 Guest Mode
  2. 之后任何人都可以在机器人从未加入的会话里发送 @your_bot_username …
  3. 回复这条访客消息会再次召唤机器人

Guest 召唤使用独立的 访客模式策略,不受 群组策略 限制。关键词唤醒和常驻群聊流量仍需要把机器人加进群。

接入策略

三个独立的策略控制入站消息,默认都为 开放。

允许的用户 ID(全局)

填入 允许的用户 ID 后,所有入站消息(私信、群聊 @提及 和 Guest 召唤)都必须来自列表里的 Telegram 数字用户 ID。留空则不做用户级过滤。让目标用户私信 @userinfobot 拿到自己的数字 ID,或直接从机器人收到的 update 里读 from.id。

私信策略

  • 开放 (Open)(默认) — Telegram 上任何用户都可以私信机器人(若设置了全局白名单则受其约束)。
  • 白名单 (Allowlist) — 私信需要发送者在 允许的用户 ID 里。和 Open 的差别在白名单为空时:Allowlist 模式全部拒绝。
  • 配对审批 (Pairing) — 与 Allowlist 共享同一份名单,但非名单用户被拒后会收到一次性配对码,由你(属主)通过 /approve <code> 审批。审批通过的用户会被自动追加到 允许的用户 ID,后续 DM 直通。需先填 你的平台用户 ID(runtime 用它校验 /approve 发起人),并需要部署 Redis。
  • 禁用 (Disabled) — 机器人忽略所有私信,只在群组里被 @提及 时回复。

群组策略

控制机器人会在哪些 Telegram 群组 / 频道里响应。

  • 开放 (Open)(默认) — 在机器人加入的任何群组 / 频道里都响应。
  • 白名单 (Allowlist) — 只在 允许的频道 ID 列出的会话里响应。把群里的一条消息转发给 @userinfobot 即可拿到 chat ID(群组是负数)。
  • 禁用 (Disabled) — 忽略所有群组流量,机器人只接受私信。

访客模式策略

控制谁可以在不把机器人加入会话的情况下,通过 Telegram Guest Mode 召唤机器人。

  • 开放 (Open)(默认) — 接受任何人的 Guest 召唤。若 允许的用户 ID 非空,它仍会作为全局用户闸门生效。
  • 白名单 (Allowlist) — 只有 允许的用户 ID 中的用户可以召唤。名单为空时全部拒绝。
  • 配对审批 (Pairing) — 非名单用户会在 Guest 回复中收到一次性配对码。通过 /approve <code> 审批后,请用户重新召唤机器人。需要配置 你的平台用户 ID 和 Redis。
  • 禁用 (Disabled) — 拒绝所有 Guest 召唤,不影响私信或机器人已加入的群组。

跨平台细节见 渠道概览。

配置参考

字段是否必需描述
机器人令牌是来自 BotFather 的 API 令牌
Webhook 密钥令牌否用于验证 Webhook 请求的可选密钥
允许的用户 ID否逗号或空格分隔的 Telegram 数字用户 ID。全局闸门 — 私信、群聊 @ 和访客模式都受其约束
私信策略否open(默认)、allowlist、pairing 或 disabled — 控制谁可以私信机器人
群组策略否open(默认)、allowlist 或 disabled — 控制机器人在哪些群组中响应
访客模式策略否open(默认)、allowlist、pairing 或 disabled — 控制谁可以使用访客模式
允许的频道 ID否逗号或空格分隔的 Telegram chat ID(群组为负数)。仅在群组策略为白名单时使用

故障排除

  • 机器人未响应: 验证机器人令牌是否正确并确保配置已保存。点击 测试连接 进行诊断。
  • 机器人不回私信: 打开 高级设置 检查 私信策略。如果是 Disabled,改成 Open 或 Allowlist;如果是 Allowlist,确认发起方的 Telegram 用户 ID(可通过 @userinfobot 获取)已加入 允许的用户 ID。
  • Webhook 注册失败: 确保您的 LobeHub 订阅处于活动状态。Telegram 要求 Webhook 使用 HTTPS 端点,LobeHub 会自动提供。
  • 群组聊天问题: 确保机器人已被添加到群组并具有读取消息的权限。使用 @username 提及机器人以触发响应。如果机器人在群组中没有响应,尝试将机器人从群组中移除后重新加入 ——Telegram 的隐私模式设置变更需要重新加入群组才能生效。