config.yaml / 字段参考

Clash 配置文件参考

第一次导入订阅、选择模式和验证连接,从上手教程开始。教程解决怎么接通;这份手册解决接通之后怎么读配置、改字段,以及改过以后到哪里确认结果。

示例以 Mihomo 为参照。客户端界面的功能名称不一定就是 YAML 键,旧内核也未必认识相同的选项。除注明可以独立载入的示例外,片段只演示所属字段,应合入现有配置的对应位置。

config.yaml / 01

YAML 结构与配置入口

顶层键、映射和列表

配置文件顶层是一组键和值。同一层的 mixed-port、mode 和 rules 各管一件事,写在这里的前后次序通常不改变含义。但 rules 下面是一张有顺序的规则表,第一条和最后一条不能随意换位。先辨认自己面对的是映射还是列表,再判断复制过来的几行应该插在哪里。像写成 dns: true 这样把一整组设置简化成一个开关,即使能够被 YAML 解析,也不是内核预期的结构。

通常每深入一层加两个空格,不用制表符。下面的文件可以独立载入:只开一个混合监听端口,收到的请求全部直连,没有上游节点依赖。载入前需要确认本机的端口没有被其他实例占用;它适合验证应用是否接入,不能用来检验任何远端节点。想加解析设置,在顶层新增 dns,不能接在最后一条规则下面继续缩进。

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
rules:
  - MATCH,DIRECT

带短横线的每一项都属于列表。节点列表里的一项可以有多行,比如第一行写名称,下面对齐的是类型、服务器和端口;规则列表里的一项通常只是一行字符串。尤其容易看错的是策略组下面的 proxies:它列的是候选名称,不是另一份带服务器地址的节点定义。两个键拼写相同,所在层级不同,数据形状也不同,不能互相替代。

标量类型与重复键

端口按整数写,开关按布尔值写,名称和服务器按字符串写。想把一串数字当成名称时给它加引号,引用它的地方也按字符串处理。普通字符串里如果出现紧跟空格的冒号,或者出现可能被当作注释起点的井号,也给整个值加引号。规则字符串通常不用引号;如果编辑器因为标点把它拆成了别的结构,可以给整条规则加引号,而不是给逗号分开的每个字段分别加引号。

不要在同一份文件里写两段同名的顶层键。在已有 rules 的文件末尾再贴一段 rules,不是给原列表追加一项。部分解析器会报重复键,另一些可能只留下其中一段。排查这类问题时,先查该键是否出现两次,再向上多看几行定位实际属于哪一层。编辑器若提示某行缩进异常,真正的问题也可能是上一行漏写冒号,或者更早的一段列表没有正确结束。

从原始订阅到运行文件

在图形客户端里,导入项、覆写项和运行项通常不是同一个文件。导入项可能由订阅刷新重建,覆写项记录本机更改,运行项才交给内核读取。想查一个字段是否生效,先确认当前选中的配置档案,再看客户端是否提供运行配置的预览或导出。只打开当初下载的那份文件,最多能知道订阅交付了什么,不能证明系统此刻正在用它。

如果使用独立 Mihomo,可以在内核所在的工作环境中检查候选文件。相对路径、外部规则文件和工作目录应尽量与正式运行一致;含远程提供器的配置在检查时可能仍需要依赖文件或网络。下面的命令不会替图形客户端切换档案,也不能证实端口能绑定或外网一定可达。先用前面的最小配置排除格式错误,再换成实际候选文件检查引用,最后才载入运行。

mihomo -t -f ./config.yaml

127.0.0.1 / 02

监听端口、运行模式与控制接口

本地入口和上游端口分开看

浏览器或终端连接的是本机监听地址,例如 127.0.0.1:7890;内核连接的则是节点定义里的服务器地址和端口。两端可以恰好使用相同的端口号,但没有绑定关系。本地监听改了,系统代理或应用代理也要改;节点端口改了,本地应用一般不用动。看到「连接被拒绝」时,先查日志里的地址究竟属于本机还是节点,再决定检查哪个字段。

