mihomo 进阶配置手册

01 / 配置基线

配置来源、运行文件与验证顺序

打开客户端的配置页，先找到当前启用的配置，再查看运行配置或内核配置入口。订阅下载得到的文件、本地编辑的文件和最终交给 mihomo 的文件，可能是三个不同对象。界面中的系统代理、端口、DNS 或 TUN 开关也可能参与生成过程。排查时先记录当前配置名称、配置目录和实际监听端口，再开始修改。只看订阅编辑器里的一行字段，不能确定内核已经使用它；运行日志与最终生成文件才是核对生效结果的起点。

建立一份可回退的配置基线

先导出当前能联网的配置，并单独保存本地覆写内容。备份中可能包含订阅地址、服务器口令或控制接口口令，应放在本机受限目录，分享截图时遮住这些信息。建议每轮只修改一个模块，例如先换策略组，再调整 DNS，最后启用 TUN。这样故障出现时可以准确关联到最近一次变更。直接运行内核的用户还应记录启动命令与工作目录；相对路径会受配置目录影响，换目录启动可能导致规则文件和面板资源找不到。

阅读 YAML 时，先检查层级和重复键。缩进使用空格，同一层保持一致，列表项前写短横线；字段名中的短横线与列表标记作用不同。含特殊字符的字符串可以加引号，尤其是口令、带查询参数的地址和含冒号的文本。不要在文件末尾再追加第二个 dns 或 rules 顶层键来模拟覆盖：不同解析方式可能报错，也可能只保留其中一份，最后得到的结果往往与编辑时的直觉不一致。

# 合入已有可用配置；保留原来的出站和规则
mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
external-controller: 127.0.0.1:9090

先做语法检查，再观察实际连接

如果使用独立内核，可以执行下面的命令测试文件；路径按本机实际位置调整。测试能发现无法解析的 YAML、部分字段错误与引用问题，但不能证明远端服务可达，也不能证明系统流量经过该进程。图形客户端通常提供配置检查、重载或日志入口，优先使用它们操作。检查失败时从日志里第一处有意义的错误开始看，后续报错可能只是同一个层级错误引出的结果，逐条盲改反而容易破坏原本正确的部分。

mihomo -t -f ./config.yaml

语法通过后，重新加载配置，再关闭测试应用原有连接并发起新请求。在连接页确认目标域名、命中规则、策略链和出站名称；如果只刷新页面，浏览器可能复用旧连接，使新规则看起来没有生效。需要区分本地接入与远端出口时，可显式指定本地代理端口测试。下面的命令仅验证 HTTP 代理入口可用，不能替代 TUN 路由验证；端口应与运行配置一致，目标站点也可以换成当前需要排查的公开站点。

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

客户端选择也影响配置入口的位置。新装可先在客户端下载页选择首推的 Clash Plus，并按系统芯片选包；已有 Clash Verge Rev 或 FlClash 的用户可以沿用当前客户端，重点确认它实际运行的内核与支持字段。配置结构的逐段阅读见config.yaml 结构解析。遇到端口被占用、权限被拒绝或启动失败，先到帮助中心处理基础故障，再继续本手册的高级设置，避免把环境问题误判为规则问题。

02 / 出站决策

策略组类型与自动选优实战

打开代理页，先观察规则最后指向哪个策略组，再展开这个组查看成员。策略组是出站选择层，不是流量识别层：规则决定一条连接进入哪个组，组再决定使用哪个出站。修改组内选项通常不需要改写整套规则，因此适合把业务意图与具体订阅内容分开。比如让业务规则统一指向“业务出口”，再让这个组包含手动选择和自动选择两种路径。组名可以自定义，但所有引用必须逐字一致，包括空格、大小写与标点。

先区分手动选择、优选与故障切换

select 适合明确指定出口，或作为上层菜单在多个子组间切换；url-test 根据探测结果选择延迟较低的可用成员；fallback 更强调成员顺序，通常优先使用排在前面的可用成员。它们都不能保证目标业务的实际体验与探测结果一致。测试地址只代表到该地址的访问条件，视频、下载与企业系统可能采用不同网络路径。排错时先固定一个已确认可用的成员，再观察业务连接，避免自动切换让测试条件不断变化。

