Getting Started / First Connection

Import a Clash subscription and test the connection

Install a client and get a Clash subscription URL or local YAML config ready. For your first setup, test just one app and one site to pinpoint whether a problem is with the config, traffic capture, or outbound.

Import a subscription and enable the config

On your provider's site, copy a subscription URL marked for Clash or mihomo. This URL lets the client fetch a config; it isn't a login page or a link to an individual node. If you only have a local YAML file, import it directly instead of uploading it elsewhere. Subscription URLs may contain access credentials. When sharing a screenshot or asking for help, include the error message but never the full URL or config.

Fetch from a URL or load a file

Open the client's “Config” or “Subscription” page, click Add, and choose Import from URL. Paste the full URL and click Import or Save; wait for the config to appear in the list. If adding and updating are separate actions, click Update on the new entry and check that it downloads or parses successfully. To import a local file, choose Import from file in the same menu, then select the YAML file from your provider.

If fetching fails, start with the client's error: for a timeout, check that your device is online and ask your provider whether the URL is reachable on your current network. For an authorization error or expired link, return to the original provider for a valid URL. If the response can't be parsed, make sure you copied a config URL for your client, not a webpage URL. If a local file fails to import, use the reported line and field name to inspect the original file. Don't delete an entire block of rules just to clear one error. For help understanding a field, see the config field reference.

Select the imported config

An entry in the config list only means the client has saved it. Select the entry you just imported and choose “Use,” “Enable,” or the equivalent option to make it active. Check that the selected marker is on that entry. Then open the “Proxy” or “Policies” page: if the config includes proxy groups, you should see their names and available outbounds. If the old group's names are still shown, return to the config page and check whether the switch succeeded; there's no need to import it again.

Updating a subscription and enabling a config are separate actions: updating fetches the file again, while enabling determines which config the core uses. If you already have a working config, keep it for now and remove it only after the new one passes step four. Once you've confirmed the active config, choose a mode on the proxy page.

Choose a rules mode and outbound

Find the mode selector on the “Proxy” page, home screen, or tray menu. For your first test, choose “Rule.” In this mode, requests that reach the core are matched against the config's rules in order. A match may send a request direct, reject it, or pass it to a proxy group. Changing modes doesn't enable the system proxy; it only controls how the core handles requests it receives.

Choose the right proxy group, then an outbound

A config may include general-purpose groups, groups named for specific uses, and automatic selection groups. Names vary by config author, so they may not match screenshots in a guide. If the rules or config notes specify a group for your test site, open that group. In a manual group, select an available outbound and check the selection marker. If the group contains nested proxy groups, follow the selected option until you reach the final outbound. Changing a proxy group won't affect a test site that already matches a direct rule.

Automatic selection groups typically test or switch outbounds based on their configured behavior, and may not let you pin a specific member. For initial troubleshooting, use a manual group with clearly selectable options if possible. If the config only offers automatic groups, keep the default selection and note which outbound the connection uses during verification. A latency test only shows whether an outbound completed that particular probe; it doesn't prove that your browser request reached the client or replace a test visit to the target site.

Use Global and Direct for comparison

Global mode usually bypasses normal rule-by-rule routing and still requires you to choose an available outbound for the global policy. After confirming that traffic reaches the core, you can briefly compare it with Rule mode: if the same target works in Global but fails in Rule, review the matched rule and selected proxy group. Direct mode sends requests that reach the core straight out; it's not the same as turning off the system proxy or VPN. Don't use Global as a permanent fix for broken rules, or traffic that should go direct may take a different route.

Keep Rule mode and your selected outbound for now; don't change rules or switch configs yet. For the relationship between outbounds, proxy groups, and rules, see the glossary. For your first connection, remember: rules choose the route, and proxy groups determine which outbound is available.

Route app traffic through the client

First, make sure the client core is running and there are no startup errors. The quickest desktop test is to enable the system proxy and make a request from a browser that uses system proxy settings. On mobile, use the connection toggle on the client's home screen. For your first check, enable only the entry point you need; there's no need to turn on both the system proxy and TUN. Otherwise, even if the site loads, it can be hard to tell which entry point captured the traffic.

Desktop: enable the system proxy or set a per-app proxy

Turn on “System Proxy” from the client's home screen or tray menu, and make sure it stays on. Some clients also show a local listening address and port; these are where apps hand requests to the core, not the address of a remote node. If the toggle turns off immediately, check for errors writing system settings, starting the core, or binding the port. If the port is in use, check whether another proxy client is running before changing ports.

Linux desktop environments vary in their support for system proxy settings. If your client has no system proxy toggle, or the test app doesn't use system settings, enter the client's displayed local address, port, and protocol in the app's own proxy settings. For example, choose HTTP proxy if the client explicitly shows an HTTP inbound or an HTTP-capable mixed inbound. Don't paste your subscription URL there. Restore the original settings in the same place when you're done testing.

Mobile: connect and approve system access

Return to the client's home screen and make sure the config you enabled in step one is still active, then tap “Connect.” If the system prompts for VPN permission, make sure the request comes from the client you're setting up, then approve it as prompted. Wait for the client to show Connected before switching back to the app you're testing. Some devices show a VPN icon in the status bar; this only means the system tunnel is up. It doesn't show which rule matched or whether a remote outbound is working.

If the connection drops immediately, check whether another VPN is already running or a device policy blocks new connections. Don't disable a connection or security setting required by a managed work device just for testing. For desktop apps that don't use the system proxy and have no proxy setting of their own, consider TUN if your client supports it. Check the glossary for its permissions, traffic capture scope, and DNS behavior; there's no need to enable it before your first browser test.

Check connection logs and verify the route

Open the client's “Connections” or “Logs” page, then use the test app to visit a site whose expected route you know. Start a new connection if possible—for example, quit and reopen the test browser, then load a new page. An existing tab may use cached content or reuse an old connection, so a page refresh alone can't tell you which route the new request took. If the site loads from multiple domains, check the main site in the address bar rather than drawing conclusions from image or font requests.

Match the destination, rule, and outbound

Find the request you just made by its time and destination domain. If the client shows the rule, proxy chain, and outbound, check them in order: which rule matched, which group handled it, and whether the final route was direct or used your selected outbound. DIRECT doesn't necessarily mean there's a problem. If the target should go direct and the page loads, the rule is working. To test the proxy route, choose a target that should clearly use a proxy group and repeat the same checks.

Some clients only show active requests in the connections list, so short-lived requests may disappear. Check the logs for an entry at the same time, or keep the connections page open and make the request again. If there's still no entry but the request succeeds, check whether the test app uses the system proxy, a proxy extension overrides its settings, or the app is reusing an old connection. Terminals and browsers may use different proxy settings; success in a browser doesn't mean terminal traffic will take the same route.

Change one thing at a time, then test again

If a request appears but takes an unexpected route, check the destination domain and matched rule first, then see whether the corresponding proxy group selected a different outbound. Rules are evaluated in order, so a broader earlier rule may have matched first. If the route is correct but the request fails, leave the rules unchanged and check whether the logs show an error during name resolution, the remote connection, or the node handshake. Only switch to another outbound in the same manual group after confirming the failure is related to your current selection. Change one thing at a time and retest the same destination to identify what fixed it.

Once the target loads and the logs show the expected route, your initial setup is complete. If you switched to Global or Direct for comparison, switch back to Rule mode. To pause the desktop proxy, turn off the system proxy before quitting the client. Restore any local proxy settings you added to the test app. On mobile, disconnect from the client's home screen. For custom rules, DNS settings, or config overrides, continue with the mihomo config field reference.