把 Moltbot 接到 Telegram 上

Telegram 是目前与 Moltbot 兼容性最好的渠道。私聊、群组均可使用，消息格式支持也最丰富。如果你只打算接一个渠道，推荐 Telegram。

本文从零开始，覆盖完整的接入流程。

在 BotFather 中创建 Bot

Telegram 的 Bot 统一通过官方的 @BotFather 创建。

打开 Telegram，搜索 @BotFather 并进入对话，发送：

/newbot

BotFather 会依次询问两个问题：

1. Bot 的显示名称 — 可以是任意名称，中英文均可，例如「我的助手」
2. Bot 的用户名 — 必须为英文且以 bot 结尾，例如 my_cool_bot 或 zhangsan_moltbot

完成后，BotFather 会返回一串 Bot Token，格式如下：

123456789:ABCdefGHIjklMNOpqrsTUVwxyz

冒号前面是数字 ID，后面是密钥字符串。这串 Token 等同于 Bot 的凭证。

务必妥善保管，不要将其提交到 GitHub、发到群聊或出现在任何公开场所。 持有 Token 即可完全控制该 Bot。将 Token 提交到公开仓库导致 Bot 被滥用的情况并不少见。

将 Token 配置到 Moltbot

拿到 Token 后，选择以下任一方式配置。

方式一：环境变量

推荐方式，简洁安全。

export TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz

如需持久生效，将这行添加到 ~/.bashrc 或 ~/.zshrc 中。

方式二：配置命令

moltbot configure --section telegram

交互式提示中填入 Token 即可。实际上是写入了配置文件 ~/.moltbot/config.yaml：

channels:
  telegram:
    botToken: "123456789:ABCdefGHIjklMNOpqrsTUVwxyz"

使用配置文件时，确保该文件不会被 git 提交。在项目的 .gitignore 中添加 .moltbot/。

启动与配对

Token 配置完成后，启动 Moltbot：

moltbot start

打开 Telegram，找到刚创建的 Bot，发送一条任意消息。

终端会输出一个配对码，格式类似 ABCD-1234。

在终端执行：

moltbot pairing approve telegram YOUR_CODE

将 YOUR_CODE 替换为实际的配对码即可。配对只需执行一次，后续无需重复。

在群组中使用

要在群聊中使用 Moltbot，有一个关键步骤不能遗漏。

关闭 Privacy Mode

Telegram Bot 默认开启 Privacy Mode。启用状态下，Bot 在群组中只能接收两类消息：直接 @ 它的消息，以及以 / 开头的命令。其他消息 Bot 无法收到。

需要在 BotFather 中关闭该设置：

1. 打开 @BotFather
2. 发送 /setprivacy
3. 选择你的 Bot
4. 选择 Disable

BotFather 会确认 Privacy Mode 已关闭。

注意： 修改 Privacy Mode 后，需要将 Bot 从群组中移除并重新添加，设置才会生效。这一点容易遗漏。

群组中的触发方式

默认情况下，Moltbot 在群组中只在被 @提及 时才会回复。这样可以避免对群内每条消息都做出响应。

@my_cool_bot 帮我查一下明天的天气

也可以自定义触发词：

channels:
  telegram:
    groupMentionPatterns:
      - "@my_cool_bot"
      - "小助手"
      - "嘿bot"

配置后，在群里说「小助手帮我查个东西」也会触发响应。

群组安全

不建议将 Moltbot 加入不受信任的群组。

群内任何成员都可以向 Bot 发送指令。如果 Moltbot 配置了 GitHub Token 等凭证，群成员理论上可以通过对话引导 Bot 执行非预期操作。

私聊是最安全的使用方式。如果需要在群组中使用，确保群成员都是可信的。更多信息参见安全配置。

Webhook 模式

默认情况下 Moltbot 使用长轮询（Long Polling），即持续向 Telegram 服务器查询新消息。对个人用户来说完全够用。

如果 Moltbot 部署在具有公网 IP 的服务器上，可以切换为 Webhook 模式。Webhook 由 Telegram 主动推送消息，响应更快。

channels:
  telegram:
    mode: webhook
    webhookUrl: https://your-domain.com/telegram/webhook
    webhookPort: 8443

Webhook 模式要求 HTTPS。如果还没有证书，可以使用 Cloudflare Tunnel，或 nginx + Let's Encrypt。

如果不需要 Webhook，保持默认的长轮询即可。

国内网络问题

在国内访问 Telegram 需要代理，Moltbot 同样需要能连通 Telegram 服务器。

如果系统配置了全局代理，Moltbot 通常能自动使用。否则可以设置 HTTPS_PROXY 环境变量：

export HTTPS_PROXY=http://127.0.0.1:7890

端口号根据你的代理软件调整。

常见问题

Bot 收不到消息？

检查以下几点：

• Token 是否填写正确（多余的空格或缺少字符都会导致失败）
• 网络是否能连通 Telegram（国内需要代理）
• 终端日志中是否有报错信息

群组里 Bot 不回复？

绝大多数情况是 Privacy Mode 未关闭。按上文步骤操作，关闭后需将 Bot 移出群组再重新添加。

配对码在哪看？

启动 moltbot start 后查看终端输出。向 Bot 发送第一条消息时会显示配对码。如果终端内容较多，也可以查看日志文件。

想换一个 Bot？

在 BotFather 中创建新的 Bot，获取新 Token 后替换旧的即可。旧 Bot 无需额外处理。