How to Use the Built-in YAML Config Editor in ClashFX

Published on 2026-03-01 · Last updated 2026-11-11

Overview of the Built-in YAML Editor

Power users and network administrators frequently need to customize routing rules, change local port bindings, or adjust DNS fallback servers. While legacy clients required switching back and forth between third-party editors (like VS Code or Sublime Text) and the menu bar, ClashFX includes a dedicated, native YAML Configuration Editor.

Key features of the built-in editor:

• Full Syntax Highlighting: Clear visual differentiation for YAML keys, scalar strings, numerical ports, booleans, arrays, and comments.
• Line Numbering: Easily pinpoint syntax errors reported by the parser.
• Large File Optimization: Smooth scrolling and immediate rendering even for multi-thousand line configuration profiles.
• Instant Hot Reloading: Saving (Cmd + S) automatically signals the underlying mihomo core to reload configuration trees in-place.

How to Open and Access the Editor

To launch the editor:

1. Click the ClashFX icon in the macOS menu bar.
2. Navigate to Config → Edit Current Config.
3. A clean, dedicated window opens displaying the exact YAML file currently powering ClashFX.

Alternatively, to edit an inactive configuration or a custom template:

• Click Config → Open Config Folder (~/.config/clashfx).
• Right-click any .yaml file and choose to open it with ClashFX, or edit it directly.

Essential YAML Configuration Sections

Here is a breakdown of the primary blocks you can modify directly within the editor:

1. General & Port Settings

Control local listening ports and external interface access:

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
ipv6: false
external-controller: 127.0.0.1:9090

• mixed-port: Serves both HTTP and SOCKS5 proxy protocols on a unified port.
• allow-lan: When set to true, permits other devices on your local Wi-Fi or LAN to connect to your Mac’s proxy.

2. DNS Engine Settings

Crucial for Enhanced Mode (TUN) and resolving target hostnames without DNS poisoning:

dns:
  enable: true
  listen: 0.0.0.0:1053
  ipv6: false
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  nameserver:
    - 223.5.5.5
    - 119.29.29.29
  fallback:
    - 1.1.1.1
    - 8.8.8.8
    - https://dns.google/dns-query

• enhanced-mode: fake-ip: Delivers instantaneous local DNS responses to macOS applications while offloading actual name resolution to remote proxies.

3. Proxy Groups & Policies

Define how traffic is balanced or distributed across nodes:

proxy-groups:
  - name: "PROXIES"
    type: select
    proxies:
      - AUTO-FAST
      - DIRECT
      - US-Node-01
      - SG-Node-01

  - name: "AUTO-FAST"
    type: url-test
    url: http://cp.cloudflare.com/generate_204
    interval: 300
    tolerance: 50
    proxies:
      - US-Node-01
      - SG-Node-01

• type: select: Allows manual selection from the ClashFX menu.
• type: url-test: Automatically routes connections to the node with the lowest latency, testing every 300 seconds.

4. Custom Routing Rules

Route packets based on domain names, IP CIDR ranges, or processes:

rules:
  # Direct connections for local subnets and domestic sites
  - DOMAIN-SUFFIX,local,DIRECT
  - IP-CIDR,127.0.0.0/8,DIRECT
  - IP-CIDR,192.168.0.0/16,DIRECT
  - GEOIP,CN,DIRECT
  
  # Proxy foreign traffic
  - DOMAIN-SUFFIX,github.com,PROXIES
  - DOMAIN-KEYWORD,google,PROXIES
  
  # Fallback rule
  - MATCH,PROXIES

Best Practices & Avoiding Common Syntax Errors

YAML is strict regarding structure and whitespace. Keep these rules in mind:

1. Never Use Tabs: YAML forbids tab characters (\t) for indentation. Always use standard spaces (2 spaces per nesting level is recommended).
2. Space After Colons: Every key-value pair must include a space after the colon:

   # Valid
   port: 7890
   # Invalid (will cause parse error)
   port:7890

3. Array Hyphen Formatting: Ensure a space follows the hyphen in lists:

   # Valid
   - DOMAIN-SUFFIX,openai.com,PROXIES
   # Invalid
   -DOMAIN-SUFFIX,openai.com,PROXIES

Hot Reload in Action

When you press Cmd + S:

1. ClashFX validates the syntax buffer.
2. If syntax is valid, the file is written to ~/.config/clashfx.
3. The mihomo core reloads the routing graph seamlessly.
4. Active connections continue uninterrupted, while new outbound sockets adopt the updated rules and proxy groupings immediately.

Free Core Editor vs. Pro Concept

ClashFX provides direct, unconstrained YAML editing as a fundamental free feature for developers. In future roadmap discussions, ClashFX Pro (currently in preparation and concept stage) explores optional visual form builders and graphical rule generators. However, the full-featured YAML code editor remains free and unrestricted for all users.

Next Steps

• Copy a tested, production-ready template in our Clash Meta YAML Template Guide.
• Learn how to decouple complex rules with Custom Rule Providers.
• Read our Troubleshooting Guide if your edits result in unexpected routing behavior.