load-balance 用于按策略分配新连接，不等于把多个出口带宽合并给同一条连接。对登录会话、支付页面或限制出口一致性的服务，频繁改变出口可能触发重新验证，因此更适合流量特征明确的场景。需要稳定访问的业务，可以单独建立 select 组并固定出口。分组越复杂，阅读连接链条的成本越高；先用一个手动组加一个优选组覆盖常见需要，再根据真实使用情况逐步拆分。

用本地代理集合搭建两层选择

下面示例的前提是配置目录下已有 providers/nodes.yaml，文件中包含合法的 proxies 列表，内容由现有订阅或本机配置提供。示例不生成远端账号，也不替代订阅。先确认代理集合能被加载，再把两个组加入已有配置。use 引用代理集合，proxies 引用单个出站或其他组；二者都不是填写订阅 URL 的位置。用于探测的地址应能稳定访问，并且确实适合当前网络。

proxy-providers:
  local-nodes:
    type: file
    path: ./providers/nodes.yaml

proxy-groups:
  - name: 自动选择
    type: url-test
    use:
      - local-nodes
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 50
  - name: 业务出口
    type: select
    proxies:
      - 自动选择
      - DIRECT
    use:
      - local-nodes

interval 是探测间隔，单位为秒；tolerance 是切换容差，单位为毫秒，用来减少结果接近时的反复切换。把间隔设得很短会增加探测请求与唤醒频率，在移动网络上也会消耗额外流量。若同一代理集合启用了健康检查，而多个策略组又各自测试，需要审视是否存在重复探测。不同测试层服务于不同目的，优先保留能够解释、能够观察的一套安排，而不是把所有检查同时打开。

验证时，先在规则中让一个明确的测试域名指向“业务出口”，再分别选“自动选择”和一个具体成员，新建连接后查看策略链。上层组不能间接引用自身，否则会形成循环；订阅更新后，如果组内只写死了已经删除的成员，也可能出现空组或引用失败。需要筛选集合时可以使用过滤字段，但应先在代理页确认筛选结果确实有成员。自动优选解决的是候选出口之间的选择问题，DNS 失败、认证失败或目标服务限制仍需单独排查。

03 / 规则维护

规则集订阅化管理与匹配优先级

打开运行配置的 rules 段，先确认自定义规则在订阅规则之前还是之后。mihomo 通常按从上到下的顺序匹配，遇到能够决定去向的规则就采用该结果；因此最具体的业务例外应放在前面，范围较大的地区规则和最终兜底放在后面。把规则列表拆成规则集，可以把内容维护与路由意图分开：规则集负责列出域名或网段，主配置负责决定这些对象走直连、代理还是拒绝。

先对齐规则内容与 behavior

rule-providers 定义规则来源，RULE-SET 在主规则列表中调用它。behavior: domain 面向域名集合，ipcidr 面向地址段集合，classical 则使用带类型的经典规则条目。格式与行为是两个维度：YAML、文本或二进制格式描述文件怎样存储，behavior 描述每条内容怎样解释。拿到规则订阅后先阅读它的格式说明，不能仅凭文件扩展名判断内容，更不能把完整客户端配置直接当成规则集载入。

先用本地文件建立最小测试比直接接入远端更容易定位问题。下面第一个片段写入 rules/local-direct.yaml，文件位于配置目录之下；第二个片段合入主配置。示例使用 classical 行为，每条规则写类型与匹配内容，不在规则文件里写最终策略。主配置里的 RULE-SET 才把整个集合导向 DIRECT。兜底使用前章建立的“业务出口”，如果采用其他组名，应同步修改引用。

# rules/local-direct.yaml
payload:
  - DOMAIN-SUFFIX,apple.com
  - DOMAIN-SUFFIX,example.com
  - IP-CIDR,192.168.0.0/16,no-resolve

# 合入主配置
rule-providers:
  local-direct:
    type: file
    behavior: classical
    format: yaml
    path: ./rules/local-direct.yaml

