[Feature]: Configurable Clash/Mihomo proxy groups for subscriptions with fallback/url-test support

[v0stok-p]

Is your feature request related to a problem?

Yes.

3x-ui can already generate Clash/Mihomo YAML subscriptions with multiple proxies and a default PROXY group, and recent releases added routing rules / enable-routing support for Clash subscriptions.

However, the generated proxy-groups section is currently not configurable enough for client-side failover scenarios.

For example, a generated subscription may look like this:

proxies:
  - name: AMS-01
    type: vless
    server: ams-01.example.com
    port: 443

  - name: RU-01
    type: vless
    server: ru-01.example.com
    port: 443

proxy-groups:
  - name: PROXY
    type: select
    proxies:
      - AMS-01
      - RU-01
      - DIRECT

rules:
  - MATCH,PROXY

This works for manual selection, but it does not provide real priority-based failover.

The desired behavior is:

Client -> AMS-01 directly during normal operation
Client -> RU-01 only if AMS-01 is unavailable or fails health checks

This is not the same as the existing Xray outbound balancer workflow. Xray balancer works on the entry node after the client has already connected to that node, which means the entry node becomes part of the data path. In this use case, the backup/control node must not relay all traffic during normal operation.

Describe the solution you'd like

Please add configurable Clash/Mihomo proxy group templates for generated YAML subscriptions.

The panel could allow admins to configure the generated proxy-groups section, at least for these group types:

• select
• fallback
• url-test
• optionally load-balance

Suggested UI placement:

Settings -> Subscription -> Clash / Mihomo

or a dedicated section near the existing Clash/Mihomo routing settings.

Suggested options:

1. Group name
   Example: PROXY, AUTO, FALLBACK

2. Group type
   Example: select, fallback, url-test, load-balance

3. Ordered proxy list
   The admin should be able to choose which generated nodes/inbounds are included and in what order.

4. Optional DIRECT entry
   Checkbox: include DIRECT in the group or not.

5. Health-check options for fallback / url-test
   Example fields:

url: http://www.gstatic.com/generate_204
interval: 30
timeout: 5000
lazy: false

6. Default routing target
   The generated final rule should be able to use this group:

rules:
  - MATCH,AUTO

instead of always targeting a hardcoded PROXY group.

Expected generated YAML example:

proxies:
  - name: AMS-01
    type: vless
    server: ams-01.example.com
    port: 443

  - name: RU-01
    type: vless
    server: ru-01.example.com
    port: 443

proxy-groups:
  - name: AUTO
    type: fallback
    proxies:
      - AMS-01
      - RU-01
    url: http://www.gstatic.com/generate_204
    interval: 30
    timeout: 5000
    lazy: false

rules:
  - MATCH,AUTO

Expected behavior:

• Clash/Mihomo uses AMS-01 first.
• If AMS-01 fails health checks or becomes unreachable, Clash/Mihomo switches to RU-01.
• When AMS-01 becomes healthy again, Clash/Mihomo switches back to it.
• The backup node is not used during normal operation, so it does not relay traffic unless failover is actually needed.

Alternatives you've considered

1. Current generated type: select group
   This requires manual switching and does not provide automatic failover.

2. Xray outbound balancer
   This is not suitable for this use case because users connect to the entry node first, and then the entry node forwards traffic to backend nodes. That makes the entry node part of the normal data path, which is exactly what I want to avoid.

3. Inbound fallbacks
   Xray inbound fallbacks are useful for protocol/SNI/path fallback after a connection reaches the server, but they do not solve client-side endpoint failover when the primary server is unreachable.

4. External subscription converters
   This works, but moves subscription logic outside 3x-ui, makes deployments more complex, and breaks the idea of 3x-ui being the single source of truth for clients, nodes, subscription links, and generated configs.

5. Manually editing YAML after subscription import
   This works only temporarily. The changes are lost or need to be repeated after subscription updates.

Concrete use case

I manage a main 3x-ui panel on RU-01.

RU-01 acts as:

- the main 3x-ui control panel
- the subscription endpoint
- the backup ingress node

There is also a remote node:

AMS-01 - primary data-plane node

Clients fetch their Clash/Mihomo subscriptions from RU-01, but during normal operation they should connect directly to AMS-01.

Normal data path:

Client -> AMS-01

If AMS-01 is down, unreachable, or blocked from the client network, the client should automatically fail over to RU-01.

Failover data path:

Client -> RU-01 -> tunnel/routing rule -> AMS-01

