Guides / Migration

Migrate from ClashX to ClashFX

Know the product and directory differences

Current development is focused on ClashFX. The ClashX site retains historical downloads, tutorials, and troubleshooting resources; future maintenance arrangements will follow published announcements.

ClashFX 1.1.11 uses ~/.config/clashfx as its default config directory. Standard ClashX uses ~/.config/clash. They do not share a directory. On first launch, ClashFX 1.1.11 copies the old ~/.config/clash directory only if ~/.config/clashfx does not already exist. If the new directory exists, even if it is empty, automatic copying is skipped.

Copying config files does not migrate every app setting. The remote subscription list is stored in app preferences and does not move with the directory, so add subscriptions again in ClashFX. Config formats, paths, and runtime behavior may differ; review and verify your setup after import.

ClashFX's current free core includes Enhanced Mode (TUN), remote subscriptions, and the YAML editor. ClashFX Pro is in preparation and is not open for purchase or activation. Final Pro features and pricing are to be announced; Pro is not required for migration.

Migration steps

1. Record details and back up

Note the config currently selected in ClashX and securely save any subscription URLs you will need to add again. A subscription URL may contain account credentials; do not share it publicly.

Stop editing configs, then copy both default directories if they exist. After the backup completes, confirm there were no errors and keep the printed backup path:

(
  set -e
  task_stamp="$(date +%Y%m%d-%H%M%S)"
  task_backup_dir="$HOME/.config/clashfx-migration-backup-$task_stamp"
  mkdir -p "$HOME/.config"
  mkdir "$task_backup_dir"
  if [ -d "$HOME/.config/clash" ]; then
    cp -a "$HOME/.config/clash" "$task_backup_dir/"
  fi
  if [ -d "$HOME/.config/clashfx" ]; then
    cp -a "$HOME/.config/clashfx" "$task_backup_dir/"
  fi
  printf 'Backup: %s\n' "$task_backup_dir"
)

If the old client uses a custom config directory, back up that actual directory separately. If the command reports an error or the copy is incomplete, stop and resolve the backup before continuing.

2. Quit ClashX

After confirming the backup, fully quit ClashX and check that its menu bar icon is gone. Do not let ClashX and ClashFX manage the system proxy or TUN at the same time during migration.

3. Install and launch ClashFX

Download ClashFX from the download page and install it. On its first launch, version 1.1.11 copies the entire old ~/.config/clash directory if ~/.config/clashfx does not exist; the old directory remains in place.

If ~/.config/clashfx already exists, automatic copying is skipped. Do not clear or delete that directory to trigger a copy. Back up its existing contents, then import the YAML files you need through ClashFX's config menu. Keep related rule sets and other dependencies, and check paths referenced by the YAML.

4. Import configs and add subscriptions again

Use ClashFX's config menu to review available configs and select the YAML you intend to use. If automatic copying did not happen, import the needed config from your backup. Do not assume every config, preference, or external dependency was transferred.

The in-app remote subscription list does not move with the config directory. Open remote config management, add the subscription URLs you saved, and confirm that a manual update succeeds. See the guide center for current setup guides.

5. Verify the config and network

Check that the config loads and the intended config is selected. Then verify that nodes and proxy groups exist, rules and rule sets load, DNS and ports are correct, and paths referenced by YAML work. Test normal system proxy behavior first. Enable TUN only if needed, then check system authorization and actual traffic.

If parsing errors or behavior differences appear, review ClashFX's messages and logs and adjust the config as needed. Re-importing a subscription does not automatically upgrade or convert config syntax.

6. Keep a rollback path

Keep ClashX and the backups until ClashFX is working reliably. To roll back, turn off TUN and the system proxy in ClashFX, quit it completely, and then start ClashX. Do not run both clients at once.

Before restoring files from a backup, save a separate copy of the current directory and compare the files. Do not clear a directory or overwrite files with the same name without checking them first. Once ClashX is working again, decide whether to continue troubleshooting ClashFX.

Common questions

Will the ClashX config appear automatically?

Only on the first ClashFX 1.1.11 launch when ~/.config/clashfx does not exist. The old directory is copied as a folder; the in-app subscription list is not transferred and must be added again.

Can I use the old config without changes?

That is not guaranteed. Review parsing, rules, dependencies, and network behavior after import; some configs may need adjustments.

Can both clients be installed?

They can be installed, but do not run them at the same time while they could compete for the system proxy, TUN, or listening ports.