Configuration Practices · Clash Technical Blog

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

Use url-test for low latency among available nodes and fallback for ordered failover. Choose the goal first, then set the test address, interval, and tolerance.

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

“Automatic” can mean chasing lower latency or preserving the primary route

Both url-test and fallback run health checks, but they optimize for different goals. url-test compares probe latency among candidate nodes and selects a lower result that meets its conditions; fallback uses the first available node in configuration order and moves down the list only when the current one fails.

The former is suited to favoring lower latency among equivalent nodes; the latter is for “primary route first, backup route if needed.” If you simply want to choose a node yourself, use select. To distribute connections across multiple routes, use load-balance; fallback is not a substitute.

Choose a policy group by intent first

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 policyFor concurrent traffic distribution, not failover

An automatic group can choose only among its candidates; it cannot turn a bad list into a good one

Before creating an automatic group, use select to pin each candidate node and complete one real request through it. Remove candidates whose protocols the current core does not support, whose subscriptions have expired, or that are completely unreachable from the local network. Otherwise, health checks will fail continuously and flood the logs with useless results.

Nodes can be listed directly under proxies or referenced from proxy-providers with use. New nodes enter the candidate pool after a provider update, so watch name filters, region filters, and empty lists. A group can appear to exist even when it contains no items.

Requirements for the candidate list

  • Every node has completed a real request while selected directly
  • Node names distinguish regions or routes instead of repeating the same name in bulk
  • The provider updated successfully and the filtered result is not empty
  • Keep a separate select group when an important account needs fixed egress

The test URL defines what “available” means

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, and lazy determine whether the group keeps making unnecessary changes

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 single parameter set fits every network. On a stable home network where node latencies are similar, use a longer interval and moderate tolerance. Even on a mobile network that switches frequently, do not reduce the interval to a few seconds, because repeated egress changes interrupt sign-ins and streaming connections.

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.

The order of a fallback list defines primary and backup priority

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.

Use a two-level group to select the fastest route within a region and fail over between regions

When there are many candidates, you do not need to put every node into one url-test. Create a separate url-test for each region, then place those regional groups in fallback priority order. This separates “choose by latency within a region” from “preserve primary/backup order across regions,” and Connections can show which groups a request traversed.

More levels make empty provider results, circular references, and duplicate group names harder to spot. If two levels express the goal, do not add a third. Verify every lower-level group on its own before handing it to the parent 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

Verify the selection process for url-test and the failover order for fallback

How to verify without disrupting everyday sessions

  1. Create or use a separate test group

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

  2. Manually trigger one health check

    Record the result for every candidate and the currently selected item.

  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.

When an automatic group does not work, the cause is usually the candidate list, probe, or reference

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.

Use real requests to decide whether an automatic group is worth keeping

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 every health check is green but the original service still fails, pin the current node, retest, and return to the protocol, DNS, or target service. The standard for keeping an automatic group is simple: the service is stable, egress changes are explainable, and primary/backup order matches expectations. A green probe page alone does not mean setup is complete.

References