First-time setup · 4 steps
Clash Getting Started.
Import a subscription → Choose a proxy mode → Connect → Verify traffic.
Start with an installed Linux desktop client. These four steps cover the controls you need for your first connection. With a subscription link from a trusted source, basic setup usually takes about 10 minutes, excluding subscription downloads, system permissions, and network troubleshooting. Haven’t installed a client yet? Choose an installer from the Linux downloads, then come back here.
This guide gets a first connection working without editing configuration files. For protocol compatibility, core families, and client trade-offs, see the protocol and core technical reference.
Step 1: Import and enable a subscription
A subscription link is how the client retrieves a configuration; it is not a regular web page to open in a browser. It may include nodes, policy groups, and routing rules, or just node details. For your first setup, use a complete Clash- or mihomo-compatible subscription that works with your client. The client does not include proxy service, so you’ll need a configuration you’re authorized to use.
Add a remote subscription and download the configuration
Open the client and find “Subscription,” “Configuration,” or “Profiles” in the sidebar or bottom navigation. Add a remote configuration. If prompted to choose between a local file and a remote link, select the remote link option. Paste the subscription URL, give it a recognizable name such as “Daily config,” then select Import, Download, or Save. Some clients save the entry first and require you to select an update button beside it. When done, the configuration name should appear; it should not remain stuck on “Downloading.”
Before pasting, check that the URL has no extra spaces, line breaks, or explanatory text added by a chat app. Subscription URLs may contain personal access credentials: don’t post the full URL publicly or hand it to an unfamiliar online conversion service. If a download fails, read the error message first. A network timeout, authentication failure, and invalid configuration format are different problems; repeatedly clicking the same update button usually won’t fix them.
Select the configuration, then check the proxy page
A successful import does not mean the configuration is active. Select the new configuration by clicking its name, radio button, or “Use” button. Look for a selection outline, current-use indicator, or confirmation that it was applied. Then open the “Proxies” page and check for policy groups and node names. If you still see the old configuration, return to the list, confirm the new one is selected, and check whether it needs to be applied manually.
If you only have a local configuration file, choose “Import file” and select the relevant YAML file, then select and apply it as above. A file extension alone does not guarantee compatibility, and a file containing only nodes may not include routing rules. If the client reports missing fields or a parsing error, ask the configuration provider about the format. Don’t delete unfamiliar sections just to dismiss the error.
You can keep the default update interval until the first connection is verified. Remote updates may overwrite edits made directly in the subscription file. If you need to keep custom rules, learn how your client handles overrides rather than re-editing after every update. For help with inaccessible subscriptions or unexpected changes after an update, see subscription questions.
Step 2: Choose a mode and node
With the configuration loaded, find the client’s mode selector. Common options are “Rule,” “Global,” and “Direct.” The mode may also appear as Rule, Global, or Direct. It determines how connections choose an outbound route; it is separate from the system proxy and TUN toggles. Choose how traffic should be routed here, then connect your apps to the client in the next step. This makes it easier to identify which layer is causing a problem.
Start with rule mode
In Rule mode, the core checks requests against the configuration’s rules in order and decides whether to connect directly, use a policy group, or take another action. It works well for everyday use, provided the configuration includes suitable rules. Rule mode does not guarantee that every site uses the proxy or that every local connection goes direct. Check the actual match in the connection log.
Global mode generally sends connections that have reached the core through the global policy group. It can be useful for a quick comparison, but it does not automatically capture traffic from apps that are not connected to the client. Direct mode sends ordinary connections that reach the core straight to their destinations; it is not the same as closing the client or clearing the system proxy. For initial setup, stick with Rule mode and configure the node and connection settings first.
Open the policy group used by the matching rules
On the Proxies page, find the main policy group provided by the configuration. Its name is chosen by the configuration author; it might be “Proxy,” “PROXY,” or something else. There’s no need to rename it to match this guide. Select a node in the group and confirm it becomes the current choice. If the group contains nested policy groups, open them until you reach an actual node—not a Direct option.
Some configurations split traffic into groups for websites, media, and other apps. Keep this structure at first and change only the main group you need. If a site matches a separate group, check that group’s selection too. An automatic group picks a node using the configuration’s test mechanism; a manual group keeps the node you select. To make troubleshooting easier, use a manual group to pin one node for the initial test. Once it works, consider automatic switching.
Node latency tests: Check reachability before the numbers
Look for a test, latency check, or refresh icon on the Proxies page and run a test. Most latency tests send a request through the node to a probe URL and report how long it takes—not download bandwidth. A timeout means the probe did not complete; the probe URL, name resolution, or temporary network conditions may be to blame. A low latency result also does not guarantee that every site will load smoothly.
Start with a node that responds, then test it with a real website. Avoid running repeated batch tests while browsing, and don’t switch constantly over differences of a few milliseconds. If every node times out, go back to step 1 and confirm the configuration was applied and the subscription is still valid, then use the troubleshooting guide. For protocol names and mihomo compatibility, see the core technical reference; there’s no need to change protocol settings here.
Step 3: Connect and enable the system proxy
You now have an active configuration, Rule mode selected, and a node chosen. Next, route app traffic through the client. Check the home screen’s running status. If there is a separate Start button, start the core; if the client is already running, there’s no need to start it again. If you see a specific error, such as a configuration load failure or a port conflict, fix it first. An open window alone does not mean the core is working.
On desktop, enable the system proxy first
Find “System Proxy” in Settings, a home-screen toggle, or the system tray menu, and turn it on. The client will try to set the desktop environment or operating system proxy to its local listening address. Then reopen your browser or make a new request. Existing long-lived connections may keep using their old route, so don’t judge the toggle by a page that has been playing continuously.
On Linux, desktop environments and apps differ in how they use the system proxy. Check the proxy settings in GNOME or KDE system settings, but note that some terminal programs, self-contained apps, and programs with their own network settings won’t follow them automatically. A browser proxy extension may also override system settings. For your first test, use a browser known to follow the system proxy and temporarily disable its proxy extensions to avoid conflicts.
On Windows and macOS, use the system proxy for the initial test as well. If another proxy client or VPN is running, quit the one you don’t need to prevent the tools from competing over settings. Minimizing another app usually does not stop its service. Don’t change the listening port, DNS, and several network toggles at once; change one thing at a time so you can tell what worked.
On mobile, approve the system VPN request
Android and iOS clients generally create a system VPN tunnel when you tap Connect on the home screen. The first time, the system may ask to add a VPN configuration or allow the connection. Check which app is making the request before approving it. This VPN is the system’s way of routing traffic; it does not mean the subscription is configured correctly. After granting permission, confirm the selected configuration and node, and check that the system shows an active connection.
Android battery-saving settings may pause the client when the screen is off. Complete step 4 in the foreground first and confirm the connection works, then allow background activity if needed. If another VPN is already connected, Android may ask to replace it. Before switching, check whether your work or campus network depends on that connection.
TUN mode: Enable it only when needed
If your browser works but a target app ignores the system proxy, consider TUN. It uses a virtual network interface to capture more connections. What it captures depends on routing, exclusions, and the client implementation; it is not a universal switch that makes every app work. Desktop clients may require a helper service or administrator permission. On Linux, TUN also involves virtual interfaces, routing, and permissions, so one client’s authorization steps may not apply to another.
Use only the service installation or authorization options provided by your client, and read the system prompt before confirming. If enabling TUN fails, check the logs for the specific permission or interface error. Don’t copy privilege-escalation commands from unfamiliar websites. If the system proxy is enough for your first connection, leave TUN off for now. If TUN conflicts with another VPN, a container network, or local development tools, disable it to restore connectivity, then check the relevant troubleshooting category.
Step 4: Verify requests and routing
A lit connection button only tells you that part of the client is running. Use real requests to verify the route. Open a browser and visit a site you normally use that is accessible on your current network, then try a destination that should use the proxy according to your configuration. To reduce the effect of cached content, open a new private window or refresh the page. Don’t rely on an old tab or assume a slow-loading page is automatically a node problem.
Check connection logs, not just the status icon
Open the client’s “Connections” page and watch for new entries while making a request. Find the domain you just visited and check the matched rule, policy group, and actual outbound chain. In Rule mode, some requests going direct is expected. Requests that should use the proxy should enter the intended policy group and ultimately use the node you selected. The group name is not necessarily the final outbound; expand the chain if needed.
If no entry appears, first confirm that the browser made a new request. Then check whether the system proxy is enabled, whether the browser uses system settings, and whether a proxy extension is still handling traffic. Some clients show only active connections, so a short request may disappear quickly; watch the page while refreshing. If an entry appears but the request fails, check the node and logs. There’s no need to change the system proxy port first.
If the log shows an unexpected policy group, return to step 2 and adjust that group instead of switching only the most prominent group on the home screen. If a destination matches a Direct rule when you expected it to use the proxy, first check the configuration author’s intended rules. Avoid adding broad rules when you’re just getting started. Learn more about rule order and matching in the technical reference alongside your current configuration.
Troubleshoot one layer at a time
Check in this order: configuration applied → core running → app connected → policy selected → destination responds. If there are no policy groups, return to the subscription. If the core reports an error, read its startup message first. If a request never reaches the client, check the system proxy or app settings. If it reaches the client but fails, try another responsive node for comparison. If only one site has a problem, the destination service itself may be at fault; don’t reset the entire configuration based on that alone.
Use logs to identify the type of error; you don’t need to enable the most detailed logging level and leave it running from the start. When asking for help, include your operating system, client name, connection method, and whether all apps or just one app fails. Before sharing a screenshot, hide subscription URLs, node addresses, credentials, and personal browsing records. If a Windows Store app alone cannot connect, see the UWP loopback guide; don’t mistake one app’s connection issue for a failure of all nodes.
Once verified, enable everyday conveniences
After confirming that websites load and connection logs show the expected routes, enable options such as launch at startup, automatic subscription updates, or tray mode if needed. Check whether closing the window quits the app or minimizes it to the tray so you don’t assume the connection has stopped. If an update changes policy group names, check the default selection again; don’t assume the same outbound will remain selected after every update.
You should be able to clearly describe the final setup: which configuration is in use, which mode is selected, whether apps connect through the system proxy or TUN, and what the main policy group is set to. Knowing these four things gives you a starting point when changing networks or troubleshooting. To switch clients, see the client comparison. For specific issues such as subscription updates or app connectivity, check the FAQ; you don’t need to read the full technical documentation for everyday use.