rules:
  - RULE-SET,local-direct,DIRECT
  - GEOIP,CN,DIRECT
  - MATCH,业务出口

把远端更新与本地例外分开

确认本地规则命中后，再将需要持续维护的集合改为 type: http，填写可信来源提供的真实规则地址、缓存路径与更新间隔。interval 以秒为单位，不必为了追求及时把它设成极小值。不同规则集应使用不同的本地缓存路径，避免互相覆盖。首次启动时若缓存还不存在，远端规则必须能够成功获取；已有缓存时的可用表现则与文件状态和内核处理有关，因此要同时查看下载日志与规则集加载结果。

规则集下载本身也要经过网络路径。若下载地址需要代理才能访问，而代理路径又依赖尚未加载的同一规则集，可能形成启动依赖环。可在客户端提供的资源下载策略里指定已经可用的出口，或为规则源域名建立明确、可工作的访问路径。不要只看规则页是否出现集合名称，还应查看载入日志、更新时间和实际命中情况。下载成功但条目数异常、行为类型不符或内容为空，都会让路由效果偏离预期。

no-resolve 常用于 IP 类规则，表示不为匹配该条规则而主动把域名解析成 IP。它不等于关闭整个连接的 DNS，也不意味着该连接从此没有地址信息；已经是 IP 的请求仍可按地址匹配。域名规则通常更直观，IP 规则适合网段与缺少域名的连接。将宽泛的 IP 规则放在业务域名规则之前，可能让业务过早落入直连或代理，因此应该结合连接页显示的规则类型判断实际匹配顺序。

需要继续细分时，可阅读自定义规则语法与优先级，以及国内外分流配置实战。订阅更新后例外丢失时，应调整覆写合并位置，而不是反复编辑远端生成文件。共享配置前同时检查规则来源是否可信、规则是否会将敏感业务导向意外出口；规则文本能正常解析，只说明结构可读取，并不等于策略符合使用需求。

04 / 域名解析

DNS 配置优化与解析路径拆分

打开 DNS 设置前，先在日志里确认失败发生在域名解析、代理服务器连接还是目标站点响应阶段。DNS 负责把域名转换为后续可使用的信息，但浏览器、操作系统、客户端和远端代理都可能参与解析。同一个域名在命令行能打开、在浏览器打不开，可能是浏览器使用了自己的加密 DNS；代理服务器域名解析失败，也不代表目标网站的解析服务有问题。先区分“解析谁”和“请求走哪里”，再决定修改哪个字段。

把引导解析与普通查询分开看

nameserver 定义主要上游，default-nameserver 用于解析 DNS 上游自身的域名等引导需要，proxy-server-nameserver 则用于代理服务器域名解析。使用带域名的加密 DNS 地址时，内核必须先知道该服务器的 IP，才能建立连接；如果引导过程又依赖尚未建立的代理，就容易卡在启动阶段。下面是便于理解的最小分工片段，使用真实公共解析服务，不代表它们在所有网络环境下都有同样可达性。

dns:
  enable: true
  listen: 127.0.0.1:1053
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  default-nameserver:
    - 223.5.5.5
  nameserver:
    - https://dns.alidns.com/dns-query
  proxy-server-nameserver:
    - 223.5.5.5
  fake-ip-filter:
    - "*.lan"
    - "localhost"

将监听地址放在回环接口，可以让本机进程或 TUN 劫持路径访问它，同时减少局域网暴露。端口 1053 只是一个可选示例，运行配置与相关重定向设置必须一致。写入 listen 不会自动把 macOS 的所有 DNS 查询交给内核；系统 DNS、TUN 的 DNS 劫持与应用自身解析仍要分别确认。若需要让其他设备使用本机解析服务，还要检查监听地址、防火墙、访问范围与回程路由，而不只是改成全接口监听。

按域名选上游，而不是盲目堆叠服务

