External Configuration

外部配置与模板

外部配置决定基础模板、策略组、规则集、重命名和其他生成策略。请求参数：

&config=URL编码后的配置地址

支持格式

• INI：传统 subconverter 生态中最常见，重复键保持声明顺序；
• YAML：使用映射和序列；
• TOML：推荐用于结构清晰的自部署配置。

仓库示例位于：

base/config/example_external_config.ini
base/config/example_external_config.yml
base/config/example_external_config.toml

请求示例

https://api.asailor.org/sub?target=clash&url=...&config=https%3A%2F%2Fexample.com%2Fcustom.ini

外部配置 URL 本身包含查询参数时，必须完整编码。

默认外部配置

自部署者可设置：

[common]
default_external_config = "https://example.com/default.ini"
fallback_to_default_external_config = false

含义：

• 请求未提供 config 时，使用部署者设置的默认外部配置；
• 请求显式提供的 config 失败时，默认不回退到另一份配置；
• 确实需要旧式回退时，显式设置 fallback_to_default_external_config = true。

默认关闭回退可以避免请求者选择的配置失败后，后端悄悄生成语义不同的结果。

本地和远程资源

部署者配置的本地模板与请求者提供的远程 URL 具有不同信任级别。

• lan 允许较宽的历史访问范围；
• public、strict 会限制请求方可控 URL 访问本机、私网和 fake-ip 字面量；
• 项目内置本地模板和部署者配置的可信本地资源仍可使用。

详见安全与隐私。

GitHub 地址回落

后端识别以下 GitHub 文件形式：

https://raw.githubusercontent.com/<owner>/<repo>/<ref>/<path>
https://github.com/<owner>/<repo>/raw/<ref>/<path>
https://github.com/<owner>/<repo>/blob/<ref>/<path>

原始 GitHub 地址因网络问题失败时，可以尝试对应 jsDelivr 地址。非 GitHub URL 不进入该回落逻辑。

此功能只影响后端取源，不代表 CDN 一定包含最新分支内容。需要严格版本一致时使用提交固定 URL。

Custom OpenClash Rules 取源

[custom_openclash_rules]
fallback_enabled = false

开启后，只对能够明确识别的官方 COCR main 分支来源应用项目定义的取源回落。它不会把任意 URL 改写为镜像，也不会改变生成配置中已经写入的规则 URL。

外部规则扩展

SubConverter-Extended 支持：

[custom]
ruleprepend=https://example.com/first.list
ruleprepend=https://example.com/second.list
ruleappend=https://example.com/last.yaml

传统 subconverter 会忽略这些扩展键。完整规则格式、顺序和限制见规则与规则集。

模板变量

主配置可以向模板提供全局变量：

[[template.globals]]
key = "clash.http_port"
value = "7890"

请求参数也可以被模板读取。不要在模板调试输出或脚本日志中打印订阅 URL、令牌、Cookie 或其他秘密。

失败处理

外部配置获取、渲染、解析、导入或资源限制失败时，应把它当作配置失败处理，而不是继续假设输出仍然等价。

排查顺序：

1. 使用浏览器或 curl 检查配置 URL 是否可访问。
2. 检查响应是否为真实配置而不是 HTML 页面。
3. 使用 explain=true 查看加载阶段和回退状态。
4. 检查安全档位是否拒绝目标地址。
5. 检查出站代理和 TLS 验证。
6. 检查导入路径、语法和资源数量限制。

不要把真实订阅或凭据放进公开的外部配置示例。