Telegram-WSP

Неофициальный форк Telegram для Android со встроенным TgWsProxy: прокси работает внутри клиента и не требует отдельного приложения или собственного VPS. Проект сохраняет Telegram максимально близким к upstream и не изменяет TMessagesProj/jni/tgnet/.

Быстрый старт · Документация · Релизы · Обратная связь

О проекте

Telegram-WSP встраивает TgWsProxy непосредственно в Telegram Android. Приложение поднимает локальный proxy runtime на 127.0.0.1:1443 и подключает его через штатный proxy API Telegram.

Цель проекта — дать обычный Telegram-клиент с WebSocket/Cloudflare-маршрутами и резервными вариантами соединения без отдельного TgWsProxy-приложения и без переноса собственного transport-кода в Telegram networking.

Проект построен как воспроизводимый overlay поверх DrKLO/Telegram. Полный исходный код Telegram в репозитории не хранится: нужный upstream checkout загружается по закреплённому commit.

Принципы интеграции

Главный принцип Telegram-WSP — минимально изменять оригинальный Telegram. Интеграция вынесена в отдельный overlay, не меняет TMessagesProj/jni/tgnet/ и на текущем pinned upstream затрагивает только ограниченный набор source-level путей.

Telegram-WSP использует собственные название, package ID, launcher icon и release-подпись, чтобы не выдавать себя за официальный клиент. Проект является независимым неофициальным форком Telegram for Android.

Статус проекта

Стадия: Stable.

Текущий публичный релиз: v13.1.1-wsp.3 (31 октября 2026 года).

Компонент	Текущее состояние
Telegram upstream	13.1.1, build 7237
Telegram commit	`3de37c8cfb039452be7398909461da6288babf15`
tgwsproxy-core commit	`515fc50af9797c69722f14409dedcaf96868d9ce`
Android package	`org.telegram.messenger.web`
Встроенный TgWsProxy	Работает через локальный listener
Экран управления прокси	Встроен в настройки прокси Telegram
Подписанный APK	Публикуется через GitHub Releases
Автообновление приложения	Реализовано через GitHub Releases
Upstream sync	Автоматическая проверка DrKLO/Telegram с integration gates

Релиз v13.1.1-wsp.3 сохраняет экран управления маршрутами, Cloudflare-домены, WARP/AmneziaWG-профиль и Worker pools. В этой ревизии обновлены обработка полного исчерпания CF domain pool, отмена устаревших попыток CF dial/TLS при смене маршрута, обработка ошибок WebSocket/TLS и Worker transport/failover. Версия Telegram upstream остаётся 13.1.1 (7237). Подписанный APK, контрольные суммы и точные исходные компоненты доступны в релизе. Подробности: на русском и на английском.

Возможности

встроенный TgWsProxy runtime без отдельного Android-приложения;
локальный MTProto proxy на 127.0.0.1:1443;
использование штатного ConnectionsManager.setProxySettings(...) без патчей Telegram tgnet;
режимы маршрутизации Auto / Cloudflare Proxy / WARP-AmneziaWG / Cloudflare Worker / Direct;
разные цепочки Auto для Wi-Fi и мобильной сети;
ввод, обновление и проверка списка Cloudflare-доменов;
создание, импорт, экспорт и удаление WARP/AmneziaWG-профиля;
независимые списки Worker для Proxy Worker и Amnezia provisioning Worker;
локализация встроенного интерфейса для локалей текущей версии Telegram;
собственные название, launcher icon, package ID и постоянная release-подпись;
встроенная проверка обновлений через GitHub Releases;
проверка скачанного APK по SHA-256, package ID и signing certificate;
автоматическая проверка новых Telegram version/build с валидацией integration overlay;
публикация Corresponding Source для каждого публичного APK.

Быстрый старт

Скачайте последний Telegram-WSP-release.apk.
Разрешите Android устанавливать приложения из выбранного источника, если система запросит это.
Установите APK и запустите Telegram-WSP.
Войдите в Telegram как в обычном клиенте.
При необходимости откройте штатные настройки прокси Telegram и выберите нужный режим маршрутизации.

Для базового сценария отдельное приложение TgWsProxy на устройстве не требуется.

Требования

Для готового APK:

Для текущей Telegram 13.1.1: Android 6.0 / API 23 или новее (итоговый minimumSdk также публикуется в latest.json);
доступ в интернет;
разрешение Android на установку APK не из магазина.

Для сборки из исходников используются JDK 17, Go 1.25.x, Android SDK, NDK 27.2.12479018 и Gradle. Точные production-настройки зафиксированы в release.yml.

