> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ruapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 用大模型做 Telegram 机器人(Claude/GPT)

> 半小时搭一个通过大模型回复的 Telegram 机器人。Python,代码可直接复制。

Telegram 机器人大概是把大模型交到用户手里最快的方式:不用做网站,也不用做 App,打开聊天框直接输入就行。下面是从空文件夹到一个可用机器人的完整流程——它用你的 RuAPI 密钥,通过 Claude 或 GPT 来回复。代码不多,可以整段复制。

我们使用 RuAPI 的 OpenAI 兼容协议:只换 `base_url`,同一个 `openai` SDK 就能调用 Claude、GPT、Gemini 和 DeepSeek。

<Steps>
  <Step title="准备工作">
    * **RuAPI 密钥** —— `sk-...`。在控制台创建:**「令牌」** → **「创建令牌」**。余额用 USDT 充值,见[充值](/zh/topup)。
    * **Python 3.10+** —— 用 `python --version` 检查。
    * **Telegram 机器人 token** —— 下一步获取。
  </Step>

  <Step title="在 Telegram 里创建机器人">
    在 Telegram 中打开 [@BotFather](https://t.me/BotFather),发送 `/newbot`。BotFather 会询问机器人的名称和用户名(必须以 `bot` 结尾),然后回复一个 **HTTP API token**——形如 `123456789:AAH...` 的字符串。把它复制下来,后面要用。

    <Warning>
      机器人 token 相当于密码。不要把它写进代码、仓库或截图里。如果不小心泄露了,
      给 BotFather 发 `/revoke` 重新生成。
    </Warning>
  </Step>

  <Step title="安装依赖">
    ```bash theme={null}
    pip install python-telegram-bot openai
    ```

    `python-telegram-bot` 21+ 是一个异步的 Telegram 框架。`openai` 是我们要指向 RuAPI 的客户端。
  </Step>

  <Step title="编写机器人">
    创建文件 `bot.py`。这是一个可直接运行的最小机器人:每收到一条文本消息,就把内容发给模型,并用模型的回复作答。

    ```python bot.py theme={null}
    import os

    from openai import OpenAI
    from telegram import Update
    from telegram.ext import (
        ApplicationBuilder,
        ContextTypes,
        MessageHandler,
        filters,
    )

    # 从环境变量读取密钥——不要把机密硬编码进代码。
    TELEGRAM_TOKEN = os.environ["TELEGRAM_TOKEN"]
    RUAPI_KEY = os.environ["RUAPI_KEY"]

    # 指向 RuAPI 的 OpenAI SDK 客户端(OpenAI 兼容协议)。
    client = OpenAI(
        api_key=RUAPI_KEY,
        base_url="https://www.ruapi.ai/v1",
    )


    async def handle_message(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
        user_text = update.message.text

        response = client.chat.completions.create(
            model="claude-opus-4-8",  # 准确的模型名见主站定价页
            messages=[{"role": "user", "content": user_text}],
        )
        answer = response.choices[0].message.content

        await update.message.reply_text(answer)


    def main() -> None:
        app = ApplicationBuilder().token(TELEGRAM_TOKEN).build()
        app.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, handle_message))
        app.run_polling()


    if __name__ == "__main__":
        main()
    ```

    <Note>
      示例用的模型是 `claude-opus-4-8`。同一个密钥还能调用其他模型:`gpt-5.4`、
      `gemini-3.5-flash`、`deepseek-v4-pro` 等等。准确的名称见主站\*\*「定价」\*\*页面。
    </Note>
  </Step>

  <Step title="运行">
    通过环境变量传入两个 token,然后运行脚本:

    ```bash theme={null}
    export TELEGRAM_TOKEN="123456789:AAH..."
    export RUAPI_KEY="sk-你的密钥"
    python bot.py
    ```

    机器人会安静地启动并开始监听消息(`run_polling` 会轮询 Telegram)。在 Telegram 里按用户名找到机器人,随便发点什么,它就会通过大模型回复。按 `Ctrl+C` 停止。
  </Step>

  <Step title="进阶改进">
    最小版机器人没有记忆,每条消息都是从头作答。几个可以拓展的方向:

    * **对话历史。** 按 `chat_id` 保存消息历史(例如存进 `context.chat_data`),把整个列表传给 `messages=[...]`,机器人就能记住之前的对话。
    * **系统提示词。** 在首位加上 `{"role": "system", "content": "你是一个友好的助手……"}`,用来设定语气和角色。
    * **/start 命令。** 加一个带欢迎语的 `CommandHandler("start", ...)`,让机器人更友好。
    * **切换模型。** 修改 `model` 字段即可切到 GPT 或 Gemini。
    * **高并发更省钱。** 消息量大时,换成更实惠的模型——`gemini-3.5-flash` 或 `deepseek-v4-pro`。聊天场景下效果很好,余额消耗明显更低。
    * **流式回复。** 长回答让用户干等很难受,改用[流式输出](/zh/streaming)逐段发回去,机器人会显得更灵敏。
  </Step>
</Steps>

## 出问题了怎么办

<AccordionGroup>
  <Accordion title="机器人没反应,不回复消息">
    检查机器人 token 是否完整复制、有没有多余空格,以及脚本是否真在运行
    (`run_polling` 应处于工作状态,终端窗口没关闭)。确认你发消息的正是在
    BotFather 创建的那个机器人。报错会打印在终端里,去那里看。
  </Accordion>

  <Accordion title="401(Unauthorized)错误">
    问题出在 **RuAPI** 密钥上,而不是机器人 token。检查 `RUAPI_KEY`——它应以
    `sk-` 开头。可以在控制台\*\*「令牌」\*\*页面查看密钥。
  </Accordion>

  <Accordion title="402(Payment Required)错误">
    余额用完了。用 USDT 充值,见[充值](/zh/topup)。
  </Accordion>
</AccordionGroup>

## 下一步

* [快速开始](/zh/quickstart) —— API 与 `base_url` 的基础用法。
* [错误处理](/zh/errors) —— 各个返回码的含义。
* 有问题?[support@ruapi.ai](mailto:support@ruapi.ai)