字段用途核对位置
mixed-port在同一个端口接收 HTTP 和 SOCKS 代理连接系统代理和支持 SOCKS 的应用可各用相应协议接入
port单独的 HTTP 代理监听端口应用的 HTTP 代理地址
socks-port单独的 SOCKS 代理监听端口应用的 SOCKS 代理地址
allow-lan是否允许局域网设备接入代理监听监听地址、系统防火墙和实际访问来源
external-controller内核的外部管理接口客户端面板或本地管理工具,不是应用代理入口

只用本机时,保留 allow-lan: false。回环地址永远指向发出连接的那台机器,手机上填 127.0.0.1 不会连到电脑。确需在可信局域网共享时,才检查 allow-lan、bind-address 和防火墙;只向确有需要的设备开放,避免把监听端口映射到公网。若当前只是检查电脑上一个浏览器是否接入,没有必要为了让它生效而打开局域网访问。

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info

模式先于单条规则

rule 模式使用规则表选择目标;global 模式走全局策略的当前选择,不等于一定使用某个远端节点;direct 模式让接入内核的流量直连,不等于关闭监听或撤销系统代理。临时切换后应重新发起一次连接,既有长连接不一定立即按新模式重建。常驻的聊天、同步或下载程序在后台保留连接时,先从连接详情辨认这是旧连接还是新连接。

图形客户端能通过管理接口改变运行模式。因此文件上写着 mode: rule,不代表前一分钟在界面里点过的全局模式已经撤销。要诊断规则没有命中的问题,应先核对界面当前模式和当前档案,再看规则。想知道三个模式怎样用作对照,可查规则、全局与直连模式的区别,不要把模式切换当作永久修复。

先验证接入,再检查管理接口

系统代理由操作系统或客户端写入,只有读取这项设置的程序才会走它。终端可能需要单次命令指定代理,一些浏览器则会优先采用扩展或自身设置。可先执行下方命令,再在连接记录中找同一时间的目标。出现响应说明这次指定代理的请求完成了,不代表终端里所有命令都会走代理。若命令报本地拒绝连接,先查端口和进程,再按浏览器与终端分开排查的方法缩小范围。

curl -I --proxy http://127.0.0.1:7890 https://example.com/

管理接口是另一条路径。已有图形客户端管理内核时,不要为了试配置随意替换它维护的控制地址或认证值。自行运行内核且需要外部控制时,优先绑定回环地址,并按管理工具要求在本机设置认证。若报端口占用,分别检查代理和管理端口;改动一处后也要同步对应的调用方。临时提高日志级别有助于定位,但完成排查后宜恢复常用级别;分享片段前应去掉私有地址、订阅地址和认证信息。

proxies / 03

代理节点字段与外部节点来源

名称、协议、远端地址和端口

proxies 定义内核能够选用的出站节点。name 是供策略组或规则引用的名字,type 决定采用哪种协议,server 和 port 指向协议服务所在的位置。服务器字段只写主机名或地址,不带协议前缀、路径或额外的端口部分。名称尽量简短并保持唯一,也不要沿用 DIRECT、REJECT 这样的内置目标名。

下面是一条 SOCKS5 出站定义。只有在同一台机器上确实有一个独立 SOCKS5 服务监听 1080,且该服务允许本机免认证访问时,才可用它测试转发。这个地址不是可供公众使用的节点,也不能换成上章 Clash 自己的混合端口,否则可能把出站再次送回同一内核。把片段合到最小配置后,还需要让一条测试规则或策略组引用该节点,单纯定义不会改变 MATCH,DIRECT 的走向。

proxies:
  - name: 本机上游
    type: socks5
    server: 127.0.0.1
    port: 1080
    udp: false

换一种协议时,除了改类型,往往还需要换一整套参数。以带 TLS 的节点为例,服务器地址是去哪里建立连接,服务器名称则可能用于握手及证书核对,两者未必相同。额外的传输方式也要和服务器一致,不能仅凭端口是四四三就加上 TLS 或某种传输设置。字段名不确定时,先对照当前内核支持的协议说明和服务端提供的参数,别把另一个协议的认证项直接搬过来。