So RU-01 should only be used as a backup ingress path when the direct connection to AMS-01 fails health checks.

The undesired normal behavior is:

Client -> RU-01 -> AMS-01

because that makes RU-01 part of the normal data path and consumes traffic on the control/backup node all the time.

This is why the current Xray balancer model is not suitable for this use case. Xray outbound balancing works after the client has already connected to the entry node. In my scenario, the client should normally bypass the entry/control node entirely and connect to AMS-01 directly.

This request is specifically about client-side Clash/Mihomo failover in generated subscriptions:

Primary:
Client -> AMS-01

Fallback:
Client -> RU-01 -> AMS-01

Mockups, screenshots, or examples

Current generated behavior:

proxy-groups:
  - name: PROXY
    proxies:
      - AMS-01
      - RU-01
      - DIRECT
    type: select

rules:
  - MATCH,PROXY

Requested generated behavior:

proxy-groups:
  - name: AUTO
    type: fallback
    proxies:
      - AMS-01
      - RU-01
    url: http://www.gstatic.com/generate_204
    interval: 30
    timeout: 5000
    lazy: false

rules:
  - MATCH,AUTO

Possible UI idea:

Panel Settings -> Subscription -> Clash / Mihomo

[ ] Enable configurable proxy groups

Group name: AUTO
Group type: fallback
Health-check URL: http://www.gstatic.com/generate_204
Interval: 30
Timeout: 5000
Lazy: false

Proxies:
  [1] AMS-01
  [2] RU-01

[ ] Include DIRECT
Default MATCH target: AUTO

Which parts of the panel would this affect?

Frontend (UI / panel pages), Subscription (share links / Clash / JSON), Backend (API endpoints, login, settings), Xray config generation

Are you willing to help?

• I'd like to implement this feature myself and open a PR.
• I can help test once a PR is open.

Before submitting

• I searched existing issues and this feature has not been requested.
• This feature request is written in English.

[github-actions]

Thanks for the detailed write-up and concrete use case.

What exists today

The routing merge machinery in sub/subClashService.go (mergeClashRulesYAML, line 563) already handles arbitrary top-level YAML keys. When Clash/Mihomo routing is enabled and the Clash/Mihomo Rules field contains a full YAML map, any key that is not rules — including proxy-groups — is set directly in the output config, overriding the generated default. So a partial workaround is possible right now:

Settings → Subscription → Clash/Mihomo:

1. Enable Clash/Mihomo routing
2. Paste the following into the Clash/Mihomo Rules field (replacing remark names with your actual generated proxy names):

proxy-groups:
  - name: AUTO
    type: fallback
    proxies:
      - AMS-01
      - RU-01
    url: http://www.gstatic.com/generate_204
    interval: 30
    timeout: 5000
    lazy: false
rules:
  - MATCH,AUTO

Because mergeClashRulesYAML sees proxy-groups as a non-rules key, it does base["proxy-groups"] = value, replacing the default PROXY / select group entirely. The MATCH,AUTO rule is recognized as a terminal MATCH rule (see hasClashMatchRule, subClashService.go:633), so it replaces rather than prepends.

The limitation this workaround has

The proxy names in proxies: must be exact string matches for the remark names that the panel generates from your inbounds. There is no template variable like {{all-proxies}} or {{proxy-1}}. If remark names change, the YAML must be updated manually.

What this feature request adds

The core ask is dynamic proxy name injection: the panel should automatically populate the proxies list of a configured group from the subscription's generated nodes, without the admin having to hardcode each remark name. That, plus dedicated UI fields for type, health-check url/interval/timeout/lazy, and the MATCH target, would make this fully self-managing.

This is not covered by the existing subClashRules / subClashEnableRouting machinery — those fields are raw YAML with no templating support — so this is a valid new feature request. A related older request (#4404) was closed as completed after routing injection was added, but the dynamic-group / health-check part was never implemented.

Affected files for a future implementation:

• sub/subClashService.go — GetClash() builds proxy-groups; needs to accept structured group config and populate proxies from the generated proxyNames slice
• web/service/setting.go — needs new settings keys (e.g. subClashGroupType, subClashGroupUrl, subClashGroupInterval, etc.)
• web/entity/entity.go — AllSetting struct for the new fields
• Frontend Settings → Subscription panel for the UI controls

[MHSanaei]

Closing as a duplicate of #4941, which tracks the same request (customizable Clash/Mihomo proxy-groups with fallback/url-test for subscriptions). Let''s keep the discussion in #4941.