nameserver-policy 可为特定域名或匹配集合指定上游，适合企业内部域、家庭网络域名与需要指定解析来源的业务。先为一个明确的域名建立策略并验证，再逐步扩大范围；直接加入大量上游，可能增加请求并发、路径不确定性与排错成本。使用规则集作为 DNS 匹配条件时，还应确认当前内核支持相应语法，且规则集已经加载。路由规则中的策略名与 DNS 上游配置各有语法，不能把其中一套字符串直接搬到另一处。

如果启用 respect-rules，上游 DNS 连接会按相应路由规则处理，这时代理服务器域名的独立解析尤其重要。没有可用出口之前就让解析依赖代理，可能形成循环。先保证代理服务器域名能通过明确可达的解析服务取得地址，再处理普通网站查询。配置中若还同时出现 fallback 与过滤条件，应阅读它们的实际判定方式：它不是简单的“第一个服务器失败才用第二个”，不能按传统顺序备用 DNS 的直觉判断行为。

验证解析时，区分真实 IP 模式与 Fake-IP 模式。Fake-IP 下看到映射网段地址通常是设计结果，不能因为地址不像网站公网 IP 就判断解析错误。改 DNS 后先重建连接，必要时再清理相关缓存；同时清空所有缓存会丢掉诊断线索，也可能制造短时波动。对解析服务的选择应结合当前网络、隐私需求与访问目标，不必机械照抄一套公共配置。涉及本机内网服务时，保留可回退的原有 DNS 设置，避免调整期间影响工作网络。

05 / 系统接入

TUN、系统代理与 Fake-IP 协同

打开系统代理后，先检查需要使用的应用是否遵循系统代理；只有部分应用或命令行工具接入时，再考虑 TUN。系统代理主要向应用公布 HTTP、HTTPS 或 SOCKS 接入信息，是否采用取决于应用实现；TUN 则通过虚拟网络接口和路由接管更广泛的 IP 流量。二者不是必须同时开启的两个加速开关。先保留一个已经验证的接入方式，确认目标应用的流量进入内核，再根据需要增加接管范围。

启用 TUN 前先核对系统权限

在 macOS 客户端里找到 TUN 或服务模式入口，按提示完成辅助服务安装和系统授权，然后重新查看运行日志。不同客户端的按钮名称可能不同，授权流程也会随系统变化；应以当前界面为准，不要为了解决授权问题而关闭系统安全机制。独立运行内核通常需要足够的网络权限。启用失败时先检查权限、虚拟接口建立和路由配置，远端代理是否可用是后续步骤，两类问题应分别验证。

# 合入现有可用配置；DNS 仍需使用上一章的有效设置
tun:
  enable: true
  stack: mixed
  auto-route: true
  auto-detect-interface: true
  dns-hijack:
    - any:53

auto-route 用于自动建立接管路由，auto-detect-interface 用于检测出站接口，stack 决定 TUN 使用的网络栈。示例中的 mixed 是一种选择，遇到兼容性问题时应依据内核支持情况比较其他栈，而不是同时改 MTU、DNS、规则和系统路由。dns-hijack 接管进入相关路径的常规 DNS 查询，但应用直接发往加密 DNS 服务的 HTTPS 请求，并不会因为目的端口是网络请求就自动变成普通 DNS 查询。

理解 Fake-IP 地址为什么能连接网站

Fake-IP 为域名分配映射地址，连接到来时再根据映射还原域名并执行规则。这样内核可以在无需先取得目标真实地址的情况下保留域名语义，有利于域名分流，也能减少某些本地解析路径对结果的影响。它并没有把映射网段变成真实网站所在的网络，更不意味着网站最终不需要实际连接。代理出站与直连出站如何解析和建立远端连接，仍取决于协议、DNS 设置及出站行为。

fake-ip-filter 用于让指定域名避开虚拟映射，适合确实依赖真实解析结果的业务，例如某些局域网服务发现或对地址结果敏感的程序。先为出现问题的具体域名建立例外，再测试功能恢复情况，不要把全部域名加入过滤列表来消除表象。若更换 Fake-IP 网段，需要确认它与现有网络、企业 VPN 和其他虚拟接口不冲突。已经缓存旧映射的应用可能继续访问旧地址，因此修改后要考虑连接与 DNS 缓存的生命周期。