节点列表与策略组的依赖

单个节点改名,应同步检查组内的候选列表、直接指向该节点的规则以及客户端保存的手选项。新名字即使只比旧名字多一个空格,也不会自动继承原引用。若同名节点来自不同来源,在维护时容易把日志中的当前节点认错;更稳妥的做法是先在来源端区分名称,或者使用当前内核明确支持的提供器名称覆写能力,再看最终生成的候选列表。

节点多或需要单独更新时,可以用 proxy-providers 给来源命名,再由组通过 use 接入。下面是文件型提供器片段,适用于可读取该相对路径的 Mihomo 工作目录。对应文件需事先存在,其内容可以用上一个示例中的完整 proxies 映射;节点就挪到那份外部文件维护,主配置不用再定义同名节点。提供器名称不是节点名称,不能直接把来源名当成规则目标。

proxy-providers:
  office-socks:
    type: file
    path: ./providers/office-socks.yaml

proxy-groups:
  - name: 办公出口
    type: select
    use:
      - office-socks
    proxies:
      - DIRECT

把加载错误和连通错误分开

提供器没出现在组里时,先查引用名、文件路径和载入日志。文件看得到却读不进,常见原因是拿到的内容结构与提供器类型不合,例如把一份订阅网页、普通节点分享文本或错误响应当成 YAML 文件。若节点已显示且能被选中,问题就移到连接阶段:先看服务器域名能否解析、目标端口是否可达,再看握手或认证失败,最后才比较网页请求与测试请求的差异。

同一节点能打开网页,不代表支持所有应用所用的传输。udp: true 不能为上游凭空增加 UDP 能力,转发仍取决于协议、服务端和客户端的接入方式。游戏或语音有问题但普通网页可用时,先确认故障流量确实进入内核、实际属于哪类传输,再看规则选到哪个出口。需要换客户端做对照时,可先看客户端页的 Clash Plus 与其他平台选项,按系统和所需功能选择。

proxy-groups / 04

策略组、候选成员与探测方式

策略组是规则和出口之间的一层

策略组本身不描述服务器,规则可以把流量交给组,再由组挑选节点、直连或另一个组。好处是规则不必逐条记住正在使用哪台服务器。例如把办公域名交给「办公出口」,需要临时直连只调整组内选择;改完后,其他走同一组的地址也会一起改变。如果只想修改一个域名,不应先切整个组,而应检查是否要给该域名单设一条更具体的规则。

select 是手动选择。下面的片段要求主配置已经定义上一章的「本机上游」。用于核对本机路由时,可以先明确选中 DIRECT,记录一次请求的实际走向,再切到上游做同一个请求。节点显示在候选里,并不代表它已经被选中;若客户端记得先前的选择,也不能简单按 YAML 列表的第一项推定当前出口。

proxy-groups:
  - name: 办公出口
    type: select
    proxies:
      - DIRECT
      - 本机上游

测速、故障转移与负载分配

url-test 依据候选对指定探测地址的测试结果自动挑选出口,fallback 更侧重在按顺序列出的候选里采用可用项。假如首选线路本来就比较远,但只希望它失联时才走备用,优先理解故障转移,而不是用一次延迟结果就切走。load-balance 则用于在候选间分配连接,不应理解为把一次下载拆给多条线路,也不宜未经验证就套在对登录会话出口敏感的业务上。

下面用直连和本机上游演示自动探测。实际使用中如果业务必须走某一类出口,不要为让探测表好看就把直连加入自动候选。interval 是以秒计的测试间隔,tolerance 在这个组里用于容忍一定的延迟差,避免为了小幅变化频繁更换候选。探测地址应稳定、能从各候选访问,并尽可能反映实际需求;能连通示例站点,不代表业务域名在同一出口也可用。

proxy-groups:
  - name: 连通性测试
    type: url-test
    proxies:
      - 本机上游
      - DIRECT
    url: https://example.com/
    interval: 300
    tolerance: 50

