Operator API Template Variables zh

X-Brand-* 响应头中的模板变量

🌐 English · Русский · 中文

现代 Clash 面板（Remnawave、Pasarguard、Marzban、Marzneshin、3x-ui）允许管理员在自定义响应头中写入模板占位符。面板会在请求时、在把响应发给 ClashFest 之前完成替换。从客户端角度看，响应头的值到达时就是一个普通字符串 —— 客户端没有替换引擎，每个 X-Brand-* 值都被视为最终文本。

这意味着本规范中的每个响应头都已支持模板。你的面板能插入字符串的任何内容，都能插入 X-Brand-* 响应头。

---

端到端如何工作

面板管理员在自定义响应头 UI 中输入：
  X-Brand-Tagline: Welcome {{USERNAME}}, {{DAYS_LEFT}} days remaining

面板处理用户 "vasya" 的订阅请求：
  X-Brand-Tagline: Welcome vasya, 12 days remaining

ClashFest 收到该响应头并原样渲染。

客户端永远看不到 {{USERNAME}}，只看到 vasya。

---

各面板速查表

变量名与语义因面板而异。下列为撰写时的文档情况 —— 如有疑问，请查看你面板的自定义响应头 UI，或用测试订阅试一个占位符并用 curl -I 检查响应。

Remnawave

变量	你（大概）会得到
{{USERNAME}}	管理面板中配置的用户名
{{EMAIL}}	用户邮箱（若已设置）
{{TELEGRAM_ID}}	用户 Telegram ID（若已关联）
{{TAG}}	管理员设置的自由用户标签 —— 如 "premium-2024" 或 "vip"
{{STATUS}}	订阅状态（如 active、expired）
{{DAYS_LEFT}}	整数 —— 距到期天数
{{TRAFFIC_USED}} / {{TRAFFIC_LEFT}} / {{TOTAL_TRAFFIC}}	人类可读（如 12.4GB）
{{TRAFFIC_USED_BYTES}} 等	原始字节整数
{{EXPIRE_UNIX}} / {{CREATED_AT_UNIX}} 等	Unix 纪元秒
{{RESET_STRATEGY}}	重置周期（daily、monthly、no_reset）
{{SUBSCRIPTION_URL}}	订阅 URL 本身
{{SHORT_UUID}} / {{ID}}	短标识符 / 内部用户 ID
{{SS_SUPPORT_LINK}} / {{SS_PROFILE_UPDATE_INTERVAL}} / {{SS_HWID_LIMIT}}	面板级设置

Pasarguard

变量	你（大概）会得到
{{PROFILE_TITLE}}	配置文件标题
{url}	订阅 URL（此面板为小写、单花括号）
{format}	匹配的订阅格式（clash、v2ray 等）
{{USERNAME}} / {{ADMIN_USERNAME}}	用户名 / 创建者管理员用户名
{{SERVER_IP}} / {{SERVER_IPV6}}	服务器 IP
{{DATA_USAGE}} / {{DATA_LEFT}} / {{DATA_LIMIT}}	已格式化（12.4GB）
{{USAGE_PERCENTAGE}}	使用百分比（53%）
{{DAYS_LEFT}} / {{TIME_LEFT}}	天数 / 剩余时间（12d 5h）
{{EXPIRE_DATE}} / {{JALALI_EXPIRE_DATE}}	公历 / 贾拉利历日期
{{STATUS_EMOJI}}	状态表情（✅ / ⛔ 等）

Marzban / Marzneshin / 3x-ui

这些面板通常暴露上述的一个子集；常见名称有 {USERNAME}、{DATA_LIMIT}、{DATA_USED}、{DAYS_LEFT}、{EXPIRE_DATE}。请查看管理面板的 Custom Headers / Subscription Headers 区域。

---

实用配方

按用户帮助 URL

X-Brand-Help-URL: https://help.example.com/u/{{USERNAME}}

点击 Operator 标签上的 Help，打开预填用户名的帮助页。

带订阅状态的标语

X-Brand-Tagline: {{DAYS_LEFT}} days · {{DATA_LEFT}} left

标语成为品牌名下方的实时状态指示。

Operator 标签上的个性化问候

X-Brand-Greeting: Hi {{USERNAME}} — {{DAYS_LEFT}} days, {{DATA_LEFT}} left

带推荐 / 令牌的续费 URL

X-Brand-Renew-URL: https://billing.example.com/renew?user={{USERNAME}}&token={{SHORT_UUID}}

点击临期徽标即打开直指该用户账单的页面。

带自动上下文的支持深链

X-Brand-Support-URL: https://t.me/yoursupportbot?text=user%20{{USERNAME}}%20needs%20help

Telegram 打开时已预填含用户名的消息。

---

客户端不做什么

• ClashFest 不解析 {{...}}。若响应头中带字面 {{USERNAME}}（面板未替换），客户端会显示字面文本。请在面板侧修复，而非此处。
• 客户端也不知道用户名、邮箱等。凡想展示的内容都须以已替换的形式随响应头到达。

客户端在替换后会校验什么

每个值仍会经过安全中的校验器：

• 最大长度截断（如 X-Brand-Name 替换后最多 32 字符）
• URL 仅 HTTPS（任何模板都无法混入 http://）
• 强调色的十六进制正则 + WCAG 对比度过滤
• 徽标 URL 的 SSRF 防护（模板无法绕过私有 IP 拒绝）

因此恶意 / 错误的替换无法突破既有安全边界。

调试

curl -I -H "User-Agent: ClashforAndroid" https://your-domain.example/sub/<token>

查看 X-Brand-* 响应头。若看到字面 {{...}}，说明替换未触发 —— 检查面板日志 / 配置。若看到正确的替换值，ClashFest 会在下次订阅更新时采用。

相关

• 响应头参考 —— 完整规范
• 快速开始 —— 各面板教程
• 安全 —— 校验规则