Practical guides

Start with confidence.

From first launch to system-wide capture, every step is clear and reversible.

Install and launch

Download safely, move the app into Applications, and complete the first-run prompts.

Read guide →

Import a configuration

Add a subscription, local file, or URL scheme without exposing sensitive links.

Read guide →

Enable Enhanced Mode

Route TCP and UDP traffic from every app through the TUN interface.

Read guide →

Migrate from ClashX

Back up old configurations, avoid client conflicts, and validate in stages.

Read guide →

Route apps by process

Find the actual executable name and create reliable PROCESS-NAME rules.

Read guide →

TUN troubleshooting

Separate DNS, permission, node, port, and network-extension problems.

Read guide →

Direct routing for Chinese apps

Use cn-apps-direct to bypass common apps and contribute verified process rules.

Read the full article →
Guide 01

Install and first launch

The process takes about two minutes. Always download from the official repository.

  1. Download the latest releaseOpen GitHub Releases and choose the latest Stable build.
  2. Move it to ApplicationsOpen the downloaded image and drag ClashFX into Applications.
  3. Approve first launchOpen ClashFX and follow the macOS security prompt.
  4. Find the menu bar iconClashFX runs from the menu bar, where its main controls are available.
Guide 02

Import your configuration

ClashFX is a client and does not provide proxy nodes or subscriptions.

  1. Copy the subscription URLTreat it as a secret and never include it in screenshots or public issues.
  2. Open remote config managementChoose Config → Remote Config Management from the menu bar.
  3. Add and name itPaste the URL, choose a clear local name, and wait for the download.
  4. Activate the new configSelect it from Config and verify that groups and nodes appear.
Guide 03

Enable Enhanced Mode

TUN captures system-wide traffic and requires administrator permission the first time.

Verify that your current configuration works with the system proxy before enabling TUN.
  1. Activate a working configChoose a valid configuration and node.
  2. Enable Enhanced ModeOpen the menu bar item and select Enhanced Mode → Enable.
  3. Grant permissionApprove the macOS prompt to create the network interface.
  4. Test and recoverIf connectivity fails, turn Enhanced Mode off before troubleshooting.
Guide 04

Migrate from ClashX

Most Clash YAML files work, but old core-specific fields may require changes.

Do not run ClashX and ClashFX at the same time. Both can change system proxy settings.
  1. Record your setupBack up subscriptions, custom rules, and DNS settings.
  2. Quit ClashX completelyDisable its proxy and TUN before quitting.
  3. Import into ClashFXRe-add the remote subscription or place local YAML files under ~/.config/clashfx.
  4. Validate in stagesTest the system proxy first, then enable Enhanced Mode.
Guide 05

Route an app by process

Process rules are useful when a specific app should always connect directly.

- PROCESS-NAME,WeChat,DIRECT
  1. Find the executableRun ls /Applications/App.app/Contents/MacOS/ and use the returned filename.
  2. Create a PROCESS-NAME ruleUse the rule generator on the Tools page if needed.
  3. Put specific rules firstThe first matching rule wins; keep MATCH at the end.
  4. Use built-in bypasses when possibleCommon Chinese apps can use the Enhanced Mode bypass toggle.
Guide 06

No network after enabling TUN

Restore connectivity first, then reproduce one layer at a time.

Open diagnostic tools
  1. Turn Enhanced Mode offAlso disable the system proxy. If networking remains down, inspect Wi-Fi, other VPNs, or stale routes.
  2. Test only the system proxyIf it fails, update the subscription, change nodes, and check config errors.
  3. Check DNS and permissionsIf only TUN fails, inspect helper permission, DNS, browser secure DNS, and old extensions.
  4. Collect redacted diagnosticsRemove subscription URLs, node addresses, usernames, and public IPs before posting.