tg-ws-proxy-telegram-socks5

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

TG WS Proxy

Skill by ara.so — Daily 2026 Skills collection.

TG WS Proxy is a local SOCKS5 proxy server for Telegram Desktop that reroutes traffic through WebSocket (WSS) connections to Telegram's Data Centers, bypassing network-level blocking without external servers.

Telegram Desktop → SOCKS5 (127.0.0.1:1080) → TG WS Proxy → WSS → Telegram DC

由ara.so提供的Skill——属于Daily 2026 Skills合集。

TG WS Proxy 是一款面向Telegram Desktop的本地SOCKS5代理服务器，它将流量通过WebSocket（WSS）连接重新路由到Telegram数据中心，无需外部服务器即可绕过网络级别的封锁。

Telegram Desktop → SOCKS5 (127.0.0.1:1080) → TG WS Proxy → WSS → Telegram DC

How It Works

工作原理

Starts a local SOCKS5 proxy on
```
127.0.0.1:1080
```
Intercepts connections to Telegram IP addresses
Extracts DC ID from MTProto obfuscation init packet
Opens a WebSocket (TLS) connection to the matching DC via Telegram domains
Falls back to direct TCP if WebSocket returns a 302 redirect

在
```
127.0.0.1:1080
```
启动本地SOCKS5代理
拦截指向Telegram IP地址的连接
从MTProto混淆初始化数据包中提取DC ID
通过Telegram域名打开与对应数据中心的WebSocket（TLS）连接
如果WebSocket返回302重定向，则回退到直接TCP连接

Installation

安装方法

From Source (All Platforms)

从源码安装（全平台）

bash

git clone https://github.com/Flowseal/tg-ws-proxy.git
cd tg-ws-proxy
pip install -e .

bash

git clone https://github.com/Flowseal/tg-ws-proxy.git
cd tg-ws-proxy
pip install -e .

Run Console Proxy (No GUI)

启动控制台代理（无GUI）

bash

tg-ws-proxy

bash

tg-ws-proxy

Run with Tray GUI

启动托盘GUI版本

bash

undefined

bash

undefined

Windows

tg-ws-proxy-tray-win

macOS

tg-ws-proxy-tray-macos

Linux

tg-ws-proxy-tray-linux

undefined

tg-ws-proxy-tray-linux

undefined

Linux — AUR (Arch-based)

Linux — AUR（基于Arch发行版）

bash

paru -S tg-ws-proxy-bin

bash

paru -S tg-ws-proxy-bin

or

或

git clone https://aur.archlinux.org/tg-ws-proxy-bin.git cd tg-ws-proxy-bin makepkg -si

undefined

git clone https://aur.archlinux.org/tg-ws-proxy-bin.git cd tg-ws-proxy-bin makepkg -si

undefined

Linux — systemd CLI

Linux — systemd 命令行启动

bash

sudo systemctl start tg-ws-proxy-cli@1080

bash

sudo systemctl start tg-ws-proxy-cli@1080

Linux — .deb

Linux — .deb包安装

Download

TgWsProxy_linux_amd64.deb

from releases and install:

bash

sudo dpkg -i TgWsProxy_linux_amd64.deb

从发布页面下载

TgWsProxy_linux_amd64.deb

并安装：

bash

sudo dpkg -i TgWsProxy_linux_amd64.deb

Linux — binary

Linux — 二进制文件直接运行

bash

chmod +x TgWsProxy_linux_amd64
./TgWsProxy_linux_amd64

bash

chmod +x TgWsProxy_linux_amd64
./TgWsProxy_linux_amd64

CLI Reference

CLI参考

bash

tg-ws-proxy [--port PORT] [--host HOST] [--dc-ip DC:IP ...] [-v]

Argument	Default	Description
`--port`	`1080`	SOCKS5 proxy port
`--host`	`127.0.0.1`	SOCKS5 proxy bind host
`--dc-ip`	`2:149.154.167.220` , `4:149.154.167.220`	Target IP per DC ID (repeat for multiple)
`-v` , `--verbose`	off	Enable DEBUG logging

