Clash 配置进阶

策略组类型与实战

策略组解决的是“匹配到这类连接后，使用哪个出口”。规则负责识别流量，策略组负责选择目标，节点负责建立实际连接。三者不能混为一谈：规则命中正确但访问失败，问题可能在组内选项或节点；节点可以连接但业务走错出口，则应回到规则顺序和组名引用。先在连接页面记录命中的规则、策略链与最终出口，才有依据判断应改哪一层。

手动选择、自动测试与故障回退

select 用于明确选择一个成员，适合需要固定出口的业务。成员既可以是节点，也可以是其他策略组。建议把手动选择保留为最外层入口，让自动组成为其中一个可选项。这样在自动测试结果与真实业务体验不一致时，可以临时固定出口，而不必重新编辑所有规则。选择状态可能由客户端或内核缓存保存，重载配置后应检查实际选中项。

url-test 定期访问测试地址，依据测试结果选择成员；tolerance 用于减少轻微差异引起的频繁切换。测试衡量的是到该地址的访问情况，不代表任意网站、下载任务或实时通话的表现。fallback 更强调按成员顺序选择可用出口，适合主备安排；首个可用成员恢复后可能重新被选择，因此不应把它理解为永远保持当前节点的粘性组。

load-balance 将不同连接分配给成员，常见策略包括 consistent-hashing 与 round-robin。它并不是把一条连接拆到多个节点叠加带宽。某些业务对出口变化敏感，例如登录会话、支付验证和长连接服务；这类流量通常更适合固定选择。即使采用一致性哈希，也要考虑成员增删会改变分配结果，不应把出口稳定性当作绝对保证。

先建立可理解的策略链

下面的最小片段只使用内置直连目标，便于理解引用关系。实际使用时，把已经存在的节点或自动组加入“手动出口”的成员列表。业务组引用出口组，规则再引用业务组，名称必须完全一致。名称中出现空格或特殊字符时建议加引号。避免业务组与出口组相互引用，循环依赖会使配置无法通过检查，或让界面显示的选择链失去意义。

proxy-groups:
  - name: 手动出口
    type: select
    proxies:
      - DIRECT
  - name: 日常访问
    type: select
    proxies:
      - 手动出口
      - DIRECT

rules:
  - DOMAIN-SUFFIX,example.com,日常访问
  - MATCH,手动出口

当节点来自 proxy-providers 时，组内通过 use 引用提供者名称，而不是把订阅 URL 填入 proxies。自动组通常还需要 url 与 interval；例如测试地址可选 https://www.gstatic.com/generate_204，间隔可设为 300 秒。该地址只是连通性探测目标，网络环境不适用时应更换，不要根据一个探测结果删除整份订阅。

切换后的验证与排错

修改组内选择后，先新建一个访问请求，再查看连接详情。已经建立的连接通常不会因为组切换自动迁移，浏览器连接复用也会保留旧出口；需要验证时可关闭相关连接或重新启动测试应用。关闭连接会中断正在进行的任务，因此应先确认下载、会议和远程会话可以结束。不要把旧连接没有变化误判为配置重载失败。

若自动组始终没有可选成员，依次检查提供者是否成功加载、过滤表达式是否过严、成员名称是否匹配，以及健康检查是否执行。若成员存在却频繁切换，再查看探测超时、测试地址可达性和容差设置。尽量减少重复探测：多个自动组同时对同一批节点高频测试，会增加连接数量和电量消耗，尤其不适合移动设备长期运行。

规则集订阅化管理

规则集把“识别哪些流量”的内容从主配置分离出来。主配置保留策略顺序与目标组，提供者文件维护域名或网段集合。这样更新一个业务分类时，不必改动全部节点和 DNS 参数。订阅化也引入了新的依赖：规则来源、下载路径、本地缓存和格式必须相互匹配。规则集下载成功不代表已经参与匹配，还需要在 rules 中通过 RULE-SET 引用。

选择 behavior 与文件格式

