Локальный прокси для Telegram на Android с MTProto- и SOCKS5-frontend и маршрутизацией через Cloudflare Proxy, прямой WebSocket, Cloudflare Worker или TCP.
Русский · English
TgWsProxy запускает локальный прокси на Android-устройстве. Telegram подключается к нему через MTProto Proxy или совместимый SOCKS5-режим, после чего нативный runtime выбирает разрешённый маршрут к инфраструктуре Telegram.
Основной сценарий версии 1.10.12 — MTProto Proxy → Cloudflare Proxy на локальном адресе 127.0.0.1:1443. Приложение не создаёт системный VPN-туннель и не перенаправляет весь трафик устройства.
Версия: 1.10.12 (versionCode 50)
Стадия: активная разработка
| Область | Статус |
|---|---|
MTProto Proxy через cf_proxy_ws |
Основной сценарий; по release notes вручную проверен на мобильной сети и Wi-Fi |
| SOCKS5 / WebSocket frontend | Реализован как режим совместимости |
direct_ws и tcp_fallback |
Реализованы; доступность зависит от сети |
| Cloudflare Worker | Реализован как необязательный маршрут |
| Worker Pool | Реализован, но в версии 1.10.12 остаётся медленным и не рекомендуется как основной маршрут |
- локальный MTProto Proxy с генерацией ссылок
t.me/proxyиtg://proxy; - совместимый SOCKS5 frontend на том же настраиваемом порту;
- маршруты
cf_proxy_ws,direct_ws,cf_worker_wsиtcp_fallback; - отдельные политики маршрутов для Wi-Fi, мобильной и неизвестной сети;
- Fake TLS secrets формата
dd<secret>иee<secret><domain_hex>; - необязательный passthrough probe-соединений на указанный masking domain;
- foreground service, уведомление о состоянии и watchdog локального listener;
- диагностика маршрутов, runtime status, экспорт отчёта и настраиваемое логирование;
- русский и английский интерфейс.
- Установите ARM64 APK из GitHub Releases, если нужная версия опубликована, либо соберите debug APK.
- Откройте TgWsProxy.
- Оставьте frontend MTProto Proxy и порт
1443, если он не занят другим локальным сервисом. - Нажмите Включить прокси.
- Нажмите Применить в Telegram и подтвердите конфигурацию в Telegram.
Если Telegram не подключается, откройте встроенную диагностику и отдельно проверьте маршрут cf_proxy_ws.
- Android 8.0 или новее (
minSdk 26); - устройство с ABI
arm64-v8a; - установленный Telegram;
- сеть, в которой доступен хотя бы один разрешённый маршрут.
- Windows и PowerShell;
- JDK 17;
- Android SDK и Android NDK;
- Go;
- Python 3;
- Gradle Wrapper из репозитория.
Текущий native build script использует Windows-путь к NDK toolchain. Сборка на Linux и macOS репозиторием не заявлена.
Проверьте GitHub Releases на наличие APK нужной версии. Локально собранный debug APK устанавливается через ADB:
adb install -r app\build\outputs\apk\debug\app-debug.apkПри переходе между debug- и release-подписями Android может потребовать удалить ранее установленное приложение.
- Выберите frontend MTProto Proxy.
- Проверьте локальный адрес и порт.
- При необходимости укажите masking domain.
- Запустите сервис и примените конфигурацию в Telegram.
Без masking domain ссылка использует secret вида dd<32 hex chars>. При указанном домене используется формат ee<secret><domain_hex>.
Настройте Telegram вручную:
Host: 127.0.0.1
Port: 1443
Username: пусто
Password: пусто
Если порт изменён в приложении, укажите то же значение в Telegram.
| Frontend | Назначение | Ограничение |
|---|---|---|
| MTProto Proxy | Основной режим с применением через MTProto proxy link | Использует только локальный порт приложения |
| SOCKS5 / WebSocket | Совместимость с ручной SOCKS5-конфигурацией Telegram | Требует ручного ввода адреса и порта |
| Route kind | Назначение | Ограничение |
|---|---|---|
cf_proxy_ws |
WebSocket через Cloudflare Proxy domains: kws{dc}.<domain>/apiws |
Доступность зависит от внешних доменов и сети |
direct_ws |
Прямой WebSocket к kws{dc}.web.telegram.org |
Может блокироваться или работать нестабильно |
cf_worker_ws |
WebSocket через Cloudflare Worker пользователя | Требует отдельной настройки Worker |
tcp_fallback |
Прямой TCP к IP датацентра Telegram на порту 443 |
Не является WebSocket-маршрутом |
WebSocket — транспорт. Фактический путь в интерфейсе и диагностике обозначается отдельным route kind.
Значения по умолчанию для версии 1.10.12:
| Параметр | Значение |
|---|---|
| Локальный адрес | 127.0.0.1 |
| Локальный порт | 1443 |
| Frontend | MTProto Proxy |
| Мобильная сеть | только cf_proxy_ws, без fallback |
| Wi-Fi | cf_proxy_ws → direct_ws → tcp_fallback |
| Неизвестная сеть | только cf_proxy_ws, без fallback |
| Runtime-сбор логов | выключен |
| Persistent file logs | выключены |
Миграция значений по умолчанию применяется только к пользователям, которые не меняли политики маршрутов вручную.
Warning
Включайте masking-domain passthrough только для доверенного домена. Приложение будет устанавливать реальные исходящие соединения с указанным хостом.
Telegram
│
▼
локальный MTProto Proxy или SOCKS5 frontend
│
▼
Android ProxyService (foreground service)
│
▼
Go runtime: libtgwsproxy.so
│
├── cf_proxy_ws
├── direct_ws
├── cf_worker_ws
└── tcp_fallback
Android-часть написана на Kotlin и Jetpack Compose. Нативный runtime расположен в native/tgwsproxy/, собирается как libtgwsproxy.so и подключается к Android-приложению через JNA/CGO bridge.
Подробное описание: docs/architecture/architecture.md.
- MTProto secret, query-параметры и чувствительные адреса маскируются в интерфейсе, диагностических отчётах и логах там, где это предусмотрено реализацией.
- URL Cloudflare Worker, proxy secrets, keystore и переменные подписи нельзя публиковать в issue, логах или коммитах.
- Release signing использует локальные переменные окружения; keystore исключён из Git.
- Masking domain меняет форму Fake TLS handshake, но не превращает приложение в VPN.
Перед публикацией диагностического отчёта проверьте его вручную.
TgWsProxy обрабатывает соединения, которые Telegram направляет в локальный proxy frontend. Приложение не создаёт системный VPN-туннель и не перехватывает трафик остальных приложений.
В зависимости от политики трафик идёт напрямую к Telegram, через Cloudflare Proxy или через Cloudflare Worker, настроенный пользователем. Runtime-сбор и постоянное сохранение логов выключены по умолчанию и включаются вручную для диагностики.
Встроенная диагностика показывает:
- настроенный, выбранный и фактически активный маршрут;
- результаты DNS, TCP, TLS, HTTP и WebSocket probe-шагов;
- состояние Cloudflare Proxy и Worker;
- статистику Fake TLS;
- последние ошибки и причины fallback;
- экспортируемый диагностический отчёт.
Runtime использует тег TgWsProxy в logcat. Диагностические проверки не должны менять активную политику маршрутов.
Текущий стек:
| Компонент | Версия или значение |
|---|---|
| Android Gradle Plugin | 8.2.2 |
| Gradle Wrapper | 8.2.1 |
| Kotlin | 1.9.22 |
| compileSdk / targetSdk | 35 / 35 |
| minSdk | 26 |
| ABI | arm64-v8a |
Сборка debug APK:
.\gradlew.bat assembleDebugGradle вызывает native build и генерацию иконок через preBuild. Результат:
app\build\outputs\apk\debug\app-debug.apk
Сборка с копированием APK в локальный каталог artifacts/:
.\scripts\build-apk.ps1 -Configuration DebugОтдельная сборка Go runtime:
.\scripts\build-native-android.ps1Команды, определённые в проекте:
.\gradlew.bat testDebugUnitTest
.\gradlew.bat assembleDebug
cd native\tgwsproxy
go test ./...В рамках подготовки этого README команды не запускались. Release notes версии 1.10.12 сообщают о выполнении unit-тестов, debug-сборки, Go-тестов и ручной проверке MTProto через Cloudflare Proxy на мобильной сети и Wi-Fi.
Ручная проверка должна включать запуск и остановку proxy service, подключение Telegram, загрузку сообщений и медиа, смену сетевой политики, диагностику маршрутов и просмотр экспортируемого отчёта на наличие секретов.
Актуальный чек-лист: docs/testing/README.md.
| Задача | Документ |
|---|---|
| Архитектура и поток данных | docs/architecture/architecture.md |
| Пул Cloudflare Proxy domains | docs/architecture/CF_DOMAIN_POOL.md |
| Настройка Cloudflare Worker | docs/architecture/cloudflare-worker.md |
| Структура репозитория | docs/development/repository-structure.md |
| Ручное тестирование | docs/testing/README.md |
| Подготовка релиза | docs/releases/release.md |
Изменения версии 1.10.12 |
docs/releases/RELEASE_NOTES_v1.10.12.md |
| История изменений | CHANGELOG.md |
- Flowseal/tg-ws-proxy — upstream runtime и основная идея WebSocket-маршрутизации;
- amurcanov/tg-ws-proxy-android — Android-обёртка, от которой началась эта ветка;
- Regstar2/TgWsProxy_Android — текущая Android-реализация и дальнейшая разработка.
При разработке отдельных участков кода, тестов и документации использовались AI-инструменты. Итоговые изменения проверялись вручную.
- поддерживается только ABI
arm64-v8a; - приложение является прокси для Telegram, а не системным VPN;
- доступность маршрутов зависит от сети и внешней инфраструктуры;
- Worker Pool в версии
1.10.12остаётся медленным и не предназначен для основного сценария; - порт
1443нужно изменить, если его уже использует другой локальный сервис; - native build script ориентирован на Windows; поддержка Linux и macOS не подтверждена;
- masking-domain passthrough создаёт соединения с указанным доменом;
- наличие APK для каждой версии в GitHub Releases не гарантируется.
Проект распространяется по лицензии GNU General Public License v3.0.