V2Ray Client Configuration for macOS: Complete Setup Guide for V2rayX and V2RayU

Configure a V2Ray client on macOS using GUI wrappers like V2RayU or V2rayX by importing a subscription URL or editing the JSON configuration directly, then routing traffic through a local SOCKS5 proxy at 127.0.0.1:1080.

V2Ray is a modular proxy platform that routes traffic through configurable inbound and outbound protocols. On macOS, you typically run the V2Ray core binary through a user-friendly GUI wrapper rather than managing the command line manually. This guide covers V2Ray client configuration for macOS using the two documented clients in the bannedbook/fanqiang repository: V2rayX (legacy) and V2RayU (actively maintained).

How V2Ray Works on macOS

The V2Ray architecture separates concerns into three layers:

• V2Ray Core — The single v2ray binary that implements the proxy engine. It reads a JSON config defining inbound listeners, outbound handlers, and transport layers.
• GUI Wrapper — A macOS app bundling the core, providing system-tray controls and subscription management.
• System Proxy Integration — Optional macOS network settings to tunnel all traffic through the local V2Ray port.

According to the repository documentation, the core binary handles protocols like vmess, vless, trojan, and shadowsocks via outbound handlers, while inbound listeners expose local SOCKS5/HTTP proxies that macOS applications connect to.

Choosing Your Client: V2RayU vs. V2rayX

The bannedbook/fanqiang repository documents two macOS clients at different maintenance levels:

Client	Status	Documentation Path
V2RayU	Actively maintained, simpler workflow	[macos/V2RayU.md](https://github.com/bannedbook/fanqiang/blob/master/macos/V2RayU.md)
V2rayX	Legacy, outdated	[macos/V2rayX.md](https://github.com/bannedbook/fanqiang/blob/master/macos/V2rayX.md)

For new installations, V2RayU is recommended. The repository notes that V2rayX's tutorial remains available for reference but is no longer updated.

Installing V2RayU and Importing a Subscription

V2RayU streamlines V2Ray client configuration for macOS through subscription-based node management. The repository maintains a public list of free V2Ray accounts that can serve as your subscription source.

Step-by-Step Subscription Setup

1. Download and install V2RayU from the releases page (typically via Homebrew Cask or direct DMG).

2. Open V2RayU → click the ⚙️ Settings button in the system tray menu.

3. Navigate to Subscribe → paste your subscription URL.

4. Click Update — the app fetches the node list and populates the Servers section.

The subscription URL format is a plain text list containing base64-encoded vmess://... or vless://... links. The repository's free account list is documented at the v2ray免费账号 Wiki.

Manual JSON Configuration

For advanced users or custom server setups, both V2RayU and V2rayX support hand-editing the JSON configuration. The core configuration requires three sections: inbounds (local proxy), outbounds (remote server), and optional routing rules.

Minimal Working Configuration

{
  "inbounds": [
    {
      "port": 1080,
      "listen": "127.0.0.1",
      "protocol": "socks",
      "settings": {
        "auth": "noauth",
        "udp": true
      }
    }
  ],
  "outbounds": [
    {
      "protocol": "vmess",
      "settings": {
        "vnext": [
          {
            "address": "your.v2ray.server",
            "port": 443,
            "users": [
              {
                "id": "YOUR-UUID-HERE",
                "alterId": 64,
                "security": "auto"
              }
            ]
          }
        ]
      },
      "streamSettings": {
        "network": "tcp",
        "security": "tls"
      }
    }
  ]
}

Configuration File Locations

Save your config.json to the appropriate directory for your client:

• V2RayU: ~/Library/Application Support/V2RayU/
• V2rayX: ~/Library/Application Support/V2rayX/

The GUI automatically reloads when you click Restart. Both paths are documented in [macos/V2RayU.md](https://github.com/bannedbook/fanqiang/blob/master/macos/V2RayU.md) and [macos/V2rayX.md](https://github.com/bannedbook/fanqiang/blob/master/macos/V2rayX.md) respectively.

Configuring System-Wide Proxy on macOS

Once your V2Ray client configuration for macOS is running, enable system-wide traffic routing through the local SOCKS proxy.

Via System Settings

1. Open System Settings → Network → Wi-Fi → Details → Proxies
2. Enable SOCKS proxy
3. Enter 127.0.0.1 and port 1080 (or your configured inbound port)

Via Command Line

# Check current proxy settings

scutil --proxy

# Enable SOCKS5 proxy for Wi-Fi interface

networksetup -setsocksfirewallproxystate Wi-Fi on
networksetup -setsocksfirewallproxy Wi-Fi 127.0.0.1 1080

# Disable when finished

networksetup -setsocksfirewallproxystate Wi-Fi off

Applications that respect macOS system proxy settings will now tunnel through V2Ray. Note that some apps (particularly command-line tools) require explicit proxy environment variables:

export ALL_PROXY=socks5://127.0.0.1:1080

Server-Side Configuration Reference

Understanding the server configuration helps debug client issues. The repository includes reference files in v2ss/server-cfg/:

• v2ss/server-cfg/v2ray.service — Systemd service definition showing core startup options
• [v2ss/server-cfg/v2ray_check.sh](https://github.com/bannedbook/fanqiang/blob/master/v2ss/server-cfg/v2ray_check.sh) — Health-check script demonstrating the "restart if down" pattern applicable to client stability

These files illustrate how the same v2ray binary operates on both sides of the connection.

Troubleshooting Common Issues

Symptom	Cause	Solution
"Connection refused" on port 1080	V2Ray core not running	Check V2RayU/V2rayX status, click Restart
Subscription update fails	URL blocked or expired	Verify URL in browser, try alternative from Wiki
Slow or intermittent connections	TLS fingerprinting	Enable xtls or WebSocket transport in streamSettings

Summary

• V2RayU is the recommended macOS client for new installations, documented in [macos/V2RayU.md](https://github.com/bannedbook/fanqiang/blob/master/macos/V2RayU.md).
• Subscription URLs automate node management — the repository provides free account lists via Wiki.
• Manual JSON configuration offers full control over inbound/outbound settings and transport layers.
• Configuration files reside in ~/Library/Application Support/ under the client-specific folder.
• System-wide proxy integration routes all macOS traffic through the local SOCKS5 listener at 127.0.0.1:1080.

Frequently Asked Questions

What is the difference between V2RayU and V2rayX?

V2RayU is actively maintained with a simpler installation flow and modern protocol support, while V2rayX is legacy software that is no longer updated. The bannedbook/fanqiang repository recommends V2RayU for new users and keeps the V2rayX documentation for historical reference only.

How do I find a working subscription URL?

The repository maintains a public list of free V2Ray accounts at the v2ray免费账号 Wiki. These URLs contain base64-encoded node lists that V2RayU can import directly. Subscription availability varies; test the URL in a browser first to verify accessibility.

Can I run V2Ray without a GUI wrapper?

Yes — you can download the official v2ray core binary for macOS and run it directly with v2ray -config config.json. However, you lose convenient features like subscription auto-update, system-tray controls, and quick server switching that GUI wrappers provide.

Why does my connection fail even with correct server settings?

Common causes include: TLS certificate issues (try disabling certificate verification temporarily), transport layer mismatch between client and server (verify streamSettings.network matches), or local port conflicts (change inbounds[0].port from 1080 to an unused port like 1081).

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