用 Python 打造你的第一个 Telegram 机器人：超详细教程

用 Python 构建自定义 Telegram 机器人，能为你带来极大的灵活性和强大功能。无论你是想自动化任务、创建互动服务，还是仅仅想探索 Telegram 强大的 API，Python 都是一个绝佳的选择，因为它简单易学且拥有丰富的库支持。在这份详尽的指南中，我们将手把手教你完成第一个 Telegram 机器人 Python 项目的整个过程，从搭建开发环境到编写功能代码，再到最终部署你的机器人。

Python 的可读性以及 python-telegram-bot 库活跃的社区支持，使其成为初学者和经验丰富的开发者入门的绝佳选择。学完本教程，你将拥有一个功能齐全的 Telegram 机器人，随时可以与用户互动。

核心要点

• 你将学会如何使用 BotFather 注册机器人并获取 API 令牌。
• 我们将介绍如何设置 Python 开发环境并安装必要的库。
• 你将编写代码来处理基本的命令和消息。
• 我们将探讨如何为你的机器人添加更复杂的功能。
• 你将了解部署 Telegram 机器人 Python 应用的基础知识。

1. 设置你的 Telegram 机器人和开发环境

在深入编写代码之前，你需要先在 Telegram 上设置你的机器人，并准备好 Python 环境。

1.1 使用 BotFather 创建你的机器人

任何 Telegram 机器人的第一步都是使用 BotFather 进行注册，它是 Telegram 官方用于管理其他机器人的机器人。

1. 打开 Telegram 并搜索 @BotFather： 在你的 Telegram 应用中，搜索 “@BotFather” 并开始聊天。请确保是带有蓝色认证徽章的官方 BotFather。
2. 开始创建机器人流程： 输入 /newbot 并发送消息。
3. 选择一个名称： BotFather 会要求你为机器人取一个名称。这是用户将看到的易读标题（例如，“我的超棒机器人”）。
4. 选择一个用户名： 接下来，为你的机器人选择一个独一无二的用户名。这个用户名必须以“bot”结尾（例如，my_awesome_bot）。如果用户名已被占用，BotFather 会要求你尝试另一个。
5. 获取你的 API 令牌： 成功后，BotFather 会提供一个 HTTP API 令牌。这个令牌至关重要，它就像你机器人的密码。请务必妥善保管，切勿公开分享。 它看起来会像 123456:ABC-DEF1234ghIkl-zyx57W23L1qR_456。

1.2 安装 Python 和 pip

