# Guide to Using ClashX on macOS for Internet Circumvention

> Learn to use ClashX on macOS for internet circumvention. This guide explains routing traffic via Shadowsocks and V2Ray nodes using rule-based configurations.

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

---

**ClashX is a macOS graphical client for the Clash proxy engine that enables internet circumvention by routing traffic through Shadowsocks and V2Ray nodes using rule-based YAML configurations.**

This guide covers the complete workflow for setting up ClashX on macOS using the official tutorial from the `bannedbook/fanqiang` repository. You will learn how to install the application, configure remote subscriptions, and manage proxy rules to bypass network restrictions.

## What ClashX Does and How It Works

ClashX embeds the **Clash core** engine into a native macOS application bundle. According to the source documentation in [`macos/ClashX.md`](https://github.com/bannedbook/fanqiang/blob/main/macos/ClashX.md)【5†L5-L8】, the application reads a YAML configuration file to build proxy groups and intercepts system traffic by registering a local HTTP proxy at `http://127.0.0.1:Port`.

### Core Architecture

When launched, ClashX performs three critical operations:
- Reads the configuration from `~/.config/clash/config.yml`
- Builds **proxy groups** based on node definitions in the subscription
- Registers a system-wide proxy to intercept HTTP/HTTPS requests

The application runs as a menu bar utility, allowing you to toggle proxy modes and select specific nodes without editing configuration files manually.

### Supported Protocols

As documented in the repository's overview section【5†L5-L8】, ClashX supports multiple circumvention protocols:
- **Shadowsocks** (with simple-obfs plugin)
- **V2Ray-plugin** variants
- Native **V2Ray/VMess** (TCP, WebSocket, and other transports)

## Installing ClashX on macOS

The installation process requires downloading the official binary and granting system permissions for proxy management.

### Download and Install

1. Download the latest `ClashX.dmg` from the project's release page at `https://github.com/bannedbook/ClashX/releases`【5†L13-L16】
2. Open the DMG and drag the ClashX icon into your **Applications** folder【5†L34-L42】
3. Launch ClashX from `/Applications`

### First Run Configuration

When opening ClashX for the first time:
- **Security Prompt**: macOS may block the unsigned application. Navigate to **System Preferences → Security & Privacy** to allow the executable【5†L52-L53】
- **Helper Daemon**: Click "Install" when prompted to add the proxy helper tool, entering your administrator password to enable system-wide proxy capabilities【5†L46-L48】

## Configuring ClashX with a Subscription

ClashX operates by loading remote configuration files containing proxy node definitions. The repository recommends using a free V2Ray airport service to obtain a subscription URL.

### Obtaining a Subscription URL

The guide in [`macos/ClashX.md`](https://github.com/bannedbook/fanqiang/blob/main/macos/ClashX.md) references a public V2Ray airport that provides free subscription links【5†L20-L27】:
1. Register at the recommended airport service
2. Navigate to the user dashboard
3. Copy the **Clash** subscription link (not the V2Ray or SSR links)

### Adding the Subscription to ClashX

Configure the managed configuration through the menu bar interface【5†L54-L64】:
1. Click the ClashX menu bar icon → **Configuration → Managed Config → Edit**
2. Click **Add** and paste your subscription URL
3. Click **Update** to fetch the latest node list

### Critical System Settings

After loading the subscription, adjust these settings immediately:
- Set **Outbound Mode** to **Rule** (enables domain-based routing)
- Check **Set as system proxy** to route all browser traffic
- Enable **Launch at login** for persistent availability

**Warning**: Do not manually edit `~/.config/clash/config.yml` to change proxy ports unless you understand the implications. Modifying the default ports may break the application【5†L75-L76】.

## Understanding the Configuration File Structure

While subscription files are generated automatically, understanding the YAML structure helps with troubleshooting. Below is a minimal configuration snippet showing the expected format:

```yaml
port: 7890                      # HTTP proxy port

socks-port: 7891                # SOCKS5 proxy port

allow-lan: false                # Disallow LAN devices

mode: rule                      # Use rule-based routing

log-level: info

# Proxy node definitions – normally filled by the subscription

proxies:
  - name: "Free-SS-01"
    type: ss
    server: ss.example.com
    port: 443
    cipher: aes-256-gcm
    password: "yourpassword"

# Rule sets – route traffic to the proxy for certain domains

rules:
  - DOMAIN-SUFFIX,google.com,Free-SS-01
  - DOMAIN-KEYWORD,github,Free-SS-01
  - GEOIP,CN,DIRECT
  - MATCH,Free-SS-01

```

ClashX automatically writes the subscription data to `~/.config/clash/config.yml`. You can place custom rules under the `rules:` section, but changes made outside the Managed Config interface may be overwritten on the next subscription update.

## Daily Usage and Proxy Selection

Once configured, operate ClashX through the menu bar icon:
- Click **Proxy** → Select **Auto** for automatic node selection, or choose a specific server
- Ensure **Mode** is set to **Rule** so only blocked domains route through the proxy while domestic sites connect directly

When **Rule** mode is active, ClashX matches requests against its domain lists. Traffic to sites like Google or GitHub automatically flows through the selected node, while local Chinese services bypass the proxy for better speed.

## Known Limitations

Current versions of ClashX have specific protocol restrictions. According to the troubleshooting section in [`macos/ClashX.md`](https://github.com/bannedbook/fanqiang/blob/main/macos/ClashX.md)【5†L65-L66】:

- **No VLESS Support**: ClashX does not support the V2Ray **vless** protocol. Subscription nodes using vless will appear as failed or unavailable within the proxy list.

Users requiring VLESS support must use alternative clients such as V2RayU (also documented in the repository at [`macos/V2RayU.md`](https://github.com/bannedbook/fanqiang/blob/main/macos/V2RayU.md)).

## Summary

- **ClashX** is a native macOS GUI for the Clash proxy engine, supporting Shadowsocks and V2Ray/VMess protocols as detailed in [`macos/ClashX.md`](https://github.com/bannedbook/fanqiang/blob/main/macos/ClashX.md)
- Installation requires dragging the DMG to `/Applications` and authorizing the helper daemon【5†L34-L48】
- Configuration relies on **Managed Config** subscription URLs rather than manual file editing
- The application defaults to ports **7890** (HTTP) and **7891** (SOCKS5) with a **Rule**-based routing mode
- **VLESS protocol is unsupported** and will cause connection failures【5†L65-L66】

## Frequently Asked Questions

### How do I update my proxy nodes in ClashX?

Click the ClashX menu bar icon, navigate to **Configuration → Managed Config**, and select **Update**. This fetches the latest node list from your subscription URL without requiring manual configuration file edits.

### Why does ClashX ask for my administrator password?

The application requires elevated privileges to install a **helper daemon** that modifies macOS system proxy settings【5†L46-L48】. This allows ClashX to intercept and route all HTTP/HTTPS traffic through the selected proxy node. The password is required only during initial setup.

### Can I use ClashX with a manual configuration instead of a subscription?

Yes, though the repository recommends subscription-based workflows. You can manually edit `~/.config/clash/config.yml` following the YAML format shown above. However, avoid changing the default ports (7890/7891) unless necessary, as this may break the system proxy integration【5†L75-L76】.

### What should I do if some websites still won't load?

First, verify you are in **Rule** mode and have selected an active node. If specific sites fail, the node may use the **vless** protocol, which ClashX does not support【5†L65-L66】. Try switching to a different server or use **Global** mode temporarily to force all traffic through the proxy for testing purposes.