Configuration Practices · Clash Technical Blog

Configuring Automatic Node Selection in Clash: url-test, fallback, and Latency Tolerance

Use url-test for automatic low-latency selection and fallback for a fixed primary/backup order. Health checks do not replace real tasks: compare browsing, long replies, and downloads with a fixed node, then adjust the test address, interval, and tolerance.

  • policy group
  • url-test
  • fallback
On this page

Automatic selection can serve different needs: lower latency, a backup only when the main connection fails, or a fixed outbound connection throughout a login session. Decide which result you need before choosing a policy group and test method. Settings that look similar can affect long-lived connections and account sessions differently.

Choosing url-test, fallback, select, or load-balance

How Policy Groups Choose an Exit

typeHow it decidesBest use case
selectSelected manually by the userTroubleshooting, fixed egress for an account, and important long-lived connections
url-testChooses based on health-check latencyRoutine automatic selection among equivalent nodes
fallbackChooses the first available item in list orderPrimary/backup failover with explicit priority
load-balanceDistributes connections among multiple items according to a policyDistributes concurrent traffic rather than choosing in a fixed primary/backup order

Candidate Nodes: Availability, Filtering, and Empty Lists

Before creating an automatic group, use select to pin each candidate node and complete a real request through each. Remove candidates whose protocol is unsupported by the current core, whose subscription is invalid, or which are completely unreachable on the local network. Otherwise health checks will keep failing, and repeated errors will make useful logs harder to find.

Nodes can be listed directly in proxies or referenced through proxy-providers using use. A provider update changes the candidate list, so check name filters, region filters, and empty lists, and use node names that distinguish regions or routes.

The Health-Check URL and Real Application Requests

A health check makes every candidate node access the address specified by url. If that address is unstable, blocked in some regions, or requires sign-in, the entire group's results become misleading. In most cases, choose a stable HTTPS address with a tiny response and no account requirement, such as a probe page that returns 204.

The test URL should resemble your everyday traffic, but do not use an API with a personal token or send high-frequency requests to a third-party site. A successful node probe only proves that this URL was reachable at that moment; video, AI streaming responses, and UDP still need verification in the relevant app.

Self-contained url-test structure
proxy-groups:
  - name: 自动选择
    type: url-test
    include-all: true
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 80
    lazy: true

interval, tolerance, lazy, and Probe Timeouts

interval
Interval between health checks, in seconds. Setting it too short increases traffic and server load.
tolerance
Latency tolerance for url-test, in milliseconds. When the difference is minor, keeping the current selection reduces unnecessary switching.
lazy
Reduces or stops active checks while the group is unused; useful for policy groups that are not always needed.
timeout
Some configurations can set a wait time for each probe. If it is too short, an occasional slow response will be treated as unavailable.

No parameter set suits every network. On a stable home network with similar node latencies, use a longer interval and moderate tolerance. Even if a mobile network changes frequently, do not reduce checks to a few seconds. New requests may switch outbound routes frequently; whether existing connections stop depends on node failures and whether the client closes them.

Observe real use for a while after making changes. If Connections shows the node switching back and forth within minutes while candidates differ by only a few dozen milliseconds, increase tolerance or interval before adding more nodes.

Main and Backup Ordering in fallback

fallback does not switch to the second item merely because it has lower latency. As long as the first item passes its health check, it remains in use; only when the first item is unavailable does the group choose a later available item. Configuration order should therefore reflect business priorities—for example, a stable primary route first, followed by a more expensive backup or one in another region.

Complete primary and backup group definitions; adjust the filter keywords to match node names
proxy-groups:
  - name: 主线路
    type: select
    include-all: true
    filter: "(?i)主线"
    proxies: [DIRECT]

  - name: 同区备用
    type: select
    include-all: true
    filter: "(?i)同区备用"
    proxies: [DIRECT]

  - name: 异区备用
    type: select
    include-all: true
    filter: "(?i)异区备用"
    proxies: [DIRECT]

  - name: 主备线路
    type: fallback
    proxies: [主线路, 同区备用, 异区备用]
    url: https://www.gstatic.com/generate_204
    interval: 300
    lazy: true

After the primary route recovers, fallback reevaluates it during a later health check. Existing connections may not migrate when it switches back; new requests are more likely to reveal the new egress. For account dashboards and long downloads, consider a fixed select group to avoid session disruption from egress changes.

Combine url-test and fallback by Region

When you have many candidate nodes, you do not need to put them all in one url-test. Create a separate url-test for each region, then add the regional groups to fallback in priority order. Each regional group selects a lower-latency node; if the current region is unavailable, the main group switches to the next region. Connections also shows which policy groups handled the request.

The more groups you nest, the harder it is to spot an empty provider, circular references, or duplicate group names. If two levels are enough, do not add a third. Verify that each regional group works on its own before adding it to the primary/backup group.

Two-level decision example; regional keywords must match your node names
proxy-groups:
  - name: 香港自动
    type: url-test
    include-all: true
    filter: "(?i)香港|HK"
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 80

  - name: 日本自动
    type: url-test
    include-all: true
    filter: "(?i)日本|JP"
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 80

  - name: 地区主备
    type: fallback
    proxies: [香港自动, 日本自动]
    url: https://www.gstatic.com/generate_204
    interval: 300

Observe Selection and Failover in a Separate Test Group

The earlier YAML fragments only define proxy groups. Edit a copy of the complete configuration, add the new groups to its existing proxy-groups list, and keep the original nodes, proxy-providers, and rules. Do not replace the whole configuration with a fragment or repeat the proxy-groups key.

In Clash Verge Rev v1.6.2 or later, drag the complete YAML copy into the client, create a local profile, and select it for use. The new groups should appear in Proxies. If loading fails, select the original configuration again and check the logs; do not overwrite the original subscription file.

How to verify without disrupting everyday sessions

  1. Use a separate test group in the configuration copy

    Do not test switching while downloading, attending a meeting, or signed in to an important account.

  2. Manually trigger one health check

    Record each candidate’s result and the current selection. In this example, lower-level select groups must point to actual proxy nodes rather than DIRECT.

  3. Route the browser through this policy group

    Connections should show the parent group, lower-level node, and actual egress.

  4. Observe the next check cycle

    For url-test, confirm whether the choice stays within tolerance; for fallback, confirm whether the earliest list item takes priority.

To test fallback, temporarily place a confirmed failed test node that contains no sensitive information first in a separate group and observe whether it moves to the second item; remove it immediately afterward. Do not manufacture a failure by disconnecting the network, disabling the system proxy, or breaking a production configuration, because that changes too many variables at once.

Handling Empty Lists, Failed Probes, and Frequent Node Changes

The group appears empty

Check proxies / use references, the provider's update time, and the node-filtering result.

All candidates show Timeout

Test the health URL separately, then compare the current network with a real request through the node.

url-test keeps switching between two nodes

Increase tolerance or interval, and confirm that the probe address is stable.

fallback always chooses the second item

The first item failed its health check; inspect its specific error instead of changing the order.

The account repeatedly requires sign-in after switching

Put sensitive sessions in a fixed select group to prevent automatic egress changes.

The group suddenly becomes empty after a provider update

Check the filter expression and new node names; an old cache may have hidden the problem before.

Verify Automatic Groups with Browsing, Long Replies, and Downloads

Point the target service's rule to the automatic group, then complete several web, streaming-response, or download requests in a row. Connections should show the expected parent group and specific node. url-test should not jump frequently over tiny latency differences, and fallback should remain on the first item while the primary route is available.

If health checks pass but the original task still fails, switch to select, keep the current node fixed, and retest, then check the protocol, DNS, or target service.

References