ClashX Connection Timeout Overview
Connection timeout is one of the most common issues. About 30% of users run into it. Use this 3-step flow to quickly locate and fix the root cause.
Typical symptoms
- Browser shows “ERR_CONNECTION_TIMED_OUT”.
- Pages load very slowly or never open.
- Apps cannot reach the internet.
- ClashX menu-bar icon turns red.
- Only specific sites fail while others work.
1) Click the ClashX menu icon and confirm “System Proxy” is enabled.
2) Open http://www.gstatic.com/generate_204 — it should return a blank 204 page.
3) Run curl -I google.com in Terminal to see if you get a response.
Step 1: Ensure ClashX Is Running
Many timeouts occur because ClashX isn’t actually running or system proxy isn’t enabled.
Check process
Terminal check
# Verify ClashX process
ps aux | grep -i clashx | grep -v grep
# Expected: a ClashX process path under /Applications/ClashX.app
Review logs
Open logs
# Tail realtime logs
tail -f ~/.config/clash/clashx.log
# Or open Console.app and search "ClashX"
Common startup problems
| Issue | Fix |
|---|---|
| ClashX icon is gray | Click icon → Enable System Proxy |
| Quits right after launch | Check config.yaml for syntax errors |
| TUN mode won’t start | Grant admin permissions / reinstall helper |
| Dashboard not reachable | Check if port 9090 is taken |
If ClashX repeatedly asks for permissions, go to System Settings → Privacy & Security → Full Disk Access and ensure ClashX is allowed.
Step 2: Verify Port Configuration (Critical)
Port conflicts are the #1 cause of timeouts. Defaults: HTTP/HTTPS 7890, SOCKS5 7891.
Check listening ports
Use lsof
lsof -i :7890 # HTTP proxy
lsof -i :7891 # SOCKS5 proxy
lsof -i :9090 # Dashboard
# Expect ClashX listening on these ports
Free a taken port
Find & kill
lsof -ti :7890
sudo kill -9 $(lsof -ti :7890)
Change ClashX ports
If conflicts persist, edit the config:
Edit config.yaml
port: 7890 # change if needed
socks-port: 7891 # change if needed
external-controller: 127.0.0.1:9090
Restart ClashX and update system proxy/app proxy settings to the new ports.
Test connectivity
curl -x http://127.0.0.1:7890 http://www.gstatic.com/generate_204 -w "%{http_code}
" -o /dev/null
# Should return 204
curl -x socks5://127.0.0.1:7891 http://www.gstatic.com/generate_204 -w "%{http_code}
" -o /dev/null
# Should return 204
Step 3: DNS Checks
Bad DNS causes timeouts. Validate and optimize DNS.
Test DNS
nslookup / dig
nslookup google.com
dig google.com
dig @8.8.8.8 google.com
Recommended DNS config
dns:
enable: true
listen: 127.0.0.1:53
enhanced-mode: fake-ip
nameserver:
- 119.29.29.29
- 223.5.5.5
fallback:
- https://1.1.1.1/dns-query
- https://dns.google/dns-query
fallback-filter:
geoip: true
geoip-code: CN
Clear DNS cache
sudo dscacheutil -flushcache
sudo killall -HUP mDNSResponder
Node Validity
Even perfect configs fail if the node is dead.
Test via Dashboard
- Open Dashboard: http://127.0.0.1:9090/ui
- Proxies tab → Speed Test
- Pick nodes with lowest latency.
CLI tests
curl through proxy
curl -x http://127.0.0.1:7890 -I https://www.google.com
curl -x http://127.0.0.1:7890 -o /dev/null -s -w "speed: %{speed_download} bytes/s
" https://speed.cloudflare.com/__down?bytes=10000000
Common node failures
| Cause | Symptom | Fix |
|---|---|---|
| Server down | All requests timeout | Switch to another node |
| Quota exhausted | Suddenly stops working | Check subscription quota |
| IP blocked | Specific sites fail | Ask provider for new IP |
| Bad config | Never connects | Re-import subscription |
Update subscription
# ClashX menu:
# Profiles → Reload
# or Profiles → Update subscription
ls -la ~/.config/clash/config.yaml # check update time
Firewall Checks
macOS firewall or security apps may block ClashX.
macOS firewall status
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --getglobalstate
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --listapps | grep -i clash
Add exception
- System Settings → Network → Firewall → Options.
- Add
/Applications/ClashX.appand allow incoming connections.
If you use Little Snitch/Lulu/Norton, allow ClashX for all connections.
System Proxy Verification
Confirm macOS proxies point to ClashX.
Check via scutil
scutil --proxy
# Expect HTTP/HTTPS 127.0.0.1:7890, SOCKS 127.0.0.1:7891
Manual setup (if needed)
- System Settings → Network → your connection → Details.
- Proxy tab: enable HTTP/HTTPS 127.0.0.1:7890, SOCKS 127.0.0.1:7891.
- Proxy bypass list:
localhost, 127.0.0.1, 192.168.0.0/16, 10.0.0.0/8.
In ClashX menu, keep “Set as system proxy” enabled to auto-manage settings.
Advanced Troubleshooting
If it still fails, try these:
Tune timeouts
dial-timeout: 10
tcp-keep-alive-interval: 30
tcp-fast-open: true
Packet capture
brew install --cask wireshark
sudo tcpdump -i any port 7890 -w ~/clashx-capture.pcap
MTU check
networksetup -getMTU Wi-Fi
ping -D -s 1472 google.com
sudo networksetup -setMTU Wi-Fi 1400
Full reset (backup first!)
cp -r ~/.config/clash ~/Desktop/clash-backup
killall ClashX
rm -rf ~/.config/clash
rm -rf ~/Library/Application\ Support/com.west2online.ClashX
rm -rf ~/Library/Preferences/com.west2online.ClashX*
rm -rf ~/Library/Caches/com.west2online.ClashX
open /Applications/ClashX.app
Check the FAQ, the full troubleshooting guide, or open a GitHub issue.