behavior: domain 面向域名集合，ipcidr 面向网段集合，classical 面向包含规则类型的完整条目。不能仅凭文件扩展名判断行为类型。同样是 YAML，域名集合的内容可能是 +.example.com，而 classical 条目可能是 DOMAIN-SUFFIX,example.com。把两者混用会出现解析失败或匹配不符，导入前应阅读来源对格式的说明。

format 决定文件如何被读取，可按来源选择 yaml、text 或相应的二进制规则格式。YAML 规则集通常在 payload 下列出条目；文本格式则按行保存。二进制规则格式有行为类型限制，不应把任意 classical 文件改个扩展名就当作可用。需要转换时使用内核支持的转换工具，并保留原始数据以便检查转换前后的语义。

先用本地规则集验证链路

下面先定义文件型提供者，避免把远程下载问题与匹配问题混在一起。示例的 ./rules/local-sites.yaml 是相对配置工作目录的路径，不一定等于界面里导入文件所在的位置。桌面客户端可能在独立的内核目录生成运行配置，应先确认实际工作目录，并在那里创建规则文件。目录不存在或文件权限不足时，先处理读取错误，再检查规则内容。

rule-providers:
  local-sites:
    type: file
    behavior: domain
    format: yaml
    path: ./rules/local-sites.yaml

rules:
  - RULE-SET,local-sites,DIRECT
  - MATCH,手动出口

在对应的 local-sites.yaml 中写入下列内容。+.example.com 是 mihomo 域名集合常见的后缀匹配写法，用于覆盖该域及其子域。注意这与 rules 中的逗号分隔完整规则不是同一种结构。保存后重载，访问相应域名并查看连接规则；本节的“手动出口”沿用上一章定义，若单独测试，需要先创建同名策略组。

payload:
  - '+.example.com'
  - '+.example.org'

本地匹配验证成功后，再改为 type: http，增加真实 url 与 interval，保留唯一的缓存 path。更新间隔的单位为秒，应按来源变化频率设置，不必为了“及时”进行高频请求。如果规则来源必须经代理下载，可按当前内核支持情况指定下载使用的策略；同时确保该策略不依赖尚未加载的同一份规则，避免初始化环节互相等待。

规则顺序比分类数量更重要

连接通常按规则从上到下匹配，先命中的条目决定策略。把少量明确例外放在前面，业务分类放在中间，兜底 MATCH 放在最后。大范围网段或宽泛域名集合过早出现，会截走后面的精细规则。两个规则集存在重叠并不一定错误，但必须明确重叠时谁优先；否则同一个域名因调整顺序而改变出口，看起来就像节点不稳定。

IP 类规则可能触发解析以获得目标地址；适用的条目可以使用 no-resolve 避免为匹配主动解析，但代价是当连接只有域名、尚无目标 IP 时可能无法命中该规则。它不是提升所有规则性能的通用开关。先确认该分类是靠域名还是网段识别，再选择行为类型；不要把域名规则、IP 规则和进程规则全部塞进一个难以追踪的集合。

更新失败与缓存边界

远程更新报错时，检查获取地址是否仍有效、返回内容是否确实为规则文件、下载连接是否被现有规则拒绝，以及本地缓存是否可写。浏览器打开地址看到登录页面，不代表内核可以取得规则数据。旧缓存可能让已有分类继续工作，也可能掩盖来源已经失效；应查看提供者更新时间和日志，而不是只根据页面能访问判断更新成功。

DNS 配置优化

DNS 配置需要同时回答三个问题：由谁接收应用查询、由谁解析目标域名，以及访问解析器本身走哪条路径。客户端启用了 DNS 功能，不等于所有应用都使用该解析入口。浏览器内置加密 DNS、系统缓存、局域网解析器和 TUN 接管范围，都会影响实际路径。优化应从观察查询来源开始，而不是一次填入大量解析器，期待数量自动带来可靠性。

区分业务解析与节点地址解析

