Clash Multi-Device Configuration Sync: Subscriptions, Overrides, and Private Repositories

When using Clash or mihomo across Windows, macOS, Linux, and mobile devices, the configuration that needs syncing is usually more than a single YAML file. Proxy nodes may come from a subscription, rules from remote rule sets, and proxy groups from personal preferences, while ports, TUN, LAN access, and DNS listener addresses depend on each device. Copying an entire client data directory can bring caches, runtime state, databases, and platform-specific fields to another device, causing port conflicts, configuration load failures, or overwritten local changes.

A more reliable approach is to separate the configuration into layers: let subscriptions or Providers handle continuously updated remote data, keep cross-device rules and policies in a reviewable base configuration, and leave ports, TUN, DNS, and LAN settings in the device override layer. Subscription links, override files, and private repositories are not mutually exclusive choices; each addresses a different need: data distribution, device differences, and version control.

Define the sync boundary first: configuration sources, device settings, and runtime data

The first step in multi-device syncing is not choosing a tool, but deciding which content should have a single authoritative source. A Clash configuration can be divided into four categories:

• Remote resources: proxy subscriptions, proxy Providers, and rule Providers. These are maintained remotely and refreshed by the client on a configured schedule.
• Shared logic: proxy group names, rule order, domain rules, regional routing, and fallback policies. These belong in a base YAML file or version-controlled repository.
• Device settings: mixed-port, the controller port, LAN listening, the TUN switch, network interface selection, and some DNS listener settings. Maintain these per device.
• Runtime data: logs, caches, connection records, downloaded Geo data, Provider caches, and client databases. Each device should generate these locally.

A client's “configuration directory” often contains several of these data types at once, so it should not be bidirectionally synced through a cloud drive. When two devices run at the same time, databases and state files may overwrite one another repeatedly; different operating systems also write different paths, permissions, and line-ending formats. When migrating, export an explicit YAML file or a client-provided backup instead of treating the active data directory as a shared folder.

Approach 1: Use a subscription link to sync proxy nodes

Subscription links are best for ensuring that multiple devices receive the same set of nodes. Import the same subscription URL on each device and let the client refresh it on schedule. There is no need to copy node lists manually, and each device can independently receive updates when node names, addresses, or availability change.

A subscription usually provides only proxy entries or a complete configuration generated by the service. If that complete configuration includes proxy groups and rules, the remote content remains authoritative when the client updates. To prevent local customization from being overwritten, keep an unmodified copy of the subscription configuration and use the client's supported merge, scripting, or override features to add device-specific rules. Clients differ in how they implement “overrides,” “configuration merging,” and “preprocessing scripts,” so verify the processing order before migrating between clients.

For mihomo configurations, you can also declare the node source with proxy-providers, so the shared base configuration only references a remote Provider. The structure below shows how the update interval, cache path, and health check work together:

proxy-providers:
  primary:
    type: http
    url: https://sub.example.net/profiles/team-laptop.yaml
    path: ./providers/primary.yaml
    interval: 21600
    health-check:
      enable: true
      interval: 600
      url: https://www.gstatic.com/generate_204

proxy-groups:
  - name: Manual Selection
    type: select
    use:
      - primary
    proxies:
      - DIRECT

interval controls how often the Provider is fetched; the health-check interval checks the proxies it contains and does not trigger another subscription download. Keep the cache path local to the current device rather than placing it in the sync repository. The example domain is for structure only; replace it with your own subscription URL and choose a test address that is reachable in your network environment.

How to isolate subscription credentials

Subscription URLs often contain credentials that grant access to resources and should be treated as sensitive information. Never put a real subscription URL in a public repository, screenshot, troubleshooting log, or publicly shareable configuration snippet. For multi-device use, store the subscription URL locally in each client and keep the shared repository limited to credential-free policies and rules. If the service supports separate URLs for different devices, device-specific credentials make it easier to revoke access for just one device.

Also note that a standard Clash client may not be able to read a private repository URL that requires a Git login session. A private file opening in a browser does not mean the kernel's HTTP request carries the same authentication. Short-lived download URLs can likewise cause automatic updates to fail after they expire, so the subscription distributor should provide an access method suitable for long-term client fetching.