看到自动组总选同一条线路,先看另外几项是测得较慢、探测超时,还是压根不在生成后的组中。测试请求也可能被目标站限流或被某个出口返回非预期页面。不要先把间隔缩短到几秒,尤其是移动设备上,这会增加探测开销,却不一定解释问题。可以挑一条异常候选单测,再比较连接日志、当前选项和业务请求;三者描述的不是同一件事。

组嵌套与选择状态

主组可以包含自动组,形成「先手选用途,再自动选线路」的结构,但引用不能绕回自身。例如「办公出口」把「连通性测试」当作候选时,测试组里就不应再放「办公出口」。阅读日志时,沿着规则目标、外层组、内层组一路查到实际节点。若组层叠得太深,精简到能够解释当前选择往往比再包一层组更容易维护。

Mihomo 的 profile.store-selected 可用于保存策略组选择;具体恢复结果还和客户端的档案标识、缓存目录以及组和节点名称有关。下面是合入顶层的片段,键名是单数。如果刷新订阅后原节点被删除或改名,持久化也不能恢复一个已经不存在的候选。切换配置之后,重点核对保存的选择是不是仍在候选里,而不是靠重复切换几次猜测是否记住了。

profile:
  store-selected: true

DIRECT / 05

规则语法、匹配顺序与默认目标

从第一条匹配规则读起

在规则模式中,规则从上往下检查。一旦匹配,就交给该条指定的目标,不会自动再找一条写得更具体的规则。域名例外应放在覆盖它的后缀规则前面,特定地址的例外也应放在覆盖它的网段规则之前。网络现象看起来像是「某网站总走错」,先找同一次请求命中的第一条规则,不要只搜索文件里是否写过这个域名。

这里假设策略组「办公出口」已经定义。DOMAIN 精确匹配完整域名,DOMAIN-SUFFIX 匹配该域及其子域,所以第一条先把 www.example.com 从后缀规则里分出来。IP-CIDR 识别 IPv4 网段;下面把三个常见私网范围和本机回环段送往直连。最后的 MATCH 是兜底,只有前面都没有命中才会用到。示例选的是直连,实际的兜底目标应根据部署用途决定。

rules:
  - DOMAIN,www.example.com,DIRECT
  - DOMAIN-SUFFIX,example.com,办公出口
  - IP-CIDR,127.0.0.0/8,DIRECT,no-resolve
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  - IP-CIDR,172.16.0.0/12,DIRECT,no-resolve
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - MATCH,DIRECT

no-resolve 不会关闭整个客户端的 DNS。它的用途是让这一类 IP 规则不为了匹配当前条件而额外触发域名解析;如果连接已有目标 IP,仍可按 IP 判断。所以某个内网域名虽然最终会解析到私网地址,却不一定在这一条上命中。已知哪些域名该直连时,可以在前面补精确域名或合适的域后缀,而不是指望私网段规则对每种接入形态都产生同一结果。

地址、域名与实际观察值

规则看到的目标取决于应用和内核之间交付了什么。某应用把域名交给代理,另一个应用可能先做完解析,只把 IP 交进来。看到浏览器地址栏有域名,不能据此断定规则一定拿到了它。IPv6 目的地址也不能用 IPv4 的网段规则覆盖;如果环境同时有两种地址,可在连接详情按协议族分别看实际目的地,再按需要补相应规则,避免用关闭其中一套地址作为唯一排查办法。

同一个页面通常会请求多个目标。主页面直连并不意味着字体、图片、登录和接口请求也直连。验证改动时,只用一次明确的目标请求对照规则日志,选好时间点并清理旧连接。客户端若显示命中的规则和策略链,按「目标、匹配项、组、实际出口」记下来。这样可以分辨是匹配错了、选错组内成员,还是路由正确但目标服务本身没响应。

把较长的域名列表拆到提供器

当多个域名共用同一出口,可以用 rule-providers 管理名单,主规则只保留名单的插入位置和目标。下面的本地文件使用 domain 行为,文件中写域名条目,不写逗号分隔的完整规则。主配置对名单做一次 RULE-SET 匹配,名单只提供条件,目标仍由主配置决定。若要搬的是完整规则类型及其匹配内容,应按内核支持的 classical 格式整理,不能直接把带策略目标的整行复制进去。