nameserver 用于一般目标解析；default-nameserver 主要承担解析器域名的引导解析，并不是所有查询失败后的统一备用。代理节点服务器如果使用域名，其解析发生在建立代理连接之前，可通过 proxy-server-nameserver 单独安排。否则节点地址解析依赖尚未建立的代理，就可能产生循环：需要连接代理才能查询，但需要查询完成才能连接代理。

nameserver-policy 为特定域名选择解析器，适合内部域名或有明确解析要求的业务。应把局域网名字交给能够理解该网络的解析服务，而不是一律交给公共解析器。下面是演示结构，地址仅表示一种参数组合，实际应依据网络可达性选择。监听地址限定在本机；如果只测试 DNS，不必先把监听端口暴露给其他设备。

dns:
  enable: true
  listen: 127.0.0.1:1053
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  default-nameserver:
    - 1.1.1.1
  nameserver:
    - https://cloudflare-dns.com/dns-query
  proxy-server-nameserver:
    - https://cloudflare-dns.com/dns-query
  nameserver-policy:
    '+.home.arpa':
      - system

home.arpa 是家庭网络名称使用的特殊域；示例将它交给系统解析路径，但系统解析器仍须实际支持该名称。不要据此假设任意局域网都有同一套域名。企业内网可能要求指定内部 DNS 地址，修改前记录原有系统设置。若设备同时连接 VPN 与本地网络，还要确认访问内部解析器的路由，没有被代理规则或另一个隧道截走。

理解加密解析的传输路径

DoH 和 DoT 保护的是到解析器的查询传输，不决定业务连接最终是否代理。使用加密 DNS 仍然需要可达的解析器、正常的系统时间与有效的证书链。若启用 respect-rules，解析器连接会按规则选择路径，需要同时妥善配置节点域名解析，避免循环依赖。该参数不是越早打开越好，先验证基础解析，再检查解析器连接的规则命中。

fallback 与 fallback-filter 可以帮助按域名或返回地址选择解析结果，但增加后也会引入更多查询和依赖。不同解析器对同一域名给出不同地址，可能来自 CDN 调度、缓存时间或访问位置，不应仅凭“不一样”判断某个结果异常。先记录失败域名、解析答案和实际连接地址，再决定是否需要策略化解析，而不是把所有差异都交给备用解析器处理。

用单域名测试代替整体重置

在具有 dig 的系统上，可以执行下列命令直接查询本地监听端口。Fake-IP 模式下收到映射地址属于预期现象；这个测试说明本地 DNS 能回答，并不能单独证明真实业务可连接。继续发起应用访问，查看连接是否保留域名、规则是否正确以及出口是否可用。若未收到答案，则检查监听状态、配置是否生效和端口是否被其他进程使用。

dig @127.0.0.1 -p 1053 example.com A

若只有浏览器失败而命令查询正常，先检查浏览器安全 DNS、扩展和缓存；若所有应用都失败，再检查系统 DNS 与接管配置。切换增强模式后，旧解析缓存可能保留不适用于新路径的地址，应关闭相关应用连接并按系统方式清理缓存。遇到 HTTPS 证书报错，不要通过关闭证书验证来掩盖问题，可参考证书错误与代理关系解析区分时间、证书链和网络路径。

TUN 与 Fake-IP

TUN 是流量接管入口，Fake-IP 是 DNS 与连接关联方式，两者可以配合，但并非同一开关。系统代理主要影响遵循代理设置的应用；TUN 通过虚拟网络接口与路由，让更多 IP 流量进入内核。Fake-IP 为查询建立域名到映射地址的关系，连接进入内核后再按域名处理。理解这两个层次，才能解释“开了 TUN 仍有应用未进入”或“收到映射地址却无法访问”的现象。

权限、虚拟接口与默认路由

启用 TUN 前先确认 Clash 客户端具备创建接口和调整路由的权限。桌面系统通常需要管理员授权、服务模式或特权辅助组件；移动系统通过 VPN 授权建立接管接口。界面开关显示开启，只说明客户端尝试启动，应继续查看内核日志中的接口与路由状态。多个 VPN、虚拟机网络或安全软件同时修改路由时，不能仅靠反复重启客户端判断冲突来源。