验证 TUN 不能只运行带 --proxy 的命令，因为显式代理请求可能绕过需要验证的系统接管路径。选择一个不单独设置代理的应用，新建连接并在客户端连接页找它；再测试局域网设备、休眠唤醒和网络切换。Wi-Fi 切到有线网络后，如果日志仍指向旧接口，应先检查接口检测与路由恢复。多个代理客户端同时启用 TUN 时，可能出现路由竞争、重复 DNS 接管或回环，测试期间只保留当前需要的一套接管机制。

如果启用后整机断网，按逆序回退：先关 TUN，确认系统代理状态，再恢复原有 DNS 与网络连接。不要立即删除所有配置，这会把可定位的问题变成重新安装任务。界面显示开关开启，只代表配置意图，不代表虚拟接口、路由和 DNS 均已成功。把授权日志、接口状态和目标连接记录连起来看，才能判断故障位于接入层还是出站层；基础恢复步骤也可在帮助中心继续查阅。

06 / 连接识别

域名嗅探的用途、边界与排错

打开连接页，先找出真正缺少域名的连接，再判断是否需要启用嗅探。部分应用直接提交 IP，或者使用独立解析路径，导致内核收到连接时没有原始域名。域名嗅探可以从部分协议握手或明文请求信息中提取域名，补充规则匹配依据。它不是抓取所有加密内容的通用工具，也不是打开后所有 IP 流量都能变回域名。目标是否携带可识别信息、协议是否受支持以及握手是否可见，都会影响结果。

先保守启用，再决定是否覆盖目标

HTTP 请求可能包含主机信息，TLS 握手可能携带服务器名称，QUIC 的部分握手也可能提供可识别线索。现代加密握手保护、非标准协议、纯 IP 服务和无法读取的握手都会限制识别能力。配置中的 sniff 指定尝试识别的协议与端口范围，并不意味着这些端口上的所有流量都使用对应协议。下面的片段先保留原连接目标，只补充识别条件，适合观察嗅探是否改善规则判断。

sniffer:
  enable: true
  force-dns-mapping: true
  parse-pure-ip: true
  override-destination: false
  sniff:
    HTTP:
      ports:
        - 80
        - 8080-8880
    TLS:
      ports:
        - 443
        - 8443
    QUIC:
      ports:
        - 443

parse-pure-ip 允许对缺少域名的纯 IP 连接尝试识别；force-dns-mapping 与 DNS 映射场景的处理有关。是否覆盖目的地址由 override-destination 控制，它与“为规则取得一个域名”是不同层次的决定。保留原目的地址有助于减少应用选定地址被替换后的差异；确实需要覆盖时，应对目标业务单独验证。尤其是依赖特定 CDN 地址、专用网关或固定访问路径的应用，域名识别正确也不代表改写目的地一定合适。

用同一连接比较规则证据

排查时先固定策略组成员，然后选定一个具体业务：关闭嗅探，新建连接并记录目标、规则类型和出站链；再开启嗅探，重复同样操作。不要把两个不同网页或两个已经复用的连接拿来直接比较。若日志没有出现域名，并不一定是字段未生效，也可能是流量没有经过内核、端口不在识别范围，或协议没有可提取信息。先确认接入层，再看协议识别，最后才调整规则，顺序反过来会让问题越来越复杂。

嗅探结果不是 DNS 查询结果的替代品。某条连接携带的服务器名称可能只是入口域名，而业务随后访问的内容域名另有其名；同一 IP 也可能承载多个域名。仅凭地址反查去猜测域名，无法稳定恢复应用原始意图。规则应该尽量使用可验证的业务域名集合，而不是把一次抓到的主机名当成整个服务的永久边界。处理登录、媒体和更新服务时，还要考虑跳转域名与资源域名是否走了不同出口。

