How to Install and Configure ClashX on macOS: Complete Setup Guide

ClashX is a native macOS GUI client for the Clash proxy engine that enables system-wide traffic routing through Shadowsocks, V2Ray, and VMess protocols via subscription-based configuration imports.

ClashX provides a user-friendly interface for managing proxy connections on macOS without manual configuration file editing. The bannedbook/fanqiang repository hosts comprehensive documentation in macos/ClashX.md that walks users through downloading release binaries, importing remote subscriptions, and activating system-wide proxy settings.

Understanding the ClashX Architecture

Before installation, understand how ClashX operates across three distinct layers according to the repository documentation:

• Clash Core – The underlying engine that parses YAML configuration files from ~/.config/clash/config.yml and handles all traffic routing logic.
• ClashX UI – A native macOS wrapper that displays core status, allows switching between rule groups, and toggles system-wide proxy settings via the menu bar.
• Subscription Service – A remote URL (typically provided by V2Ray or Shadowsocks service providers) that supplies encrypted JSON or YAML node lists and routing rules.

Download and Install ClashX

The repository does not ship pre-built binaries. You must download the latest release directly from the project's GitHub releases page.

1. Visit the official ClashX GitHub repository releases section.
2. Download the latest .dmg file for macOS.
3. Open the .dmg and drag the ClashX application to your /Applications folder.
4. Launch ClashX from Applications or Spotlight.

Note: macOS may block the application on first launch due to Gatekeeper. Navigate to System Preferences > Security & Privacy and click "Open Anyway" if prompted.

Configure ClashX on macOS

ClashX supports two configuration methods: manual file editing or GUI-based subscription import.

Manual Configuration via config.yml

Create the configuration directory and file manually if you need custom settings:

mkdir -p ~/.config/clash
nano ~/.config/clash/config.yml

Paste the minimal configuration structure:

port: 7890                     # HTTP proxy port

socks-port: 7891                # SOCKS5 proxy port

redir-port: 7892                # Transparent proxy port (optional)

allow-lan: false                # Whether to allow LAN devices

mode: rule                      # Proxy mode – `global`, `direct`, or `rule`

log-level: info
external-controller: 127.0.0.1:9090

Important: Avoid changing the default ports (7890, 7891) unless necessary, as applications may reference these values in their proxy settings.

Import Subscription via GUI (Recommended)

Most users import proxy nodes through the subscription URL method documented in macos/ClashX.md:

1. Open ClashX and click the cat icon in the menu bar.
2. Select 配置 (Configuration) → 托管配置 (Managed Configuration) → 管理 (Manage).
3. Click 添加 (Add).
4. Paste your subscription URL (e.g., https://example.com/clash.yaml).
5. Click OK to download the node list and rule definitions.

The application automatically parses the remote configuration and populates your available proxy nodes.

Activate System-Wide Proxy

After configuration, enable system proxy routing:

1. Click the ClashX menu bar icon.
2. Set the outbound mode to 规则 (Rule) for intelligent routing or 全局 (Global) for full proxy.
3. Check 系统代理 (System Proxy) to route all macOS traffic through ClashX.

Verify Connectivity via Command Line

Confirm ClashX is proxying traffic correctly by running:

curl -x http://127.0.0.1:7890 https://www.google.com -I

If the request returns HTTP 200 headers, your traffic is routing through the ClashX HTTP proxy on port 7890.

Repository Resources and Related Files

The bannedbook/fanqiang repository contains several related documentation files for macOS proxy solutions:

• macos/ClashX.md – The primary tutorial covering download, installation, subscription import, UI usage, and troubleshooting.
• macos/readme.md – An index of macOS-specific proxy tools linking to the ClashX guide and alternatives.
• macos/Surge.md – Documentation for Surge, an alternative macOS proxy client with advanced scripting capabilities.
• macos/V2rayX.md and macos/V2RayU.md – Guides for V2Ray-specific clients that utilize different plugin architectures.

Summary

• ClashX combines the Clash core engine with a native macOS interface for managing Shadowsocks and V2Ray connections.
• Configuration files reside in ~/.config/clash/config.yml and follow standard YAML syntax with ports 7890 (HTTP) and 7891 (SOCKS5).
• Subscription imports use the GUI path: 配置 → 托管配置 → 管理 → 添加, requiring only a remote URL.
• System proxy activation toggles via the menu bar icon, immediately routing all macOS traffic through your selected nodes.
• Verification can be performed via curl commands targeting 127.0.0.1:7890 to ensure the local proxy is listening.

Frequently Asked Questions

Where does ClashX store its configuration files on macOS?

ClashX reads and writes its primary configuration to ~/.config/clash/config.yml. This location follows the XDG Base Directory specification. The GUI may also cache subscription data in the same directory, though runtime settings like selected nodes are typically stored in macOS user defaults.

How do I update my proxy nodes without manually editing files?

Navigate to 配置 → 托管配置 → 管理, select your existing subscription, and click the update or refresh button. ClashX fetches the latest YAML from your subscription URL and reloads the node list automatically without requiring manual file edits.

What is the difference between ClashX and the Clash core?

Clash core is the command-line Go binary that parses YAML and manages network routing. ClashX is a Swift/Objective-C wrapper that provides the menu bar interface, system proxy toggles, and graphical rule management while communicating with the core process. You can run the core standalone without ClashX, but you lose the native macOS GUI conveniences.

Why isn't my system proxy working after enabling it in ClashX?

First, verify ClashX is actually running and bound to the expected ports using lsof -i :7890. Second, check that you have selected an active proxy node (not "DIRECT") in the menu. Third, some applications cache proxy settings and require a restart to recognize system proxy changes. Finally, ensure no other VPN or proxy software is conflicting with port 7890/7891 bindings.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}