如果你尚未安装 Python，请从官方 Python 网站 (https://www.python.org/downloads/) 下载最新稳定版本。安装时，请务必勾选“Add Python to PATH”选项，以便更方便地在命令行中使用。

pip 是 Python 的包管理器，通常随 Python 一起预装。你可以通过打开终端或命令提示符并输入以下命令来验证 Python 和 pip 的安装：

python --version
pip --version

1.3 安装 python-telegram-bot 库

python-telegram-bot 库是一个流行且强大的 Telegram Bot API 封装库。它简化了与 API 的交互，让开发机器人变得更加容易。

使用 pip 安装它：

pip install python-telegram-bot

现在你已经成功设置了你的机器人和开发环境。接下来，让我们开始编写代码吧！

2. 你的第一个 Telegram 机器人 Python 代码：回声机器人

我们将从一个经典案例开始：一个回声机器人。这个机器人只会简单地重复它收到的任何消息。这个简单的例子将教会你处理消息的核心概念。

2.1 导入必要的模块

创建一个新的 Python 文件（例如 my_telegram_bot.py），然后开始导入 telegram 库中所需的组件。

from telegram import Update
from telegram.ext import Application, CommandHandler, MessageHandler, filters
import logging
import os

• Update: 代表来自 Telegram 的传入更新（例如，新消息、命令）。
• Application: 管理机器人生命周期的主类。
• CommandHandler: 用于注册特定命令（例如 /start, /help）的处理程序。
• MessageHandler: 用于注册各种类型消息（文本、照片等）的处理程序。
• filters: 提供方便的过滤器，用于指定 MessageHandler 应该响应哪些消息。
• logging: 用于调试和理解机器人行为的良好实践。
• os: 用于安全地从环境变量加载你的 API 令牌。

2.2 设置日志记录

日志记录对于故障排除至关重要。将以下行添加到你的脚本中：

# Enable logging
logging.basicConfig(
    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s", level=logging.INFO
)
logger = logging.getLogger(__name__)

2.3 定义我们的处理程序

处理程序是处理传入更新的函数。

start 命令处理程序：

当用户发送 /start 命令时，将调用此函数。

async def start(update: Update, context):
    """Sends a welcome message when the command /start is issued."""
    user = update.effective_user
    await update.message.reply_html(
        f"Hi {user.mention_html()}! I'm an echo bot. Send me anything!",
        # reply_markup=ForceReply(selective=True), # Optional: force reply to this message
    )

echo 消息处理程序：

此函数将回显它收到的任何文本消息。

async def echo(update: Update, context):
    """Echoes the user message."""
    await update.message.reply_text(update.message.text)

help_command 处理程序：

一个简单的帮助命令。

async def help_command(update: Update, context):
    """Sends a help message."""
    await update.message.reply_text("Send me any message, and I'll echo it back!")

2.4 main 函数：将所有功能整合在一起

main 函数是我们初始化机器人、注册处理程序并开始轮询更新的地方。

def main() -> None:
    """Start the bot."""
    # Get the API token from environment variables (BEST PRACTICE!)
    # Alternatively, you can hardcode it here for quick testing: TOKEN = "YOUR_TELEGRAM_BOT_TOKEN"
    TOKEN = os.environ.get("TELEGRAM_BOT_TOKEN")

    if not TOKEN:
        raise ValueError("TELEGRAM_BOT_TOKEN environment variable not set.")

    # Create the Application and pass it your bot's token.
    application = Application.builder().token(TOKEN).build()

    # Register handlers
    application.add_handler(CommandHandler("start", start))
    application.add_handler(CommandHandler("help", help_command))
    application.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, echo))

    # Run the bot until the user presses Ctrl-C
    application.run_polling(allowed_updates=Update.ALL_TYPES)


if __name__ == "__main__":
    main()

2.5 在本地运行你的机器人

1. 将你的 API 令牌设置为环境变量：

   • Linux/macOS: export TELEGRAM_BOT_TOKEN="YOUR_API_TOKEN_HERE"
   • Windows (命令提示符): set TELEGRAM_BOT_TOKEN="YOUR_API_TOKEN_HERE"
   • Windows (PowerShell): $env:TELEGRAM_BOT_TOKEN="YOUR_API_TOKEN_HERE" 或者，为了快速本地测试，你可以直接在代码中用你的实际令牌字符串替换 os.environ.get("TELEGRAM_BOT_TOKEN")（例如，TOKEN = "123456:ABCDEF..."），但不建议在生产环境中使用。

2. 运行你的 Python 脚本： 在终端中导航到你保存 my_telegram_bot.py 的目录，然后运行：

   python my_telegram_bot.py

3. 与你的机器人互动： 打开 Telegram，搜索你的机器人用户名（例如 @my_awesome_bot），然后开始聊天。尝试发送 /start、/help 或任何文本消息。你的机器人应该会回复！

恭喜！你刚刚创建并运行了你的第一个 Telegram 机器人 Python 应用。

3. 添加更多高级功能

回声机器人很酷，但让我们让它更有用。以下是扩展你的 Telegram 机器人的一些想法。

3.1 处理不同类型的消息

除了纯文本，Telegram 还支持照片、视频、文档等等。你可以使用 filters 来专门处理这些类型。

示例：响应照片

async def handle_photo(update: Update, context):
    """Responds to a photo with a confirmation message."""
    # You can access photo details via update.message.photo
    # The list contains different sizes of the same photo; the last one is usually the largest.
    photo_file_id = update.message.photo[-1].file_id
    await update.message.reply_text("Nice photo! I received it.")

# Add this handler in your main function
# application.add_handler(MessageHandler(filters.PHOTO, handle_photo))

3.2 使用内联键盘和回复键盘

键盘为用户提供了结构化的交互选项。

• 回复键盘 (Reply Keyboards)： 出现在消息输入字段上方，有效地取代了标准键盘。非常适合预定义的选择。
• 内联键盘 (Inline Keyboards)： 直接附加到消息上，按钮可以触发回调或打开 URL。是交互式菜单的理想选择。

