feat(telegram): add dedicated proxy configuration

astrbot/core/config/default.py

@@ -450,6 +450,7 @@
                         "type": "telegram",
                         "enable": True,
                         "telegram_token": "your_bot_token",
+                        "telegram_proxy": "",
                         "start_message": "Hello, I'm AstrBot!",
                         "telegram_api_base_url": "https://api.telegram.org/bot",
                         "telegram_file_base_url": "https://api.telegram.org/file/bot",
@@ -673,7 +674,12 @@
                     "telegram_token": {
                         "description": "Bot Token",
                         "type": "string",
-                        "hint": "如果你的网络环境为中国大陆，请在 `其他配置` 处设置代理或更改 api_base。",
+                        "hint": "在此处填入你的 Telegram Bot Token",
+                    },
+                    "telegram_proxy": {
+                        "description": "Telegram 代理地址",
+                        "type": "string",
+                        "hint": "可选的代理地址，如 http://ip:port 或 socks5://ip:port。仅 Telegram 适配器使用，留空则回退到全局代理设置。",
                     },
                     "mattermost_url": {
                         "description": "Mattermost URL",

astrbot/core/platform/sources/telegram/tg_adapter.py

@@ -130,13 +130,18 @@ def __init__(
         )  # max seconds - hard cap to prevent indefinite delay
 
     def _build_application(self) -> None:
-        self.application = (
+        builder = (
             ApplicationBuilder()
             .token(self.config["telegram_token"])
             .base_url(self.base_url)
             .base_file_url(self.file_base_url)
-            .build()
         )
+        proxy = self.config.get("telegram_proxy")
+        if proxy:
+            # getUpdates long-polling uses a separate request pool, so .proxy()
+            # alone would leave polling on a direct connection.
+            builder = builder.proxy(proxy).get_updates_proxy(proxy)
+        self.application = builder.build()
         message_handler = TelegramMessageHandler(
             filters=filters.ALL,
             callback=self.message_handler,

dashboard/src/i18n/locales/en-US/features/config-metadata.json

@@ -600,9 +600,13 @@
         "description": "Telegram Polling Restart Delay",
         "hint": "Waiting time in seconds when the polling loop needs to restart after unexpected exits. Defaults to 5s."
       },
+      "telegram_proxy": {
+        "description": "Telegram Proxy URL",
+        "hint": "Optional proxy URL, e.g. http://ip:port or socks5://ip:port. Used only by the Telegram adapter; falls back to the global proxy settings when empty."
+      },
       "telegram_token": {
         "description": "Bot Token",
-        "hint": "If you are in mainland China, set a proxy or change api_base in Other Settings."
+        "hint": "Enter your Telegram Bot Token here."
       },
       "mattermost_url": {
         "description": "Mattermost URL",

dashboard/src/i18n/locales/ru-RU/features/config-metadata.json

@@ -596,9 +596,13 @@
                 "description": "Интервал автообновления команд Telegram",
                 "hint": "Интервал автоматического обновления команд Telegram в секундах."
             },
+            "telegram_proxy": {
+                "description": "Proxy URL для Telegram",
+                "hint": "Формат: http://ip:port или socks5://ip:port. Используется только адаптером Telegram. Если поле пустое, применяются глобальные настройки прокси."
+            },
             "telegram_token": {
                 "description": "Токен бота",
-                "hint": "Если вы находитесь в материковом Китае, установите прокси или измените api_base в разделе «Другие настройки»."
+                "hint": "Введите сюда токен вашего Telegram-бота."
             },
             "mattermost_url": {
                 "description": "URL Mattermost",

dashboard/src/i18n/locales/zh-CN/features/config-metadata.json

@@ -602,9 +602,13 @@
         "description": "Telegram 轮询重启延迟",
         "hint": "当轮询意外结束尝试自动重启时的延迟时间，单位为秒。默认为 5s。"
       },
+      "telegram_proxy": {
+        "description": "Telegram 代理地址",
+        "hint": "可选的代理地址，如 http://ip:port 或 socks5://ip:port。仅 Telegram 适配器使用，留空则回退到全局代理设置。"
+      },
       "telegram_token": {
         "description": "Bot Token",
-        "hint": "如果你的网络环境为中国大陆，请在 `其他配置` 处设置代理或更改 api_base。"
+        "hint": "在此处填入你的 Telegram Bot Token"
       },
       "mattermost_url": {
         "description": "Mattermost URL",

tests/test_telegram_adapter.py

@@ -465,3 +465,55 @@ async def final_start_polling(*args, **kwargs):
     app_two.shutdown.assert_awaited()
     app_three.initialize.assert_awaited()
     app_three.start.assert_awaited()
+
+
+@pytest.mark.asyncio
+async def test_telegram_proxy_is_applied_to_bot_api_and_polling_requests():
+    TelegramPlatformAdapter = _load_telegram_adapter()
+    module_globals = TelegramPlatformAdapter.__init__.__globals__
+    proxy_url = "http://127.0.0.1:7890"
+
+    builder = MagicMock()
+    builder.token.return_value = builder
+    builder.base_url.return_value = builder
+    builder.base_file_url.return_value = builder
+    builder.proxy.return_value = builder
+    builder.get_updates_proxy.return_value = builder
+
+    with patch.dict(
+        module_globals,
+        {"ApplicationBuilder": MagicMock(return_value=builder)},
+    ):
+        TelegramPlatformAdapter(
+            make_platform_config("telegram", telegram_proxy=proxy_url),
+            {},
+            asyncio.Queue(),
+        )
+
+    builder.proxy.assert_called_once_with(proxy_url)
+    builder.get_updates_proxy.assert_called_once_with(proxy_url)
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("telegram_proxy", [None, ""])
+async def test_telegram_proxy_is_skipped_when_not_configured(telegram_proxy):
+    TelegramPlatformAdapter = _load_telegram_adapter()
+    module_globals = TelegramPlatformAdapter.__init__.__globals__
+
+    builder = MagicMock()
+    builder.token.return_value = builder
+    builder.base_url.return_value = builder
+    builder.base_file_url.return_value = builder
+
+    with patch.dict(
+        module_globals,
+        {"ApplicationBuilder": MagicMock(return_value=builder)},
+    ):
+        TelegramPlatformAdapter(
+            make_platform_config("telegram", telegram_proxy=telegram_proxy),
+            {},
+            asyncio.Queue(),
+        )
+
+    builder.proxy.assert_not_called()
+    builder.get_updates_proxy.assert_not_called()