若开启后某个应用握手失败、连接等待变长或访问了错误入口，先关闭目的地址覆盖，再针对该业务缩小嗅探范围。内核支持的跳过域名等字段可以用于建立局部例外，但具体语法应与当前内核文档一致。不要因为单个业务异常就把全局 DNS、TUN 与嗅探一并重置，这会失去比较基础。更有效的方法是保留原本可用路径，只修改一项识别行为，并在日志中核对该项是否真的影响了连接。

分享排错材料时，截取必要的目标域名、规则类型与错误信息即可，避免上传整段连接历史。域名与访问时间本身也可能包含工作和个人使用信息。需要进一步判断规则写法时，可以回到规则集章节，检查域名规则是否被更早的 IP 规则截走；如果连接根本没有出现在列表中，则回到TUN 与系统代理章节，确认应用使用的网络路径。嗅探应服务于明确的识别缺口，而不是作为所有连接问题的默认开关。

07 / 配置维护

本地覆写与多订阅合并

打开配置管理页，先找到客户端提供的覆写、扩展或合并入口，再决定自定义内容放在哪里。远端订阅是持续更新的数据来源，直接编辑下载后的文件，下一次刷新时很容易被替换。更稳妥的分工是：订阅提供代理数据，本地覆写保留端口、DNS、业务规则和策略组织。不同客户端对这些功能的命名与执行顺序不完全相同，因此不能只复制一份覆写文件就假定所有客户端都会以相同方式处理。

先弄清对象合并与列表合并

配置中的映射对象和列表需要不同处理。映射对象可能按字段递归合并，也可能整段替换；列表则可能前置、后置、拼接或完全替换。规则列表顺序决定匹配优先级，所以“追加成功”不等于“例外生效”。自定义直连规则若被放在 MATCH 后面，就没有机会处理流量。DNS 子字段也可能被客户端设置再次覆盖，排查时必须查看最终运行文件，而不是只看覆写编辑器里保存了什么。

先建立一个很小的本地例外，确认它在运行配置中的位置，然后再搬入完整规则。下面是用于理解目标结果的最终规则片段，不是所有客户端通用的覆写文件格式。它假设前面章节已建立“业务出口”，并把本机与私有网段安排在宽泛规则之前。是否允许这些地址直连应结合实际网络要求；企业网络中的专用网段、其他 VPN 分配的地址与容器网络，也应逐项检查，避免用一个过宽范围掩盖真实路由需求。

# 目标运行配置中的规则顺序
rules:
  - DOMAIN-SUFFIX,lan,DIRECT
  - 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
  - GEOIP,CN,DIRECT
  - MATCH,业务出口

把多个订阅拆成独立代理集合

多订阅合并时，优先判断来源提供的是完整 Clash 配置，还是可以直接作为代理集合读取的内容。完整配置包含 DNS、规则与其他顶层字段，不能简单塞进只期待代理列表的位置。将每个可用来源组织为独立 proxy-providers 后，再由本地策略组引用，通常更便于维护。两个来源使用不同的集合键和缓存路径，业务规则只引用本地稳定组名；这样上游调整服务器列表时，主规则不必跟着频繁改动。

代理名称冲突是合并时常见的隐患。两个来源可能使用相同名称，却对应不同服务器；手动拼接 proxies 时可能造成重复或引用歧义。先保留来源边界，用独立集合检查成员，再决定是否需要受支持的名称处理方式。不要随意改写节点名称后仍沿用旧策略组引用，也不要把多个文件中的同名顶层键直接拼接。脚本转换如果不可避免，应使用当前客户端明确支持的接口，并保留原始文件以便回退。

修改完成后，主动执行一次订阅更新，再检查自定义内容是否仍然保留。这比等待几天后发现规则失效更容易定位问题。导出的运行配置也不一定包含完整的维护逻辑：它可能只有合并后的结果，缺少覆写顺序、脚本或外部集合来源。因此备份应包括配置数据和生成方式，但敏感订阅地址仍应妥善保存。向他人展示配置时，使用去除账号信息的最小复现文件，不要直接共享整份个人备份。