rule-providers:
  office-domains:
    type: file
    behavior: domain
    format: yaml
    path: ./rules/office-domains.yaml

rules:
  - RULE-SET,office-domains,办公出口
  - MATCH,DIRECT
# ./rules/office-domains.yaml
payload:
  - 'example.com'
  - 'www.example.com'

大名单放在哪里比是否拆文件更重要。若一项例外要先直连,仍应放在覆盖它的 RULE-SET 之前;规则集放到兜底之后就没有机会匹配。准备使用 REJECT 时,也先用一个确认不需要访问的精确域名做对照。拒绝规则命中时,界面上看起来可能与网络失败类似,连接记录比反复切换代理模式更能说明原因。

dns / 06

DNS 上游、合成地址与 TUN 接入

先确认是谁在解析

内核的 dns 控制自身的解析逻辑。设置了上游,并不意味着操作系统、浏览器或所有应用都会把查询交给内核。浏览器可能使用自己的加密 DNS,应用可能在把连接交给代理之前已做完解析,系统也可能保留先前的缓存。遇到「内核里填了一个上游,查到的却是另一个结果」时,先确定当前测试是直接问系统解析器、问内核的 DNS 监听,还是让代理替应用处理域名。

下面在回环地址开一个非标准端口,便于区分查询路径。启用后,可在装有 dig 的环境中显式查询这个端口。示例上游是一项公开 DNS 服务,需要从当前网络可达;组织内网的私有域名通常仍需要组织提供的解析器。单次有返回只能证明这一路得到了应答,不能证明浏览器正在采用它,也不能证明结果符合所有应用的需要。

dns:
  enable: true
  listen: 127.0.0.1:1053
  enhanced-mode: redir-host
  nameserver:
    - 223.5.5.5
dig @127.0.0.1 -p 1053 example.com A

业务域名和节点域名分别核对

nameserver 是一般查询的上游列表。需要分开处理某一组域名时,Mihomo 可以用 nameserver-policy 为域名指定上游。先确认这个上游对预定域名确实能答复,再添加范围适当的匹配项。组织的内部域如果被交给公共解析器,拿不到结果并不奇怪;应确认系统在直连时用了哪个解析器,而不是不断加入同类公共上游重试。

上游本身若使用域名,还涉及如何先找到上游服务器。default-nameserver 用于解析 DNS 服务器的域名,proxy-server-nameserver 用于代理节点服务器域名的解析,可帮助把节点建立连接的前置查询与普通查询分开。排查时特别留意依赖是否绕成一圈:要访问某个解析器得先接通节点,但要找节点地址又依赖该解析器。应先恢复一条可独立工作的解析路径,再逐项恢复按规则选择解析出口的设置。

合成地址不是服务端实际地址

fake-ip 模式下,内核可对域名返回合成地址,稍后在相应连接进入内核时再用映射找回原域名。日志里看到 198.18.0.0/16 范围内的地址,不代表公网网站搬到了那里。下面是单独的一组替换设置,不要把它接在前面那段 dns 之后形成重复键。对必须拿到真实解析结果并经验证确实有兼容问题的内网域名,可按需使用 fake-ip-filter。

dns:
  enable: true
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  fake-ip-filter:
    - '+.lan'
  nameserver:
    - 223.5.5.5

切换解析模式时,如果应用还握着旧缓存,可能继续尝试连接旧的合成地址。先让受影响应用重新发起查询,再对照 DNS 应答和连接日志。如果同一环境已经用该网段做测试或内部路由,先检查地址是否冲突。解析失败、有应答但没进入内核、已经接入但选错出口,是三种不同故障,不需要同时改上游、规则和端口。

TUN 处理接入,不代替路由规则

