Before You Begin: Install the Client and Preserve Existing Settings
Start on the client download page and choose an installer that matches your device's operating system and processor architecture. Install it and open the main interface. The client handles configuration management, the UI, and system integration; the core handles proxy connections, rules, and DNS. A successful installation only prepares the tools—it does not provide usable nodes. You still need a configuration you are authorized to use, from a trusted source, and compatible with the current core.
Before the first setup, open a site you normally access directly while no proxy is enabled, and confirm that local Wi-Fi, mobile data, or Ethernet is working. Complete any network sign-in page first. Record the system's existing proxy settings, and export or back up current client settings if available. Disconnect other proxy tools cleanly so multiple programs do not rewrite the system proxy or compete for the VPN connection.
When preparing a subscription, confirm whether the provider supplied a complete Clash-compatible YAML file, a plain node list, or a single node share link. They may use different import options. A subscription URL may contain account identifiers and should not appear in public screenshots, issue reports, or online conversion tools. This guide covers only the steps required for a first connection; see the Complete Configuration Reference for DNS, rule syntax, and configuration merging.
Step 1: Import the Subscription and Make It Active
Open the client's Configuration, Subscription, or “Profiles” page and find New, Add, or Import. For a remote subscription, choose the URL option and paste the complete link into the address field. If a name is supported, use a recognizable name such as “Daily Configuration.” Before submitting, check for extra spaces, line breaks, or punctuation added by a messaging app at either end. Then save or import and wait for the client to download and parse the file.
After a successful import, the configuration list will usually show a new entry, perhaps with an update time or update control. An entry appearing does not necessarily mean it is active: click it or use an adjacent Use, Activate, or Set as Current Configuration action until the interface clearly marks it as selected. Then open the proxy page and confirm that the configuration's policy groups and options are visible. A download-complete message alone does not prove that the core accepted every field.
Use the File Import Option for Local YAML
If you already have a local configuration file, choose Import from File on the same page and open the actual YAML file with the system file picker. Do not paste YAML into the subscription URL field, and do not treat ordinary text as a compatible configuration merely by changing its extension. If the client references the file instead of copying it, keep it in a stable directory and do not move or delete it after importing.
A complete configuration usually contains structures such as nodes or node providers, policy groups, and rules, but not every subscription writes nodes directly into the main file. With a remote provider, linked resources may also need time to update. If policy groups are empty after the configuration loads, first check whether it depends on other resources and whether those resources failed to load, rather than immediately adding unknown fields by hand.
If Import Fails, First Separate Download Errors from Parsing Errors
For timeout or connection-failed messages, first confirm that the link can be fetched on the current network and that the subscription is still valid. For YAML parsing errors or unknown-field messages, record the field name and line number. A login page, error page, or plain node list returned by the server may also be read as a configuration and trigger an error. A URL opening in a browser does not mean its response is a usable configuration, and credential-bearing links should never be sent to public testing sites.
Keep the original file for now instead of clearing the client's data. Ask the provider about the subscription format and supported core, or read the difference between subscription URLs, complete YAML files, and share links to choose the correct import option. After the first import, avoid overly frequent automatic updates. Confirm that the configuration works, then set an update interval and keep local changes in a separate override so the next update does not overwrite them.
Step 2: Choose a Rules Mode and Proxy Exit
Keep the newly imported configuration selected and find the Mode menu on the home, proxy, or settings page. For a first setup, choose Rules or “Rule.” This lets the core use the configuration's rules to decide whether each connection goes direct, through a proxy policy group, or is rejected. It suits complete configurations that already include routing rules. If the import contains only nodes and lacks rules and policy groups, add a compatible configuration first rather than expecting a mode switch to create routing automatically.
The other two common modes are Global and Direct. Global mode generally sends traffic that has already reached the core through the global policy, but it does not automatically intercept applications that bypass the client. Direct mode mainly lets intercepted connections access their destinations without a proxy. These modes can narrow down troubleshooting, but they do not replace correct rule settings. Mode selection and traffic interception are separate steps: choosing Global does not mean every program on the system is using the proxy.
Confirm the Active Exit in the Policy Group
After selecting the rules mode, open the Proxy or Policy Groups page. Based on the group names in the configuration, find the group responsible for ordinary proxied traffic. It may be called Proxy Selection or “Proxy,” or use a provider-defined name. Expand it and select a valid node you are authorized to use. If the group contains another policy group, inspect its current selection too, until it is clear which node, auto-select group, or direct policy will be used in the end.
Do not select an option just because it appears first. In particular, DIRECT means a direct connection and normally bypasses remote proxy nodes. If matching connections should use a proxy, confirm that the final exit is not direct. An auto-select group can choose a candidate according to its configured probing logic, but the candidate nodes must work, the probe address must be reachable, and the client must have loaded the relevant settings.
If the interface offers a connection test, test a candidate node once to rule out obvious failures. A successful test only means that a particular probe request completed at that moment; it does not guarantee that every site, protocol, or app will work. A failed test may also be caused by the probe address. For the first setup, keep one confirmed working exit selected so that automatic node switching does not complicate rule troubleshooting.
Use the Interface First Instead of Editing Fields
You do not need to modify DNS, TUN, and the rule list together for “optimization.” Some clients use UI settings or local overrides to replace subscription fields with the same names. As a result, a file may contain mode: rule while the interface shows another mode. Prioritize the mode that is actually active in the client. If the field and interface remain inconsistent, read the Override and Merge Guide. Start system interception only after confirming the rules mode and policy-group exit.
Step 3: Connect and Enable Traffic Interception
Return to the client home page and confirm that the core starts normally. If the interface opens but continuously reports startup failures, check the log for port conflicts, configuration-loading errors, or permission problems first. Enabling the system proxy at this point may send applications to a local endpoint that is not working. Hand traffic to the core only after it is running normally and the configuration has loaded.
Desktop: Start with Browser Verification Through the System Proxy
On Windows, macOS, or a Linux desktop client with the required integration, find and enable the System Proxy switch. This usually points the system proxy to the local listening address and port. Then open the operating system's proxy settings and inspect the actual values, confirming that the address and port match the client. If the client cannot write system settings automatically, configure them manually using its displayed listening values rather than copying a fixed port from another guide.
For example, a local app can use the HTTP proxy 127.0.0.1:7890 only when the client is actually using the mixed port 7890. These numbers are instructional examples, not a check of the device's current state. If the client changes its port, update the system or app settings accordingly. For initial local-only use, do not enable LAN access or expose the listening endpoint to other devices just to make troubleshooting easier.
The system proxy is a good first test for applications that respect that setting. Some browser extensions have their own proxy configuration, while some command-line tools, games, and apps do not read the system proxy. If a browser works but one program does not, check that program's interception method before assuming the node is unusable. On Linux, proxy settings may also be read differently across desktop environments and applications.
Mobile: Use the Connect Button to Grant System Access
On Android or iOS, confirm the configuration and policy group, then tap the Connect button on the home page. The first connection usually displays an operating-system VPN permission prompt. Confirm that the request comes from the client you just installed and intend to use, then approve it. Return to the client and wait for the connection status to change. A VPN icon means the tunnel interface is enabled; it does not by itself prove that the remote node is reachable or that every rule behaves as expected.
If the connection fails, check whether another VPN is occupying the connection slot and whether the client has per-app exclusion settings. If an Android device disconnects only when locked or in the background, review background activity and battery restrictions; there is no need to grant every system permission during the first setup. On iOS, confirm that the system authorization flow completed, then return to the client and read the error message instead of repeatedly importing the same subscription.
After completing this stage, keep the client running and temporarily avoid switching configurations, nodes, or interception methods. Next, use a set of new real requests to check the result so that each observation corresponds to the same settings.
Step 4: Verify Requests, Rules, and Access Results
Open a browser tab and visit an HTTPS site you are authorized to access and expect to match a proxy rule. Do not rely only on an already-open tab: cached content, a reused connection, or an existing session may look normal without creating a new connection to inspect. Then return to the client's Connections or Logs page and look for the requested domain and timestamp. Fields vary by client, so use the information that is actually shown.
Verify three layers: whether the request reached the core, which rule or policy group it matched, and whether the connection actually completed. If a destination record appears, first check that the exit matches the one selected in Step 2. If a direct rule matched, a working webpage does not prove that the proxy node works. If no corresponding record appears, check log filters and retention first, then determine whether the app bypassed the system proxy or was excluded from VPN interception.
Check Proxied and Direct Requests Separately
Next, visit a site expected to go direct and check how the rules handled it. When both request types behave as expected, that says more about correct routing than checking a single exit IP. An exit-IP lookup is useful as a secondary signal, but different sites may use different policies in rules mode, so one lookup cannot establish the exit used by every app. If the client provides only simplified logs, keep the destination and node fixed and compare results after changing one setting at a time.
If a webpage works but one app does not, return to Step 3 and check that app's proxy settings, browser extensions, or per-app exclusions. When logs show a resolution error, first distinguish a failure to resolve the destination domain from a failure to resolve the node server address; they occur in different places and should not both be labeled a node timeout. DNS interception and leak testing are also affected by encrypted system DNS, browser Secure DNS, and TUN routing. See the DNS Configuration section for details, but keep a reproducible record of the issue for this test.
Change Only One Variable at a Time
If every webpage stops loading after interception is enabled, first disable the system proxy or disconnect the client's VPN, then test a site that previously worked directly. If it recovers, focus next on the local listener, current configuration, and remote path. If it still fails, fix local connectivity, network authentication, or the original system settings first. Once the network is restored, verify the subscription, node parameters, and connection logs in order; reinstalling the client should not be the first step.
If only one node fails, keep the same destination and mode and compare it with a confirmed working node. If only one site fails, keep the node unchanged and inspect that site's matched rule and error type. Record only the destination, time, policy used, and a short error summary; never publish the full subscription URL or credentials. For layered troubleshooting, see the node-timeout troubleshooting order; for core-loading failures, read Configuration Validation and Troubleshooting.
Keep a Working Baseline and a Way to Exit
Once both proxied and direct requests behave as expected, save a backup of the working configuration and local settings before considering automatic updates, startup launch, or more complex rule changes. Add one feature at a time and return to this baseline if something breaks. To stop using the proxy, disable the system proxy, disconnect the VPN, or disable TUN through the client before exiting. If the network fails after an abnormal exit, check whether the system still points to a local port that is no longer listening and restore the proxy settings recorded before setup.
Back to Subscription Import · View the Client Selection Guide