Node HandbookNODE HANDBOOK中文
Stash · iOS and macOS

Stash: reading a configuration before trusting it

Stash reads Clash-style configurations and layers overrides on top. That makes it capable and makes it easy to end up with a profile that looks correct while the final configuration does nothing.

Node Handbook editorial team ·

Client, configuration, and the layer in between

LayerWhat it holdsTypical failure
Remote configurationProxies, groups, rules, DNSFetched but not parseable; missing top-level keys
OverridesModifications applied after downloadA reference that no longer matches, emptying the list
SelectionWhich configuration and which proxy are activeA configuration present but not active
CaptureHow the system routes traffic into the clientAn application that bypasses the tunnel

Before importing

  • Confirm the configuration is in a Clash-compatible format. A file extension is not a format check.
  • Open it in a text editor: the top-level keys should include proxies or proxy-providers, plus proxy-groups and rules.
  • Check whether the configuration references external resources — providers, rule sets — that must also be reachable.
  • If the source provides several formats, take the Clash-compatible one rather than converting another format through a third party.

Why an override can empty the list

Overrides rewrite the downloaded configuration. If an override filters by name and the provider renamed its nodes, the filter matches nothing. If it references a group that no longer exists, the resulting configuration can be unusable even though it parses.

The diagnostic is a contrast, not a guess: disable the override, reload, and see whether entries return. If they do, re-enable one item at a time to find the one responsible.

Rules decide per connection

In a Clash-style configuration, rules are evaluated in order and the first match decides whether a connection is proxied, rejected or sent direct. Two patterns cause most single-site failures: a broad rule above a specific one, and a specific rule pointing at a group whose selection is direct.

Capture on Apple platforms

The client runs as a VPN configuration, so the system indicator shows a tunnel is active. That indicator does not prove traffic passed. Applications that use their own network handling may behave differently, and a second VPN or filter can conflict.

When it fails

SymptomFirst check
Import succeeds, list emptyThe body that was downloaded; then overrides
Configuration will not loadThe first syntax or field error, and the client version
Connected, pages failThe matched rule, the group's selection, and one real request
One site failsThat site's rule and the policy behind it
Resolution errorsDNS block, the client's DNS mode, and correct system time

Verify, then keep the record

  • One HTTPS request with the intended configuration active.
  • Observed exit, if region matters.
  • Client version and the configuration's source, so a later comparison is possible.
  • Whether the same request works with overrides disabled.

Scope

This page describes the configuration model and the order of checks. It names no provider, and it does not claim that any particular subscription is compatible with this client.