示例：内联键盘

让我们修改 /start 命令来提供按钮。

from telegram import Update, InlineKeyboardButton, InlineKeyboardMarkup
from telegram.ext import Application, CommandHandler, MessageHandler, CallbackQueryHandler, filters
# ... (other imports and logging) ...

async def start(update: Update, context):
    """Sends a welcome message with an inline keyboard."""
    user = update.effective_user
    keyboard = [
        [InlineKeyboardButton("Visit TeleClaw", url="https://teleclaw.bot")],
        [InlineKeyboardButton("About Bot", callback_data="about")],
    ]
    reply_markup = InlineKeyboardMarkup(keyboard)
    await update.message.reply_html(
        f"Hi {user.mention_html()}! Welcome to my bot. What would you like to do?",
        reply_markup=reply_markup,
    )

async def button_callback(update: Update, context):
    """Handles callback queries from inline keyboard buttons."""
    query = update.callback_query
    await query.answer() # Always answer callback queries

    if query.data == "about":
        await query.edit_message_text(text="This is a simple demo bot created with Python and the `python-telegram-bot` library.")
    # Add more conditions for other callback_data values

你需要更新你的 main 函数以包含 CallbackQueryHandler：

    # ... inside main() ...
    application.add_handler(CommandHandler("start", start))
    application.add_handler(CallbackQueryHandler(button_callback)) # Add this line
    application.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, echo))
    # ...

