Examples and troubleshooting

This page shows a complete override that can be saved directly, as well as practical expectations for common errors.

Modify port and mode

基础字段.yaml

mixed-port: 7890
mode: rule

基础字段 diff.yaml

mixed-port: 10801
mixed-port: 7890
mode: global
mode: rule

mixed-port and mode are both scalars, and ordinary keys will directly overwrite the original values.

Modify DNS

Recursive modification

DNS 子字段.yaml

dns:
  enable: true
  enhanced-mode: fake-ip

DNS 子字段 diff.yaml

dns:
  enable: false
  enable: true
  enhanced-mode: fake-ip
  nameserver:
    - 223.5.5.5

Complete replacement

DNS 完整替换.yaml

dns-force:
  enable: true
  enhanced-mode: fake-ip
  nameserver:
    - 1.1.1.1

dns-force will delete other fields in the original dns object, leaving only the above content.

Add direct connection rules

添加直连规则.yaml

rules-start:
  - DOMAIN-SUFFIX,baidu.com,DIRECT
  - DOMAIN-SUFFIX,tencent.com,DIRECT

添加直连规则 diff.yaml

rules:
  - DOMAIN-SUFFIX,baidu.com,DIRECT
  - DOMAIN-SUFFIX,tencent.com,DIRECT
  - DOMAIN-SUFFIX,old.example,PROXY
  - MATCH,PROXY

Add Provider

添加规则 Provider.yaml

rule-providers-merge:
  local:
    type: http
    behavior: domain
    format: yaml
    interval: 86400
    url: https://example.com/local.yaml
    path: ./ruleset/local.yaml

rules-end:
  - RULE-SET,local,PROXY

The runtime patch will normalize the Provider path to the current configuration directory to prevent relative paths from leaving the configuration scope.

Modify policy group

修改策略组.yaml

proxy-groups-end:
  - name: PROXY
    type: select
    proxies:
      - DIRECT

修改策略组 diff.yaml

proxy-groups:
  - name: PROXY
    type: url-test
    proxies: 
      - AUTO
  - name: PROXY
    type: select
    proxies: 
      - DIRECT

YAML anchors and `<<`

The overwritten file will first expand anchors, aliases, and << merge keys by the YAML parser.

使用锚点.yaml

provider-default: &provider-default
  type: http
  interval: 86400
  behavior: domain
  format: yaml

rule-providers-merge:
  example:
    <<: *provider-default
    url: https://example.com/rules.yaml
    path: ./ruleset/example.yaml

Explicit fields take precedence over anchor content:

锚点覆盖结果 diff.yaml

example:
  type: http
  interval: 86400
  behavior: domain
  format: yaml
  url: https://example.com/rules.yaml
  path: ./ruleset/example.yaml

`reality-opts.short-id`

YumeBox protects the string value of reality-opts.short-id in the top-level proxies list. This way 0123 and 1e5 will not be parsed as numbers by YAML.

Reality short-id.yaml

proxies-end:
  - name: 示例节点
    type: vless
    server: example.com
    port: 443
    reality-opts:
      short-id: 0123

Reality short-id 预期.yaml

reality-opts:
  short-id: "0123"

short-id nested within other custom objects will not trigger this private protection.

Literal keys

Angle brackets turn off modifier parsing and remove the angle brackets at compile time:

字面量键.yaml

<rules+>:
  enabled: true

字面量键结果 diff.yaml

rules+:
  enabled: true

When not wrapped, rules+ will be parsed into appending to rules; only after wrapping will the field named rules+ be written.

Multiple overwrite files

The overwritten files are executed in the binding order in the subscription, and the latter file can modify the results of the previous file.

第一个覆写.yaml

mixed-port: 7890
rules-start:
  - DOMAIN-SUFFIX,first.example,DIRECT

第二个覆写.yaml

mixed-port: 7891
rules-end:
  - DOMAIN-SUFFIX,last.example,DIRECT

覆写链最终 diff.yaml

mixed-port: 7890
mixed-port: 7891
rules:
  - DOMAIN-SUFFIX,first.example,DIRECT
  - DOMAIN-SUFFIX,original.example,DIRECT
  - DOMAIN-SUFFIX,last.example,DIRECT
  - MATCH,PROXY

Empty file

Empty files or files containing only whitespace characters will be skipped and the configuration will not be modified:

空覆写.yaml

The compilation result will be successful, but skip empty override file will appear in warnings.

YAML parsing error

Indentation errors, illegal mappings, or unclosed strings will stop the current overwriting chain:

错误的缩进.yaml

proxy-groups:
  -
  name: PROXY

Expected results:

parse yaml override <覆写文件路径>: <YAML 解析错误>

The error message will include the path to the overwritten file, and subsequent overwriting will not continue.

Wrong root type

When the YAML top level is not an object, the override engine replaces the root configuration with that value; the compiler then rejects it:

错误的根类型.yaml

- this-is-a-list

Expected results:

compiled root config must be an object

`geosite-matcher` Verification error

The override itself can write strings, but the final check only accepts mph and succinct:

错误的 Matcher.yaml

geosite-matcher: unknown

Expected results:

geosite-matcher must be one of: mph, succinct

Runtime boundaries

After the user overwrite is completed, YumeBox will still perform runtime patches:

Scenario	Final Action
DNS is not enabled	Supplementary default DNS, `fake-ip` and filters.
`Vpn Service` or `eBPF`	Turn off `tun.enable`, `auto-route`, and `auto-detect-interface`.
`Tun`	Preserves the Tun settings in the configuration.
`listeners`	Remove `redir` and `tun` type listeners.
Configuration preview	Clear ports, listeners and Tun entries.

Therefore, successful overwriting does not mean that all fields will become the final running values; the running mode related settings may be adjusted by applying a patch at the end.

Start here

Guides

Overrides

More

Examples and troubleshooting

Modify port and mode

Modify DNS

Recursive modification

Complete replacement

Add direct connection rules

Add Provider

Modify policy group

YAML anchors and `<<`

`reality-opts.short-id`

Literal keys

Multiple overwrite files

Empty file

YAML parsing error

Wrong root type

`geosite-matcher` Verification error

Runtime boundaries

​Modify port and mode

​Modify DNS

​Recursive modification

​Complete replacement

​Add direct connection rules

​Add Provider

​Modify policy group

​YAML anchors and <<

​reality-opts.short-id

​Literal keys

​Multiple overwrite files

​Empty file

​YAML parsing error

​Wrong root type

​geosite-matcher Verification error

​Runtime boundaries

Modify port and mode

Modify DNS

Recursive modification

Complete replacement

Add direct connection rules

Add Provider

Modify policy group

YAML anchors and `<<`

`reality-opts.short-id`

Literal keys

Multiple overwrite files

Empty file

YAML parsing error

Wrong root type

`geosite-matcher` Verification error

Runtime boundaries