Step 1: Import a Subscription or Local YAML File
Open the client and go to Profiles or Subscriptions in the sidebar. Look for an option such as New, Add, or Import. For a remote subscription, choose import by URL, paste the full link from your provider, then click Download or Save. Give it a recognizable name, such as “Everyday,” to tell it apart from other entries. The name doesn’t change the nodes or rules. If the URL contains access parameters, keep them intact; don’t copy the title or description of a web page displaying the link.
Wait for the download to finish and check that the entry shows a success status. Then click Use, Activate, or the equivalent selection button. Some clients activate a profile as soon as it’s imported; others only add it to the list. The real test isn’t whether the entry appears, but whether its policy groups and nodes show up on the Proxies page. Check that they’ve loaded before moving on.
If you have a file, choose Import Local File on the same page and select a config with the .yaml or .yml extension. Don’t convert it to an image, web page, or rich-text file, or simply rename another subscription format to make it look like YAML. If the client has a config checker, run it first. Field names and line numbers in an error message are usually more helpful than a generic “import failed” notice.
What to Check When an Import Fails
First, check whether the link downloads on your current network and returns a compatible config—not a login page, expiration notice, or web error. Then confirm that your provider offers a Clash subscription URL rather than one for another format. If you can’t reach the subscription URL right now, ask your provider for a local config instead of repeatedly changing your system proxy. For YAML indentation and common fields, see the config field reference.
Updating a subscription fetches its remote contents again. During your first connection, leave the imported config unchanged; don’t rush to edit the original file. If you later need to keep custom rules, use the client’s override feature. See overrides and merging to avoid losing local changes during future updates.
Step 2: Choose Rule Mode and an Outbound Route
Once the config is active, open the client’s Proxies page or the mode menu from its menu bar icon. For a first setup, choose Rule mode, sometimes shown as Rule. In this mode, the core uses the config’s rules to decide whether each request connects directly, is rejected, or goes through a policy group. It doesn’t send all traffic through one node, so different websites using different routes is normal.
Expand the main policy groups and check the current selection. Group names come from the config author: they might be “Proxy Selection” or “Auto,” or something else entirely. Don’t infer a group’s purpose from its name alone. Find the select group referenced by your rules and assign an available node, or use an automatic-selection group included in the config. If a group is set to DIRECT, matching requests connect directly. Only a remote node or a valid group containing nodes sends those requests through a proxy.
Node tests offer a quick connectivity check, but a successful test doesn’t mean every website will load, and a failed test needs to be considered alongside the test URL and your current network. For your first setup, manually select a node you know works and keep it selected while testing. Avoid changing DNS, reordering rules, or replacing policy groups at the same time; otherwise, it’s hard to tell which change caused a problem.
| Mode | How Requests Are Routed | When to Use During Initial Setup |
|---|---|---|
| Rule / Rule | Routes requests according to the matching rule. | Everyday use and initial testing. |
| Global / Global | Requests that reach the core use the global policy selection. | Temporarily check whether rules affect the result. |
| Direct / Direct | Requests that reach the core usually connect straight to their destination. | Compare access over your local network. |
“Global” describes how requests are handled after they reach the core; it doesn’t automatically route traffic from every app on your computer. Whether an app sends requests to the client depends on the system proxy, the app’s own settings, or TUN. You don’t need to configure automatic selection, failover, or load balancing in policy groups for your first connection. See policy group fields later.
Step 3: Start the Core and Enable the System Proxy
Return to the client’s main screen and make sure the core is running. Some clients start it automatically after a config is imported; others require you to click Connect or Start. If you see a config error, port conflict, or core startup failure, fix it before enabling the system proxy. The system proxy directs app requests to a local listening address. If nothing is listening there yet, the browser will send requests to a port with no service to handle them.
Find and enable the System Proxy toggle. It may be in Settings, a quick-access area on the home screen, or the menu bar menu. If macOS or the client asks to install a helper service or authorize network changes, check which app is making the request and why, then follow the prompts. Helper names and authorization steps vary by client; don’t look for a button that isn’t in your interface just to match this guide.
Open macOS System Settings, go to Network, select the active Wi-Fi or Ethernet service, then open Details and Proxies. On older macOS versions, these options may be under Network > Advanced in System Preferences. Check that the web proxy and secure web proxy addresses and ports match the client. If the client has a SOCKS proxy configured, check that entry too. A common local address is 127.0.0.1, and 7890 is an example mixed port; use the values in your actual config.
Keep system-level proxy controls in other proxy apps off while testing to prevent them from repeatedly changing the same network settings. Work-managed proxies, VPNs, and security software may also affect routing and DNS, so follow your network administrator’s requirements. Don’t enable TUN yet; move on to the browser test first. This order helps isolate system proxy issues from virtual network interface issues.
Step 4: Test Browser and Terminal Connections Separately
In Safari or another browser that uses system proxy settings, open an HTTPS site you want to access, then try a site that normally connects directly for comparison. A page loading is only the first check. Also open the client’s Connections or Logs page, retry the request, and look for the domain, matched rule, selected policy group, and outbound route. Connection entries may disappear quickly, so refresh the page and check the log right away if needed.
If your browser has a separate proxy extension, make sure it isn’t overriding system settings. A site matched by a direct-connection rule may not use a remote node even when the client is working correctly. Don’t assume the proxy is broken just because the outbound IP hasn’t changed. Check the site’s matched rule and confirm that the result is what the config intends. See rule syntax for how rules are matched in order.
Check Proxy Settings for the Current Network Service
Open Terminal and run these commands to read system network service settings without changing the proxy. List the service names first, then replace Wi-Fi in the following commands with the name of your active service. The enabled status, server address, and port should match the client. This confirms the system settings were applied, but doesn’t prove that a remote node is working.
networksetup -listallnetworkservices
networksetup -getwebproxy "Wi-Fi"
networksetup -getsecurewebproxy "Wi-Fi"
networksetup -getsocksfirewallproxy "Wi-Fi"Use an Explicit Proxy to Check Local Listening and System Routing Separately
Terminal tools don’t necessarily use the macOS system proxy. The command below explicitly tells curl to send a request through the local HTTP proxy, so you can check the listening port and the connection chain separately. Before running it, confirm the actual HTTP or mixed port. Replace 7890 if yours is different. The destination is a public example domain; results also depend on your network, node, and the destination service.
curl --proxy http://127.0.0.1:7890 --connect-timeout 10 -I https://example.com/If curl can’t connect to the local port, check the core and listening address in the client. If the local connection succeeds but the remote request times out, check the node, policy group, and destination network. A valid HTTP response means the request reached an HTTP service, but check the connection log to confirm the route. If the browser works but curl fails without an explicit proxy option, check terminal proxy settings before reinstalling the client.
Set a Proxy for the Current Terminal Session
To route supported command-line tools through the proxy, run these commands in the current shell. HTTPS requests still travel through an HTTP proxy tunnel, so the proxy URL uses http://. These settings affect only the current shell and child processes started afterward; they don’t change terminal tasks that are already running. Support for these environment variables varies by tool.
export http_proxy="http://127.0.0.1:7890"
export https_proxy="http://127.0.0.1:7890"
export no_proxy="localhost,127.0.0.1,::1"
curl --connect-timeout 10 -I https://example.com/Confirm that the settings work in the current session before adding them to a shell config file. Don’t append them to multiple startup files right away, or they may remain set after you quit the client. At this point, you’ve tested browser requests, system proxy settings, and an explicit proxy request separately. If a target app still ignores the system proxy, consider the TUN steps below.
Optional: TUN Mode and Permissions
TUN routes requests through a virtual network interface and is useful for apps that don’t use the system proxy. It’s a separate layer from Rule, Global, and Direct mode: TUN determines how requests reach the core, while proxy mode determines the outbound route once they’re there. TUN support, network stack options, and helper service installation vary by client and core. Clients using the mihomo core may also expose different settings.
After you’ve verified the system proxy, open the client’s Network or Advanced settings and look for TUN mode or a similar option. If the interface asks you to install a service mode or privileged helper, authorize it as prompted before enabling TUN. Don’t manually copy routing commands from the internet. For the first run, keep the client’s default network stack and routing settings, open the target app, and check the connection log to confirm its requests reach the core.
If enabling TUN causes DNS problems, blocks access to local devices, or conflicts with another VPN, turn it off and return to the system proxy setup you’ve already verified. Then change one setting at a time. An enabled toggle doesn’t guarantee that all traffic is being routed; app protocols, excluded routes, and system permissions all affect the result. For details on DNS, routing, and YAML structure, see the YAML guide. You don’t need to change everything to get started.
Platform Notes: Windows App Loopback
This section applies to Windows only. Some apps that use AppContainer isolation may be restricted from accessing a local loopback proxy. The browser may work while a specific app still can’t connect. This is different from proxy permissions on macOS: Mac users don’t need to look for a UWP loopback setting or run Windows exemption commands.
On Windows, first make sure the same local proxy port works in a standard desktop app, then check whether the target app is restricted from loopback access. If the client includes a “Loopback Exemption” tool or similar feature, follow its instructions and grant exemptions only to apps that need to access the local proxy. Save your changes, then fully quit and restart the target app. If the client doesn’t include this tool, that doesn’t mean all Windows apps can’t use a proxy—and a loopback exemption isn’t a universal fix.
A loopback exemption only grants an app permission to access a local address; it doesn’t replace subscription import, node selection, or system proxy setup. If the app still fails, check whether it uses the proxy, whether it relies on UDP, and whether the current config allows that traffic. To get a Windows client, choose one from the Windows download page. You don’t need to change your working Mac setup.
Quit the Client and Restore Network Settings
When you’re done testing, turn off TUN and the system proxy in the client before quitting. This prevents system network settings from pointing to a port where the local listener has stopped. Closing the main window may only hide the client in the menu bar, not quit it. Use the menu bar’s Quit command to stop it; the exact behavior depends on the client’s settings.
If the client quits unexpectedly and your browser can’t connect, check the proxy settings for your active network service. Look for HTTP, HTTPS, or SOCKS proxies still pointing to a local address. Remove only entries you’ve confirmed were set by the client; don’t delete a proxy address or automatic proxy config required by your work network. If you set terminal environment variables, clear them in that session or close it and open a new terminal.
unset http_proxy https_proxy all_proxy no_proxy
unset HTTP_PROXY HTTPS_PROXY ALL_PROXY NO_PROXYIf you added variables to a startup file such as ~/.zshrc, running unset won’t stop them from loading in new sessions. Remove the lines you added as well. Once settings are restored, test the browser and terminal separately. Keep a copy of a config you’ve verified, and change one thing at a time when updating subscriptions, adding rules, or enabling TUN. To continue customizing, start with config overrides instead of replacing the entire subscription file.