下面是常见的起始片段。auto-route 自动配置接管路由，auto-detect-interface 尝试选择出口接口，dns-hijack 将指定 DNS 流量交给内核 DNS 模块。stack: mixed 的实际支持与行为应以运行内核为准；如果客户端生成了自己的 TUN 配置，应在最终运行文件中确认值，而不是只检查原始订阅文件。

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

dns:
  enable: true
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  fake-ip-filter:
    - '*.lan'
    - '*.local'
    - '+.home.arpa'

DNS 劫持针对这里列出的传统 DNS 端口流量，不会自动解密应用内置的 DoH，也不等于接管所有组播名称发现协议。局域网发现、打印和设备控制可能走独立协议，需要结合系统路由观察。移动端的 VPN 实现与桌面 TUN 字段也不完全等价，某些开关由客户端接管，不能把桌面 YAML 的每个字段都当作手机界面一定提供的选项。

Fake-IP 映射与例外域名

映射地址不是网站的真实服务器地址，不应复制到浏览器中作为永久访问入口。应用应通过域名查询得到映射，再由内核依据映射关联建立实际连接。若查询在内核完成、连接却绕过内核，应用会尝试把映射地址当作真实目的地访问，结果可能超时。因此，Fake-IP 模式下需要保证相关查询与业务连接的路径一致，尤其是在仅接管部分应用时。

fake-ip-filter 用于让特定名称按过滤模式返回真实地址，常用于需要实际地址的本地服务或兼容性例外。示例按默认的黑名单过滤方式理解；若另设过滤模式，应重新核对列表语义。过滤不是“让这些域名直连”的规则，它只改变解析回答方式，最终出口仍由 rules 决定。添加例外后还要检查缓存与现有连接，否则应用可能继续使用旧映射。

映射范围通常使用专门用途地址段，不能随意改成家庭网络正在使用的私有网段。若它与已有路由、另一 VPN 或实验网络冲突，需要同时调整 DNS 映射范围和接管路径，而不只是更换一个地址。IPv6 也必须整体考虑：应用可能优先使用 AAAA 结果，如果只验证 IPv4，会漏掉 IPv6 路径未被接管的情况。是否启用 IPv6 应依据网络和客户端支持确定。

平台差异与恢复顺序

排查时先关闭其他 VPN，保留一个接管入口，再验证内核是否成功创建接口。随后检查 DNS 回答，最后新建连接观察规则命中。只有特定应用失败时，查看应用绕过列表、协议类型和自带解析；全局断网时，优先考虑路由与 DNS 环路。完整的节点超时排查可参考订阅到 DNS 的逐项排查顺序，不要同时删除全部配置。

域名嗅探

域名嗅探用于从连接初始数据补充目标域名，帮助只有 IP 信息的连接匹配域名规则。例如应用自行解析后直接连接地址，内核可能没有对应的 DNS 映射；嗅探可在协议允许的范围内读取 HTTP Host、TLS 握手中的服务器名称或支持的 QUIC 握手信息。它补充的是可观察的协议元数据，并不是读取所有应用内容，也不是解决任意连接故障的通用工具。

何时需要补充域名

如果连接详情已经有正确域名，并且规则命中符合预期，通常没有必要扩大嗅探范围。更值得启用的情况是：同一业务经常只显示 IP，域名分类因此失效，而目标协议本身具有可观察的名称。先挑一个具体业务对照启用前后的连接详情，确认是否确实补充了域名，再考虑扩大覆盖。不要只看到日志里出现嗅探动作，就认为出口已按预期改变。

下面的示例限定常见 HTTP 与 TLS 端口，并保留本地名称跳过列表。force-dns-mapping 与 parse-pure-ip 会扩大尝试范围，适合已经确认存在映射缺失或纯 IP 连接的情形。初次排查可先不加这两个参数，观察默认范围是否足够；同时修改接管、解析与嗅探，会让验证结果难以对应到单一原因。