Установка

Актуальный APK публикуется в GitHub Releases.

Имя пакета:

org.telegram.messenger.web

Telegram-WSP использует постоянный release key. Новая версия устанавливается поверх предыдущей Telegram-WSP-сборки только при совпадении package ID и сертификата подписи.

Если на устройстве уже установлено приложение с тем же package ID, но другой подписью, Android не позволит обновить его поверх существующей установки. Для перехода с v13.1.1-wsp.2 на v13.1.1-wsp.3 удалять приложение не требуется при совпадении подписи. Не удаляйте установленный клиент ради исправления ошибки подписи без сохранения важных локальных данных.

Использование

После запуска Telegram-WSP:

TgWsProxyBootstrap запускает tgwsproxy-core;
core открывает локальный listener 127.0.0.1:1443;
Telegram получает эту конфигурацию через штатный proxy API;
трафик проходит через выбранный маршрут Telegram-WSP.

Если встроенный runtime не запускается, Telegram-WSP не должен произвольно сбрасывать стороннюю proxy-конфигурацию пользователя.

Настройки Cloudflare, WARP/AmneziaWG и Worker pools доступны из встроенного экрана управления прокси.

Режимы работы

Auto

Telegram-WSP выбирает цепочку автоматически в зависимости от типа сети.

Wi-Fi:

Cloudflare Proxy → WARP-AmneziaWG → Cloudflare Worker → Direct

Мобильная сеть:

Cloudflare Proxy → WARP-AmneziaWG → Cloudflare Worker

Direct намеренно не входит в мобильную Auto-цепочку.

Cloudflare Proxy

Использует настроенный список Cloudflare-доменов. Экран управления позволяет изменить список, подтянуть актуальные домены и проверить их доступность.

WARP-AmneziaWG

Использует WARP/AmneziaWG-профиль. Профиль можно создать, импортировать, экспортировать или удалить из интерфейса Telegram-WSP.

Cloudflare Worker

Использует отдельный список Proxy Worker. Список Amnezia provisioning Worker хранится независимо и применяется для соответствующего provisioning-сценария.

Direct

Пытается использовать прямой маршрут без Cloudflare Proxy, AWG и Worker. В Auto этот fallback доступен только для Wi-Fi.

Сеть и прокси

Базовый путь соединения:

Telegram-WSP
     │
     │ штатный Telegram proxy API
     ▼
127.0.0.1:1443
     │
     ▼
tgwsproxy-core
     │
     ├─ Cloudflare Proxy
     ├─ WARP / AmneziaWG
     ├─ Cloudflare Worker
     └─ Direct

Порядок маршрутов задаётся выбранным режимом. Telegram networking видит только локальный proxy endpoint и не содержит реализации transport Telegram-WSP.

Такой подход уменьшает собственный diff и снижает количество конфликтов при обновлении Telegram upstream.

Архитектура

Проект разделён на три уровня:

DrKLO/Telegram
      │
      │ deterministic overlay
      ▼
Telegram integration adapter
      │
      ▼
tgwsproxy-core
      │
      ▼
libtgwsproxy.so

Исходный Telegram checkout загружается по точному commit из config/upstream.json, а tgwsproxy-core — из config/core.json. Generated worktree создаётся в .work/ и не коммитится.

Подробности: docs/architecture.md и integration/README.md.

Безопасность

Публичный APK подписывается постоянным Telegram-WSP release key.

Встроенный updater принимает новую сборку только после проверки:

HTTPS URL из разрешённого GitHub Releases path;
SHA-256 APK;
package ID org.telegram.messenger.web;
того же signing certificate, что у установленного приложения.

Финальную установку выполняет системный Android package installer, поэтому подтверждение пользователя остаётся обязательным.

Release key и Telegram API credentials не хранятся в репозитории. Для GitHub Actions они передаются через repository secrets.

Обновление

Telegram-WSP проверяет:

https://github.com/Regstar2/telegram-wsp/releases/latest/download/latest.json

автоматически не чаще одного раза в 12 часов после успешной проверки. После сетевой ошибки повторная автоматическая попытка допускается через 10 минут; кнопка ручной проверки не зависит от этого интервала.

В интерфейсе «Встроенный прокси» доступны «Проверить обновления Telegram-WSP» и «Открыть релизы Telegram-WSP». Последний пункт открывает официальный GitHub Releases в браузере, если прямой HTTPS-доступ updater отсутствует: локальный MTProto frontend не является HTTP(S)-прокси. Автоматическая проверка возобновляется при возврате Telegram на экран.