TUN 使用虚拟接口接入流量,和给应用手填代理端口不是一码事。启用前要确认客户端有创建接口和设置路由的权限,先关闭会接管相同流量的其他连接工具做基线比较。下面启用自动路由并把匹配的传统 DNS 查询交给内核;它并不把应用自己的加密 DNS 请求自动变成普通查询。若客户端已经管理 TUN 参数,先查它生成的运行配置,不要直接并列写两份设置。

tun:
  enable: true
  stack: mixed
  auto-route: true
  auto-detect-interface: true
  dns-hijack:
    - any:53

开关打开却找不到目标连接时,看接口是否建立、系统路由是否指向它、应用流量是否被平台排除;已经在日志中看到连接,就按规则或 DNS 排查,不要继续反复开关虚拟网卡。若本地打印、共享或办公连接受影响,先关闭 TUN 恢复工作,再用单一目标验证是路由接入还是命名解析出了变化。

config.yaml / 07

订阅覆写、字段合并与回退

把可更新的来源和本机修改分开

订阅负责提供会更新的节点和规则;本机覆写负责端口、常用例外或适合本机的解析设置。不建议在每次刷新都会被替换的原件上反复手改同一行。客户端若支持覆写,先确认作用范围是所有档案还是单个档案,再处理确实需要保留的字段。若没有相应功能,可以复制为一个本地档案做试验;这样修改会留下,但该副本不会自动继承下一次订阅内容。

不要假定各客户端使用同一种覆写语法。某些编辑入口接收完整的 Mihomo YAML,某些接收客户端约定的合并指令,另一些只允许在界面更改有限字段。即使名称叫「合并」,也需要分别确认标量是替换还是保留、映射是否逐键合并、列表是否整段替换。看到内核不认识的扩展键时,先确认是不是把覆写文件直接选作了内核配置,而不是怀疑节点本身不可用。

分别比较标量、映射和有序列表

端口是一个标量,候选配置中只有一个最终值。dns 是映射,有的工具只换其中一键,有的工具会把整段替换。比如原配置已经有 nameserver,仅覆写 enable 后若上游设置从运行文件消失,就说明这次不是按子键保留原段。对已有映射比较复杂的档案,先导出当前生效值,再根据工具实际行为决定是否需要提交完整映射。

规则和策略组都是列表,但比较时关注点不同。规则的顺序决定优先级;策略组通常还依赖名称和候选引用。假设原档案已经定义「办公出口」并使用下方第一段规则,要单独让 www.example.com 直连,第二段才是期望的最终结果。这两段都是正常的内核 YAML,拿来核对合并结果,不是任何客户端通用的覆写指令。若采用追加而刚好接到 MATCH 后面,文件可以载入,例外仍然不会生效。

rules:
  - DOMAIN-SUFFIX,example.com,办公出口
  - MATCH,DIRECT
rules:
  - DOMAIN,www.example.com,DIRECT
  - DOMAIN-SUFFIX,example.com,办公出口
  - MATCH,DIRECT

如果更新后看见两个同名策略组,不要只留排在前面的那一个就结束。先看是否误用了列表拼接,再确认两个组各自原来的候选从哪里来。可能应按名称替换一个组,也可能只需要改一个组的候选。类似地,节点提供器的路径若从覆写目录搬到运行目录,解析位置可能有变化;检查相对路径时,以内核实际采用的工作目录为准。

按解析、接入、匹配的顺序验收

改动以前留一份可运行的快照,并记下当前档案和模式。改动以后先看生成文件是否含有目标字段,再载入检查有无解析错误和占用提示。能启动后只做一组对照:用同样的接入方式访问应该直连和应该交给策略组的两个目标,核对命中项及出口。两个结果都符合预期,再手动更新一次订阅,重复看生成文件,确认这项改动能经受更新。

如果新配置一载入就闪退或让系统断网,先撤回最后应用的覆写并恢复已知可用档案,再确认系统代理或 TUN 没有继续指向已经退出的内核。能恢复时,重新尝试一项最小改动,保留第一条有意义的报错。与其同时替换端口、DNS 和整张规则表,不如先证明哪一级出错。需要按日志继续定位,可查启动闪退的处理办法和常见故障排查。