这展示了如何链接到像 TeleClaw 这样的外部网站，并在机器人内部执行操作。你可以在 python-telegram-bot 文档中了解更多关于不同键盘选项的信息 (https://docs.python-telegram-bot.org/en/stable/telegram.keyboardbutton.html)。

3.3 与外部 API 集成

Telegram 机器人 Python 开发的真正强大之处在于它能够与第三方服务集成。你可以获取天气数据、最新新闻、翻译文本，甚至与 AI 模型集成。

示例：简单的 API 调用（使用 requests 库）

首先，安装 requests：pip install requests。

import requests

async def get_fact(update: Update, context):
    """Fetches a random fact from an external API."""
    try:
        response = requests.get("https://uselessfacts.jsph.pl/api/v2/facts/random")
        response.raise_for_status() # Raise an HTTPError for bad responses (4xx or 5xx)
        fact_data = response.json()
        await update.message.reply_text(f"Did you know? {fact_data['text']}")
    except requests.exceptions.RequestException as e:
        logger.error(f"Error fetching fact: {e}")
        await update.message.reply_text("Sorry, I couldn't fetch a fact right now. Please try again later.")

# Add this command handler:
# application.add_handler(CommandHandler("fact", get_fact))

这展示了机器人如何与外部数据源交互，就像 @claw 集成各种服务以提供复杂功能一样。对于更高级的 AI 交互，可以考虑使用 TeleClaw 等平台，它们抽象了与 GPT-4 或 Gemini 等模型集成的复杂性。你可以在我们关于如何构建 Telegram 聊天机器人的文章中阅读更多关于集成 AI 工具的信息。

4. 持久化数据和状态管理

对于更复杂的机器人，你需要一种在交互之间存储数据的方法。例如，如果你的机器人需要记住用户偏好或正在进行的对话。

4.1 使用 context.user_data 和 context.chat_data

python-telegram-bot 库提供了 context.user_data 和 context.chat_data 字典（在你的处理程序函数中可用），它们可以存储与用户或聊天相关的临时数据。这些数据在机器人运行期间持续存在。

async def set_favorite_color(update: Update, context):
    """Allows users to set their favorite color."""
    if context.args:
        color = " ".join(context.args).strip()
        context.user_data["favorite_color"] = color
        await update.message.reply_text(f"Okay, I've noted your favorite color as {color}.")
    else:
        await update.message.reply_text("Please tell me your favorite color, e.g., /setcolor blue")

async def get_favorite_color(update: Update, context):
    """Tells the user their favorite color."""
    color = context.user_data.get("favorite_color")
    if color:
        await update.message.reply_text(f"Your favorite color is {color}.")
    else:
        await update.message.reply_text("I don't know your favorite color yet. Use /setcolor.")

# Add these handlers:
# application.add_handler(CommandHandler("setcolor", set_favorite_color))
# application.add_handler(CommandHandler("getcolor", get_favorite_color))

4.2 跨重启持久化数据

为了让数据在机器人脚本重启后仍然存在，你需要一个更健壮的解决方案，例如：

• 文件 (CSV, JSON)： 适用于少量数据。
• 数据库 (SQLite, PostgreSQL, MongoDB)： 推荐用于更大、更复杂的数据存储。SQLite 是本地开发的好选择，因为它基于文件，无需单独的服务器。
• 第三方存储解决方案： 像 Firestore 或 DynamoDB 这样的云数据库。

python-telegram-bot 库还提供了 BasePersistence 类，可以与 PicklePersistence 或 DictPersistence 一起使用，将 user_data、chat_data 和 bot_data 保存到文件中。请参阅官方 python-telegram-bot 示例，了解如何使用持久化 (https://docs.python-telegram-bot.org/en/stable/telegram.ext.basepersistence.html)。

5. 部署考量

在本地机器上运行机器人进行开发是没问题的，但要让它 24/7 可用，你需要将其部署到服务器上。

5.1 轮询 vs. Webhooks

Telegram 机器人接收更新主要有两种方式：

• 长轮询 (Long Polling)： 你的机器人反复向 Telegram 服务器请求新更新。这就是我们使用 application.run_polling() 的方式。设置简单，但对于非常活跃的机器人来说，可能会消耗大量资源。
• Webhooks： 你告诉 Telegram 你的服务器 URL。当发生更新时，Telegram 会向该 URL 发送一个 HTTP POST 请求。对于生产环境来说更高效，但需要一个可公开访问的服务器和处理 HTTPS。

对于简单的机器人和初始开发，长轮询就足够了。对于生产环境，通常更推荐使用 Webhooks。python-telegram-bot 库同时支持这两种方式。

5.2 部署平台

有几个平台适合部署 Python 机器人：

• Heroku： 非常适合中小型项目，提供免费套餐。使用 git 部署非常简单。
• Render： 类似于 Heroku，但通常提供更慷慨的免费套餐和现代功能。
• AWS (EC2, Lambda), Google Cloud (Compute Engine, Cloud Functions), Azure (App Service, Functions)： 提供强大、可扩展的解决方案，但学习曲线较陡峭。
• 虚拟专用服务器 (VPS)： 像 DigitalOcean、Linode、Vultr 这样的服务为你提供更多控制权，但你需要负责服务器管理。

部署时，请记住：

• 保护你的 API 令牌： 使用环境变量。
• 安装依赖项： 创建一个 requirements.txt 文件（pip freeze > requirements.txt），并确保你的主机安装了它们。
• 配置进程管理器： 像 systemd 或 pm2 这样的工具可以确保你的机器人在崩溃时也能继续运行。

对于商业应用或高度可扩展的 AI 驱动机器人，像 TeleClaw 这样的平台提供了健壮、托管的环境。它们处理基础设施、安全和扩展，让你能够专注于机器人的逻辑和用户体验。查看我们关于企业级 Telegram 机器人的详细指南，了解 TeleClaw 提供的功能。

总结

现在你已经掌握了构建 Telegram 机器人 Python 应用的核心原理。从使用 BotFather 进行初始设置和环境配置，到编写命令和消息处理程序，处理不同数据类型，以及考虑部署策略，你已经打下了坚实的基础。python-telegram-bot 库让与 Telegram API 的交互变得出奇地简单，为自动化和交互开启了无限可能。

随着你越来越熟练，你可以探索更高级的主题，例如：

• 使用 ConversationHandler 处理对话。
• 错误处理和健壮的日志记录。
• 与数据库集成以进行复杂的数据存储。
• 利用更高级的 filters。
• 实现内联模式以实现全局搜索功能。

请记住，Telegram 的开放性和 Python 的多功能性之美在于，你几乎可以构建任何东西。如果你希望在没有繁重编码负担的情况下，通过尖端 AI、自然语言理解或无缝集成来提升你的机器人，那么像 TeleClaw 这样的平台就是为你量身定制的。

准备好构建、增强或管理你的 Telegram 机器人，并实现智能自动化了吗？

立即探索 TeleClaw，为你的 Telegram 机器人注入超能力！ 或直接在 Telegram 上尝试我们的机器人：@claw