Если versionCode новой сборки выше установленного, приложение предлагает обновление (с точным WSP release tag и ссылкой на release notes). После согласия APK скачивается, проверяется и передаётся системному installer.

Нумерация Telegram-WSP учитывает как Telegram build, так и WSP revision:

versionCode = telegramBuild * 1000 + wspRevision * 10 + 9

Поэтому WSP hotfix той же версии Telegram может обновляться поверх предыдущего WSP-релиза.

Автоматическое обновление Telegram upstream

Обновление состоит из двух независимых уровней:

DrKLO/Telegram → Telegram-WSP. Workflow upstream-sync.yml проверяет официальный upstream, обновляет pinned commit, воспроизводит integration overlay и запускает project gates.
Telegram-WSP → устройство. После успешной проверки совместимости release.yml собирает подписанный APK, формирует metadata и Corresponding Source и публикует GitHub Release. Установленное приложение обнаруживает релиз через latest.json.

Если overlay не применяется или проверки не проходят, новая версия Telegram не должна становиться публичным Telegram-WSP-релизом.

Workflow запускается по расписанию без участия пользователя. Если upstream pin уже обновлён, но подписанный stable-релиз ещё не опубликован (например, предыдущий Windows release job завершился ошибкой), следующая проверка повторно запускает release-сборку. Уже существующий stable tag/подписанный APK не перезаписывается; WSP revision наследуется от последней опубликованной стабильной ревизии.

Разработка

Рабочий Telegram checkout и core создаются локально:

git clone https://github.com/Regstar2/telegram-wsp.git
cd telegram-wsp

./scripts/prepare-integration.ps1
./scripts/ci.ps1

Основные конфигурации:

config/upstream.json — pinned Telegram commit и version/build;
config/core.json — pinned tgwsproxy-core;
integration/ — integration/branding layer;
scripts/ — fetch/build/release операции.

Для локальной сборки с собственными Telegram api_id / api_hash используйте environment variables TELEGRAM_API_ID и TELEGRAM_API_HASH либо локальный .work/telegram/local.properties. Credentials нельзя коммитить или публиковать в Issue/PR.

Сборка

Быстрый ARM64 prototype APK:

./scripts/build-apk.ps1

Полная afatStandalone сборка:

./scripts/build-apk.ps1 -Full

Подписанный release APK:

./scripts/build-release.ps1

Результат release-сборки:

dist/Telegram-WSP-release.apk

Создание release key — одноразовая операция:

./scripts/create-release-keystore.ps1

Потеря или замена этого ключа нарушит update compatibility уже установленных сборок.

Production releases собираются на GitHub-hosted Windows runner через release.yml.

Release notes автоматически сравнивают новую сборку с последним опубликованным стабильным релизом: обновление Telegram описывается отдельно, а изменения ядра прокси и кода интеграции WSP указываются только при их наличии. Изменения CI, документации и механизма публикации не считаются изменениями функциональности WSP. Генератор и его регрессионные тесты: write-release-notes.ps1 и test-release-notes.ps1.

Тестирование

Базовые проверки репозитория:

./scripts/ci.ps1

Workflow trusted-ci.yml на pull request:

выполняет repository checks;
воспроизводит Telegram overlay на pinned Telegram 13.1.1 и регрессионном fixture 13.0.3;
повторно запускает проверки на подготовленном worktree и проверяет отказ при несовместимом SDK anchor;
компилирует prototype APK без release-подписи.

Успешный CI не доказывает доступность маршрутов Cloudflare Proxy, AWG и Worker в реальной сети. Подписанный production APK отдельно собирается в release.yml.

Перед публичным релизом production workflow дополнительно выполняет подписанную сборку и проверяет package, branding и APK signature.

Документация

Архитектура — границы Telegram/core и модель минимального diff;
Integration layer — startup path, credentials, branding и build variants;
Исходный MVP scope — исторический план первого прототипа, не перечень всех текущих возможностей;
Релиз WSP 3 (RU) · Release notes (EN) — изменения актуального релиза;
Лицензирование — GPL-модель, third-party компоненты и Corresponding Source;
NOTICE.md — third-party notices.

Точные исходные компоненты каждой публичной сборки прикладываются к GitHub Release вместе с SOURCE_MANIFEST.json и SHA256SUMS.txt.

Если возникла проблема

APK не устанавливается. Проверьте Android 6.0+ для текущего релиза и наличие уже установленного org.telegram.messenger.web с другой подписью. В последнем случае Android не сможет установить обновление поверх него. Сверьте APK и метаданные с официальным релизом; не удаляйте приложение без учёта возможной потери локальных данных.

