The system proxy determines whether an app sends requests to v2rayN; the routing mode determines whether requests that reach it go direct or through a proxy node. For everyday browsing, start with “Set system proxy automatically” and a Bypass mainland China routing preset. You can configure a local proxy separately for development tools. This guide explains the three system proxy options, where to check them in macOS, how to test them in Terminal, and how to restore your settings when you’re done.
System Proxy vs. Global Routing: Two Separate Settings
v2rayN is a desktop client for managing subscriptions, nodes, and core settings. Importing a subscription and selecting a node prepares a proxy egress route, but it doesn’t mean every app will use it. A browser must first send requests to a local listening port before the core can apply routing rules.
The macOS system proxy is an entry-point setting: it adds a proxy server and port to a network service’s proxy configuration. Apps that follow system settings use these values to connect to the local proxy; apps with their own network stack or proxy settings, or ones configured to connect directly, may not. “Global” is a separate setting: it usually means requests that have reached the proxy core are routed through the selected node. It does not automatically take over the entire Mac.
| Setting | What it controls | What it does not guarantee |
|---|---|---|
| System proxy | Where apps that follow system settings send requests | It does not guarantee that every process or UDP traffic is captured |
| Global routing | Regular requests that reach the core use the proxy egress route | It does not automatically reroute apps that are not connected to the proxy |
| Bypass mainland China routing | Whether traffic goes direct or through a proxy, based on domain, IP, and other rules | It does not guarantee that every service in mainland China will be identified correctly |
| TUN mode | Captures more IP traffic through a virtual network interface | It does not replace DNS, route exclusions, or permission settings |
v2rayN’s Three System Proxy Options: Set, Clear, and Leave Unchanged
Check the system proxy option in the status bar at the bottom of v2rayN’s main window or in its tray menu. The location and wording can vary slightly between desktop builds. Common options are “Set system proxy automatically,” “Clear system proxy,” and “Do not change system proxy.” These options change system settings, not subscription data.
Set system proxy automatically
RecommendedThe client adds the local proxy address to system settings. The core must be running, with a valid listening address and port. Choose an appropriate routing preset as well to determine which requests go direct and which use the proxy.
Best for: everyday browsing and desktop apps that follow system proxy settings
Clear system proxy
Removes system proxy settings managed by the client. This does not stop the local core or guarantee that tools with manually configured proxy addresses stop using the proxy. Any active TUN setup must be handled separately.
Best for: restoring a direct connection and troubleshooting connection issues after closing the client
Do not change system proxy
Leaves the system proxy as it is; it does not enable or clear it. If a local proxy address was already set, choosing this option won’t remove it. This is not the same as direct mode.
Best for: managed network configurations or configuring a proxy only for development tools
How to disable the system proxy: choose Clear, not Do not change
If you switch from Set system proxy automatically to Do not change while the system still points to a local port, apps may continue to use the proxy. To restore a direct connection, clear the proxy first, then check its actual status in macOS network settings.
A company network may already use an automatic proxy configuration script or a fixed proxy. Before making changes, note the original address, port, and enabled status. Clearing the client’s proxy settings won’t restore the configuration required by your company. On managed devices, follow your organization’s network requirements and avoid overwriting settings without checking first.
Global vs. Bypass Mainland China: Check the Rules, Not the Option Name
The Bypass mainland China preset typically routes local network traffic, some domains in mainland China, and IP addresses in mainland China through a direct connection. Other requests use the proxy. The exact behavior depends on the preset’s rules, their order, and the databases in use. Xray routing rules are generally checked in order, so a specific rule near the top can take precedence over a broader rule below it.
- Global routing: Useful for quickly checking whether a problem is caused by routing rules. If Global works but Bypass mainland China doesn’t, check domain matching, DNS resolution, and the direct outbound route before reinstalling the client.
- Bypass mainland China: Useful when you need both access to services in mainland China and a proxy for other sites. It depends on routing data; if a domain in mainland China uses an overseas content delivery address, domain and IP rules may route it differently.
- Local network access: Printers, routers, and local development services usually need an explicit direct route. After switching to Global, check that local network exclusions are still in place; don’t rely on the mode name alone.
- DNS behavior: Whether a domain is resolved before matching, and which resolver is used, can affect IP-based rules. Bypass mainland China isn’t an automatic fix for DNS failures or DNS leaks.
geosite:cn represents a collection of domains, while geoip:cn represents a collection of IP addresses. geoip:private is commonly used for private address ranges. These aren’t universal strings you can enter in any interface: graphical routing editors and native core JSON use different field formats, so follow the requirements of your current editor.
Settings for Two Common Workflows
Everyday Work and Web Browsing
- Set the system proxy automatically.
- Choose Bypass mainland China routing and check that local network traffic goes direct.
- Test a work site and a site that requires a proxy separately.
- If an internal site has issues, check the domain rules and company DNS first.
Development and Individual Commands
- Clear any existing system proxy, then choose Do not change.
- Specify the local proxy in the command arguments or tool settings.
- Compare direct and proxied results for the same URL.
- Don’t post terminal output containing subscription credentials in public channels.
First decide which apps need a proxy, then choose where their requests should go. This makes troubleshooting easier than changing the system proxy, routing, and TUN settings all at once.
Set It Up on Your Mac: Check the Listening Port and System Settings
Download the v2rayN package for your chip from the download page, then import your subscription and update the groups using the setup guide. The ports below are examples for showing what to check, not defaults for every version. Use the listening configuration shown in your current client.
- Check the node and core. Select a working node and check the logs for configuration errors or port conflicts. The node’s remote port and the local inbound port are different; don’t enter the node’s port 443 as the system proxy port.
- Check the local listener. In “Settings” → “Parameter settings,” check the local listening port and protocol. The section names may vary by build. The examples below assume
127.0.0.1:10808accepts HTTP proxy requests. Adjust them if your port is different or supports SOCKS only. - Enable the system proxy. Choose Set system proxy automatically, then select Bypass mainland China routing. For your first test, leave TUN off to reduce variables.
- Check macOS. Open “System Settings” → “Network” → your active network service → “Details” → “Proxies.” Check whether Web Proxy, Secure Web Proxy, or SOCKS Proxy is enabled, along with its server and port. Don’t rely on the client icon alone.
- Test each route. Open a work site in mainland China, a site that requires a proxy, and a local network address. Check the core logs to see which outbound route each request uses. Recheck after switching between Wi-Fi and Ethernet, since proxy settings are tied to network services.
Test from Terminal: Check System Settings, Proxy Connectivity, and the Destination Separately
Terminal apps don’t always read the macOS system proxy settings automatically. If a browser can open a site but curl can’t, that doesn’t necessarily mean the node is at fault. The commands below check system status, connect directly without a proxy, and connect through an explicitly specified proxy. They don’t change your network settings.
# Show the current system proxy configuration
scutil --proxy
# Ignore proxy environment variables and send a direct request to the same address
curl --noproxy '*' --connect-timeout 10 -I https://example.com
# Assume 10808 is a local proxy port that supports HTTP
curl --noproxy "" --proxy http://127.0.0.1:10808 --connect-timeout 10 -I https://example.com
# If this listening port supports SOCKS, test the SOCKS route separately
curl --noproxy "" --proxy socks5h://127.0.0.1:10808 --connect-timeout 10 -I https://example.comexample.com is a sample domain for demonstrating the syntax. When troubleshooting, replace it in both commands with the same address you want to check. Here, 10 is the connection timeout in seconds, not a speed test result. An HTTP error status may still mean the connection was established; check whether the response came from the destination service or the proxy.
- Local port refuses the connection: First check whether the core is running and whether the port is correct. Don’t start by changing DNS.
- Explicit proxy works, but the browser doesn’t: Check the system proxy address, the browser’s own proxy settings, and whether an old connection is still active.
- HTTP fails, but SOCKS works: Check which protocols the inbound listener supports. Don’t use a SOCKS-only port as an HTTP proxy port.
- Global works, but Bypass mainland China doesn’t: Check which outbound route the request matched in the routing logs, especially direct rules and domain resolution.
socks5h sends the destination domain to the SOCKS proxy to resolve. That differs from resolving the domain locally in Terminal. This can help narrow down DNS issues, but one successful test doesn’t prove that every app resolves domains the same way.
FAQ: Stale Settings, Development Tools, and TUN
Why can’t I open any websites after closing v2rayN?
First check whether the system proxy still points to a local port that is no longer running. If you can reopen the client, clear the system proxy before closing it. If you can’t, go to “System Settings” → “Network” → your current service → “Details” → “Proxies” and check for entries left by the client. Restore any company proxy settings using the details you recorded earlier.
Why am I still using a proxy node after choosing Do not change system proxy?
This option only leaves the current settings as they are. Clear the system proxy first, then check the app’s own proxy address, terminal proxy environment variables, and TUN status. Existing connections may also keep using their original route; if needed, restart the app you’re testing and check again.
What if my browser works but my development tools don’t use the proxy?
Enter the local proxy address in the tool’s network settings, or test it first with the explicit curl options above. Don’t assume every command-line tool reads system settings or supports the same proxy environment variables.
Does enabling TUN mean I can ignore the system proxy?
TUN can capture more traffic from apps that don’t follow system proxy settings, but it still depends on interface routes, permissions, DNS, and exclusion rules. For initial troubleshooting, use just one connection method. Enable TUN only if you need to capture additional apps, then check that local network access and routes to proxy servers still work.
How do I troubleshoot a slow service in mainland China after enabling Bypass mainland China?
Record the full domain and the time the issue occurred. Check the logs to see whether it used a direct or proxy route, then compare it temporarily with Global. If the service is on your company network, check company DNS and explicit direct routes for internal addresses first. Verify where the service is hosted using DNS results and the actual connection IP.
Once things are working reliably, keep a repeatable troubleshooting order: check that the local listener works, system settings are correct, the app is connected, and the routing egress matches expectations. Subscription updates address changes to node details; the system proxy controls how apps connect; routing determines where requests go. Each has a separate role, so checking them layer by layer is more effective than repeatedly reinstalling the client.