sniffer:
  enable: true
  force-dns-mapping: true
  parse-pure-ip: true
  sniff:
    HTTP:
      ports:
        - 80
        - 8080-8880
      override-destination: false
    TLS:
      ports:
        - 443
        - 8443
  skip-domain:
    - '+.home.arpa'
    - '*.lan'

补充域名与覆盖目标的区别

嗅探得到域名后，内核可以用它辅助规则匹配；是否用该域名覆盖连接目标，则由相应配置控制。override-destination 会改变目标处理方式，可能使后续解析和连接不再沿用应用原先选定的 IP。对于 CDN、内网映射或刻意指定地址的业务，这种变化未必合适。示例把 HTTP 的覆盖设置为关闭，是为了先观察分类效果，而不是立刻改变所有连接的目标地址。

当应用连接某个 IP，但握手中的名称指向另一个服务时，应先理解这是否是正常的共享托管或特殊网络设计，再决定是否覆盖。不能仅因嗅探结果“像域名”就认定它一定适合作为新的连接目标。若原业务需要保留特定地址，可限定端口、增加跳过域名，或对该场景关闭覆盖；修改后要同时比较命中规则与最终连接地址，而非只看页面能否打开。

加密协议的可观察边界

TLS 的服务器名称并不在所有情况下都可被观察。采用加密客户端握手信息的连接、没有名称的握手以及非标准协议，都可能让嗅探无法获得有效域名。QUIC 也受内核支持、握手格式与接管路径影响。把 QUIC 加入嗅探配置，只代表尝试识别相应流量，不意味着把 UDP 自动转换为 TCP，也不代表节点一定具备该业务需要的 UDP 转发能力。

嗅探通常需要等待连接开始阶段的数据。端口范围设置过宽时，会让大量与预期协议无关的连接进入尝试流程，增加排查复杂度。对游戏、实时语音和自定义服务，应先确认协议，再决定是否纳入。连接建立缓慢时，比较关闭嗅探与限定端口后的结果；只有结果可重复且变化明确，才把问题归因于嗅探，而不是依据一次偶然的访问成功下结论。

跳过规则与分层验证

skip-domain 用于排除不适合嗅探处理的名称，常见对象是内部域名、需要保持原始目标的服务或已经确认存在兼容问题的业务。它与 Fake-IP 过滤列表的职责不同：前者限制嗅探，后者改变 DNS 回答。一个域名出现在其中一份列表，不代表自动进入另一份。若需要同时调整，应分别写明原因，避免日后删除一处配置却遗留另一处例外。

验证可以分三次进行。先保持原配置，记录域名是否存在以及实际出口；随后只开启嗅探，检查域名是否补充、规则是否改变；最后在确有需要时尝试目标覆盖，比较连接地址与业务表现。每一步都新建连接，保留可以回退的配置文件。日志级别临时提高到足够观察即可，排查结束后恢复日常级别，减少不必要的域名和访问记录留存。

本地覆写与多订阅合并

订阅配置与本地偏好有不同的维护周期。订阅方更新节点、策略与规则，本地用户维护监听端口、DNS、业务例外和接管范围。直接编辑下载得到的订阅文件，下一次更新可能覆盖修改；把本地内容拆成覆写层，才能持续复用。需要注意，覆写并非 mihomo 统一规定的一种界面功能：不同 Clash 客户端可能采用合并文件、脚本、图形选项或配置模板，实际顺序必须在客户端中确认。

原始配置、覆写层与运行配置

建议区分三份材料：订阅保存的原始文件、用户维护的覆写内容，以及客户端交给内核的最终运行文件。问题定位应以最后一份为准。界面中某个开关可能在生成阶段覆盖 YAML，同一个字段也可能被模板重复赋值。若原始文件写着 DNS 已开启，但运行文件没有对应块，继续编辑原始文件不会解决问题；应找出生成顺序和后续覆盖来源。