如果客户端并不提供需要的合并能力，可以先使用一份稳定主配置加本地文件集合，避免为了自动化引入无法审视的订阅转换链。确需转换时，应理解第三方服务能够接触到订阅中的信息。关于 URL、剪贴板和本地文件的导入差异，可查阅订阅格式与导入方法；这里只处理导入之后怎样长期维护。判断维护方案是否合适，重点看更新能否重复、例外能否保留、最终结果能否解释，而不是配置文件是否足够复杂。

08 / 本机控制接口

外部控制面板与配置变更闭环

需要外部控制面板时，先在运行配置中检查 external-controller 的监听地址，再确认面板运行在哪里。控制接口用于查询连接、切换策略和管理内核运行状态，它不是应用连接网站时使用的代理端口。把面板连接到 7890 这类 mixed-port，通常不会得到控制接口响应。对本机使用而言，优先监听回环地址，并保留现有客户端的管理方式；图形客户端可能依赖同一个接口，随意改端口会让界面与内核失去连接。

本机接口与静态面板资源分开配置

external-ui 指定本地静态面板文件目录，目录里应当已有兼容面板的页面资源。内核不会因为看到目录字段，就自动拥有完整前端文件。下面的片段只说明本机监听和本地目录关系；合入前确认端口空闲，且客户端允许修改控制接口。需要口令时，应通过客户端支持的安全方式在本机设置足够强的独立值，并让面板使用同一个值。不要把实际口令写进公开示例、截图或可被同步分享的配置链接。

# 仅用于本机；先将面板静态文件放入对应目录
external-controller: 127.0.0.1:9090
external-ui: ./ui

面板通常需要填写接口地址、端口和认证信息。接口拒绝连接时，先看监听是否存在；出现认证错误时，再核对口令；只有浏览器访问失败而命令行可达时，才继续检查跨域、安全上下文或混合内容限制。回环地址始终指向访问者自己的设备：手机浏览器填写 127.0.0.1 并不会连到电脑。需要跨设备控制时，应使用受控的安全访问方式，并理解监听范围扩大后增加的风险，而不是直接把管理端口暴露到公网。

只读检查先于写入操作

初次连接面板，先查看当前模式、策略组与连接列表，确认对应的是预期内核实例。电脑上同时运行两个客户端时，面板可能连到了旧进程，导致切换策略看似成功却不影响当前流量。核对监听端口、当前配置与一条新建连接，能够避免这种误判。下面命令演示本机版本接口的只读请求，响应可以帮助确认接口可达；启用了认证时，需要按本机实际设置附带认证头，不能因为请求未带认证而把拒绝访问当成内核损坏。

curl --fail --silent --show-error \
  http://127.0.0.1:9090/version

通过面板切换组成员后，要确认变化是否需要持久保存。运行状态、客户端配置和远端订阅是不同层次，重启后能否恢复选择取决于内核配置与客户端管理方式。不要把一次接口写入当作已经更新了本地覆写文件。使用脚本自动操作时，应先验证响应和目标组名，再进行有限范围的修改；接口错误、组名变化或当前配置切换，都可能使脚本作用于错误对象。自动化的价值在于重复可靠，而不是省略检查。

连接列表适合验证域名、规则与策略链，日志适合查看下载、解析和握手错误。调试期间可以临时提高日志详细程度，但完成后应恢复日常级别，避免积累过多访问记录。面板来源也需要审慎选择：能够调用控制接口的页面可能读取连接信息并执行管理操作，应只使用可信的本地资源或明确了解的部署。浏览器提示证书、跨域或内容安全问题时，先弄清调用关系，不宜为了打开面板就宽泛放开所有来源。

最后做一次完整回归：订阅能够更新，代理集合与规则集能够加载，系统代理或 TUN 按预期接入，DNS 能处理常用域名，内网服务仍可访问，面板控制的是当前实例。再测试休眠唤醒与网络切换，确认不是只在刚启动时可用。若某一步失败，回到本手册对应章节缩小范围；首次安装与基本导入仍以快速上手教程为主，客户端选择回到下载页，一般性故障查阅帮助中心。保留一份可解释、可恢复的配置，比一次性打开所有高级功能更便于长期维护。