Нет соединения через Cloudflare Proxy. В настройках «Встроенный прокси» проверьте список доменов и результат их проверки. WSP 3 обрабатывает исчерпание доступного пула, но это не гарантирует наличия рабочего домена в конкретной сети. При необходимости проверьте другой настроенный маршрут (AWG или Worker). В мобильном Auto-режиме Direct отсутствует.

Не удаётся проверить обновления. Updater запрашивает GitHub Releases по обычному HTTPS, а не через локальный MTProto proxy. Откройте «Открыть релизы Telegram-WSP» и попробуйте загрузить APK в браузере, если он доступен через другое соединение. Установка всё равно требует подтверждения Android.

Для ошибки маршрутизации полезно приложить к Issue версию WSP, тип сети (Wi-Fi/мобильная), выбранный маршрут и воспроизводимые действия. Не публикуйте секреты, ключи AWG и приватные конфигурации.

Обратная связь

Ошибки и проблемы совместимости можно сообщать через GitHub Issues.

Для отчёта об ошибке полезно указать:

модель устройства и версию Android;
версию Telegram-WSP;
выбранный режим маршрутизации;
что ожидалось и что произошло;
воспроизводится ли проблема с другим режимом.

Не публикуйте Telegram API credentials, signing keys, access tokens и другие секреты.

Происхождение и благодарности

Telegram-WSP основан на:

DrKLO/Telegram — официальный исходный код Telegram for Android;
Regstar2/tgwsproxy-core — переиспользуемое Android/native ядро;
Regstar2/tg-ws-proxy-android — форк Android-обёртки TgWsProxy и источник ранней Android-интеграции;
amurcanov/tg-ws-proxy-android — исходная Android-обёртка, от которой создан форк;
Flowseal/tg-ws-proxy — первоначальный TgWsProxy/WebSocket runtime.

Происхождение proxy runtime:

Flowseal/tg-ws-proxy
        ↓
amurcanov/tg-ws-proxy-android
        ↓
Regstar2/tg-ws-proxy-android
        ↓
Regstar2/tgwsproxy-core
        ↓
Telegram-WSP

Telegram-WSP является независимым неофициальным форком и не связан с Telegram и не одобрен Telegram.

Ограничения

проект находится на стадии Stable;
поддерживается только Android;
распространение выполняется через GitHub Releases, а не Google Play или RuStore;
доступность конкретного маршрута зависит от сети, Cloudflare-доменов, Worker и WARP/AmneziaWG-конфигурации;
Direct не используется как fallback мобильного Auto-режима;
обновления требуют системного подтверждения установки Android;
совместимость с новой версией Telegram принимается только после успешного применения overlay и CI/release gates;
проект не изменяет и не открывает платные функции Telegram.

Лицензия

Собственный integration/overlay и TgWsProxy-derived combined code распространяются по GNU GPL-3.0-only.

Telegram for Android распространяется по GNU GPL v2 or later; для объединённого клиента используется совместимая GPLv3-модель. Third-party компоненты сохраняют собственные лицензии и notices.

Каждый публичный APK сопровождается точным Corresponding Source использованной сборки.

Полный текст: LICENSE. Подробности: docs/licensing.md.

Navigation Menu

Repository navigation

About

Repository files navigation

Telegram-WSP

О проекте

Принципы интеграции

Статус проекта

Возможности

Быстрый старт

Требования

Установка

Использование

Режимы работы

Auto

Cloudflare Proxy

WARP-AmneziaWG

Cloudflare Worker

Direct

Сеть и прокси

Архитектура

Безопасность

Обновление

Автоматическое обновление Telegram upstream

Разработка

Сборка

Тестирование

Документация

Если возникла проблема

Обратная связь

Происхождение и благодарности

Ограничения

Лицензия

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
config		config
docs		docs
integration		integration
patches		patches
scripts		scripts
.gitignore		.gitignore
LICENSE		LICENSE
NOTICE.md		NOTICE.md
README.md		README.md

Latest commit

History

Folders and files

Repository files navigation

Telegram-WSP

О проекте

Принципы интеграции

Статус проекта

Возможности

Быстрый старт

Требования

Установка

Использование

Режимы работы

Auto

Cloudflare Proxy

WARP-AmneziaWG

Cloudflare Worker

Direct

Сеть и прокси

Архитектура

Безопасность

Обновление

Автоматическое обновление Telegram upstream

Разработка

Сборка

Тестирование

Документация

Если возникла проблема

Обратная связь

Происхождение и благодарности

Ограничения

Лицензия

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages