OSS 远程配置

把配置文件放到云端，客户端启动时自动读取。

默认使用图形化配置，不需要手写 JSON。准备好面板 API 地址和可以公开读取文件的对象存储，按下面四步操作即可。

本文目录

先分清两个地址

面板 API：https://api.example.com/api/v1，用于客户端登录、读取套餐和订阅。

配置文件直链：https://cdn.example.com/web-config.json，用于客户端获取你填写的配置。下面教你生成这个文件。

首次配置，只需四步

填写配置
进入服务配置，填写面板 API、三个平台版本、官网和下载页。不需要的可选项留空。
下载密文
点击“校验并下载密文”，得到品牌专用的加密文件 web-config.json。草稿会保留，之后可以继续修改。
上传文件，复制直链
将文件上传到 OSS、COS、R2 等对象存储，设置公开读取、私有写入，复制长期有效的 HTTPS 文件直链。
用无痕窗口打开，应直接看到包含 flclash.remote-config 的 JSON，而不是登录页或分享页。
保存地址并打包
回到服务配置，填写直链，检查通过后保存。再到创建构建打包，安装新客户端并测试登录和套餐读取。

请上传本平台生成的密文，不能上传原始明文或其他品牌的文件。配置中不要放云账号密钥、后台密码。

直链要求与备用地址

直链必须无需登录、Cookie、临时签名或验证码，直接返回 HTTP 200；不跟随重定向。文件不超过 1 MiB，Content-Type 设置为 application/json。

最多填写 5 个地址，每行一个，均上传同一份品牌密文。新客户端轮换起始地址，失败时尝试其他地址。平台只检查文件，不替你上传。

以后怎么更新？

只改配置内容：重新下载密文，覆盖云端同一个文件，按需清理 CDN 缓存。完全退出并重开客户端即可，无需重新打包；仅影响已接入功能。
换了配置文件地址：保存新地址后重新打包。旧客户端仍使用原地址，先保留旧文件。
改了应用图标：上传新图标后重新打包。

更新失败或断网怎么办？

读取失败时客户端使用上次成功读取的缓存；首次安装没有缓存时会报错。修改前请自行备份旧密文，出错时覆盖回原文件、清理 CDN 缓存，再重启客户端。

版本号和公告会跟着更新吗？

version 和 minSupportedVersion 目前不会触发自动或强制更新，也不会改变后台设置的安装包版本。notes 只是版本说明，客户端公告从面板接口获取，两者相互独立。其他可选项的用途见字段说明。

JSON 模板（可选）

图形表单就能完成配置。高级配置只用于原始 JSON 的批量编辑。

查看、复制或下载 JSON 模板

原始 JSON / JSONC 只在主动打开“高级配置”后显示。替换示例值后粘贴到那里，再生成密文；不要直接上传模板。

{
  "domain": [ // 面板 API 地址列表，填写 1–5 个并以 /api/v1 结尾
    "https://api.example.com/api/v1"
  ],
  "version": { // 各平台最新发布版本
    "windows": "1.0.0", // Windows 最新版本
    "macos": "1.0.0", // macOS 最新版本
    "android": "1.0.0" // Android 最新版本
  },
  "download": "https://www.example.com/download", // 客户端下载页面
  "website": "https://www.example.com" // 官网或地址发布页
}

每个字段后均有中文备注。替换占位值后粘贴到平台生成密文，不要把明文模板直接上传对象存储。

支持单行和多行注释，不支持尾随逗号、Markdown 代码围栏或 window.FLCLASH_CONFIG 包装。

全部字段说明

字段名区分大小写。“必填”指本平台的 JSON 格式校验要求；可选字段不填时不会自动启用对应功能。

共 16 个字段 · 展开说明可查看填写规则和平台现状