映射结构与列表结构的合并方式常常不同。DNS 参数有时按字段合并，rules、proxy-groups 和节点列表却可能被整体替换。不能把通用 YAML 合并工具的行为推定为客户端行为。测试时先只覆写一个可观察字段，例如日志级别，确认运行文件变化，再增加规则列表。若整个规则列表被替换，需要明确保留订阅规则，而不是误以为“增加一条”只会追加。

用提供者统一节点来源

多订阅合并不一定要拼接两份完整 Profile。更容易维护的方法，是把支持的节点来源作为多个 proxy-providers，主配置只维护一套策略和规则。下面演示两个 HTTP 提供者的结构，地址为教学示例，必须在本地换成真实、兼容的节点来源。并非所有完整订阅都能直接当作节点提供者使用；导入前确认响应格式，特别是是否包含适用的 proxies 数据。

proxy-providers:
  source-a:
    type: http
    url: https://example.com/provider-a.yaml
    path: ./providers/source-a.yaml
    interval: 3600
  source-b:
    type: http
    url: https://example.org/provider-b.yaml
    path: ./providers/source-b.yaml
    interval: 3600

proxy-groups:
  - name: 合并出口
    type: select
    use:
      - source-a
      - source-b
    proxies:
      - DIRECT

每个提供者应使用独立路径，避免不同来源写入同一个缓存文件。更新间隔按来源安排，必要时手动更新，不要把两个来源强制设成很短的周期。节点名称重叠时，界面选择和日志阅读容易产生歧义；应使用客户端支持的名称整理或提供者覆写机制增加来源标识。不要在名称中混入真实订阅凭据，也不要靠删除名称中的所有字符来解决重复。

本地规则应放在明确的位置

新增本地例外时，先确定插入位置。如果规则追加在订阅的 MATCH 后面，通常不会再被匹配。更合理的做法是将少量本地规则放在前部，再接入订阅原有规则或规则提供者。客户端若提供“前置规则”和“后置规则”，也应检查最终顺序，尤其是模板自动补兜底条目的情况。一次加入大量例外，会让业务异常时难以判断究竟是哪条改变了路径。

策略组引用也需要随合并检查。原订阅中的规则可能引用“自动选择”，而新模板只定义“合并出口”；即使节点都导入成功，未定义的策略名称仍会使配置报错。规则提供者名称、节点提供者名称和策略组名称属于不同引用关系，不能只做全文替换。先列出每类定义，再逐项核对引用；修改名称时同步检查规则、组内成员和控制面板显示。

验证语法与功能回归

如果可以直接使用内核命令行，可用配置测试检查结构和引用关系。下列命令要求系统能够执行 mihomo，且当前目录中的文件存在；桌面客户端也可能提供配置检查入口。语法测试通过，不等于节点凭据有效、规则来源可下载或全部业务正常，因此仍要进行功能回归。优先检查本地服务、常用网页与一个需要代理的业务，分别观察连接详情。

mihomo -t -f ./config.yaml

每次订阅更新后，都应抽查运行配置是否仍包含本地 DNS、例外规则和接管设置。保存一份短变更记录，注明修改字段、目的及恢复方式，比保留很多无法辨认的备份文件更有帮助。如果更新后启动崩溃，先回到最近可用配置，再根据启动崩溃的日志定位方法检查语法、路径和权限，避免把全部 Profile 一并清空。

外部控制面板

外部控制接口用于读取运行状态、切换策略、查看连接和管理部分内核功能。面板只是接口的可视化客户端，不是另一套代理内核。打开面板页面不代表已经连接到当前 Clash 客户端，应核对控制地址、鉴权方式和实例。一个页面可能连接旧进程，系统代理却指向新进程；出现“切换成功但连接不变”时，先确认控制对象，而不是马上重装软件。

先绑定本机，再考虑远程访问

