Node HandbookNODE HANDBOOK中文
Hiddify · cross-platform

Hiddify: import a configuration, then choose a capture mode

Hiddify wraps a sing-box core. It accepts several input shapes — a subscription URL, a share link, a Clash or sing-box configuration — and the mode you choose decides how much of the system it captures.

Node Handbook editorial team ·

Get the app from the project

Download from the project's own release channel and match the platform package. The app bundles a core, so the app version and the core version move together — a detail worth writing down, because field-level errors are often version questions.

What counts as input

InputAccepted asCommon mistake
https://… subscription URLA remote subscriptionPasting a login or product page
A single vless://, trojan://, vmess:// linkA single proxyExpecting it to behave like a subscription with many nodes
A Clash or sing-box configuration fileA configurationAssuming any file with the right extension parses
A QR codeWhatever it encodesTreating the whole message as a URL

The five events behind “no nodes”

  1. Fetch. Did the request complete, and with what status?
  2. Content. Was the body a configuration, a login page, an empty body, or an error page?
  3. Parse. Did the content load, or did the parser reject a field?
  4. Selection. Is the newly added profile the active one?
  5. Start. Did the core start and open its listeners?

The first error in the log identifies the event. Reading only the last lines usually shows a symptom downstream of the cause.

Modes

ModeCoverageCost
System proxyApplications that read proxy settingsGames, CLI tools and some store apps bypass it
VPN / TUNBroader, subject to routes and exclusionsNeeds a tunnel interface and permissions; interacts with other VPNs

Start with the simpler mode. Move to VPN mode when a specific application needs it, and record the pre-change DNS and routing state so you can restore it.

Platform notes

  • Windows: VPN mode needs a helper process. An elevation error at connect time is a local permission question, not a node question.
  • macOS: first launch requires approving a system extension or VPN configuration. A database migration error at startup is a local data question.
  • Linux: TUN needs the relevant capability or a privileged helper. A bare exit code usually means a prerequisite process never started.
  • Android and iOS: the VPN indicator reflects an active configuration; it does not prove traffic passed.

Reading the first error

MessageLayer
HTTP 401/403/404/429Fetch and authorisation
unmarshal error with a field nameParse: a field this build does not accept
Profile exists, list emptySelection, filtering or core start
Exit status with a numberA helper process failed to start
duplicate column nameLocal database migration on macOS

Verify

  • One real HTTPS request with the intended mode active.
  • Observed exit, if region matters.
  • Whether the same request works in the other mode — that separates capture from forwarding.
  • App version, core version, platform and the time.

Scope

This page describes import and mode selection. Interface wording differs by platform and release, and the project's own documentation is the authority for each. Nothing here evaluates a provider.