全部 OSS 配置字段说明
字段	类型	必填	说明
`domain`	类型Array<String>	要求必填	面板 API 地址列表，用于登录、套餐、订单和订阅等请求。填写规则与平台现状填写规则：填写 1–5 个不重复的 HTTPS 地址，路径为 /api/v1，不带查询参数或 # 片段。按优先级排列；当前订阅入口也使用这些地址。本平台现状：已接入 API 请求与备用地址。不是 OSS 配置文件地址。
`version`	类型Object	要求必填	三个平台的最新客户端版本信息。填写规则与平台现状填写规则：必须包含 windows、macos、android 三项。版本是字符串，例如 "1.0.0"，不是数字。本平台现状：当前读取并缓存版本信息；尚未接入版本比较和更新提示。不会改变安装包自身版本号。
`version.windows`	类型String	要求必填	Windows 最新发布版本。填写规则与平台现状填写规则：例如 "1.0.0"，应与实际可下载的 Windows 版本对应。本平台现状：作为版本信息保留。
`version.macos`	类型String	要求必填	macOS 最新发布版本。填写规则与平台现状填写规则：例如 "1.0.0"。即使当前只构建 Android，也需要填写此项。本平台现状：作为版本信息保留，不代表平台已开放 macOS 构建。
`version.android`	类型String	要求必填	Android 最新发布版本。填写规则与平台现状填写规则：例如 "1.0.0"，应与实际可下载的 Android 版本对应。本平台现状：作为版本信息保留。
`minSupportedVersion`	类型String	要求可选	最低支持版本；原文档用于强制更新策略。填写规则与平台现状填写规则：例如 "1.0.0"；不用时可以省略。本平台现状：当前仅保留此值，尚未实现强制更新拦截。设置后不会阻止旧客户端使用。
`download`	类型String	要求必填	供用户获取安装包的下载页面地址。填写规则与平台现状填写规则：填写 HTTPS 页面地址，可带 # 路由，例如 https://www.example.com/#/download。不是 OSS 配置文件直链。本平台现状：当前读取并缓存，尚未接入自动更新或下载跳转。
`website`	类型String	要求必填	官网、地址发布页或导航站地址。填写规则与平台现状填写规则：填写 HTTPS 地址，可带页面路径或 # 路由。本平台现状：已读取为官网配置；当前没有由此字段驱动的独立“打开官网”入口。
`invitationWebsite`	类型String	要求可选	用于指定邀请链接的站点地址。填写规则与平台现状填写规则：填写 HTTPS 地址；不用时省略或留空。本平台现状：当前仅保留，尚未接入邀请链接拼接。客户端现有邀请功能不由此字段改写。
`notes`	类型String	要求可选	配置附带的版本更新说明。填写规则与平台现状填写规则：最多 2000 个字符；换行写为 \n。不要在 JSON 字符串里直接敲未转义的换行。本平台现状：与面板公告无关；面板公告从面板接口获取。此字段仅作为配置内容保留。
`customerServiceType`	类型String	要求可选，成对填写	在线客服提供商。填写规则与平台现状填写规则：支持 crisp / chatwoot。不启用时，类型和 Token 一起省略或留空。本平台现状：客户端通过浏览器打开对应的客服会话。
`customerServiceBaseUrl`	类型String	要求可选	Chatwoot 服务的 HTTPS 地址。填写规则与平台现状填写规则：自建 Chatwoot 填自己的服务地址；留空使用 https://app.chatwoot.com。本平台现状：仅用于 Chatwoot。
`customerServiceToken`	类型String	要求配置客服时必填	Crisp 使用 Website ID；Chatwoot 使用 Website Token。填写规则与平台现状填写规则：填写网站渠道提供的公开站点标识，不要填写账户密码、私有 API Token。Crisp 标识为 UUID；Chatwoot 标识不能包含空白。本平台现状：与客服类型配对后用于打开在线客服网页。模板里的全零示例不是可用客服账号。
`userAgents`	类型Array<Object>	要求可选	下发可选的 User-Agent 预设。填写规则与平台现状填写规则：最多 20 项，每项必须同时含 label 和 value；不用时写 [] 或省略。本平台现状：当前仅保留预设，尚未接入客户端选择器或请求 UA 切换。
`userAgents[].label`	类型String	要求每个预设必填	预设的展示名称。填写规则与平台现状填写规则：1–80 个字符，例如 "自定义 UA"。本平台现状：随 userAgents 保留。
`userAgents[].value`	类型String	要求每个预设必填	实际的 User-Agent 字符串。填写规则与平台现状填写规则：1–200 个字符，不含控制字符，例如 "clash-verge/v2.4.0"。本平台现状：随 userAgents 保留；不是节点名称或订阅链接。