external-controller 设置 HTTP 控制接口监听地址。普通桌面使用建议绑定 127.0.0.1，让接口只接受本机连接。secret 是接口访问口令，应在本地设置足够长且独立的值。下面故意只展示监听与本地界面目录，不提供可复制的公共口令；使用外部面板前，在自己的配置中补充鉴权设置。不要把控制口令与节点密码或订阅令牌共用。

external-controller: 127.0.0.1:9090
external-ui: ./ui

external-ui 指向已准备好的面板静态文件目录，并不会仅凭这行配置生成完整界面。目录的相对位置仍取决于内核工作目录，客户端也可能自带面板并自动设置路径。先确认入口文件存在、内核能够读取，再访问面板。若只出现空白页面或资源加载失败，检查界面目录与静态资源路径；不要将这类前端加载错误误判为代理节点故障。

接口鉴权与浏览器限制

常规 HTTP API 使用 Bearer 鉴权，即请求携带 Authorization 头。面板一般通过连接设置保存控制地址和口令，填写后先读取基础状态，再尝试切换。浏览器的跨来源限制与接口鉴权是不同层次：口令正确仍可能被跨来源策略阻挡。若使用独立来源的面板，应按内核支持的 CORS 配置限定可信来源，而不是为了排错允许任意网站访问本地控制接口。

HTTPS 页面访问 HTTP 控制地址还可能遭遇混合内容限制，特别是控制接口不在本机时。不要通过关闭浏览器安全功能作为长期方案。优先使用客户端内置面板，或将面板与控制服务安排在合适的同源路径。若必须远程管理，应使用受控隧道或具有鉴权与 TLS 的管理入口，并明确限制可访问的人与网络范围，不能把控制端口当作普通公开网页端口。

先执行只读检查

下面的命令读取环境变量中的本地口令，不把真实值写进文档。执行前在自己的终端环境中设置 MIHOMO_SECRET；如果没有设置，命令会提前报错而不是发送空鉴权。返回成功说明对应地址的接口可访问，但还需要核对是否为当前实例。查看连接与日志时只保留排查需要的信息，避免把包含访问域名和网络地址的完整结果公开上传。

: "${MIHOMO_SECRET:?请先在本地设置控制口令}"
curl --fail --silent --show-error \
  -H "Authorization: Bearer ${MIHOMO_SECRET}" \
  http://127.0.0.1:9090/configs

只读检查正常后，再使用面板切换一个手动组，并新建连接确认策略链。直接调用 API 时，还要处理名称的 URL 编码，不能把含空格或中文的组名原样拼接后假设所有工具都会正确转换。修改操作通常影响运行状态，不一定写回订阅文件；重载或重启后能否保留，取决于缓存与客户端保存机制。需要长期生效的字段仍应在正确的配置层维护。

控制端口与代理端口分开排查

控制接口端口用于管理，HTTP、SOCKS 或混合代理端口用于业务连接，两者不能互换。浏览器把控制端口填进系统代理后，网页访问会失败；面板把混合代理端口填成控制地址，也无法取得策略列表。检查配置时将端口用途写清楚，核对是否被其他进程占用。如果运行多个实例，为每个实例使用独立的工作目录和控制端口，避免缓存、规则文件与界面操作互相干扰。

面板连接失败可按响应分层定位：无法建立连接时检查监听地址、进程和防火墙；返回未授权时检查口令与请求头；页面能开但数据失败时检查控制地址、跨来源限制与浏览器控制台。策略切换生效但旧业务不变，则回到现有连接复用问题。不要通过临时开放全部监听地址解决本机连接错误，本机管理并不需要让整个局域网都能访问接口。

形成可重复的配置检查流程

完整检查顺序应保持稳定：先确认当前 Profile 与运行实例，再核对最终 YAML；接着检查提供者是否加载、策略组是否有成员、规则是否命中；然后验证 DNS 与接管路径，最后才调整嗅探或面板。每次只改一个因素，记录原值与观察结果。需要返回快速上手流程时，继续阅读使用文档；需要按具体表现定位时，前往疑难解答，不必从头重建已经正常工作的配置层。