Approach 2: Store device differences in override files

The override layer is useful when the rules are mostly shared but system settings differ. For example, a desktop may need TUN to capture applications that ignore the system proxy, an office device may enable only the system proxy, and a home device may allow LAN access. Forcing these differences into one YAML file means manually restoring local settings after every sync.

Keep the shared base configuration neutral, then maintain a short difference file for each device. Conceptually, split the configuration as follows:

profiles/
  base.yaml
overrides/
  windows-desktop.yaml
  macbook.yaml
  linux-shell.yaml
rules/
  local-direct.yaml
  service-routing.yaml

A Windows desktop override can enable TUN and automatic routes, a Linux command-line environment may need only a fixed mixed port, and macOS may enable TUN depending on the client and system permissions. allow-lan, bind-address, and the external controller's listening address should also be treated as device settings because they change what is reachable on the LAN.

mixed-port: 7890
allow-lan: false

tun:
  enable: true
  stack: mixed
  auto-route: true
  auto-detect-interface: true

An override does not mean that any YAML can be layered automatically. Clients may use shallow merges, deep merges, scripts, or field replacement; arrays are especially likely to behave differently. For example, an override's rules array may replace the base configuration's rules entirely rather than append to them. Proxy group arrays may also be replaced as a whole. When setting up a sync workflow, start with a few test rules to confirm the actual merge behavior before migrating the full configuration.

Separate shared DNS logic from device-specific DNS settings

DNS rule logic can be shared, such as whether to use Fake-IP, which domains belong on the exclusion list, and which rule sets handle routing. Listening addresses, LAN DNS services, and how the system DNS is intercepted depend on the device environment. Mobile hotspots, home LANs, and corporate networks may have different internal domain-resolution requirements. If every device syncs the same nameserver and listener settings, a configuration working on one device does not prove it suits another.

When using TUN, also verify that the client kernel version and platform permissions support the relevant fields. mihomo extensions should not be handed directly to a client that supports only legacy Clash fields. Before syncing across platforms, identify the kernel each client actually uses, then choose the shared configuration fields accordingly.

Approach 3: Manage shared configuration and change history in a private repository

When a configuration contains many custom rules, multiple device overrides, and scripts that require long-term maintenance, a private Git repository makes changes easier to track than repeatedly sending YAML files. Its main value is recording who changed which piece of logic, why it changed, and where to roll back when something goes wrong—not replacing the subscription service.

Store only reviewable source files in the repository; do not commit the client's runtime directory. Suitable version-controlled content includes the base YAML, device overrides, rule files, generation scripts, and documentation. Exclude logs, caches, databases, real subscription URLs, and Provider files downloaded automatically by the client.

clash-config/
  profiles/
    base.yaml
  overrides/
    desktop.yaml
    laptop.yaml
    server.yaml
  rules/
    private-network.yaml
    work-services.yaml
  scripts/
    build-config.js
  README.md
  .gitignore

If a team or family needs to share the same rules, define proxy group names in the repository. For example, rules may reference only Manual Selection, Auto Select, and DIRECT, while device overrides must not rename them arbitrarily. New rules will then not fail to load because one device lacks the target proxy group.

Configuration in a private repository can be deployed in two ways. The first is to pull the repository on each device and use a local script to combine the base and device layers into the final YAML. The second is to generate the final configuration in a controlled environment and publish it at a distribution URL accessible to the client. The first is convenient for local debugging but requires Git and a generation environment on each device; the second suits clients that only import subscriptions, but distribution permissions must be managed carefully.

Prevent the repository and client from competing over edit authority

Define whether the repository or the client is authoritative. If the repository is the source of truth for rules, do not make lasting manual edits to the final configuration generated by the client; change the source file, test it, and regenerate instead. If a device needs a temporary rule, record it as a local experiment first and merge it into the shared layer only after confirming it works. Otherwise, client-side changes may disappear during the next pull or generation step, while the repository cannot explain where the difference came from.

YAML anchors can reduce repetition within one file, but they do not naturally span multiple independent files. Once a configuration is split, combining it still depends on client override support or an external generation step. Do not assume files can be merged directly based only on their extensions.

Use a fixed update order: remote resources first, overrides second, validation last