绿色勾选为必填，红色叉号为可选；条件必填以文字说明为准。手机上按字段逐项显示。

在线客服（可选）

使用 Crisp

客服类型选 crisp，Token 填 Crisp 站点的 Website ID，不要使用模板里的占位 UUID。更新云端密文后重启客户端，在用户中心打开在线客服验证；能否访问取决于用户网络。

使用 Chatwoot

客服类型选 chatwoot，Token 填网站渠道的公开 Website Token，不是个人 API Token。官方服务可不填服务地址；自建服务在 customerServiceBaseUrl 填 HTTPS 域名。客户端通过浏览器打开客服会话。

{
  "domain": [
    "https://api.example.com/api/v1"
  ],
  "version": {
    "windows": "1.0.0",
    "macos": "1.0.0",
    "android": "1.0.0"
  },
  "download": "https://www.example.com/download",
  "website": "https://www.example.com",
  "customerServiceType": "chatwoot",
  "customerServiceToken": "replace-with-your-website-token",
  "customerServiceBaseUrl": "https://support.example.com"
}

关闭客服

将客服类型、Token 和服务地址同时清空或删除，再生成密文并覆盖云端文件。不要只保留其中一项。

应用图标

到应用信息上传，不要写入 JSON。更换后需要重新打包。

图片格式要求

正方形、非动画 PNG，256–4096 像素，8 位 RGB/RGBA，不超过 5 MiB；建议 1024 × 1024。已安装应用不会自动更换系统图标。

常见问题

“检查远程配置”失败，先检查什么？

先用无痕窗口打开直链。403 通常是权限问题；404 通常是对象路径或文件名错误；301/302 表示没有使用最终直链。本平台不跟随跳转。响应必须是本品牌生成的加密 JSON，不能上传原始明文或其他品牌的文件。

JSON 能打开，为什么还报字段格式错误？

检查必填字段、版本号格式、domain 的 /api/v1 后缀、客服字段是否成对填写。domain 不要带 # 或查询参数。Logo 请在“应用信息”中上传；JSON 中出现 logo 会按未知字段拒绝。不要添加文档之外的字段，空值用省略或允许的空字符串，不要随意用 null。

发现已废弃字段怎么办？

发现 imgbbApiKey 等已登记的废弃字段时，只显示黄色提示：字段会被忽略并从新密文中移除，不影响其他配置和下载。真正未知的字段仍会报错，请检查是否拼写错误。

API 可以填多个吗？地址返回 404 怎么排查？

可以填写 1–5 个备用 API。逐个检查 https://api.example.com/api/v1/guest/comm/config 是否返回面板配置。当前客户端只接受 /api/v1 形式；如果面板用了其他接口前缀，需要先适配客户端，不能只改成任意路径。

需要填写 OSS AccessKey 或 SecretKey 吗？

不需要。平台和客户端只公开读取密文文件。仍不要把云账号密钥、后台密码、签名私钥或管理员 Token 写进业务配置；Crisp 填的是面向客户端的 Website ID。

为什么不能使用其他产品的加密工具？

不同产品的密钥和文件协议互不兼容。本平台使用每品牌独立密钥，只有这里生成的密文才能通过检查并被对应客户端读取。

更新后还是旧配置？是否需要配置 CORS？

先确认覆盖的是原 URL 对应的对象，再清理 CDN 缓存并完全退出应用后重开。读取失败时可能正在用旧缓存。原生 Android / Windows / macOS 的读取不受浏览器 CORS 限制；网站检查由服务器发起，无需为它额外开放浏览器跨域访问。

只打包 Android，也要填写 Windows 和 macOS 版本吗？

需要，当前 JSON 校验要求 version 同时包含三个平台字符串。填写完整不意味着开启三端构建；构建范围取决于平台实际启用情况。

到服务配置使用图形化表单填写内容，生成密文并保存上传地址。

生成加密配置回到顶部 ↑

先分清两个地址

首次配置，只需四步

填写配置

下载密文

上传文件，复制直链