bash

tg-ws-proxy [--port PORT] [--host HOST] [--dc-ip DC:IP ...] [-v]

参数	默认值	说明
`--port`	`1080`	SOCKS5代理端口
`--host`	`127.0.0.1`	SOCKS5代理绑定地址
`--dc-ip`	`2:149.154.167.220` , `4:149.154.167.220`	对应DC ID的目标IP（可重复指定多个）
`-v` , `--verbose`	关闭	启用DEBUG日志

Examples

示例

bash

undefined

bash

undefined

Default startup

默认启动

tg-ws-proxy

Custom port

自定义端口

tg-ws-proxy --port 9050

Specify multiple DCs with IPs

指定多个DC及对应IP

tg-ws-proxy --dc-ip 1:149.154.175.205 --dc-ip 2:149.154.167.220 --dc-ip 4:149.154.167.220

Verbose debug logging

启用详细调试日志

tg-ws-proxy -v

Full custom example

完整自定义示例

tg-ws-proxy --host 0.0.0.0 --port 1080 --dc-ip 2:149.154.167.220 -v

---

tg-ws-proxy --host 0.0.0.0 --port 1080 --dc-ip 2:149.154.167.220 -v

---

Configuration File

配置文件

The tray application stores config in a platform-specific location:

Windows:
```
%APPDATA%/TgWsProxy/config.json
```

macOS:

~/Library/Application Support/TgWsProxy/config.json

Linux:

~/.config/TgWsProxy/config.json

(or

$XDG_CONFIG_HOME/TgWsProxy/config.json

)

托盘应用会将配置存储在各平台对应的路径中：

Windows:
```
%APPDATA%/TgWsProxy/config.json
```

macOS:

~/Library/Application Support/TgWsProxy/config.json

Linux:

~/.config/TgWsProxy/config.json

（或

$XDG_CONFIG_HOME/TgWsProxy/config.json

）

config.json structure

config.json结构

json

{
  "port": 1080,
  "dc_ip": [
    "2:149.154.167.220",
    "4:149.154.167.220"
  ],
  "verbose": false
}

json

{
  "port": 1080,
  "dc_ip": [
    "2:149.154.167.220",
    "4:149.154.167.220"
  ],
  "verbose": false
}

pyproject.toml Script Registration

pyproject.toml脚本注册

CLI entry points are declared in

pyproject.toml

toml

[project.scripts]
tg-ws-proxy = "proxy.tg_ws_proxy:main"
tg-ws-proxy-tray-win = "windows:main"
tg-ws-proxy-tray-macos = "macos:main"
tg-ws-proxy-tray-linux = "linux:main"

CLI入口点在

pyproject.toml

中声明：

toml

[project.scripts]
tg-ws-proxy = "proxy.tg_ws_proxy:main"
tg-ws-proxy-tray-win = "windows:main"
tg-ws-proxy-tray-macos = "macos:main"
tg-ws-proxy-tray-linux = "linux:main"

Connecting Telegram Desktop

连接Telegram Desktop

Manual Setup

手动设置

Open Telegram Desktop
Go to Settings → Advanced → Connection type → Use custom proxy
Click Add Proxy and set:
- Type: SOCKS5
- Server:
```
127.0.0.1
```
- Port:
```
1080
```
- Username/Password: leave empty
Click Save and enable the proxy

打开Telegram Desktop
进入设置 → 高级 → 连接类型 → 使用自定义代理
点击添加代理并设置：
- 类型: SOCKS5
- 服务器:
```
127.0.0.1
```
- 端口:
```
1080
```
- 用户名/密码: 留空
点击保存并启用该代理

Automatic (Tray GUI)

自动设置（托盘GUI）

Right-click the tray icon → "Открыть в Telegram" — this opens a

