---
title: "Python Telegram 机器人：配对校验与 Long Polling 实现"
canonical: "https://siyuanailab.com/curation/translations/23c2241314fd608a26ac59506130912d-915e02988b2a819c98a56fe30cc5c025ae392b09dd701ee697a08a2979502e0c/"
dateModified: "2026-11-07"
datePublished: "2026-11-07"
---

[返回日报条目](https://siyuanailab.com/curation/#entry/23c2241314fd608a26ac59506130912d)

 

资料节译

 

# Python Telegram 机器人：配对校验与 Long Polling 实现

 

[阅读原文](https://dev.to/bestaitools-de/wie-man-einen-telegram-bot-baut-der-nur-dir-antwortet-mit-long-polling-in-python-2ao5)

 

现有资料无法确认原文完整，本页只翻译已取得的材料。

 

现有原件无法确认图片是否齐全。

 

Telegram 机器人是一个方便的遥控器，可用来控制自己电脑上的脚本或 AI 智能体。它能在任何手机上使用，不需要专门的应用，也不需要公共服务器。问题在于：机器人是公开的。任何人都能找到它的用户名并给它发消息，而令牌只能证明你的脚本就是这个机器人；它无法说明发信者是谁。osFoundry 桌面应用为其智能体提供了这样一座桥梁，用 Rust 编写（`telegram_bridge.rs`）。下面是同样的设计，用约 70 行纯标准库 Python 实现，并针对本地 Bot API 替身进行了测试；还展示了一个单行错误如何让原本安静的机器人每分钟收到 183.389 个请求。

 

Telegram 通过两种方式传递消息。Webhook 需要一个 Telegram 可以访问的公共 HTTPS URL。`getUpdates`不需要任何外部可访问的设施：脚本会轮询新消息，而借助`timeout=25`，Telegram 会让请求保持打开状态，最长 25 秒，并在有新消息到达时立即响应。在笔记本电脑上，这是合适的选择。不需要打开端口、建立隧道或配置证书。

 

```
import json, os, secrets, time, urllib.parse, urllib.request
API = os.environ.get("TG_API", "https://api.telegram.org")
TOKEN = os.environ["TG_TOKEN"]
LONG_POLL = 25
PAIR_TTL = 600
def call(method, params=None, body=None, timeout=40):
    url = f"{API}/bot{TOKEN}/{method}"
    if params:
        url += "?" + urllib.parse.urlencode(params)
    data = json.dumps(body).encode() if body is not None else None
    req = urllib.request.Request(url, data, {"Content-Type": "application/json"})
    with urllib.request.urlopen(req, timeout=timeout) as r:
        return json.load(r)
def send(chat_id, text):
    call("sendMessage", body={"chat_id": chat_id, "text": text[:3900]})
```

 

HTTP 超时（40 秒）必须长于长轮询的保持时间（25 秒）。如果更短，每个无消息的轮询周期都会以客户端超时结束，看起来就像发生了故障。应用会把令牌存储在操作系统的钥匙串中，而不是文件里。在 Python 中，`keyring.get_password`也能做到同样的事，测试时用一个环境变量就够了。

 

在 60 秒空闲期间，长轮询循环发出了 3 个请求，而每秒一次的短轮询发出了 60 个请求。在本地测试中，当一条消息在请求保持打开期间到达时，机器人在 1.5 到 6.3 毫秒后就作出了响应。实际网络还要加上与 Telegram 通信所需的时间。

 

机器人必须先知道自己为谁服务，才能执行任何操作。应用用一次性代码来完成配对。你在电脑上点击“Pair a phone”，应用会显示八个随机字符，然后你用手机向机器人发送`/pair CODE`。10 分钟内发来有效代码的人就是所有者。

 

```
pending = {}   # code -> created_at
paired = {}    # sender id -> chat id
def begin_pairing():
    code = secrets.token_hex(4).upper()
    pending[code] = time.time()
    return code
```

 

代码来自`secrets`，而不是时间或机器人名称这类可猜测的信息，因为代码是唯一用于授权发信者的凭据。代码在使用时还会被删除，因此只能使用一次。

 

保存的是数字`from.id`，而不是`@username`，也不是显示名称。两者都可以更改，而且被释放的用户名可能会被别人注册。聊天 ID 也会一并保存，原因稍后说明。

 

```
def handle(msg, run_agent):
    text = (msg.get("text") or "").strip()
    sender = msg.get("from", {}).get("id")
    chat = msg["chat"]
    if not text or sender is None:
        return
    words = text.split()
    if words[0] == "/pair" or words[0].startswith("/pair@"):
        if chat.get("type") != "private":
            return send(chat["id"], "Pair with me in a direct message, not in a group.")
        code = words[1].upper() if len(words) > 1 else ""
        created = pending.pop(code, None)
        if created is None or time.time() - created > PAIR_TTL:
            return send(chat["id"], "That code is not valid or has expired.")
        paired[sender] = chat["id"]
        return send(chat["id"], "Paired. Message me and the agent will answer.")
    if text.lower() == "/unpair":
        gone = paired.pop(sender, None) is not None
        return send(chat["id"], "Unpaired." if gone else "You were not paired.")
    if paired.get(sender) != chat["id"] or chat.get("type") != "private":
        return  # silence
    send(chat["id"], run_agent(text))
```

 

三条规则保障安全，每条规则都源于应用源代码中记载的一个具体错误。

 

未知发信者不会收到任何回应。“you are not paired”之类的回复会向陌生人透露，这个机器人连接着某个真实用户的电脑，还会引诱他们继续尝试。不回应看起来就像这个机器人无人管理。

 

只能在私聊中进行配对。机器人一旦被添加到群组，就会收到群组消息；如果在群组里配对，每个成员都能向智能体发送指令。

 

已配对的人只有在完成配对的聊天中才能收到回复。应用的注释提到一个早期版本：它检查了发信者，却回复到了消息发来的聊天中。于是，已配对用户把机器人添加到群组后，智能体就会在该群组里回复，任何人都能在那里控制所有者电脑上的工具。授权依据是发信者，而回复对象是聊天，因此两者都必须一起检查。

 

`/unpair`会在检查聊天之前处理，这样需要撤销访问权限时，就能在当下手边的手机上操作。

 

```
def poll(run_agent):
    offset, failures = 0, 0
    while True:
        try:
            res = call("getUpdates", {"timeout": LONG_POLL, "offset": offset,
                                      "allowed_updates": '["message"]'})
            failures = 0
        except Exception:
            failures += 1
            time.sleep({1: 5, 2: 15, 3: 60}.get(failures, 300))
            continue
        for u in res["result"]:
            offset = max(offset, u["update_id"] + 1)   # even for messages we ignore
            if "message" in u:
                handle(u["message"], run_agent)
```

 

`offset`是脚本用来告知 Telegram 已经看到哪些更新的方式。低于该值的更新都视为已确认并丢弃，大于或等于该值的更新会重新发送。这一行的注释才是关键。很容易让人觉得应该等处理完消息后再移动偏移量，因为这样才像是“处理过了”。但陌生人的消息会被有意忽略，因此不会得到确认；于是下次调用时它会立刻再次出现，因为有一条待处理的更新，而 Telegram 没有理由继续让请求保持打开。

 

退避机制针对的是另一种错误：被撤销或输入错误的令牌会让每个请求都失败，而以全速重试，就意味着永远每隔几秒收到一次 401。5、15、60 然后 300 秒的递增间隔，就是应用采用的策略。

 

本地替身实现了`getUpdates`（偏移量确认和超时保持时间）以及`sendMessage`，并记录每次调用。在每个场景中，都会先注入一条消息，然后读取机器人发回的内容。

 

| 消息 | 回复 |
| --- | --- |
| 陌生人：“hi” | 无 |
| 陌生人：`/pair 12345678` | 该代码无效或已过期。 |
| 我，在群组中：`/pair CODE` | 请通过私聊与我配对，不要在群组中操作。 |
| 我，在私聊中：`/pair code`（小写） | 已配对。 |
| 陌生人，重复使用我的代码 | 该代码无效或已过期。 |
| 我，在私聊中：一个问题 | 智能体的回答 |
| 我，在群组中：一个问题 | 无 |
| 我：`/unpair`，然后提问 | 未配对。，然后无 |

 

接着运行了四个循环，各自连接一个替身，持续 60 秒：

 

| 循环 | 60 秒内的 getUpdates 调用次数 |
| --- | --- |
| 长轮询，无消息 | 3 |
| 每秒一次短轮询，无消息 | 60 |
| 一条陌生人消息，每次更新都前移偏移量 | 4 |
| 一条陌生人消息，只在处理消息时前移偏移量 | 183.389 |

 

在由同一台电脑响应的替身上，这个错误以每秒约 3,000 个请求的速度运行。面对真实 API 时，循环会以网络延迟允许的速度运行，并在每次调用时重新收到同一条陌生人发来的“hi”，而不会收到任何更新的内容。只要有一条来自你永远不会回复的人的消息，就足以触发这个问题。

 

真正的桥梁还必须把回复控制在 Telegram 4,096 个字符的限制内（应用会在 3,900 个字符处截断，并遵循字符边界，因为按字节截断可能会切到日文字符中间），并以纯文本发送回复。如果使用 Markdown，星号或下划线不成对时，Telegram 会拒绝整条消息；而智能体写出`snake_case`代码时，恰好就可能造成这种情况。最重要的是：传入的文本来自拿着手机的人，因此应像电子邮件一样，作为不可信输入交给智能体。配对决定谁可以与智能体交谈；它并不能保证对方说的内容是安全的。

 

[osFoundry](https://osfoundry.io/de)桌面应用为其[AI 智能体](https://osfoundry.io/de/features/agents)提供了这座桥梁：在 Device → Background 中设置令牌，并在某个频道的 Agents 面板中点击“Pair a phone”。它可以在[osFoundry 下载页面](https://osfoundry.io/de/download)免费下载。

 

AI 翻译；具体表述请与原文对照。