The most common multi-device sync problem is not invalid configuration, but inconsistent update order. One device may update the subscription before applying overrides, while another may replace the complete configuration before updating the subscription, producing different proxy groups and rules. Use the same workflow on every device:

1. Confirm the current source of truth. Check whether the change belongs in the subscription, shared base configuration, or device override; do not edit generated output directly.
2. Pull the shared configuration. Fetch the latest base layer and rule files from the private repository, resolving version conflicts first.
3. Update remote resources. Refresh proxy Providers and rule Providers, and confirm that their URLs are still reachable.
4. Apply device overrides. Add the local port, TUN, DNS listener, and LAN settings.
5. Test the configuration. Use the client's configuration check or kernel test feature to verify YAML syntax, proxy group references, and rule targets.
6. Reload and verify traffic. Test direct domains, proxied domains, DNS queries, and applications that do not read the system proxy.
7. Commit intentional changes. Only changes to shared logic belong in the repository; keep temporary ports and local paths in the device layer.

During updates, do not have multiple devices write results to the same cloud-drive file at the same time. Git can manage text versions, but client databases and generated files are generally unsuitable for merging. When continuing work on another device, commit and push first, then pull on the target device, so both sides do not edit the same rules from an outdated version.

How to diagnose sync conflicts and load failures

Custom rules disappear after a subscription update

First check whether the custom rules were written directly into the subscription-generated file. If so, being overwritten by the remote complete configuration during an update is expected. Move the rules to an override layer supported by the client, or maintain a separate base configuration and reference the rules through rule-providers. Also check the override order: some clients automatically reapply overrides after a subscription update, while others require you to regenerate the configuration manually.

The same configuration works on one device but will not start on another

Check the kernel type, supported fields, and local resources first. Original Clash, Clash Meta, and mihomo support different ranges of extension fields; TUN also depends on system permissions and the platform network stack. Then check whether the port is occupied, whether local paths exist, and whether the external controller address conflicts. Do not rush to delete rules, as rules typically do not prevent a listening port from being created.

A proxy group reports that a proxy or Provider cannot be found

Check that the Provider name referenced by use exactly matches an entry under proxy-providers, and confirm that the Provider downloaded successfully. If the shared configuration uses fixed proxy group names, device overrides should not rename them. YAML is indentation-sensitive; a Provider nested at the wrong level can also appear to be missing.

Rule matches differ between devices

Compare the final loaded configurations, not just the repository source files. Devices may use different versions of the rule Provider cache, or an override may replace the entire rules array. Confirm that rule order is identical, especially broad domain rules, GEOIP rules, and the trailing MATCH fallback. Clash generally matches rules from top to bottom, so the first match determines where subsequent traffic goes.

A private repository URL opens in a browser but client updates fail

This is usually related to authentication. The browser has a saved login session, while the Clash kernel's Provider request does not carry the same credentials. Check whether the URL depends on a web session, temporary authorization, or a redirect page. The client must be able to retrieve the YAML content directly and receive a normal HTTP response; if it receives a login page, parsing fails because the content is not valid YAML even if the request appears successful.

How to combine the three approaches

For two or three personal devices with few rule changes, use “subscription link plus client overrides”: update nodes through the subscription, keep ports and TUN settings on each device, and put custom rules in an override configuration explicitly supported by the client. This keeps maintenance relatively light.

For long-term maintenance of many rules, use a three-layer structure: “subscription Providers, shared base configuration, and device overrides.” The base configuration handles proxy groups and rule order, Providers handle nodes and remote rules, and device overrides handle platform differences. The client or a local script generates the final configuration.

For team collaboration or a larger device fleet, add a private repository to manage the base configuration, rules, and generation process. The repository should not store real subscription credentials or sync client caches. Each change goes through pull, test, commit, and deployment; devices consume only the final configuration intended for them.

Whatever combination you choose, avoid having multiple sources of truth. Subscriptions maintain nodes, the repository maintains rules, and local overrides maintain device settings; edit each type of content in only one place. With clear boundaries, multi-device sync changes from “copy the entire configuration” to “update and validate by layer,” making subscription updates, rule iteration, and platform differences easier to manage independently.