tg://socks

deep link that auto-configures Telegram Desktop.

右键点击托盘图标 → "Открыть в Telegram"（在Telegram中打开）——这会打开一个

tg://socks

深度链接，自动配置Telegram Desktop。

Code Examples

代码示例

Launching the Proxy Programmatically

以编程方式启动代理

python

from proxy.tg_ws_proxy import main
import threading

python

from proxy.tg_ws_proxy import main
import threading

Run proxy in background thread

在后台线程中运行代理

proxy_thread = threading.Thread(target=main, daemon=True) proxy_thread.start()

undefined

proxy_thread = threading.Thread(target=main, daemon=True) proxy_thread.start()

undefined

Using the Proxy with Python Requests (via PySocks)

通过PySocks在Python Requests中使用代理

bash

pip install requests[socks]

python

import requests

proxies = {
    "http":  "socks5h://127.0.0.1:1080",
    "https": "socks5h://127.0.0.1:1080",
}

response = requests.get("https://api.telegram.org/botTOKEN/getMe", proxies=proxies)
print(response.json())

bash

pip install requests[socks]

python

import requests

proxies = {
    "http":  "socks5h://127.0.0.1:1080",
    "https": "socks5h://127.0.0.1:1080",
}

response = requests.get("https://api.telegram.org/botTOKEN/getMe", proxies=proxies)
print(response.json())

Using with Telethon (MTProto client)

在Telethon（MTProto客户端）中使用代理

python

from telethon import TelegramClient
from telethon.network.connection.tcpabridged import ConnectionTcpAbridged
import socks

client = TelegramClient(
    'session',
    api_id=int(os.environ["TG_API_ID"]),
    api_hash=os.environ["TG_API_HASH"],
    proxy=(socks.SOCKS5, '127.0.0.1', 1080)
)

async def main():
    await client.start()
    me = await client.get_me()
    print(me.username)

import asyncio
asyncio.run(main())

python

from telethon import TelegramClient
from telethon.network.connection.tcpabridged import ConnectionTcpAbridged
import socks

client = TelegramClient(
    'session',
    api_id=int(os.environ["TG_API_ID"]),
    api_hash=os.environ["TG_API_HASH"],
    proxy=(socks.SOCKS5, '127.0.0.1', 1080)
)

async def main():
    await client.start()
    me = await client.get_me()
    print(me.username)

import asyncio
asyncio.run(main())

Custom DC IP Mapping (Python)

自定义DC IP映射（Python）

python

import subprocess

dc_map = {
    1: "149.154.175.205",
    2: "149.154.167.220",
    3: "149.154.175.100",
    4: "149.154.167.220",
    5: "91.108.56.130",
}

dc_args = []
for dc_id, ip in dc_map.items():
    dc_args += ["--dc-ip", f"{dc_id}:{ip}"]

subprocess.Popen(["tg-ws-proxy", "--port", "1080"] + dc_args)

python

import subprocess

dc_map = {
    1: "149.154.175.205",
    2: "149.154.167.220",
    3: "149.154.175.100",
    4: "149.154.167.220",
    5: "91.108.56.130",
}

dc_args = []
for dc_id, ip in dc_map.items():
    dc_args += ["--dc-ip", f"{dc_id}:{ip}"]

subprocess.Popen(["tg-ws-proxy", "--port", "1080"] + dc_args)

Building Binaries (PyInstaller)

编译二进制文件（PyInstaller）

bash

undefined

bash

undefined

Windows

pyinstaller packaging/windows.spec

macOS

pyinstaller packaging/macos.spec

Linux

pyinstaller packaging/linux.spec


Builds are also produced automatically via GitHub Actions in `.github/workflows/build.yml`.

---

pyinstaller packaging/linux.spec


构建也可通过GitHub Actions自动完成，对应配置文件为`.github/workflows/build.yml`。

---

Minimum OS Support

最低系统版本支持

