README.md
May 27, 2026 · View on GitHub
ClashFX
A rule-based macOS proxy client with Enhanced Mode (TUN) — powered by mihomo core.
✨ Features
- Enhanced Mode (TUN) — Global traffic capture via TUN device, one-click setup
- HTTP/HTTPS and SOCKS protocol support
- Rule-based routing (Domain, IP-CIDR, GeoIP, Process)
- Support for VMess/VLESS/Trojan/Shadowsocks/Hysteria2 protocols
- DNS security with Fake-IP mode
- gVisor userspace network stack
- Apple Silicon native support
- macOS 10.14+ compatibility (including macOS 15 Sequoia)
📥 Installation
Download from the Releases page.
🧪 Update Channels: Stable & Lab
The Lab channel has been live since v1.1.0. Stable remains the default and recommended choice; opt into Lab in
Settings → Debug → Update Channel → Lab (Experimental)if you're on v1.1.0+.
ClashFX ships through two update channels. You can choose either — both are first-class.
| 🟢 Stable | 🟠 Lab | |
|---|---|---|
| Default | ✅ | — |
| Release cadence | Every 2–7 days, when fixes accumulate | As soon as a fix lands — sometimes daily |
| What you get | Tested fixes only | Latest fixes + occasional experimental features |
| Visual badge | None | Small orange dot on the top-right of the Dock / Applications icon |
Opt into Lab: open ClashFX → Settings → Debug → Update Channel → Lab (Experimental) and confirm. The orange dot appears immediately. You can switch back to Stable from the same place at any time.
Found a Lab bug? Use Help → Send Feedback… to open a pre-filled GitHub issue (diagnostic info auto-attached and redacted), or Help → Copy Diagnostic Info… to copy the report manually.
Stable users: you're already on the recommended channel — nothing to change.
🔨 Build from Source
Prerequisites
- macOS 10.14 or later
- Xcode 15.0+
- Python 3
- Golang 1.21+
Build Steps
-
Install Golang
brew install golang -
Install dependencies
bash install_dependency.sh -
Open and build
open ClashFX.xcworkspace # Build in Xcode (Cmd+R)
⚙️ Configuration
Default Paths
The default configuration directory is $HOME/.config/clashfx
The default configuration file name is config.yaml. You can use custom config names and switch between them in the Config menu.
Enhanced Mode
ClashFX's core feature — TUN-based global proxy that captures all TCP/UDP traffic from every application, not just browsers.
How to enable:
- Menu Bar → Enhanced Mode → Enable
- Grant administrator privileges on first use
- All traffic is now routed through ClashFX
URL Schemes
-
Import remote config:
clashfx://install-config?url=http%3A%2F%2Fexample.com&name=example clash://install-config?url=http%3A%2F%2Fexample.com&name=example -
Reload current config:
clash://update-config
🤝 Companion Repo: cn-apps-direct
The "Bypass Common Chinese Apps" toggle (added in v1.0.38, under Enhanced Mode) reads its PROCESS-NAME rule list from Clash-FX/cn-apps-direct — a small community-maintained repo of macOS executable names for high-frequency Chinese apps (WeChat, QQ, DingTalk, Feishu, Bilibili, etc.). The list updates automatically every 24 hours via rule-provider, decoupled from the ClashFX release cycle.
Want to add an app or fix a wrong process name? PRs are welcome — see CONTRIBUTING.md. Adding an entry takes about a minute:
ls /Applications/<App>.app/Contents/MacOS/ # verify the actual executable name
# append the verified name as: PROCESS-NAME,<name>,DIRECT
# open a PR