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

> Learn how to install and configure ClashX on macOS with our comprehensive guide. Easily set up system-wide traffic routing for Shadowsocks, V2Ray, and VMess protocols.

- Repository: [如何翻墙/fanqiang](https://github.com/bannedbook/fanqiang)
- Tags: how-to-guide
- Published: 2026-08-10

---

**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`](https://github.com/bannedbook/fanqiang/blob/main/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:

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

```

Paste the minimal configuration structure:

```yaml
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`](https://github.com/bannedbook/fanqiang/blob/main/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:

```bash
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`](https://github.com/bannedbook/fanqiang/blob/main/macos/ClashX.md)** – The primary tutorial covering download, installation, subscription import, UI usage, and troubleshooting.
- **[`macos/readme.md`](https://github.com/bannedbook/fanqiang/blob/main/macos/readme.md)** – An index of macOS-specific proxy tools linking to the ClashX guide and alternatives.
- **[`macos/Surge.md`](https://github.com/bannedbook/fanqiang/blob/main/macos/Surge.md)** – Documentation for Surge, an alternative macOS proxy client with advanced scripting capabilities.
- **[`macos/V2rayX.md`](https://github.com/bannedbook/fanqiang/blob/main/macos/V2rayX.md)** and **[`macos/V2RayU.md`](https://github.com/bannedbook/fanqiang/blob/main/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.