Binary	Minimum Version
`TgWsProxy_windows.exe`	Windows 10+
`TgWsProxy_windows_7_64bit.exe`	Windows 7 x64
`TgWsProxy_windows_7_32bit.exe`	Windows 7 x32
`TgWsProxy_macos_universal.dmg` (Intel)	macOS 10.15+
`TgWsProxy_macos_universal.dmg` (Apple Silicon)	macOS 11.0+
`TgWsProxy_linux_amd64`	Linux x86_64 + AppIndicator

二进制文件	最低版本要求
`TgWsProxy_windows.exe`	Windows 10+
`TgWsProxy_windows_7_64bit.exe`	Windows 7 x64
`TgWsProxy_windows_7_32bit.exe`	Windows 7 x32
`TgWsProxy_macos_universal.dmg` （Intel）	macOS 10.15+
`TgWsProxy_macos_universal.dmg` （Apple Silicon）	macOS 11.0+
`TgWsProxy_linux_amd64`	Linux x86_64 + AppIndicator

Troubleshooting

故障排除

Telegram still not connecting

Telegram仍无法连接

Confirm the proxy is running:
```
tg-ws-proxy -v
```
and watch for connection logs
Make sure Telegram Desktop is set to SOCKS5, not HTTP/MTProxy
Try restarting the proxy from the tray menu (Перезапустить прокси)
Check no firewall or other process is blocking port
```
1080
```

确认代理正在运行：执行
```
tg-ws-proxy -v
```
并查看连接日志
确保Telegram Desktop设置的是SOCKS5代理，而非HTTP/MTProxy
尝试从托盘菜单重启代理（Перезапустить прокси）
检查是否有防火墙或其他进程占用了
```
1080
```
端口

Port already in use

端口已被占用

bash

undefined

bash

undefined

Find what's using port 1080

查找占用1080端口的进程

lsof -i :1080 # macOS/Linux netstat -ano | findstr :1080 # Windows

Run on a different port

使用其他端口启动代理

tg-ws-proxy --port 1081


Then update Telegram Desktop's proxy port to `1081`.

tg-ws-proxy --port 1081


然后将Telegram Desktop的代理端口更新为`1081`。

Windows Defender false positive (Wacatac)

Windows Defender误报（Wacatac）

Download the
```
win7
```
variant — functionally identical, lower detection rate
Or temporarily disable Defender, download, add to exclusions, re-enable
Verify the build on VirusTotal using the file hash

下载
```
win7
```
版本——功能完全一致，被检测概率更低
或临时关闭Defender，下载后添加到排除列表，再重新启用Defender
通过文件哈希在VirusTotal上验证构建文件的安全性

macOS "unverified developer" block

macOS提示“无法打开，因为无法验证开发者”

Open System Settings → Privacy & Security
Scroll down and click Open Anyway next to TG WS Proxy

打开系统设置 → 隐私与安全性
向下滚动，点击TG WS Proxy旁的仍要打开

Linux tray icon not visible

Linux托盘图标不显示

AppIndicator is required. Install it:

bash

undefined

需要安装AppIndicator组件：

bash

undefined

Ubuntu/Debian

sudo apt install gir1.2-appindicator3-0.1

Fedora

sudo dnf install libappindicator-gtk3

undefined

sudo dnf install libappindicator-gtk3

undefined

WebSocket not available — proxy falls back to TCP

WebSocket不可用——代理回退到TCP连接

This is expected behavior. If WS returns a 302 redirect, the proxy automatically uses direct TCP. No action needed; Telegram will still connect.

这是预期行为。如果WS返回302重定向，代理会自动使用直接TCP连接。无需操作，Telegram仍可正常连接。

Verbose debug logging

启用详细调试日志

bash

tg-ws-proxy -v

Or set

"verbose": true

config.json

for the tray app.

bash

tg-ws-proxy -v

或在托盘应用的

config.json

中设置

"verbose": true

。