Header documentation

How it works

The client fetches the subscription with a plain HTTP request. The body is a mihomo config; the response headers carry everything else: service name, remaining traffic, theme, widget set, billing links. No SDK, no plugin and no agreement with us is required.

Headers are re-read on every profile update — manual or scheduled. Values belong to the profile, not to the application: the theme comes from whichever profile is currently active.

HTTP/1.1 200 OK
Content-Type: application/yaml; charset=utf-8
Subscription-Userinfo: upload=13421772800; download=83994443776; total=214748364800; expire=1798761600
Profile-Title: Nebula VPN
ReClash-ServiceName: Nebula VPN
ReClash-Hex: 2FD3B6:vibrant
ReClash-SupportURL: https://nebula.example/help

Three layers of headers

The headers ReClash reads fall into three groups — it helps to know which does what. The full list of each layer is in the reference.

Common

Standard Clash headers — subscription-userinfo, profile-title and the rest. If you already send them, nothing changes.

ReClash

Twenty reclash-* headers — everything that makes the dashboard yours: theme, ring, widgets, announcements. Only ReClash reads them.

Aliases

The flclashx-* headers ReClash reads for compatibility — so you need not redo anything. See “Compatibility”.

Headers are presentation hints, not a trust mechanism. The user can override nearly everything you send.

Parsing rules

These rules hold for every header at once — keep them in mind as you read the reference.

Case does not matter

Header names are compared case-insensitively: ReClash-Hex, reclash-hex and RECLASH-HEX are the same header.

reclash-* wins

When reclash-*, an alias and a common header all arrive, reclash-* wins.

Repeats are joined

Several identical headers are joined with commas, exactly as HTTP does.

Empty is ignored

Empty values and unknown tokens are dropped: a typo cannot break the app.

Base64 for non-ASCII

Text headers accept a base64: or base64, prefix. For Cyrillic and emoji it is mandatory — an HTTP header is no place for them.

HTTPS only in links

All URLs are absolute and HTTPS. The one exception is the background, which also accepts http. Credentials in URLs are rejected.

Compatibility

ReClash reads some FlClashX headers so providers do not have to redo anything. The order in the table is the priority order: the first non-empty value wins. In the reference the alias is shown right on its header's card.

The active-protection text, hero ring, widgets, reclash-custom, reclash-settings and fallback hosts have no aliases — they are ReClash features.

Delivery and debugging

The most common problem is that the headers are right at the origin but the client never sees them. Start by looking at what actually goes over the wire:

# what actually reaches the client
curl -sSI 'https://sub.nebula.example/sub/TOKEN' | grep -i 'reclash\|subscription\|profile\|content-disposition'

# the subscription body, without headers
curl -s 'https://sub.nebula.example/sub/TOKEN' | head -20

The output should carry your reclash-* and subscription-userinfo. If they are missing, the problem is between the panel and the client, not in the values themselves.

Headers never reach the client

A reverse proxy or CDN is almost always stripping them. nginx does not forward arbitrary upstream headers by default — check that nothing proxy_hide_headers reclash-* before the subscription location, and that the panel emits them upstream of the proxy. Grab a ready nginx or Caddy snippet in the builder.

Cyrillic arrives as garbage

An HTTP header carries ASCII only. Encode any non-Latin text — service name, announcement, connection headline — with a base64: prefix. The builder does this for you.

Values show up twice

The panel already sends a header and your proxy adds it again: nginx's add_header appends rather than replaces. Hide the original with proxy_hide_header, or set the value in one place only.

The CDN caches a stale response

If the subscription goes through a CDN, it may serve a cached response with the old headers. Exclude the subscription path from the cache, or send Cache-Control: no-store on it.

The header arrives but is ignored

Check the spelling and value against the reference: unknown tokens and empty values are dropped silently. The name's case does not matter, but reclash-view and reclash-hex parse by strict rules — see “Parsing rules”.

Devices and HWID

When the user enables device-identifier sharing, the subscription request carries a few extra headers. They exist so you can show a sensible device list and a plan device limit.

Responding to the client

Rollout checklist

1. Send subscription-userinfo — it is the most visible thing to the user.
2. Add reclash-servicename and a logo: the dashboard stops being nameless.
3. Set reclash-supporturl — fewer “where do I write?” messages.
4. Pick a colour via reclash-hex and check it in the live preview in the builder.
5. Verify with curl: curl -sI 'https://…/sub' | grep -i reclash.
6. Make sure the headers survive your reverse proxy and CDN.
7. Do not send reclash-settings without a reason.

The source of truth for this page is PROVIDER_HEADERS.md in the repository. If the two ever disagree, the repository is right.