openclash/.github/skills/openclash-user-guide/SKILL.md

name	description	instructions	type	tags	argument-hint	user-invocable	disable-model-invocation
openclash-user-guide	OpenClash 用户功能指南。用于回答用户关于 OpenClash 插件如何启用/关闭各项功能的问题，包括：运行模式切换、代理开关、DNS 设置、流量控制、访问控制黑白名单、IPv6 开关、规则/GEO 更新、自动重启、仪表盘设置、订阅管理、覆写设置等。每个选项均标注了对应的 UCI 配置项、修改的 Mihomo YAML 配置段、以及触发的脚本。Use when user asks how to enable, disable, configure, or troubleshoot any OpenClash feature on OpenWrt.	You are an OpenClash expert assistant. OpenClash is a LuCI plugin for OpenWrt that manages the Mihomo (Clash Meta) proxy kernel. When answering user questions about OpenClash: 1. Always provide LuCI web UI navigation paths (e.g. 服务 → OpenClash → 插件设置 → 流量控制), not command-line unless explicitly requested. 2. Explain underlying principles (firewall chains, YAML transformation logic) — not just steps. 3. Check dependency integrity first when troubleshooting (see 完整依赖清单与故障排查 section). 4. Never guess — if information is not covered in this document, actively query Mihomo Wiki (https://wiki.metacubex.one/config/), Meta-Docs (https://github.com/MetaCubeX/Meta-Docs), OpenClash source code (https://github.com/vernesong/OpenClash/tree/dev), Mihomo core source code (https://github.com/MetaCubeX/mihomo/tree/Alpha), or Smart core source code (https://github.com/vernesong/mihomo/tree/Alpha). 5. Cite sources when information comes from external queries.	knowledge-base	openclash openwrt mihomo clash proxy networking	询问 OpenClash 功能如何开启/关闭	true	false

OpenClash 完整功能参考指南

AI 行为总则

本文档是 AI 的知识库，而非给用户看的说明书。任何 AI 模型（Copilot / Claude / ChatGPT / Gemini / DeepSeek 等）在回答 OpenClash 相关问题时均应遵循以下原则。

原则	说明
主动查证，不猜测	遇到本文档未覆盖的 Mihomo 配置字段或实现细节时，禁止编造。必须使用工具主动查询外部资源（Mihomo Wiki / Meta-Docs / Mihomo 核心源码 / OpenClash 源码 / Smart 核心源码），整理后告知用户。详见文档末尾「超出本文档范围的查询」节。
查源码，不只查文档	当用户询问"为什么某选项不生效"、"底层实现逻辑是什么"时，不能仅依赖 [Mihomo Wiki] 和 [Meta-Docs] 的配置文档。必须进一步查阅 Mihomo 核心源码、OpenClash 源码 和 Smart 核心源码 中的对应脚本/函数，理解实际执行逻辑。
给出 LuCI 操作路径	所有操作指导必须指向 LuCI Web 界面的具体操作路径（如「服务 → OpenClash → 插件设置 → 流量控制」），而非命令行。仅在用户明确要求命令行操作时才提供终端命令。
解释原理，不只给步骤	说明配置选项背后的工作原理（如防火墙规则链、YAML 转换逻辑），帮助用户理解后再操作，降低误操作风险。
先排查依赖	用户报告功能异常时，首先检查依赖包是否完整。本文档「完整依赖清单与故障排查」节提供了完整的依赖速查表。
引用来源	当信息来自外部查询（Mihomo Wiki、源码、Issues 等），在回复末尾注明来源，让用户知道信息的权威性。
先要日志，不盲猜	当用户问题描述不完整、缺少关键报错信息，或本文档无对应内容时，不应猜测排查方向。应首先要求用户提供调试日志，并给出日志生成指引：① LuCI 页面操作：「插件设置 → 调试日志」页面点击「生成日志」按钮；② SSH 命令操作：/usr/share/openclash/openclash_debug.sh 生成日志文件（输出路径/tmp/openclash_debug.log）。拿到日志后再对照本文档「日志与错误信息速查」节或者文档、源码进行诊断。
查 Issues，不闭门造车	当用户遇到的功能问题在本文档中未覆盖，或报错信息在错误速查表中无匹配项时，必须主动搜索 Issues 查找是否存在相同或相似的问题：① 插件配置/订阅/防火墙/UI 相关问题 → 搜索 OpenClash Issues；② 内核级问题（代理协议/TUN/DNS 解析/规则引擎等 Mihomo 核心行为） → 搜索 Mihomo Issues。优先参考：作者/维护者的回复（OpenClash 标有 Owner 标签的 vernesong；Mihomo 标有 Contributor/Collaborator 标签的回复）——代表官方立场或已知 bug；高赞反应（👍）的社区回复——代表经过验证的有效方案；同类问题中的诊断命令（如 nft list set、dig、uci show 等）——可直接复用于用户的问题排查。搜索时使用用户报错中的关键错误信息或功能描述作为关键词。

核心资源速查:

资源	URL	用途
Mihomo Wiki	https://wiki.metacubex.one/config/	Mihomo YAML 配置字段文档
Meta-Docs	https://github.com/MetaCubeX/Meta-Docs	Mihomo 配置字段权威参考
OpenClash Issues	https://github.com/vernesong/OpenClash/issues	搜索插件侧已知问题、社区方案、作者回复
Mihomo Issues	https://github.com/MetaCubeX/mihomo/issues	搜索内核侧已知问题（代理协议/TUN/DNS/规则引擎等）
Mihomo 核心源码	https://github.com/MetaCubeX/mihomo/tree/Alpha	Mihomo 核心实现（代理协议/规则引擎/DNS/TUN 等 Go 源码）
OpenClash 源码	https://github.com/vernesong/OpenClash/tree/dev	插件实现逻辑（Shell/Ruby/Lua 脚本）
Smart 核心源码	https://github.com/vernesong/mihomo/tree/Alpha	Smart 策略、LightGBM 模型实现

---

完整依赖清单与故障排查

AI 行为指引: 当用户报告启动失败、功能异常、日志报错时，AI 应首先对照下表检查依赖完整性。 指导用户在 LuCI 的「插件设置 → 调试日志」页面点击「生成调试日志」按钮，可自动生成完整的 依赖检查报告（含 #===== 依赖检查 =====# 段）。对于缺失的依赖，指导用户在 LuCI 的「系统 → 软件包」中搜索安装，而非让用户执行命令行。

固件提醒: 推荐使用 ImmortalWrt 或 OpenWrt 官方固件（需自行将 dnsmasq 替换为 dnsmasq-full）。不推荐使用第三方魔改/高大全固件、以及已停止维护的旧版固件。旁路由组网存在固有的网络层面缺陷，强烈建议采用主路由架构部署 OpenClash。

一、包依赖总览（来自 Makefile DEPENDS 和 init.d 运行时检查）

OpenClash 依赖以下软件包，由 opkg/apk 在安装时自动拉取。若手动卸载了其中某个包，会导致对应功能异常。

依赖包	作用	缺失症状	安装命令 (LuCI)
dnsmasq-full	DNS 转发与劫持（必须用 full 版，非精简版）	DNS 劫持失效、客户端无法解析域名	「系统→软件包」搜索 dnsmasq-full
bash	所有 Shell 脚本的解释器	启动脚本执行失败	搜索 bash
curl	HTTP/HTTPS 下载（订阅、GEO、Dashboard）	订阅更新失败、GEO 下载报错	搜索 curl
ca-bundle	CA 证书包（curl HTTPS 验证）	curl SSL 证书错误	搜索 ca-bundle
ip-full	策略路由和 ipset/nftset 操作	路由表操作失败	搜索 ip-full
ruby	YAML 解析与配置生成	yml_change.sh 报错、配置无法生成	搜索 ruby
ruby-yaml	Ruby YAML 库	Ruby YAML 解析报错、订阅处理失败	搜索 ruby-yaml
ruby-psych	Ruby YAML 解析引擎（新版依赖）	同上，日志提示 "Ruby Works Abnormally"	搜索 ruby-psych
ruby-pstore	Ruby 持久化存储（订阅缓存）	订阅配置缓存异常	搜索 ruby-pstore
kmod-tun	TUN 虚拟网卡内核模块	TUN 模式无法启动	搜索 kmod-tun
kmod-inet-diag	进程名诊断（PROCESS-NAME 规则）	PROCESS-NAME 规则不生效	搜索 kmod-inet-diag
unzip	解压 Dashboard/GEO 等压缩包	Dashboard 下载后无法加载	搜索 unzip
luci-compat	LuCI >= 19.07 兼容层（新版 LuCI 必装）	LuCI 页面布局错乱、JS 报错	搜索 luci-compat

二、防火墙相关依赖（按 fw4/fw3 自动区分）

环境	依赖包	作用	缺失症状	安装命令 (LuCI)
fw4 (nftables)	kmod-nft-tproxy	nftables TPROXY 透明代理（UDP）	UDP 无法代理、启动日志报 "nft_tproxy module not found"	搜索 kmod-nft-tproxy
fw3 (iptables)	kmod-ipt-tproxy	iptables TPROXY 模块	UDP 无法代理、日志报 "xt_TPROXY"	搜索 kmod-ipt-tproxy
fw3 (iptables)	iptables-mod-tproxy	iptables TPROXY 用户态工具	TPROXY 规则无法创建	搜索 iptables-mod-tproxy
fw3 (iptables)	kmod-ipt-extra	iptables 扩展匹配模块	高级规则匹配失败	搜索 kmod-ipt-extra
fw3 (iptables)	iptables-mod-extra	iptables extra 用户态工具	同上	搜索 iptables-mod-extra
fw3 (iptables)	kmod-ipt-nat	iptables NAT 内核模块	REDIRECT/DNAT 规则失败	搜索 kmod-ipt-nat
fw3 (iptables)	ipset	IP 集合管理工具	中国 IP 绕行、黑白名单失效	搜索 ipset

三、dnsmasq 特殊要求

要求	说明
必须使用 dnsmasq-full	OpenWrt 自带的 dnsmasq 精简版缺少 ipset/nftset 支持，OpenClash 的 DNS 劫持和 chnroute 旁路依赖此功能
ipset 编译选项	dnsmasq --version 输出需包含 ipset（fw3 环境必需）
nftset 编译选项	dnsmasq --version 输出需包含 nftset（fw4 环境，影响 chnroute_pass 的 nftset 集成）

诊断方法: 先在 LuCI 的「插件设置 → 调试日志」页面生成调试日志，在日志的依赖检查段确认 dnsmasq 版本。如需手动确认，可在路由器终端执行 dnsmasq --version | head -1。 如果不是，在 LuCI 的「系统 → 软件包」中卸载 dnsmasq 然后安装 dnsmasq-full。

四、内核模块加载机制（check_mod() 函数）

init.d/openclash 的 check_mod() 函数以四级回退方式检查和加载内核模块：

1. 容器检测 — 检测 Docker/LXC/Podman 等容器环境，容器内直接返回成功（无法加载内核模块）
2. 内核编译检查 — 检查 /proc/config.gz 中是否有 CONFIG_<MODULE>=y（静态编译进内核，无需 modprobe）
3. 已加载检查 — lsmod | grep 检查模块是否已在内核中加载
4. 动态加载尝试 — modprobe <module> 尝试加载，全部失败则输出 LOG_ERROR

TUN 模块注意事项: check_mod "tun" 仅在 TUN 模式 或 IPv6 TUN 模式 时才被调用。Redir-Host/Fake-IP（非 TUN）模式下不会检查 kmod-tun。

五、更新后自动修复依赖（openclash_update.sh）

插件更新后，install_missing_packages() 会遍历以下关键包列表，对缺失的包自动重装（支持 opkg 和 apk 双包管理器，最多重试 3 次）：

luci-compat kmod-inet-diag kmod-nft-tproxy kmod-ipt-nat iptables-mod-tproxy iptables-mod-extra ipset

六、常见依赖故障速查

故障现象	可能原因	LuCI 排查路径
启动失败，日志显示 "Ruby Works Abnormally"	ruby 或 ruby-yaml 未安装/损坏	「系统→软件包」确认 ruby、ruby-yaml、ruby-psych 已安装
TUN 模式启动报错 "tun module not found"	kmod-tun 未安装或内核版本不匹配	「系统→软件包」安装 kmod-tun，注意内核版本匹配
订阅更新报 SSL 证书错误	ca-bundle 未安装或过期	「系统→软件包」安装/更新 ca-bundle
DNS 劫持不生效	安装了精简版 dnsmasq 而非 dnsmasq-full	「系统→软件包」卸载 dnsmasq，安装 dnsmasq-full
UDP 流量无法代理（fw4）	kmod-nft-tproxy 未安装	「系统→软件包」安装 kmod-nft-tproxy
Dashboard 页面白屏/404	unzip 未安装导致仪表盘解压失败	「系统→软件包」安装 unzip，然后重新下载仪表盘
LuCI 页面布局错乱、按钮无响应	luci-compat 未安装	「系统→软件包」安装 luci-compat
进程名规则 (PROCESS-NAME) 不生效	kmod-inet-diag 未安装	「系统→软件包」安装 kmod-inet-diag
更新插件后某些包丢失	更新过程中包被意外移除	更新脚本会自动修复，如仍未恢复，手动安装缺失包

通用依赖诊断方法: 在 LuCI 的「插件设置 → 调试日志」页面点击「生成调试日志」，然后在日志的 #===== 依赖检查 =====# 段查看所有依赖包的状态（已安装/未安装）。将此日志提供给技术支持时也包含完整的依赖信息。

---

系统架构速查

┌─────────────────────────────────────────────────────────────────┐
│  LuCI Web UI (Lua CBI)  — http://路由器LAN_IP/cgi-bin/luci      │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐                        │
│  │ settings │ │ overwrite│ │ subscribe│ ...                     │
│  └────┬─────┘ └────┬─────┘ └────┬─────┘                        │
│       │  UCI 读写    │            │                              │
│       ▼             ▼            ▼                              │
│  /etc/config/openclash  — UCI 配置文件 (所有选项持久化在此)       │
│       │                                                         │
│       ▼ Shell Scripts ( /usr/share/openclash/ )                 │
│  ┌──────────────────────────────────────────────────────┐       │
│  │ openclash.sh        → 订阅下载/更新/节点过滤           │       │
│  │ openclash_core.sh   → 核心二进制更新                  │       │
│  │ openclash_update.sh → 插件 IPK 更新                   │       │
│  │ openclash_geo.sh    → GEO 数据库下载 (ipdb/dat/geosite/asn)  │
│  │ openclash_chnroute.sh → 大陆 IP 路由表更新             │       │
│  │ yml_change.sh       → Ruby 修改 YAML (端口/模式/DNS/TUN/认证) │
│  │ yml_rules_change.sh → Ruby 修改 YAML (规则/Provider/URL-Test) │
│  │ openclash_debug.sh  → 诊断日志收集                    │       │
│  │ openclash_watchdog.sh → 核心存活 + 流媒体解锁守护       │       │
│  └──────────────────────────────────────────────────────┘       │
│       │                                                         │
│       ▼ 生成 / 覆写                                              │
│  /etc/openclash/config/*.yaml  — 原始订阅配置                    │
│  /etc/openclash/*.yaml          — 经脚本处理后的运行配置          │
│  /etc/openclash/overwrite/     — 覆写模块文件                    │
│  /etc/openclash/custom/        — 用户自定义规则/DNS/防火墙脚本    │
│       │                                                         │
│       ▼                                                         │
│  /etc/openclash/clash  — symlink → /etc/openclash/core/clash_meta│
│  /etc/openclash/        — GEO 数据: Country.mmdb, GeoSite.dat 等 │
└─────────────────────────────────────────────────────────────────┘

API 入口: http://路由器LAN_IP:9090 (external-controller)
Dashboard: http://路由器LAN_IP:9090/ui/

关键目录说明:

路径	作用
/etc/config/openclash	UCI 配置文件，所有 LuCI 选项持久化在此
/etc/openclash/	OpenClash 工作目录（核心、GEO 数据、Chnroute 列表）
/etc/openclash/config/	原始订阅配置存放目录（.yaml 文件，经 yml_change.sh 处理后生成 /etc/openclash/<name>.yaml 运行配置）
/etc/openclash/overwrite/	覆写模块文件（INI 格式，定义自定义 YAML 覆盖）
/etc/openclash/custom/	用户自定义文件（规则列表、DNS 策略、Hosts、防火墙脚本、Sniffer 配置等）
/etc/openclash/core/	核心二进制存放目录（多版本共存，/etc/openclash/clash 是到 core/clash_meta 的 symlink）
/etc/openclash/dashboard/	Dashboard 静态文件（yacd/metacubexd/zashboard）
/etc/openclash/Model.bin	LightGBM 智能策略模型文件（注意：不是目录，是单个 .bin 文件）
/usr/share/openclash/	插件脚本目录（Shell/Ruby/Lua 脚本）
/tmp/openclash.log	运行日志
/tmp/openclash_start.log	启动日志
/tmp/etc/openclash/	小闪存模式下的工作目录（重启后清空）
/var/etc/openclash.include	防火墙规则加载文件（由 firewall UCI 自动 include）

• UCI 配置根: openclash (所有选项均在 uci show openclash 可见)
• Mihomo 运行时 API: http://路由器LAN_IP:9090 — 部分动态选项通过 PATCH /configs 热生效。注意：API 地址是路由器 LAN 口 IP，不是 127.0.0.1（核心监听 0.0.0.0，但 LuCI 后端通过 127.0.0.1 直连核心 API）
• 核心启动脚本: /etc/init.d/openclash {start|stop|restart|reload|enable|disable}
• 自定义文件目录: /etc/openclash/custom/ — 存放用户自定义规则/DNS/防火墙脚本

---

系统启动完整流程

理解此流程是理解所有选项实现逻辑的基础

/etc/init.d/openclash start_service()
│
├─ 第1步: 读取配置
│   ├─ overwrite_file()     → 遍历 config_overwrite 条目，生成 /tmp/yaml_overwrite.sh
│   ├─ get_config()         → 读取所有 UCI 选项为 Shell 变量
│   ├─ config_choose()      → 选择活动的 YAML 配置文件
│   └─ do_run_mode()        → 解析 en_mode → 拆分 en_mode_tun/en_mode_fakeip/en_mode_mix
│
├─ 第2步: 环境准备
│   ├─ do_run_file()        → 检查/下载核心二进制 (/etc/openclash/core/clash_meta)
│   ├─ 创建 symlink         → ln -s /etc/openclash/core/clash_meta /etc/openclash/clash
│   └─ 小闪存模式处理       → 将文件移到 /tmp/etc/openclash
│
├─ 第3步: 修改 YAML 配置（按顺序执行）
│   ├─ ① yml_change.sh     → Ruby 脚本，~48 个 UCI 参数
│   │   ├─ 设置端口 (proxy_port, tproxy_port, http_port, socks_port, mixed_port, dns_port)
│   │   ├─ 设置模式 (mode, log-level, dns.enhanced-mode)
│   │   ├─ 设置 TUN (tun.enable, tun.stack, tun.device, tun.dns-hijack)
│   │   ├─ 设置 DNS (dns.* 完整段: nameserver, fallback, fake-ip-range, respect-rules...)
│   │   ├─ 设置 Sniffer (sniffer.* 完整段)
│   │   ├─ 设置认证 (authentication: [user:pass])
│   │   ├─ 设置 Meta (tcp-concurrent, unified-delay, find-process-mode, geodata-loader...)
│   │   ├─ 设置 GEO (geox-url.*, geo-auto-update, geo-update-interval)
│   │   ├─ 设置 Smart/LGBM (模型 URL, 更新间隔)
│   │   ├─ 设置 Dashboard (external-controller, secret, external-ui)
│   │   └─ 设置 NTP (ntp.*), CORS, IPv6, routing-mark
│   │
│   ├─ ② yml_rules_change.sh → Ruby 脚本
│   │   ├─ enable_rule_proxy → 注入 BT/P2P 直连规则 + PROCESS-NAME 规则
│   │   ├─ tolerance/urltest_* → 覆写 url-test 策略组参数
│   │   ├─ github_address_mod → 替换 GitHub Raw URL 为 CDN
│   │   ├─ enable_custom_clash_rules → 从 *.list 文件注入自定义规则
│   │   └─ auto_smart_switch → 将 url-test/load-balance 组改为 smart 类型
│   │
│   └─ ③ /tmp/yaml_overwrite.sh  → 来自覆写模块 [Overwrite] 段的自定义脚本
│
├─ 第4步: 启动核心
│   └─ procd 启动 clash -d /etc/openclash -f <config.yaml>
│       ├─ respawn 配置: 重试 5 次, 间隔 3s, 超时 300s
│       └─ rlimit_nofile: 1048576 (最大文件描述符)
│
├─ 第5步: 异步等待核心就绪 (check_core_status "start" &)
│   ├─ 轮询 HTTP 200 from http://127.0.0.1:9090
│   └─ 就绪后执行:
│       ├─ set_firewall()    → 建立 iptables/nftables 透明代理规则
│       │   ├─ REDIRECT/T_PROXY 规则 (按 en_mode)
│       │   ├─ DNS 劫持规则 (按 enable_redirect_dns)
│       │   ├─ 访问控制规则 (按 lan_ac_mode + lists)
│       │   ├─ QUIC 阻断规则 (按 disable_udp_quic)
│       │   ├─ 中国 IP 绕行规则 (按 china_ip_route)
│       │   └─ IPv6 防火墙链 (按 ipv6_enable)
│       └─ change_dnsmasq()  → DNS 劫持 (dnsmasq → Clash DNS)
│
└─ 第6步: 定时任务 + 守护进程
    ├─ add_cron()            → 注册 cron 任务
    │   ├─ openclash.sh      → 定时更新订阅
    │   ├─ openclash_geo.sh  → 定时更新 GEO 数据
    │   ├─ openclash_chnroute.sh → 定时更新大陆路由
    │   └─ /etc/init.d/openclash restart → 定时自动重启
    └─ start_watchdog()      → 启动守护进程
        ├─ openclash_watchdog.sh        → 核心存活监控
        └─ openclash_streaming_unlock.lua → 流媒体解锁守护

停止流程 (stop_service()):

1. 备份策略组状态历史 → 2. revert_firewall() 清除防火墙规则 → 3. kill clash + streaming unlock 进程 → 4. revert_dnsmasq() 恢复 DNS → 5. del_cron() 清除定时任务

热生效 vs 需重启:

操作	方式	延迟
切换代理模式 (rule/global/direct)	Mihomo API PATCH /configs (mode)	即时
切换日志级别	Mihomo API PATCH /configs (log-level)	即时
切换 Sniffer/Rules	Mihomo API PATCH /configs	即时
修改端口/TUN/DNS/覆写	需重启核心 (修改 YAML)	~3-5s
修改防火墙规则	/etc/init.d/openclash reload	即时
修改访问控制	需重启 (重建防火墙链)	~5s

---

防火墙与 DNS 规则详解（iptables + nftables 双后端）

OpenClash 同时支持 fw3 (iptables/ipset) 和 fw4 (nftables) 两种防火墙后端，通过 command -v fw4 自动检测：

• 存在 fw4 → 使用 nftables (OpenWrt 22.03+)
• 不存在 fw4 → 使用 iptables + ipset (旧版 OpenWrt) 所有 if [ -n "$FW4" ] / if [ -z "$FW4" ] 分支互斥，两种后端的规则逻辑完全相同，仅语法不同。

AI 行为指引: 当用户询问透明代理/防火墙相关问题时（如"为什么设备无法上网"、"旁路由模式下流量不走代理"、 "如何验证防火墙规则是否生效"、"TUN 模式下某协议不通"），AI 应首先让用户在 LuCI 的「运行状态」页面 确认核心状态为「运行中」；然后建议用户在 LuCI 的「插件设置 → 调试日志」页面生成调试日志 （包含完整防火墙规则链）。如需实时排查，可在路由器终端执行 nft list ruleset（fw4）或 iptables -t nat -L -n（fw3）查看实际规则。结合下表中的链结构和规则排序，对比用户的需求判断规则是否如预期生效。 如涉及底层实现细节，查阅 OpenClash 源码 中 /etc/init.d/openclash 的 set_firewall() 函数。 常见问题：规则排序错误（bypass 在 redirect 之后）、fwmark 未设置导致策略路由不生效、 DNS 劫持端口与 dnsmasq 冲突。

模式解析表

UCI en_mode	en_mode_tun	数据面	DNS 面
redir-host	(空)	TCP REDIRECT + UDP TPROXY	dns.enhanced-mode: redir-host
fake-ip	(空)	TCP REDIRECT + UDP TPROXY	dns.enhanced-mode: fake-ip
redir-host-tun	1	TCP+UDP 全 TUN	dns.enhanced-mode: redir-host
fake-ip-tun	1	TCP+UDP 全 TUN	dns.enhanced-mode: fake-ip
redir-host-mix	2	TCP REDIRECT + UDP TUN	dns.enhanced-mode: redir-host
fake-ip-mix	2	TCP REDIRECT + UDP TUN	dns.enhanced-mode: fake-ip

全局常量:

PROXY_FWMARK="0x162"       # 所有被代理流量的防火墙标记
PROXY_ROUTE_TABLE="0x162"  # 策略路由表 ID
SKIP_GROUP="65534"         # 绕过代理的组 ID (skgid)

---

一、fw4 (nftables) 链结构 — inet fw4 表

A. DNS 劫持链

enable_redirect_dns=1 (Dnsmasq 转发模式):

# PREROUTING: 劫持发往 53 端口的 DNS → 重定向到 dnsmasq 端口
nft insert rule inet fw4 dstnat position 0 \
  meta l4proto {tcp,udp} th dport 53 \
  counter redirect to <dnsmasq_port> comment "OpenClash DNS Hijack"

# OUTPUT (仅 router_self_proxy=1): 路由器自身 DNS
nft add chain inet fw4 nat_output { type nat hook output priority -1; }
nft insert rule inet fw4 nat_output position 0 \
  skgid != 65534 meta l4proto {tcp,udp} th dport 53 \
  ip daddr {127.0.0.1} counter redirect to <dnsmasq_port>

enable_redirect_dns=2 (防火墙重定向模式):

nft add chain inet fw4 openclash_dns_redirect
nft add rule inet fw4 openclash_dns_redirect \
  meta l4proto {tcp,udp} th dport 53 counter redirect to <dns_port>
nft insert rule inet fw4 dstnat position 0 \
  meta l4proto {tcp,udp} th dport 53 counter jump openclash_dns_redirect

B. 非 TUN 模式链 (en_mode_tun 为空或 2)

链名	钩子来源	协议	动作
openclash	dstnat jump	TCP	REDIRECT → $proxy_port(7892)
openclash_mangle	mangle_prerouting jump	UDP	TPROXY → :$tproxy_port(7895), mark 0x162
openclash_upnp	openclash_mangle jump	UDP	UPNP 端口排除 (RETURN)
openclash_output	nat_output jump	TCP	路由器自身 TCP REDIRECT
openclash_mangle_output	mangle_output jump	UDP	路由器自身 UDP 标记

openclash 链规则排序 (TCP REDIRECT):

# 1. 本地网络绕过
nft add rule inet fw4 openclash ip daddr @localnetwork counter return

# 2. 回复方向绕过
nft add rule inet fw4 openclash ct direction reply counter return

# 3. Fake-IP 范围 (仅 fake-ip 模式)
nft add rule inet fw4 openclash ip protocol tcp \
  ip daddr {198.18.0.0/16} counter redirect to $proxy_port

# 4. WAN 黑名单 IP (WAN-AC)
nft add rule inet fw4 openclash ip daddr @wan_ac_black_ips counter return
# 5. WAN 黑名单端口
nft add rule inet fw4 openclash th dport @wan_ac_black_ports counter return

# 6. LAN 黑名单 IP (LAN-AC, lan_ac_mode=0)
nft add rule inet fw4 openclash ip saddr @lan_ac_black_ips counter return
# 7. LAN 黑名单 MAC
nft add rule inet fw4 openclash ether saddr @lan_ac_black_macs counter return

# 8. 白名单检查 (lan_ac_mode=1)
#    非白名单 → RETURN: ether saddr != @lan_ac_white_macs \
#                         ip saddr != @lan_ac_white_ips counter return

# 9. 非标准端口绕过 (redir-host 模式, common_ports != 0)
nft add rule inet fw4 openclash th dport != @common_ports counter return

# 10. 中国 IP 绕行 (china_ip_route)
#   mode=1: ip daddr @china_ip_route counter return
#   mode=2: ip daddr != @china_ip_route counter return

# 11. 最终代理: 所有剩余 TCP → REDIRECT
nft add rule inet fw4 openclash ip protocol tcp counter redirect to $proxy_port

openclash_mangle 链规则排序 (UDP TPROXY): 同上 #1-#10，最终规则：

# UPNP 排除
nft add rule inet fw4 openclash_mangle ip protocol udp counter jump openclash_upnp
# TPROXY 最终规则
nft add rule inet fw4 openclash_mangle meta l4proto {udp} \
  counter tproxy ip to 127.0.0.1:$tproxy_port meta mark set $PROXY_FWMARK accept

C. TUN 模式链 (en_mode_tun=1)

链名	钩子来源	协议	动作
openclash_mangle	mangle_prerouting jump	TCP+UDP	设置 fwmark 0x162
openclash_mangle_output	mangle_output jump	TCP+UDP	路由器自身 fwmark

openclash_mangle 规则排序 (TUN 模式):

# 1. 跳过 TUN 接口自身流量
nft add rule inet fw4 openclash_mangle meta l4proto {tcp,udp} \
  iifname utun counter return

# 2-10. 同非 TUN 模式的 bypass 检查 (localnetwork/ct reply/WAN-AC/LAN-AC/common_ports/china_ip_route)

# 11. ICMP 代理
nft add rule inet fw4 openclash_mangle ip protocol icmp \
  icmp type echo-request counter meta mark set $PROXY_FWMARK

# 12. UPNP 排除 (UDP)
nft add rule inet fw4 openclash_mangle ip protocol udp counter jump openclash_upnp

# 13. 最终标记 — 全 TUN 模式标记 tcp+udp，混合模式仅标记 udp
nft add rule inet fw4 openclash_mangle meta l4proto {tcp,udp} \
  counter meta mark set $PROXY_FWMARK

TUN 转发规则 (utun 允许通过):

nft insert rule inet fw4 forward position 0 oifname utun counter accept
nft insert rule inet fw4 forward position 0 iifname utun counter accept
nft insert rule inet fw4 input position 0 iifname utun counter accept
nft insert rule inet fw4 srcnat position 0 oifname utun counter return

D. IPv6 链 (独立于 IPv4)

nftables 链	功能
openclash_v6	IPv6 TCP REDIRECT
openclash_mangle_v6	IPv6 UDP TPROXY / TUN fwmark
openclash_output_v6	路由器自身 IPv6 TCP
openclash_mangle_output_v6	路由器自身 IPv6 fwmark
openclash_post_v6	旁路由 SNAT/MASQUERADE

IPv6 模式 (ipv6_mode): 0=TProxy, 1=Redirect, 2=TUN, 3=Mix

E. ICMP/Ping 处理详解

AI 行为指引: 当用户询问「为什么 ping 不走代理」、「ping 通但 TCP 不通」、「Fake-IP 模式下 ping 198.18.x.x 被拒绝」等问题时，AI 应结合本节解释 ICMP 在非 TUN 和 TUN 模式下的不同处理方式。

OpenClash 对 ICMP（ping）请求的处理取决于运行模式：

1. 非 TUN 模式（Redir-Host / Fake-IP，en_mode_tun 为空）:

ICMP echo-request 在 openclash_mangle 链中被仅标记 fwmark（0x162）但不重定向：

nft add rule inet fw4 openclash_mangle ip protocol icmp \
  icmp type echo-request mark set "$PROXY_FWMARK" counter accept comment "OpenClash ICMP Mark"

• ICMP 不会被代理：非 TUN 模式下只有 TCP（REDIRECT）和 UDP（TPROXY）被重定向到 Mihomo 内核，ICMP 仅被标记 fwmark 后直接放行（accept）。这意味着 ping 请求走的是系统原始路由表，不会经过代理节点。
• fwmark 的作用：标记 0x162 仅影响策略路由选择（如旁路由回流），不影响代理行为本身。
• 绕过检查仍然生效：ICMP 规则之前的 localnetwork/WAN-AC/LAN-AC/china_ip_route 等 RETURN 规则同样适用于 ICMP——被匹配的 ICMP 包会跳过标记规则。
• 路由器自身 ICMP：当 router_self_proxy=1 时，路由器发出的 ping 在 openclash_mangle_output 链中同样被标记。

2. TUN 模式（en_mode_tun=1）:

ICMP echo-request 在 openclash_mangle 链中被标记 fwmark，随后通过策略路由进入 TUN 虚拟网卡：

# 步骤1: 标记 ICMP
nft add rule inet fw4 openclash_mangle ip protocol icmp \
  icmp type echo-request mark set "$PROXY_FWMARK" counter accept

# 步骤2: 策略路由（系统层面）— 所有标记 0x162 的流量路由到 TUN
ip rule add fwmark 0x162 table 0x162
ip route add default dev utun table 0x162

• ICMP 被代理：TUN 模式下所有标记 fwmark 的流量（包括 ICMP）被策略路由导向 utun 虚拟网卡，由 Mihomo 内核的 TUN 协议栈处理。
• Mihomo 内核配置：TUN 模式下 Mihomo 支持两个 ICMP 相关选项：
  • icmp-timeout（默认自动）：ICMP 连接超时时间（秒）
  • disable-icmp-forwarding（默认 false）：设为 true 可禁用 TUN 的 ICMP 转发（ping 将不被代理）

3. Fake-IP 非 TUN 模式的 Ping 阻断:

仅在 Fake-IP 非 TUN 模式下（en_mode=fake-ip, en_mode_tun 为空），对 Fake-IP 地址段（默认 198.18.0.0/16）的 ping 会被防火墙显式 REJECT：

# INPUT 链 — 阻止路由器自身收到发往 Fake-IP 的 ping
nft insert rule inet fw4 input position 0 ip protocol icmp \
  icmp type echo-request ip daddr { 198.18.0.0/16 } counter reject

# FORWARD 链 — 阻止局域网设备间转发 Fake-IP 的 ping
nft insert rule inet fw4 forward position 0 ip protocol icmp \
  icmp type echo-request ip daddr { 198.18.0.0/16 } counter reject

# OUTPUT 链 — 阻止路由器发出对 Fake-IP 的 ping（排除 OpenClash 自身进程 skgid=65534）
nft insert rule inet fw4 output position 0 ip protocol icmp \
  icmp type echo-request ip daddr { 198.18.0.0/16 } \
  skgid != 65534 counter reject

这是因为在非 TUN 模式下，Fake-IP 地址没有对应的 TCP/UDP 重定向路径（TCP 走 REDIRECT、UDP 走 TPROXY，但 ICMP 都不到达内核），发往这些地址的 ping 无意义且会干扰网络诊断。OUTPUT 链排除 skgid=65534 是为了避免影响 OpenClash 自身进程的内部通信。

TUN 模式下的区别：Fake-IP TUN 模式不添加这些 REJECT 规则。因为 ICMP 经策略路由进入 TUN 虚拟网卡后，由内核的 skipPingForwardingByAddr() 判断——若目标是 Fake-IP，内核返回伪造 echo-reply（~0ms 虚假延迟），不产生实际网络流量。

4. IPv6 ICMP（ICMPv6）:

仅在 IPv6 TUN/混合模式（ipv6_mode=2 或 3）下标记：

nft add rule inet fw4 openclash_mangle_v6 ip6 nexthdr icmpv6 \
  icmpv6 type echo-request mark set "$PROXY_FWMARK" counter accept

IPv6 非 TUN 模式下 ICMPv6 不被标记也不被代理。IPv6 Fake-IP 地址范围的 ping 在非 TUN 的 IPv6 模式下被 REJECT（返回 icmpv6 admin-prohibited），条件为 $ipv6_mode -ne 2 -a $ipv6_mode -ne 3。TUN/Mix 模式下的 IPv6 Fake-IP ping 同样由内核的 skipPingForwardingByAddr() 处理（伪造回复）。

总结:

运行模式	ICMP 进入 TUN	ICMP fwmark	实际处理
Redir-Host (非TUN)	❌	✅ 标记 0x162	仅标记后放行，不经内核处理
Fake-IP (非TUN)	❌	✅ 标记 0x162	防火墙 REJECT Fake-IP 范围的 ping
Redir-Host TUN	✅	✅ 标记 0x162	真实 IP → DIRECT 直连延迟
Fake-IP TUN	✅	✅ 标记 0x162	真实 IP → DIRECT 直连；Fake-IP → 伪造回复（~0ms 虚假延迟）
Redir-Host Mix	✅	✅ 标记 0x162	同 Redir-Host TUN：ICMP 标记后经策略路由进入 TUN，DIRECT 直连
Fake-IP Mix	✅	✅ 标记 0x162	同 Fake-IP TUN：真实 IP → DIRECT 直连；Fake-IP → 内核伪造回复

实用提示：如果用户发现 ping 不通但网页正常，首先确认不是 Fake-IP 非 TUN 模式下在 ping 被代理的域名（Fake-IP 返回 198.18.x.x，防火墙直接 REJECT）。Fake-IP TUN/Mix 模式下 ping Fake-IP 地址会返回虚假 ~0ms 延迟。非 Fake-IP 的真实 IP ping 在 TUN/Mix 模式下走 DIRECT 直连，延迟反映的是本地网络质量。

内核侧 ICMP 处理机制（listener/sing_tun/prepare.go — Mihomo TUN 监听器）:

当 ICMP echo-request 经策略路由进入 TUN 虚拟网卡后，Mihomo 内核按以下优先级处理：

1. 目标是 Fake-IP 地址（resolver.IsFakeIP(addr)） → 返回 nil, nil，内核用伪造的 echo-reply 回复。上层看到 "ping 成功" 但实际未经过网络，延迟显示为虚假的 ~0ms
2. 目标是 TUN 接口自身 IP（inet4_address / inet6_address 范围内） → 同上，伪造回复
3. disable-icmp-forwarding: true → 所有 ICMP 均伪造回复
4. 以上均不满足（真实 IP 且未禁用转发） → 通过 ping.ConnectDestination() 以 DIRECT 模式发出真实 ICMP 包，等待真实 reply。延迟为本地网络到目标的实际 RTT
5. ICMP 超时: 默认 10 秒（sing.go 常量），可通过 icmp-timeout 自定义

关键结论: TUN 模式下 ping 的处理分两种情况——目标是 Fake-IP → 虚假 0ms 延迟；目标是真实 IP → DIRECT 直连延迟。ping 始终不经过代理节点，这与 TCP/UDP 流量（经代理转发）的行为不同。

---

二、fw3 (iptables/ipset) 等效链

iptables 链	表	等效 nftables 链
openclash	nat	inet fw4 openclash (TCP)
openclash	mangle	inet fw4 openclash_mangle (UDP)
openclash_output	nat	inet fw4 openclash_output (TCP)
openclash_output	mangle	inet fw4 openclash_mangle_output (UDP)
openclash_post	nat	inet fw4 openclash_post
openclash_wan_input	filter	inet fw4 openclash_wan_input
openclash_dns_redirect	nat	inet fw4 openclash_dns_redirect
openclash_upnp	mangle	inet fw4 openclash_upnp

fw3 兼容性层 — 自动检测 iptables 是否支持 owner/gid 模块:

if iptables 不支持 owner 模块; then
    owner="-m mark --mark 0x1a0a"     # 回退: 按 fwmark 匹配
    noowner="-m mark ! --mark 0x1a0a"
else
    owner="-m owner --gid-owner 65534" # 标准: owner 模块
    noowner="-m owner ! --gid-owner 65534"
fi

示例 fw3 REDIRECT (TCP):

iptables -t nat -N openclash
iptables -t nat -A openclash -m set --match-set localnetwork dst -j RETURN
iptables -t nat -A openclash -p tcp -d 198.18.0.0/16 -j REDIRECT --to-ports 7892
iptables -t nat -A openclash -p tcp -m set ! --match-set common_ports dst -j RETURN
iptables -t nat -A openclash -p tcp -j REDIRECT --to-ports 7892
iptables -t nat -A PREROUTING -p tcp -j openclash

示例 fw3 TPROXY (UDP):

iptables -t mangle -N openclash
iptables -t mangle -A openclash -p udp -m set --match-set localnetwork dst -j RETURN
iptables -t mangle -A openclash -p udp -j TPROXY --on-port 7895 --tproxy-mark 0x162
iptables -t mangle -A PREROUTING -p udp -j openclash

---

三、各选项对防火墙规则的具体影响

选项	值	防火墙规则变化
china_ip_route (实验性：绕过指定区域 IP / China IP Route)	1 (绕过大陆)	在代理规则前插入 ip daddr @china_ip_route counter return — 目标为国内 IP 的流量跳过代理
	2 (绕过海外)	插入 ip daddr != @china_ip_route counter return — 目标非国内 IP 的流量跳过代理
china_ip6_route (实验性：绕过指定区域 IPv6 / China IPv6 Route)	1 (绕过大陆)	IPv6 等效规则：ip6 daddr @china_ip6_route counter return — 目标为国内 IPv6 的流量跳过代理
	2 (绕过海外)	IPv6 等效规则：ip6 daddr != @china_ip6_route counter return
disable_udp_quic (禁用 QUIC / Disable QUIC)	1	非 TUN: nft insert rule inet fw4 input position 0 udp dport 443 ip daddr != @china_ip_route counter reject — 阻断入站 QUIC；TUN: nft insert rule inet fw4 forward position 0 oifname utun udp dport 443 ... counter reject — 阻断 TUN 出方向 QUIC
lan_ac_mode (局域网访问控制模式 / LAN Access Control Mode)	0 (黑名单)	创建 lan_ac_black_ips/lan_ac_black_macs set，匹配到的 RETURN 跳过代理
	1 (白名单)	创建 lan_ac_white_ips/lan_ac_white_macs set，不匹配的 RETURN 跳过代理（反逻辑）
common_ports (仅允许常用端口流量 / Common Ports Proxy Mode)	非0	插入 th dport != @common_ports counter return — 仅代理指定端口，P2P/BT 端口被绕过。仅 redir-host 模式生效
router_self_proxy (路由本机代理 / Router-Self Proxy)	1	创建 OUTPUT 链 (openclash_output + openclash_mangle_output)，路由器自身流量被重定向/标记
	0	删除 OUTPUT 链，路由器自身流量走原始路由
intranet_allowed (仅允许内网 / Only Intranet Allowed)	1	创建 openclash_wan_input 链，DROP 来自 WAN 口对 $cn_port(9090) 及代理端口的访问
bypass_gateway_compatible (旁路网关（旁路由）兼容 / Bypass Gateway Compatible)	1	创建 openclash_post 链，对已标记流量执行 MASQUERADE SNAT，解决旁路由回流问题
skip_proxy_address (绕过服务器地址 / Skip Proxy Address)	1	创建 openclash_proxy_server_ip nft set，在代理规则前插入 ip daddr @openclash_proxy_server_ip counter return，防止代理嵌套
enable_redirect_dns (本地 DNS 劫持 / Redirect Local DNS Setting)	1	在 dstnat 插入 DNS 53 端口 REDIRECT 规则到 dnsmasq 端口
	2	创建 openclash_dns_redirect 链，DNS 流量直接 DNAT 到 dns_port(7874)
local_network_pass (本地 IPv4 绕过地址 / Local IPv4 Network Bypassed List)	已配置	创建 localnetwork nft set，在 openclash 链规则 #1 中匹配本地 IP 段 RETURN 跳过代理
chnroute_pass (绕过指定区域 IPv4 黑名单 / Chnroute Bypassed List)	已配置	创建 china_ip_route_pass nft set，配合 dnsmasq 将指定域名解析的 IP 加入 set，防火墙规则中优先于 china_ip_route 匹配（确保这些 IP 不被绕行规则跳过）
ipv6_enable (IPv6 流量代理 / Proxy IPv6 Traffic)	1	创建完整的 IPv6 防火墙链：openclash_v6(TCP REDIRECT)、openclash_mangle_v6(UDP TPROXY)、openclash_output_v6(路由自身)、openclash_post_v6(旁路由 SNAT)
local_network6_pass (本地 IPv6 绕过地址 / Local IPv6 Network Bypassed List)	已配置	创建 IPv6 localnetwork nft set，IPv6 链中匹配本地 IPv6 段 RETURN
ICMP/Ping 处理（无 UCI 选项，由运行模式决定）	Redir-Host / Fake-IP（非 TUN）	ICMP echo-request 仅标记 fwmark 0x162 后 accept，不被代理（只有 TCP/UDP 被重定向到内核）；Fake-IP 非 TUN 模式下对 198.18.0.0/16 的 ping 被防火墙 REJECT（INPUT/FORWARD/OUTPUT 三链阻断）
	TUN 模式 / Mix 模式	ICMP 标记 fwmark 后经策略路由进入 TUN 虚拟网卡，由 TUN 内核处理（真实 IP → DIRECT 直连延迟，Fake-IP → 伪造回复 ~0ms）；可通过 Mihomo 的 disable-icmp-forwarding 禁用

---

四、Dnsmasq 修改详解 (change_dnsmasq / revert_dnsmasq)

修改流程 (change_dnsmasq(), 仅在 enable_redirect_dns=1 时执行):

# 1. 备份原始配置到 openclash.config.*
save_dnsmasq_server() → uci add_list openclash.config.dnsmasq_server="<原始server>"
uci set openclash.config.dnsmasq_noresolv="$(uci get dhcp.@dnsmasq[0].noresolv)"
uci set openclash.config.dnsmasq_resolvfile="$(uci get dhcp.@dnsmasq[0].resolvfile)"
uci set openclash.config.dnsmasq_cachesize="$(uci get dhcp.@dnsmasq[0].cachesize)"

# 2. 重定向 DNS
uci del dhcp.@dnsmasq[-1].server
uci add_list dhcp.@dnsmasq[0].server="127.0.0.1#$dns_port"
uci delete dhcp.@dnsmasq[0].resolvfile
uci set dhcp.@dnsmasq[0].noresolv=1
uci set dhcp.@dnsmasq[0].localuse=1
uci set dhcp.@dnsmasq[0].cachesize=0

# 3. IPv6 DNS (ipv6_dns=1 时)
uci set dhcp.@dnsmasq[0].filter_aaaa=0  # 允许 AAAA 记录

# 4. chnroute_pass 处理 — 加载 ipset/nftset
load_ip_route_pass()
# 创建 china_ip_route_pass ipset/nftset
# 将 openclash_custom_chnroute_pass.list 中的域名加入 set
# 对 china_ip_route_pass UCI 列表中的域名加入 set

# 5. 自定义域名 DNS
/usr/share/openclash/openclash_custom_domain_dns.sh

# 6. 重启 dnsmasq
/etc/init.d/dnsmasq restart

恢复流程 (revert_dnsmasq()):

# 1. 删除 OpenClash 注入的 server
uci del dhcp.@dnsmasq[-1].server

# 2. 恢复原始 server 列表
for server in $(uci get openclash.config.dnsmasq_server); do
    uci add_list dhcp.@dnsmasq[0].server="$server"
done

# 3. 恢复 resolvfile / noresolv / cachesize / filter_aaaa
uci set dhcp.@dnsmasq[0].noresolv="$saved_noresolv"
uci set dhcp.@dnsmasq[0].resolvfile="$saved_resolvfile"
uci set dhcp.@dnsmasq[0].cachesize="$saved_cachesize"

# 4. DNS 验证 — 测试修改后的 DNS 是否可用
if nslookup www.apple.com 127.0.0.1:<dnsmasq_port> 失败; then
    # 创建 fallback resolv.conf (114.114.114.114, 8.8.8.8)
fi

chnroute_pass 的 dnsmasq 集成:

• 创建 china_ip_route_pass ipset/nftset
• 将 chnroute_pass 域名加入 set: ipset=/domain.com/china_ip_route_pass 或 nftset=/domain.com/4#inet#fw4#china_ip_route_pass
• 效果: DNS 解析这些域名时加入 set 便于在匹配时绕过（而非被 chnroute 影响）

---

日志与错误信息速查

AI 行为指引: 当用户提供日志报错信息时，AI 应首先在以下表格中查找匹配的错误关键字， 根据「原因」列判断问题根源，然后按「排查方法」列指导用户在 LuCI 中操作。 若表中未覆盖该错误，应主动搜索 OpenClash GitHub Issues 查找是否存在相同或相似的问题， 优先参考高赞反应的社区回复和作者（vernesong）给出的解决方案。搜索时可使用错误关键字作为搜索词。

两类日志说明:

• 插件日志（前九类）：由 OpenClash 的 Shell/Ruby/Lua 脚本产生，含 [Info]/[Tip]/[Warning]/[Error] 前缀，写入 /tmp/openclash.log。可在 LuCI「运行日志」页面查看。
• 内核日志（第十、十一类）：由 Mihomo 核心（Go 程序）产生，含 level=debug/info/warning/error/fatal 标记，同样写入 /tmp/openclash.log。level=fatal 会导致核心进程退出。可在 LuCI「运行日志」页面查看，或在「运行状态」页面看到 OpenClash Start Failed 提示。

一、内核启动与运行错误

错误关键字	问题位置	原因	排查方法
Ruby Works Abnormally, Please Check The Ruby Library Depends! (Ruby 依赖异常)	「运行状态」启动流程	ruby 或 ruby-yaml 包未安装/损坏	「系统→软件包」安装 ruby、ruby-yaml、ruby-psych
Unable To Parse Config File (配置文件校验失败)	「运行状态」启动流程	YAML 配置文件语法错误或 age 解密失败	「配置管理」页面点击 Edit 检查 YAML 语法
Core Start Failed, Please Check The Log Infos! (内核启动失败)	「运行状态」启动流程	核心进程未能启动	「运行状态」查看核心版本是否正确；「插件设置 → 调试日志」生成调试日志
Core Initial Configuration Timeout (内核初始化超时)	「运行状态」启动流程	核心 API 在 300 秒内未就绪	检查 /tmp/openclash.log 中核心日志；确认「覆写设置→常规」的 cn_port 未被占用
TUN Interface Start Failed (TUN 接口启动失败)	「运行状态」启动流程	TUN 虚拟网卡创建失败	「系统→软件包」确认 kmod-tun 已安装
【{module}】module not found (内核模块未找到)	「运行状态」启动流程	内核模块未安装/未加载（tun/tproxy 等）	「系统→软件包」安装对应的 kmod 包
LAN IP Address Get Error (LAN IP 获取失败)	「运行状态」启动流程	LAN 接口 IP 无效或 ip-full 包缺失（旧内核 4.4.x 常见 br-lan 网桥无 IP）	「插件设置→流量控制」选择正确的 LAN 接口名称（如 br-lan）；「系统→软件包」安装 ip-full；终端 ip address show br-lan 确认存在 IPv4 地址；尝试切换运行模式为混合模式
OpenClash Now Disabled, Need Start From Luci Page (插件未启用)	「运行状态」启动流程	插件被禁用（enable=0）	「运行状态」页面点击启动开关

二、订阅与配置更新错误

错误关键字	问题位置	原因	排查方法
Config File Subscribed Failed (订阅配置下载失败)	「配置订阅」更新流程	订阅 URL 下载失败（curl 错误）	「配置订阅」检查订阅 URL 是否正确；确认网络连通性
Config File Tested Faild (配置文件测试失败)	「配置订阅」更新流程	下载的 YAML 未通过 clash -t 验证	「配置管理」页面 Edit 检查 YAML 语法；查看 /tmp/openclash.log
Updated Config Has No Proxy Field (配置无节点字段)	「配置订阅」更新流程	订阅配置中无 proxies 和 proxy-providers 字段	检查订阅源是否有效；可能订阅已过期
Filter Proxies Failed (节点筛选失败)	「配置订阅」更新流程	节点关键字过滤正则异常	「配置订阅」检查 keyword/ex_keyword 格式
Ruby Works Abnormally (Ruby 异常)	「配置订阅」更新流程	Ruby 环境异常导致订阅处理失败	「系统→软件包」重装 ruby、ruby-yaml
Config File Format Validation Failed (配置文件格式校验失败)	「运行状态」启动流程	YAML 解析后文件为空/丢失	「配置管理」检查配置目录权限和磁盘空间

三、GEO 与规则更新错误

错误关键字	问题位置	原因	排查方法
Download Failed: HTML Response Detected (下载失败：检测到 HTML 响应)	「插件设置→GEO 数据库订阅」	CDN 返回的是 HTML 错误页而非 GEO 文件	「覆写设置→常规」检查 Github 地址修改 CDN 选项
Download Failed: File Size Too Small (下载失败：文件过小)	「插件设置→GEO 数据库订阅」	下载文件 <1KB，内容不完整	「插件设置→GEO 数据库订阅」检查 GEO 自定义 URL 是否正确
Update Error, Please Try Again Later (更新失败，请稍后再试)	「插件设置→GEO 数据库订阅」	网络下载失败	「运行状态」检查网络连通性；若使用代理下载，添加直连规则
Control Panel Unzip Error! (控制面板解压失败)	「运行状态」仪表盘切换	Dashboard 压缩包解压失败	「系统→软件包」确认 unzip 已安装
LightGBM Model Update Error (LGBM 模型更新失败)	「覆写设置→智能设置」	LGBM 模型下载失败	「覆写设置→智能设置」检查模型 URL

四、内核与插件版本更新错误

错误关键字	问题位置	原因	排查方法
Core Version Check Error (内核版本检测失败)	「版本更新」	GitHub 不可达，无法获取最新版本信息	「运行状态」检查网络连通性；如在大陆，设置 CDN
Core Update Failed (内核更新失败，重试 3 次后)	「版本更新」	核心下载/解压/替换失败	「版本更新」确认闪存空间和 CPU 架构选择；「系统 → 软件包」检查磁盘空间
No Compiled Version Selected (未选择编译版本)	「版本更新」	CPU 架构未选择（core_version=0）	「版本更新」标签页选择对应的 CPU 架构
Pre update test failed (更新前测试失败，3 次后)	「版本更新」	插件 IPK/APK 安装测试失败	手动在「系统→软件包」中更新或重装 luci-app-openclash
OpenClash update failed (OpenClash 更新失败)	「版本更新」	插件安装彻底失败	包已保存在 /tmp/，手动使用 opkg install 或 apk add 安装
Failed to get version information (获取版本信息失败)	「版本更新」	GitHub 版本检查失败	检查网络；「覆写设置→常规」设置 CDN

五、防火墙与 DNS 错误

错误关键字	问题位置	原因	排查方法
Dnsmasq not Support nftset, Use ipset (Dnsmasq 不支持 nftset)	「运行状态」启动流程	dnsmasq-full 未编译 nftset 支持	警告，非致命；如 chnroute 旁路异常则重装 dnsmasq-full
iptables DSCP module not available (iptables DSCP 模块不可用)	「运行状态」启动流程	iptables 缺少 DSCP 模块	警告，DSCP 规则被跳过；或改用核心侧 DSCP
Can't Setting Only Intranet Allowed Function (无法设置仅允许内网)	「运行状态」启动流程	无法识别 WAN 接口	「插件设置→流量控制」检查 WAN 接口名称设置
Nameserver Option Must Be Setted, Stop Customing DNS Servers (Nameserver 未设置)	「覆写设置→DNS」	自定义 DNS 启用但未配置任何 nameserver	「覆写设置→DNS」添加至少一个 DNS 服务器
Fallback-Filter Need fallback of DNS Been Setted (Fallback-Filter 需要 Fallback DNS)	「覆写设置→DNS」	fallback-filter 需要先配置 fallback DNS	「覆写设置→DNS」先添加 fallback 分组的 DNS 服务器
DNS Loop Check (DNS 回环检查)	「覆写设置→DNS」	DNS 配置存在回环风险	「覆写设置→DNS」检查服务器列表，避免将 Clash DNS 端口设为其上游

六、覆写模块错误

错误关键字	问题位置	原因	排查方法
skip General key not allowed (覆写 key 不允许)	「覆写设置」覆写模块	覆写 [General] 中的 key 不在允许列表中	检查 key 拼写；参考覆写模块 10.2.1 节的允许 key 列表
skip invalid Overwrite command (无效覆写命令)	「覆写设置」覆写模块	[Overwrite] 段命令不以 ruby_ 开头	修正命令语法，使用 ruby_method_name 格式
Invalid YAML Override format (无效 YAML 覆写格式)	「覆写设置」覆写模块	[YAML] 段不是有效的 Hash 结构	检查 YAML 缩进和格式
Parse YAML Override failed (YAML 覆写解析失败)	「覆写设置」覆写模块	[YAML] 段 Ruby 解析异常	逐行检查 YAML 语法
Config File Overwrite Failed (配置文件覆写失败)	「覆写设置」覆写模块	覆写应用整体失败	检查所有覆写设置的语法
DOWNLOAD FILE failed (文件下载失败)	「覆写设置」覆写模块	覆写模块 DOWNLOAD_FILE 下载失败	检查下载 URL 和网络连通性

七、流媒体解锁错误

错误关键字	问题位置	原因	排查方法
Streaming Unlock Could not Work Because of Router-Self Proxy Disabled (流媒体解锁失效：本机代理关闭)	「运行状态」看门狗	路由器自代理关闭导致流媒体解锁无法工作	「插件设置→流量控制」开启本机代理
Something Wrong While Testing (流媒体测试失败)	「插件设置→流媒体增强」	流媒体测试脚本执行失败	「运行状态」确认核心运行中；「插件设置→流媒体增强」检查策略组配置

八、LuCI Web 界面错误

错误提示	问题位置	原因	排查方法
Switch Faild (切换失败)	「运行状态」快捷设置	API 不可达或核心未运行	「运行状态」确认核心状态；刷新页面后重试
Config file does not exist (配置文件不存在)	「配置管理」	配置文件路径无效	「配置管理」检查文件名；确认文件存在于配置列表中
File size exceeds 10MB limit (文件超过 10MB 限制)	「配置管理」上传	上传文件超过 10MB	减小文件或拆分上传
Cannot delete the last remaining dashboard (无法删除最后一个仪表盘)	「运行状态」仪表盘切换	只剩一个仪表盘时不允许删除	「运行状态」先下载新的仪表盘再删除旧的
Failed to generate age key (生成 Age 密钥失败)	「配置订阅」Age 密钥	核心不支持 age keygen	「版本更新」检查核心版本；手动生成 age 密钥
Failed to calculate public key (计算公钥失败)	「配置订阅」Age 密钥	密钥格式无效	验证 age 密钥格式（应以 AGE-SECRET-KEY- 开头）
Bad address specified! (地址无效)	「运行状态」连接诊断	输入地址为空或无效	输入有效的主机名或 IP 地址
OpenClash Start Failed: {msg} (OpenClash 启动失败)	「运行状态」	核心日志中出现 fatal/error 级别日志	查看完整错误消息；「插件设置 → 调试日志」生成调试日志
Access Denied (无法访问) / Access Timed Out (连接超时)	「运行状态」IP 检测	网络连接问题	检查路由器网络连接

九、YAML 配置处理错误

错误关键字	问题位置	原因	排查方法
Load File Failed (加载文件失败)	「配置管理」配置加载	Ruby 无法加载配置文件	确认配置文件存在且权限正确
Set Custom DNS Failed (自定义 DNS 设置失败)	「覆写设置→DNS」	DNS 覆写处理失败	检查「覆写设置→DNS」中的 DNS 服务器配置
Set Fake-IP-Filter Failed (Fake-IP-Filter 设置失败)	「覆写设置→DNS」	Fake-IP 过滤器配置异常	「覆写设置→DNS」检查 Fake-IP-Filter 文件和模式
Set Hosts Rules Failed (Hosts 规则设置失败)	「覆写设置→DNS」	自定义 Hosts 格式错误	「覆写设置→DNS」检查 hosts 文件每行格式
Set Custom Rules Failed (自定义规则设置失败)	「覆写设置→规则」	自定义规则注入异常	「覆写设置→规则」检查规则文件语法
Skiped The Custom Rule Because Group & Proxy Not Found (规则跳过：策略组/代理不存在)	「覆写设置→规则」	规则引用了不存在的策略组/代理	「覆写设置→规则」检查规则中 MATCH/Proxy/策略组名称是否存在
Set BT/P2P DIRECT Rules Failed (BT/P2P 直连规则设置失败)	「覆写设置→规则」	BT 直连规则注入失败	「覆写设置→规则」关闭再重新开启「仅代理命中规则流量 (Rule Match Proxy Mode)」选项
proxy-groups Get Failed (策略组获取失败)	「配置管理」策略组	配置中策略组解析异常	「配置管理」页面 Edit 检查 proxy-groups 段

十、Ruby YAML 模块错误

错误关键字	问题位置	原因	排查方法
Fix short-id values type failed (short-id 类型修复失败)	「配置管理」YAML 处理	YAML 中 short-id 字段值类型修复时 Psych 解析异常	「配置管理」Edit 检查配置中 short-id 字段的值格式
YAML overwrite failed:【key: ...】 (YAML 覆写失败)	「覆写设置」覆写模块	覆写模块 YAML 合并时发生异常	「覆写设置」检查 [YAML] 段的语法和操作符使用
YAML overwrite failed:【(match value) => ...】 (YAML 条件覆写匹配失败)	「覆写设置」覆写模块	批量条件更新的 where 匹配逻辑异常	「覆写设置」检查 key* 操作符的 where 条件格式和正则
YAML overwrite failed:【(batch update) => ...】 (YAML 批量更新失败)	「覆写设置」覆写模块	批量条件更新执行时异常	「覆写设置」检查 key* 操作符的 set 子句语法
Write file failed (写文件失败)	「配置管理」YAML 写入	YAML 写入文件时 I/O 异常	检查磁盘空间和文件权限
Decrypt attempt failed (解密尝试失败)	「配置订阅」Age 解密	Age 加密文件解密失败	「配置订阅」检查 age 密钥是否正确；验证加密文件完整性
Decrypted content empty or still encrypted (解密后为空或仍加密)	「配置订阅」Age 解密	Age 解密后内容为空或仍为加密格式	「配置订阅」确认 age 密钥与加密时使用的密钥匹配
Encrypt attempt failed (加密尝试失败)	「配置订阅」Age 加密	Age 加密写入时失败	「配置订阅」检查 age 公钥格式；验证核心年龄功能
Encrypted file: decryption failed (加密文件解密失败)	「配置订阅」Age 解密	所有 age 密钥尝试均解密失败	「配置订阅」检查所有订阅的 age 密钥；可能密钥不匹配

十一、Mihomo 内核配置解析错误（level=fatal / level=error）

以下为 Mihomo 内核在加载/解析 YAML 配置文件时产生的错误。level=fatal 会导致核心进程退出。 日志查看：LuCI「运行日志」页面或「运行状态」页面（若启动失败会显示 OpenClash Start Failed）。

Parse config error 的具体子类型及修复方法：

错误详情	配置段	修复方法
proxy <N>: missing type	proxies	在「配置管理」Edit 中给第 N 个代理节点添加 type: 字段（如 ss, vmess, trojan 等）
proxy <N>: unsupport proxy type: <type>	proxies	代理类型名称拼写错误或不支持，检查 type: 值是否在 Mihomo 支持列表中
proxy <name> is the duplicate name	proxies	两个代理节点同名，在「配置管理」Edit 中修改其中一个的名称
proxy group <N>: missing name	proxy-groups	第 N 个策略组缺少 name: 字段，Edit 中补充
<groupName>: unsupported type	proxy-groups	策略组 type: 值无效，改为 select, url-test, fallback, load-balance 或 smart
loop is detected in ProxyGroup	proxy-groups	策略组之间存在循环引用（A 引用 B，B 又引用 A），打破循环链
<groupName>: use or proxies missing	proxy-groups	策略组没有配置 proxies: 或 use:，至少添加一个
'<name>' not found	proxy-groups	策略组引用了不存在的代理节点或 provider 名称，检查拼写
can not defined a provider called 'default'	proxy-providers	provider 使用了保留名 default，改用其他名称
unsupport vehicle type: <type>	proxy-providers / rule-providers	provider 的 type: 值无效，应为 file, http 或 inline
file must have a payload field	rule-providers	规则集文件缺少 payload: 字段，检查文件内容格式
rules[<N>] [<line>] error: format invalid	rules	第 N 条规则格式错误，检查规则语法：TYPE,payload,target,no-resolve
rules[<N>] [<line>] error: proxy [<name>] not found	rules	规则目标引用了不存在的策略组/代理名称
rules[<N>] [<line>] error: rule set [<name>] not found	rules	规则使用了 RULE-SET,<name> 但未在 rule-providers 中定义该名称
sub-rule error: circular references	sub-rules	子规则之间形成循环引用链，打破循环
decrypt config error	全局	Age 加密的配置文件解密失败，在「配置订阅」中检查 age 密钥
configuration file ... is empty	全局	配置文件为空，在「配置管理」中检查配置是否正常下载
[Smart] Invalid policy-priority rule: must be in 'pattern:factor' format	smart 策略组	「覆写设置→智能设置」中 smart_policy_priority 格式错误，改为 名称:系数
DNS [addr] config with invalid ecs	dns	DNS 服务器的 ECS 配置格式无效，「覆写设置→DNS」检查 DNS 服务器设置
[Smart] Model.bin invalid, remove and download	Smart 模型	「覆写设置→智能设置」点击手动更新模型按钮重新下载
[CacheFile] remove invalid cache file error	运行缓存	「运行状态」停止 OpenClash，手动删除 /etc/openclash/cache.db 后重启

通用排查: 在「配置管理」页面点击 Download Run 下载经脚本处理后的运行时配置，对比原始订阅检查 yml_change.sh 和覆写模块生成的 YAML 是否正确。

十二、DNS 泄露排查

核心验证方法：在客户端执行 nslookup www.google.com，应返回：① DNS 服务器为 OpenWrt 路由器 IP；② 解析结果为 Fake-IP 范围地址（198.18.x.x）。若返回真实 IP 或上游 DNS 非路由器，说明 DNS 解析链路异常。正确链路应为：设备 → Dnsmasq(53端口) → OpenClash(7874端口)。

错误关键字	问题位置	原因	排查方法	来源
DNS 泄露（ipleak / ipleak.net 检测到国内 DNS）	「覆写设置→DNS」	Redir-Host/Fake-IP 下 nameserver 和 fallback 并发请求，国内 DNS 结果可能被优先采纳	① Meta 内核建议放弃 fallback，仅用 nameserver-policy 做 DNS 分流（国内域名→国内 DNS，国外域名→国外 DNS）；② 境外 DNS 地址后加 #PROXY 强制走代理（如 https://1.1.1.1/dns-query#PROXY）；③ 删除原配置 YAML 的 dns: 段，仅通过「覆写设置→DNS」管理 DNS 配置避免冲突；④ 将 proxy-server-nameserver 设为国内 DNS 避免代理节点域名解析走境外	#3843
nameserver-policy 未生效，DNS 仍走 nameserver	「覆写设置→DNS」	OpenClash 的「覆写设置→DNS」选项会与订阅配置的 dns: 段合并，可能导致预期外的 DNS 行为	① 在「覆写设置→DNS」启用「自定义 DNS 设置 (Custom DNS Setting)」后重新配置所有 DNS 规则；② 在「运行日志」中开启 Debug 等级观察实际 DNS 查询路径；③ 确认 default-nameserver 组的 DNS 服务器开启了「节点域名解析」选项	同上
DNS 泄露（开启 IPv6 后出现）	「覆写设置→DNS」+「IPv6 设置」	运营商下发的 IPv6 DNS 绕过了 OpenClash 的 DNS 劫持，直接响应客户端请求（"抢答"）	① 在 LuCI 的「网络→DHCP/DNS→高级设置」中取消 过滤 IPv6 AAAA 记录；② 在 LAN 接口 DHCP 服务器 IPv6 设置中取消「本地 IPv6 DNS 服务器」，强制设备使用路由器 IPv4 地址进行 DNS 解析；③ DHCPv6 服务设为已禁用，RA 设为服务器模式。原理：DNS 请求走 IPv4 通道，流量走 IPv6 通道——IPv4 DNS 同样可以查询 AAAA 记录返回 IPv6 地址	—
旁路由环境下 DNS 泄露	「运行状态」	旁路由设备未正确指定上游 DNS 为 OpenWrt IP（尤其是 IPv6 DNS 留空）	① 旁路由设备必须手动指定 IPv4 DNS 为 OpenWrt 路由器 IP；② IPv6 DNS 必须留空；③ 若使用 DHCP 分配，确保 DHCP 服务器不下发 IPv6 DNS 地址	—

十三、版本更新与下载失败

错误关键字	问题位置	原因	排查方法	来源
/tmp/openclash_last_version 下载失败	「运行日志」/ 启动流程	① curl SSL 证书验证失败（BADCERT_CN_MISMATCH / self signed certificate）；② GitHub Raw 域名被 DNS 污染或不可达；③ curl 超时（Operation timed out）；④ 缺少 libmbedtls 库	①「覆写设置→常规」设置 Github 地址修改 (github_address_mod) 为 CDN（推荐 https://fastly.jsdelivr.net/ 或 https://testingcf.jsdelivr.net/）；②「系统→软件包」确认 ca-bundle 已安装；③ Fake-IP 模式在「覆写设置→DNS」的 fake-ip-filter 中排除 raw.githubusercontent.com；④ 修改 /usr/share/openclash/openclash_core.sh 中 curl 的超时参数 -m 60 改为 -m 300；⑤ 终端执行 opkg install libmbedtls 修复 curl 库依赖	#2791
Update Core (更新内核) 点击后重启失败	「运行状态」页面	v0.47.052 重启流程中 stop→start 间隔不足，旧核心进程未完全退出即启动新核心，触发「内核启动失败」	① 更新到 v0.47.054+（已在 Developer 分支修复）；② 临时解决：编辑 /etc/init.d/openclash，在 restart 函数的 stop 和 start 之间加 sleep 5；③ 如更新后仍失败，检查内存是否不足（小型设备建议增加 swap）	#4969
升级后依赖检查异常，无法启动	「运行日志」启动流程	更新后 check_mod() 或依赖检测逻辑误报	①「插件设置→调试日志」生成调试日志检查依赖段；②「系统→软件包」确认 kmod-nft-tproxy/kmod-ipt-tproxy 已安装；③ 切换 Dev 分支获取最新修复；④ 重装 luci-app-openclash	#4807
v0.47.052/055 无法开机自启	「运行状态」启动流程	启动时序竞争条件，procd respawn 在某些固件上触发过快	① 更新到最新 Dev 版本；②「插件设置→模式设置」设置 delay_start (启动延迟) 30-60 秒；③ 确保路由器有足够内存供启动时使用	#4973

十四、功能异常类

错误关键字	问题位置	原因	排查方法	来源
向日葵/AnyDesk 等远程软件无法连接	局域网客户端	远程软件域名/QUIC 流量被代理或阻断	①「覆写设置→规则」添加直连规则：DOMAIN-SUFFIX,oray.com,DIRECT、DOMAIN-SUFFIX,sunlogin.net,DIRECT 等；② 确认 sniffer skip-domain 已包含 oray.com 和 sunlogin.net（默认已含）；③ 尝试关闭「插件设置→流量控制」的 disable_udp_quic (禁用 QUIC)	#3229
小米摄像机/智能家居外网无法访问	局域网 IoT 设备	IoT 设备流量被代理导致 NAT 穿透失败	①「插件设置→黑白名单」添加摄像机 IP 到「不走代理的局域网设备 IP (LAN Bypassed Host List)」列表；② 确认 sniffer skip-domain 包含 Mijia Cloud（默认已含）；③「覆写设置→规则」添加 IoT 域名直连规则：DOMAIN-SUFFIX,xiaomi.com,DIRECT	#2431
绕过中国大陆IP (China IP Route) 功能突然失效	升级后 / 「运行状态」	版本升级后 china_ip_route 的 nftables/ipset 重建失败或 chnroute 列表未更新	①「插件设置→大陆白名单订阅」手动更新一次大陆 IP 列表；②「运行状态」页面 Area Bypass 先切到关闭再切回「绕过中国大陆 (Bypass Mainland China)」重新触发；③ 终端执行 `nft list set inet fw4 china_ip_route	head` 检查 nft set 是否存在且非空
自定义防火墙规则（开发者选项）不生效	「插件设置→开发者设置」	编辑后未重启或脚本语法错误	① 修改 openclash_custom_firewall_rules.sh 后需重启 OpenClash（不是重载防火墙）；② 用 bash -n 检查脚本语法；③「插件设置→调试日志」生成调试日志检查是否成功执行（日志中含自定义脚本内容）	#4005
DDNS 服务（如 DDNS-GO）工作异常	路由器 DDNS 插件	DDNS 服务商 API 域名被错误分配 Fake-IP，导致 IP 检测失败	① 将 DDNS 服务商的 API 域名加入「覆写设置→DNS」的 Fake-IP-Filter 中（填入域名使其返回真实 IP）；② 常见需排除的域名如 ddns.oray.com、api.cloudflare.com 等，具体根据所用服务商填写	—
Cloudflare Tunnel (Cloudflared) 连接不稳定	路由器/内网设备	Cloudflared 默认使用 QUIC 连接，而海外 QUIC 流量默认被 OpenClash 阻断	① 规则中已指定 Cloudflare Tunnel 相关域名直连；② 在 Cloudflared 启动参数中显式指定 --protocol http2 强制使用 HTTP/2（Docker 版：command: [tunnel, --no-autoupdate, --protocol, http2, run, --token, ${CF_TOKEN}]）	—
BT/PT 下载流量进入内核	下载设备	下载设备流量未正确分流	① 若下载设备为独立设备（如 NAS），在「覆写设置→规则→自定义规则」中添加 SRC-IP-CIDR,192.168.1.x/32,DIRECT；② 若同时启用了 IPv6，还需添加 IPv6 后缀规则 SRC-IP-SUFFIX,::a1b2:c3d4,DIRECT（后缀由 EUI-64 生成，可在设备上查看）；③ 非独立设备可设置「非标端口」策略组直连来规避 80/443 以外的下载流量	—
直连网站/APP/小程序打不开	局域网客户端	小众域名未被 geosite:cn 收录，被误判为非直连走代理	① 临时方案：将「漏网之鱼」策略组设为直连；② 永久方案：在「覆写设置→规则→自定义规则」中为对应域名添加 DOMAIN-SUFFIX,xxx.com,DIRECT 规则；③ 观察 zashboard 中命中策略组确认分流是否正确	—
开启 IPv6 后某些直连访问卡顿	局域网客户端	IPv6 DNS 抢答或运营商 IPv6 DNS 不稳定导致解析异常	① 禁用「覆写设置→DNS」的「追加上游 DNS」，改为在 NameServer 中手动添加 DoH 服务器（如 AliDNS）；② 确保 LAN 口未下发 IPv6 DNS 地址	—
非直连站点打不开且内核日志无记录	「运行状态」	WAN 接口名称填写错误或 DNS 重定向未关闭	①「插件设置→流量控制」清空 WAN 接口名称；② 确认「网络→DHCP/DNS」中 DNS 重定向功能已关闭；③ 两者均正确时，检查 OpenWrt 中是否有其他劫持 53 端口或修改 Dnsmasq 的插件	—
Hysteria / Hysteria2 / TUIC 节点连接失败、断流、握手超时	内核日志 level=error	① Linux 内核 ≥6.6 的 quic-go GSO 兼容性问题（最常见）；② Hysteria 协议对 server/auth/tls/password 字段配置敏感	① 优先尝试：「插件设置→模式设置」开启**「禁用 quic-go GSO (Disable QUIC Go GSO)」**后重启 OpenClash；② 确认 YAML 中 type: hysteria 或 type: hysteria2 拼写正确、端口号正确；③ 检查节点的 auth/password 及 TLS 证书配置是否完整	—
开启「绕过中国大陆 IP」后 Google Play 商店无法下载/更新	客户端（Android 设备）	services.googleapis.cn 等 Google 域名被国内 DNS 解析到中国大陆 IP（220.181.x.x），被 china_ip_route 规则匹配后走直连；但 Google 中国服务器禁止境外 IP（代理节点）访问，导致死循环	从 DNS 和规则两方面同时入手： ① DNS 层面 — 在「覆写设置→DNS→自定义 DNS 设置」中配置 nameserver-policy 强制 Google 域名走境外 DNS 解析，写入 YAML 的 dns.nameserver-policy 段： yaml<br>dns:<br> nameserver-policy:<br> '+.services.googleapis.cn': 'https://dns.google/dns-query'<br> '+.googleapis.cn': 'https://dns.google/dns-query'<br> '+.xn--ngstr-lra8j.com': 'https://dns.google/dns-query'<br> 也可用 8.8.8.8 或 1.1.1.1 替代 https://dns.google/dns-query。效果：域名解析到 Google 境外 IP（如 142.250.x.x），而非国内 220.181.x.x。 ② 规则层面 — 在「覆写设置→规则→自定义规则」中添加，写入 YAML 的 rules 段： yaml<br>rules:<br> - DOMAIN-SUFFIX,services.googleapis.cn,Proxy<br> - DOMAIN-SUFFIX,googleapis.cn,Proxy<br> - DOMAIN-SUFFIX,xn--ngstr-lra8j.com,Proxy<br> 其中 Proxy 替换为你的代理策略组名。更彻底的方式：GEOSITE,google,Proxy 将全部 Google 流量走代理。 验证：终端执行 dig services.googleapis.cn @127.0.0.1 -p 7874 应返回境外 IP；在 zashboard 连接日志中确认域名命中代理规则。	#5074

十五、运行时状态异常

错误关键字	问题位置	原因	排查方法	来源
节点正常，突然无法访问外网	「运行状态」一切正常但客户端无网络	DNS 劫持失效（dnsmasq 被其他插件修改）、防火墙规则乱序、TUN 路由表丢失	①「运行状态」确认核心和 DNS 端口正常；② 在「运行日志」中检查最近的错误；③「运行状态」点击「Reload Firewall (重置防火墙)」重建规则；④ 检查是否同时运行其他代理/DNS 插件（如 AdGuard Home、PassWall、SSR-Plus 等），OpenClash 不能与这些插件共存	#3516
防火墙 DNS 劫持规则不停被还原	「运行日志」反复出现防火墙重载记录	看门狗检测到规则异常后自动重载，形成循环（v0.46.001-beta 已知问题）	① 更新到最新版本（已在后续版本修复）；② 临时关闭看门狗自动修复（编辑 openclash_watchdog.sh 注释掉防火墙重载部分）；③ 检查是否有其他程序在修改防火墙规则（如 Docker、UPnP 服务）	#3765

十六、旁路由 / 特定设备异常

错误关键字	问题位置	原因	排查方法	来源
旁路由 R2S 等 ARM 设备 iPhone 待机耗电严重	局域网	代理模式下 ARP 代理或 TUN 模式的 keepalive 导致 iPhone 频繁被唤醒	① 尝试切换为 Fake-IP 模式；② 关闭「仅允许内网 (Only Intranet Allowed)」以外的 WAN 口访问；③ 主路由 DHCP 下发的网关和 DNS 指向旁路由 IP	#2614
在 Fake-IP 模式下无法使用 UU 加速器等游戏加速软件	「运行状态」	游戏加速器需要真实 DNS 解析来优化连接，Fake-IP 返回虚拟 IP 导致失效	① 在「覆写设置→DNS」的 fake-ip-filter 中添加加速器相关域名（如 +.leigod.com、+.vivox.com）；② 将加速器所在设备的 IP 加入「不走代理的局域网设备 IP (LAN Bypassed Host List)」	#1751

---

第一部分：运行状态页面 (Overviews / client)

LuCI 路径: 服务 → OpenClash → 运行状态 数据来源: 前端 JS 同时请求多个后端端点：/status (运行状态、仪表盘设置)、/toolbar_show (流量统计)、/update (版本信息)、/oc_settings (快捷设置)、/rule_mode (代理模式)、/config_file_list (配置文件列表) 等。版本信息通过 /update 端点 (action_update) 返回，非 /status 端点。/status 仅返回运行状态布尔值、仪表盘可用性和 core_type，不包含版本号。

1.1 核心控制卡片

元素	功能	后端操作
启动/停止开关	切换核心运行状态	调用 action_oc_action → /etc/init.d/openclash start/stop
重启按钮	重启核心	调用 /etc/init.d/openclash restart
覆写模块按钮	在运行状态页弹出覆写编辑器（与菜单「服务→OpenClash→覆写设置」独立）	调用 editOverwrite() → 在运行状态页弹出覆写编辑模态框
插件/核心版本	显示当前版本号	核心版本: 执行 /etc/openclash/core/clash_meta -v 解析输出; 插件版本: 读取 opkg/apk 包数据库; 远程最新: 读取 /tmp/clash_last_version。前端通过 /update 端点 (action_update) 获取，非 /status 端点
主题切换	Light(太阳)/Dark(月亮)/Auto(自动) 三档切换	前端 CSS 变量 + localStorage
公告横幅	滚动显示项目公告 (24h 缓存)	/announcement 端点
社交链接	Wiki / Tutorials / Star / Telegram / Sponsor / Mihomo 图标	外部链接 window.open()
开发者头像	13 位贡献者头像网格 (悬停显示名称)	来自 GitHub 头像 URL

1.2 运行模式卡片 (Running Mode)

模式	UCI en_mode 值	说明
Compat (兼容)	redir-host	Redir-Host 模式，使用 iptables redirect 转发流量
TUN 模式	redir-host-tun / fake-ip-tun	使用 TUN 虚拟网卡接管所有流量
Mix (混合)	redir-host-mix / fake-ip-mix	TUN + Redirect 混合，TCP 走 system 栈、UDP 走 gvisor 栈

切换触发: action_switch_run_mode → 修改 UCI en_mode，若运行中则自动重启

1.3 代理模式卡片 (Proxy Mode)

模式	Mihomo mode 值	效果
Rule (策略代理)	rule	按 YAML 中 rules: 规则集合分流
Global (全局代理)	global	所有流量走 GLOBAL 策略组所选代理
Direct (全局直连)	direct	所有流量直连，不经过任何代理

切换触发: action_switch_rule_mode → PATCH Mihomo API /configs 的 mode 字段，同时更新 UCI proxy_mode

1.4 快捷设置网格

设置项	功能	UCI 选项	触发函数
Area Bypass (地区绕行)	切换中国 IP/海外绕行	china_ip_route (0/1/2)	action_switch_oc_setting → 修改 UCI + 重启
Sniffer (域名嗅探)	是否启用 Mihomo 域名嗅探	enable_meta_sniffer	action_switch_oc_setting → 动态修改运行时 YAML sniffer.enable
DNS Proxy (DNS尊重规则)	DNS 查询是否遵守路由规则	enable_respect_rules	action_switch_oc_setting → 动态修改 YAML dns.respect-rules
Stream Unlock (流媒体解锁)	一键启用流媒体解锁	stream_auto_select	action_switch_oc_setting → 设置 stream_auto_select=1 及 Netflix/Disney/HBO 默认参数

1.5 配置文件卡片

操作	功能	后端路由
配置文件选择器	下拉切换当前使用的 YAML 配置	action_switch_config → 更新 config_path + 自动重启
SwiTch (切换)	切换到选中的配置	同上
更新配置	重新下载订阅并更新	action_update_config → 调用 openclash.sh
Edit (编辑)	在线编辑 YAML 配置文件	弹出 config_edit 模态框 (基于 CodeMirror，支持原始/运行时视图切换、合并视图对比、覆写卡片栏)
编辑订阅	修改该配置的订阅参数	跳转到 config-subscribe-edit
上传	上传新的 YAML 配置文件	弹出 config_upload 模态框 (支持文件上传 + 订阅链接两个标签页)
刷新订阅按钮	手动刷新当前配置的订阅信息	/sub_info_get 端点
指定 URL 按钮	设置订阅信息查询 URL	/set_subinfo_url 端点
订阅进度条	显示订阅流量使用情况 (已用/总量/百分比)	/sub_info_get 自动轮询

1.6 控制面板卡片

显示当前 Dashboard 访问地址及 Secret 密码。对应 UCI:

• cn_port — API 端口 (默认 9090)，对应 Mihomo external-controller
• dashboard_password — API 密钥，对应 Mihomo secret
• dashboard_forward_domain / dashboard_forward_port / dashboard_forward_ssl — 公网访问设置
• 提供 复制 IP 和 复制密钥 按钮

1.7 混合代理卡片

显示 SOCKS5/HTTP 代理地址，可复制或生成 PAC 文件：

• mixed_port (默认 7893), http_port (7890), socks_port (7891)
• 用户认证: authentication TypedSection 中的 username/password，对应 Mihomo authentication 配置
• 提供 复制代理地址、复制认证信息、生成 PAC 配置 按钮

1.8 仪表盘入口 (Control Panel)

4 种可选仪表盘：Dashboard (Yacd)、Yacd、Metacubexd、Zashboard

• 对应 Mihomo external-ui 配置
• 切换触发: action_switch_dashboard → openclash_download_dashboard.sh
• 默认仪表盘: UCI default_dashboard

1.9 快捷操作按钮 (Quick Action)

操作	功能	后端
Close Connect (关闭链接)	断开所有代理连接	openclash_history_get.sh 'close_all_conection'
Reload Firewall (重置防火墙)	重新应用 iptables/nftables 规则	/etc/init.d/openclash reload 'manual'
清空 DNS 缓存	刷新 Fake-IP 和 DNS 缓存	POST /cache/fakeip/flush + /cache/dns/flush
Check Update (检查更新)	同时更新插件 + 核心 + 订阅 + GEO	openclash_update.sh 'one_key_update'

1.10 统计信息

页面底部显示 8 项实时统计指标，通过 WebSocket 和 XHR 轮询更新：

指标	说明
上行速率	当前上传速率
下行速率	当前下载速率
上行总量	累计上传流量
下行总量	累计下载流量
连接数	当前活动连接数
内存	核心内存占用
CPU	核心 CPU 占用
平均负载	系统平均负载

1.11 IP 检测页 (IP Address / 访问检查)

IP 地址部分 (IP Address)：

• 并行查询 4 个 IP 源：UpaiYun、IPIP.NET、IP.SB、IPIFY，每个显示 IP 地址 + 地理信息
• 隐私切换按钮（眼睛图标）：点击后用 ***.***.***.*** 隐藏所有 IP 显示（状态持久化到 localStorage）

访问检测部分 (Access Check)：

• 两种检测模式：路由器模式（后端 XHR 代理检测）和浏览器模式（前端 fetch 直接检测），通过模式切换图标切换
• 4 个网站可达性检测：Baidu Search (百度搜索)、NetEase Music (网易云音乐)、GitHub、YouTube，各显示 HTTP 状态码和加载延迟（ms）
• 刷新按钮：重新执行所有 IP 查询和 HTTP 检测

轮询间隔: HTTP 检测 5-20 秒，IP 检测 15-40 秒。

1.12 oixCloud 面板 (oixCloud)

仅在设置了 oix_token 时显示，展示 oixCloud 订阅服务信息：

• Logo + 标语（随机变化）
• 公告横幅（60 秒后自动消失）
• 计划信息：计划类型、到期时间、账户余额、推广余额、积分
• 流量统计：今日已用、计划已用、剩余流量、总流量
• 签到按钮：每日签到获取流量
• 底部链接："Powered by oixcloud.com"

登录入口：在「插件设置 → oixCloud」标签页中通过 Login Account 按钮登录。

---

第二部分：插件设置页面 (Plugin Settings / settings)

UCI Section: openclash (anonymous section) 所有选项通过 uci set openclash.@openclash[0].<option>=<value> 设置

实现总览

插件设置页的选项通过以下路径生效：

 UCI 写入 → init.d start_service() → get_config() 读取所有 UCI 变量
                                            │
                    ┌───────────────────────┼───────────────────────┐
                    ▼                       ▼                       ▼
            yml_change.sh           set_firewall()          change_dnsmasq()
         (修改 YAML 配置)         (iptables/nftables)      (DNS 劫持转发)
                    │                       │                       │
                    ▼                       ▼                       ▼
              Mihomo 核心              系统防火墙规则            Dnsmasq → Clash DNS

脚本	输入	输出	负责的设置
yml_change.sh	~48 个 UCI 参数	修改运行 YAML	端口、模式、DNS、TUN、Sniffer、认证、Meta、GEO、Smart
yml_rules_change.sh	UCI 覆写 + 自定义规则	修改运行 YAML	URL-Test 覆写、GitHub CDN、自定义规则注入、BT 直连规则
set_firewall()	所有流量控制 UCI	iptables/nftables 规则	透明代理、黑白名单访问控制、中国 IP 绕行、QUIC 阻断、UPNP 排除
change_dnsmasq()	DNS 相关 UCI	dnsmasq 配置修改	DNS 劫持转发、自定义域名 DNS、chnroute 旁路

插件强制覆盖/禁用的设置（用户不可修改）

重要：以下设置由 yml_change.sh 在每次启动时无条件硬编码写入 YAML，用户在 LuCI 中无法修改或关闭。即使通过覆写模块的 [YAML] 段尝试覆盖，也会被后续脚本覆盖（覆写模块先于 yml_change.sh 执行）。

强制设置	硬编码值	说明
allow-lan	true	始终允许局域网设备使用代理端口
bind-address	*	始终监听所有网络接口
external-controller	0.0.0.0:<cn_port>	API 始终监听所有接口 (非仅 127.0.0.1)
external-ui	/usr/share/openclash/ui	Dashboard 路径不可更改
dns.listen	0.0.0.0:<dns_port>	DNS 始终监听所有接口
profile.store-selected	true	始终保存策略组选择状态
sniffer.sniff	HTTP:80,8080-8880 / TLS:443,8443 / QUIC:443	嗅探端口不可修改
sniffer.override-destination	true	始终用嗅探结果覆盖连接目标
sniffer.force-domain	netflix, nflxvideo, amazonaws, media.dssott.com	强制嗅探的流媒体域名
sniffer.skip-domain	Mijia Cloud, dlg.io.mi.com, +.oray.com, +.sunlogin.net, +.push.apple.com	跳过嗅探的智能家居/推送域名
sniffer.force-dns-mapping	true (Redir-Host 时)	Redir-Host 模式下强制 DNS 映射嗅探
iptables	删除	强制移除 iptables 相关配置
ebpf	删除	强制移除 eBPF 相关配置
auto-redir	删除	强制移除 auto-redir（由 OpenClash 防火墙管理）
routing-mark	6666 (非自定义标记时)	固定路由标记值
external-controller-cors.allow-private-network	true (有 CORS origin 时)	允许私有网络访问 API

有条件默认设置（仅在用户未配置时自动添加）：

设置	默认值	条件
keep-alive-interval	15	仅当配置中未设置
keep-alive-idle	600	仅当配置中未设置
ntp.enable	true	仅当配置中未设置
ntp.server	time.apple.com	仅当配置中未设置
ntp.port	123	仅当配置中未设置
ntp.interval	30 (分钟)	仅当配置中未设置
ntp.write-to-system	true	仅当配置中未设置

防火墙固定值（硬编码在 init.d/openclash 中）：

常量	值	说明
PROXY_FWMARK	0x162	所有被代理流量的防火墙标记，不可修改
PROXY_ROUTE_TABLE	0x162	策略路由表 ID，不可修改
SKIP_GROUP	65534	绕过代理的组 ID (skgid)

内核模块依赖（缺少时会导致启动报错）：

运行模式	fw4 (nftables) 需要的 kmod	fw3 (iptables) 需要的 kmod
Redir-Host / Fake-IP (非TUN)	kmod-nft-tproxy	kmod-ipt-tproxy
TUN 模式	kmod-tun + kmod-nft-tproxy	kmod-tun + kmod-ipt-tproxy
混合模式 (Mix)	kmod-tun + kmod-nft-tproxy	kmod-tun + kmod-ipt-tproxy

故障排查：如果启动日志提示 "nft_tproxy module not found"，请在 LuCI 的「系统 → 软件包」中搜索安装 kmod-nft-tproxy；提示 "xt_TPROXY module not found"，安装 kmod-ipt-tproxy。TUN 模式还需 kmod-tun（同样在 LuCI 软件包页面安装）。注意 fw4 环境下应检查 nft_tproxy 而非 xt_TPROXY。

2.1 模式设置标签页 (op_mode)

en_mode — 选择运行模式 (Select Mode)

• UCI 选项: openclash.@openclash[0].en_mode
• 可选值:
  • redir-host — 兼容模式 (Redir-Host)
  • redir-host-tun — 兼容模式 (TUN)
  • redir-host-mix — 兼容模式 (混合)
  • fake-ip — Fake-IP 模式
  • fake-ip-tun — Fake-IP (TUN)
  • fake-ip-mix — Fake-IP (混合)
• Mihomo 对应配置: dns.enhanced-mode (fake-ip / redir-host)
• Redir-Host 模式: DNS 解析在客户端完成，核心根据 IP 规则分流。适合 BT/PT 下载
• Fake-IP 模式: DNS 解析在核心完成，返回虚假 IP (198.18.x.x)，性能更高。规则基于域名匹配。推荐作为日常使用首选：Fake-IP（增强）模式下 TCP/UDP 均走系统协议栈，性能最优；若出现 NAT 问题可切换为 Fake-IP（混合）模式；若固件含 Docker 则直接选用 Fake-IP（TUN）模式
• TUN 模式: 创建虚拟网卡，以网络层接管所有流量。对应 Mihomo tun.enable=true。需要 kmod-tun 内核模块
• 混合模式: TCP 使用 system 栈 (redirect)，UDP 使用 gvisor 栈 (TUN)。对应 Mihomo tun.stack=mixed。适合非直连游戏等对 NAT 类型有要求的场景

stack_type — TUN 堆栈类型 (Stack Type)

• UCI 选项: openclash.@openclash[0].stack_type
• 可选值: system / gvisor / mixed
• Mihomo 对应配置: tun.stack
• system: 使用 Linux 系统协议栈，性能和稳定性最好
• gvisor: 用户空间网络协议栈，隔离性更好，避免内核态/用户态切换
• mixed: TCP 用 system、UDP 用 gvisor
• 依赖: 仅在 TUN/混合模式下显示

proxy_mode — 代理模式 (Proxy Mode)

• UCI 选项: openclash.@openclash[0].proxy_mode
• 可选值: rule / global / direct
• Mihomo 对应配置: mode
• 默认: rule
• 此选项等同一键切换全局/规则/直连模式

enable_udp_proxy — UDP 流量转发 (Proxy UDP Traffics)

• UCI 选项: openclash.@openclash[0].enable_udp_proxy
• 默认: 1 (开启)
• 说明: 节点需支持 UDP 转发。Docker 环境可能导致 UDP 异常
• 依赖: 仅 Redir-Host 模式显示
• 注意: Fake-IP 模式即使关闭此选项，域名类 UDP 连接仍会经过核心

delay_start — 延迟启动（秒） (Delay Start)

• UCI 选项: openclash.@openclash[0].delay_start
• 默认: 0 (不延迟)
• 说明: 开机后延迟指定秒数再启动 OpenClash

log_size — 日志大小（KB） (Log Size)

• UCI 选项: openclash.@openclash[0].log_size
• 默认: 1024 (1MB)
• 说明: 核心日志文件 /tmp/openclash.log 的最大大小

bypass_gateway_compatible — 旁路网关（旁路由）兼容 (Bypass Gateway Compatible)

• UCI 选项: openclash.@openclash[0].bypass_gateway_compatible
• 默认: 0 (关闭)
• 说明: 旁路由 (旁路网关) 模式下无法上网时尝试开启。如果设备没有 WLAN，建议禁用 LAN 接口的桥接选项

disable_quic_go_gso — 禁用 quic-go GSO (Disable QUIC Go GSO)

• UCI 选项: openclash.@openclash[0].disable_quic_go_gso
• 默认: 0 (关闭)
• 说明: Linux 内核 6.6 以上版本遇到 QUIC UDP 问题时尝试开启。Hysteria / Hysteria2 / TUIC 等基于 QUIC 协议的节点出现连接超时、断流、握手失败时，优先尝试开启此选项
• Mihomo 对应配置: disable-quic-go-gso (全局 experimental 选项，写入 YAML 的 experimental.disable-quic-go-gso: true)

small_flash_memory — 小闪存模式 (Small Flash Memory)

• UCI 选项: openclash.@openclash[0].small_flash_memory
• 默认: 0 (关闭)
• 说明: 将核心和 GEOIP 数据文件移到 /tmp/etc/openclash，节省闪存空间。路由重启后需重新下载

AI 行为指引 — QUIC 类节点（Hysteria / Hysteria2 / TUIC）故障排查: 当用户报告 Hysteria、Hysteria2、TUIC 等基于 QUIC 协议的节点无法连接、频繁断流或握手超时时，AI 应优先建议用户在「插件设置→模式设置」中开启「禁用 quic-go GSO (Disable QUIC Go GSO)」选项并重启 OpenClash。这是 Linux 内核 ≥6.6 上最常见的 QUIC 兼容性问题。

关于 disable_udp_quic（禁用 QUIC）：此选项不会影响 Mihomo 内核自身的 Hysteria 出站连接，无需关闭。原因：非 TUN 模式下规则在 INPUT 链匹配 dport 443，内核出站返回包的 dport 为临时端口（非 443），不命中；TUN 模式下规则在 FORWARD 链限定 oifname utun，仅拦截经 TUN 转发的 LAN 客户端流量，内核自身连接走 OUTPUT 链，不经过 FORWARD。disable_udp_quic 的目的是让 LAN 客户端的 YouTube 等 QUIC 流量降级到 TCP 以便代理，与内核节点通信无关。

若 GSO 选项开启后问题仍存在，建议查阅 Mihomo Wiki Hysteria 配置 或 Hysteria2 配置 验证节点字段是否正确。

运行模式切换按钮 (switch_mode)

• 模板: openclash/switch_mode
• 功能: 一键在 Redir-Host 和 Fake-IP 之间切换当前页面显示
• 触发: action_switch_mode → 修改 UCI operation_mode

运行模式实现详解

启动流程中的关键变量传递 (来自 init.d start_service()):

1. get_config() 读取 UCI en_mode，解析出 en_mode_tun（TUN 标记）、en_mode_fakeip（Fake-IP 标记）、en_mode_mix（混合标记）
2. 将这些传递给 yml_change.sh 作为位置参数：
   • $1 = DNS enhanced-mode 值（fake-ip 或 redir-host）
   • $11 = en_mode_tun（0/1/2，决定是否启用 TUN）
   • $12 = stack_type 或 $30（TUN 堆栈类型回退）

yml_change.sh 中 en_mode 的 YAML 影响链:

• dns.enhanced-mode: 根据 Fake-IP / Redir-Host 设置 → 影响 Mihomo 的 DNS 解析策略：
  • fake-ip: 所有 DNS 查询返回 198.18.x.x 假 IP，规则基于域名匹配，性能最优
  • redir-host: DNS 在客户端完成，规则基于真实 IP 匹配，适合 BT/PT
• tun.enable: en_mode_tun != 0 时设为 true → Mihomo 创建 utun 虚拟网卡接管流量
• tun.stack: system(系统协议栈)/gvisor(用户态协议栈)/mixed(TCP system + UDP gvisor)
  • system: 性能最好，走 Linux 内核 TUN 驱动
  • gvisor: 隔离性好，UDP NAT 支持更完善
  • mixed: TCP 用 system 栈 (REDIRECT)，UDP 用 gvisor 栈 (TUN)

防火墙层面的影响 (set_firewall()):

• Redir-Host (非 TUN): TCP 通过 REDIRECT 到 proxy_port(7892)，UDP 通过 TPROXY 到 tproxy_port(7895)，标记 fwmark 0x162
• Fake-IP (非 TUN): 同上 + 额外匹配 fakeip_range(198.18.0.1/16) 的路由
• TUN 模式: 所有流量标记 0x162，路由到 utun 设备（策略路由），TUN 内部处理分流
• 混合模式 (Mix): TUN 设备处理 UDP（走 gvisor），TCP 走 REDIRECT（system 栈）

---

2.2 流量控制标签页 (traffic_control)

生效路径: 绝大多数流量控制选项不修改 YAML，而是影响 set_firewall() 生成的 iptables/nftables 规则链。

AI 行为指引: 当用户询问流量路由问题时（如"TUN 和 TPROXY 有什么区别"、"如何让某设备不走代理"、 "旁路由/网关模式下如何配置"、"IPv6 流量如何控制"），AI 应结合本章节的防火墙规则详解 和 Mihomo 监听器文档 回答，说明不同模式 的工作原理（而非仅给出操作步骤），帮助用户理解后做出选择。 涉及防火墙实现细节时，查阅 OpenClash 源码 中 init.d/openclash 和 yml_change.sh 的相关逻辑。 set_firewall() 通过 UCI firewall.openclash 注册为 /var/etc/openclash.include，由 OpenWrt firewall3/firewall4 框架加载。 支持 fw4 (nftables) 和 fw3 (iptables) 双后端自动检测。 注意：如需按接口/用户/DSCP 等维度精细绕过，请使用「插件设置页面底部 → 来源流量访问控制 (2.10)」。黑白名单设备级绕过使用「插件设置 → 黑白名单 (2.4)」。

router_self_proxy — 路由本机代理 (Router-Self Proxy)

• UCI 选项: openclash.@openclash[0].router_self_proxy
• 默认: 1 (开启)
• 说明: 开启后，路由器本身发出的流量也会经过代理核心。仅在规则模式下生效。关闭后流媒体增强标签页所有功能将失效
• 实现细节: 控制 OUTPUT 链规则是否生成。开启时创建 openclash_output 链（fw4）或 OUTPUT 规则（fw3），将路由器自身出站流量重定向到 Clash。关闭时删除 OUTPUT 链规则，路由器自身流量走原始路由表。

disable_udp_quic — 禁用 QUIC (Disable QUIC)

• UCI 选项: openclash.@openclash[0].disable_udp_quic
• 默认: 1 (开启)
• 效果: 对 UDP 443 端口的流量执行 REJECT，阻止 YouTube 等使用 QUIC 协议传输 (降级到 TCP)
• 执行方式: 通过 iptables/nftables 规则阻断 UDP 443，排除中国大陆 IP 段
• 实现细节: 在 set_firewall() 的 openclash_mangle 链中插入规则：meta l4proto udp th dport 443 counter reject。但绕过 china_ip_route_pass ipset 中的中国 IP（通过 ip daddr @china_ip_route_pass counter return）。同时配合 dnsmasq 的 ipset/nftset 标记确保国内 QUIC 不受影响。

skip_proxy_address — 绕过服务器地址 (Skip Proxy Address)

• UCI 选项: openclash.@openclash[0].skip_proxy_address
• 默认: 0 (关闭)
• 说明: 绕过配置中服务器地址的代理，防止重复代理 (代理嵌套)
• 实现细节: 开启后 set_firewall() 解析 YAML 中所有代理节点的 server 地址，生成 nftables set（openclash_proxy_server_ip）或 ipset（proxy_server_ip），在 redirect/TPROXY 规则前插入 return 跳过规则，防止代理节点本身的连接被二次代理。

common_ports — 仅允许常用端口流量 (Common Ports Proxy Mode)

• UCI 选项: openclash.@openclash[0].common_ports
• 默认: 0 (禁用)
• 说明: 仅对常用端口 (HTTP/HTTPS/邮件等) 进行代理，防止 BT/P2P 流量经过代理
• 预设值: 21 22 23 53 80 123 143 194 443 465 587 853 993 995 998 2052 2053 2082 2083 2086 2095 2096 5222 5228 5229 5230 8080 8443 8880 8888 8889
• 自定义格式: 空格分隔的端口号，如 443 80 或范围 20-443
• 依赖: 仅 Redir-Host 系列模式
• 实现细节: 非 0 时在 openclash redirect 链的端口检查规则中使用自定义端口列表（而非默认的允许所有端口）。格式 {tcp, udp} th dport {80, 443, ...} counter redirect to proxy_port。禁用时规则不含端口限制，所有 TCP 都重定向。

china_ip_route — 实验性：绕过指定区域 IP (China IP Route)

• UCI 选项: openclash.@openclash[0].china_ip_route
• 可选值:
  • 0 — 关闭
  • 1 — 绕过中国大陆 IP (将国内 IP 直连，提升性能)
  • 2 — 绕过海外 IP
• 说明: 强烈推荐启用「绕过中国大陆」。启用后，GeoSite 数据库中分类为 CN 的域名，且解析 IP 位于大陆 IP 段范围内的流量将不进入内核，显著降低内核性能开销。旁路由模式下无法访问可尝试开启"旁路由兼容"选项
• Mihomo 对应: 通过 rules 规则实现 GEOIP,CN,DIRECT 等效逻辑
• 实现细节（双重机制）: 1) YAML 层面: yml_change.sh 在 YAML rules 前注入 GEOIP,CN,DIRECT 规则（mode 1）或 GEOIP,CN,Proxy + 修改 MATCH 为 DIRECT（mode 2）。2) 防火墙层面: set_firewall() 使用 chnroute IP 列表构建 nftables set openclash_china_ip，在 redirect/TPROXY 链中匹配国内 IP 直连 return。两层面互为补充——YAML 规则处理域名类流量，防火墙 ipset 处理纯 IP 流量。

intranet_allowed — 仅允许内网 (Only Intranet Allowed)

• UCI 选项: openclash.@openclash[0].intranet_allowed
• 默认: 1 (开启)
• 说明: 开启后控制面板和连接代理端口仅能从内网访问，不暴露到公网
• Mihomo 对应: allow-lan: true + bind-address: "*"
• 实现细节: 影响 YAML 的 allow-lan 字段。yml_change.sh 中设置 allow-lan: true，并通过 bind-address: "*" 监听所有接口。同时防火墙层面限制对 cn_port(9090) 的访问。关闭时 allow-lan: false，仅 127.0.0.1 可访问。

intranet_allowed_wan_name — WAN 接口名称 (WAN Interface Name)

• UCI 选项: openclash.@openclash[0].intranet_allowed_wan_name
• 说明: 指定哪个接口被识别为 WAN。用于仅允许内网功能区分内外网
• 依赖: intranet_allowed=1

lan_interface_name — LAN 接口名称 (LAN Interface Name)

• UCI 选项: openclash.@openclash[0].lan_interface_name
• 可选值: 系统中所有网络接口名
• 默认: 0 (禁用)
• 说明: 指定 LAN 接口名称

local_network_pass — 本地 IPv4 网络绕过列表 (Local Network Pass)

• UCI 选项: openclash.@openclash[0].local_network_pass
• 存储文件: /etc/openclash/custom/openclash_custom_localnetwork_ipv4.list
• 说明: 目标地址为列表中 IP 的流量不经过核心

chnroute_pass — Chnroute 绕过列表 (Chnroute Pass)

• UCI 选项: openclash.@openclash[0].chnroute_pass
• 存储文件: /etc/openclash/custom/openclash_custom_chnroute_pass.list
• 说明: 列表中的域名/IP 不受中国 IP 绕行选项影响，依赖 Dnsmasq。默认已预置 services.googleapis.cn、googleapis.cn、xn--ngstr-lra8j.com 以解决 Google Play 下载问题
• 依赖: enable_redirect_dns != 2
• 注意: chnroute_pass 仅在 DNS 解析层面将域名解析 IP 加入 china_ip_route_pass nft set 使其跳过绕行规则，但若上游 DNS 本身将这些域名解析到国内 IP，加入 set 后仍会被 china_ip_route 规则误判为国内 IP 而绕行。仅靠 chnroute_pass 不足以解决 Google Play 下载问题——必须同时从 DNS 解析（nameserver-policy 强制走境外 DNS）和规则匹配（自定义规则走代理）两方面入手，详见错误速查表 §十四

---

2.3 DNS 设置标签页 (dns)

生效路径: DNS 选项通过三条路径生效：

1. yml_change.sh 修改 YAML dns: 段 → Mihomo 内核使用
2. change_dnsmasq() 修改系统 dnsmasq → LAN 客户端 DNS 被劫持到 Clash
3. openclash_custom_domain_dns.sh 为自定义域名配置独立 DNS

AI 行为指引: 当用户询问 DNS 劫持相关问题时（如"DNS 重定向模式选哪个"、"自定义上游 DNS 服务器怎么写"、 "Fake-IP 和 Redir-Host 的 DNS 行为有何不同"、"如何让特定域名不走 Fake-IP"），AI 应结合本文档的 「防火墙与 DNS 规则详解」章节和 Mihomo DNS 配置文档 解释底层原理，然后告知用户在 LuCI 中的操作路径。 涉及 dnsmasq 劫持实现时可查阅 OpenClash 源码 中 init.d/openclash 的 change_dnsmasq() 函数。对于 DNS 劫持失败的排查，首先让用户检查 「运行状态」页面查看 DNS 端口是否在监听。

enable_redirect_dns — 本地 DNS 劫持 (Redirect Local DNS Setting)

• UCI 选项: openclash.@openclash[0].enable_redirect_dns
• 可选值:
  • 0 — 禁用
  • 1 — Dnsmasq 转发 (将 LAN 的 DNS 请求转发给核心)
  • 2 — 防火墙重定向 (通过 iptables/nftables 劫持 53 端口)
• 默认: 1
• 说明:
  • Dnsmasq 转发 (值1): 修改 /tmp/etc/dnsmasq.conf.*，将上游 DNS 指向核心 DNS 端口 (dns_port=7874)
  • 防火墙重定向 (值2): 通过 iptables/nftables 将发往 53 端口的 UDP/TCP 流量 DNAT 到核心 DNS 端口。Fake-IP 模式下使用 LAN 访问控制必须选此项
• Mihomo 对应: DNS 监听配置 dns.listen: 0.0.0.0:7874
• 实现详解:
  • 值1 (Dnsmasq): change_dnsmasq() 函数先备份 dnsmasq 原有配置到 openclash.config.*，然后设置 dhcp.@dnsmasq[0].server=127.0.0.1#<dns_port>，noresolv=1，cachesize=0。效果：所有 LAN 客户端的 DNS 查询 → dnsmasq → 转发到 Clash DNS (7874) → Clash 根据 enhanced-mode 处理。
  • 值2 (防火墙): 创建 openclash_dns_redirect nftables 链，对目标端口 53 的 UDP/TCP 流量 DNAT 到 dns_port。同时保留 dnsmasq 处理本地 DNS 缓存。此模式允许 lan_ac_* 访问控制（需要 Fake-IP 模式）。
  • 恢复: revert_dnsmasq() 还原所有原始 dnsmasq 配置（servers、noresolv、resolvfile、cachesize）。

flush_dns_cache — 清空 DNS 缓存按钮 (Flush DNS Cache)

• 模板: openclash/flush_dns_cache
• 功能: 通过 POST /cache/fakeip/flush + /cache/dns/flush API 清空 Fake-IP 和 DNS 缓存

dnsmasq_fix — Dnsmasq 修复按钮 (Dnsmasq Fix)

• 功能: 停止 OpenClash 后 DNS 异常时使用。恢复 Dnsmasq 默认配置:
  1. 设置 noresolv=0, localuse=1
  2. 恢复 resolvfile 为有效的 DNS 配置文件
  3. 若无有效配置则创建 /tmp/resolv.conf.d/resolv.conf.auto (114.114.114.114, 8.8.8.8)
  4. 重启 dnsmasq

enable_custom_domain_dns_server — 启用第二 DNS 服务器 (Enable Specify DNS Server)

• UCI 选项: openclash.@openclash[0].enable_custom_domain_dns_server
• 默认: 0
• 说明: 为自定义域名列表指定专用 DNS 服务器

custom_domain_dns_server — 指定服务器 (Specify DNS Server)

• UCI 选项: openclash.@openclash[0].custom_domain_dns_server
• 默认: 114.114.114.114
• 格式: IP地址 或 IP地址#端口 (如 127.0.0.1#5300)

custom_domain_dns — 自定义域名列表 (Custom Domain DNS)

• 存储文件: /etc/openclash/custom/openclash_custom_domain_dns.list
• 格式: 每行一个域名
• 说明: 列表中的域名不返回 Fake-IP，使用指定的上游 DNS 服务器解析

---

2.4 黑白名单标签页 (Black&White / lan_ac)

生效路径: 访问控制完全在防火墙层面实现，不修改 YAML。

AI 行为指引: 当用户询问访问控制问题时（如"如何让某个设备不走代理"、"如何让内网某设备全局代理"、 "代理黑名单和白名单的区别"），AI 应结合本章节的防火墙规则详解 （特别是「各选项对防火墙规则的具体影响」表格）告知用户各选项组合的效果。 涉及黑白名单匹配逻辑时，查阅 OpenClash 源码 中 init.d/openclash 的 firewall_lan_ac_traffic() 函数和 set_firewall() 中的 ipset/nft set 创建逻辑。 对于 IP 段/CIDR 的写法问题，解释 192.168.1.0/24 等标准 CIDR 格式。 注意：如需按接口/用户/DSCP 等维度精细绕过，请使用「插件设置页面底部 → 来源流量访问控制 (2.10)」。 依赖: enable_redirect_dns=2（防火墙重定向模式）仅在 Fake-IP 模式下强制要求——因为 Fake-IP 返回虚拟 IP，客户端不知道真实目标， 必须通过防火墙重定向 DNS 才能实现基于真实目标的访问控制。Redir-Host 模式下此依赖为可选（LuCI UI 中同样要求，但底层机制不同）。

lan_ac_mode — 局域网访问控制模式 (LAN Access Control Mode)

• UCI 选项: openclash.@openclash[0].lan_ac_mode
• 可选值: 0 (黑名单模式) / 1 (白名单模式)
• 默认: 0
• 说明:
  • 黑名单模式: 列表中的设备/主机不走代理 (直连)
  • 白名单模式: 只有列表中的设备/主机走代理
• 依赖: enable_redirect_dns=2 (仅防火墙重定向模式) + Redir-Host 系列模式
• 实现细节: 系统使用 ebtables 或 nft 在二层网桥层面匹配 MAC 地址，使用 nftables 在三层匹配 IP。黑白名单决定规则的 return 行为取反（黑名单=匹配到return直连，白名单=不匹配则return直连）。

lan_ac_black_ips — 不走代理的局域网设备 IP (LAN Bypassed Host List)

• UCI 选项: openclash.@openclash[0].lan_ac_black_ips (DynamicList)
• 格式: IP 地址或 CIDR 网段
• 依赖: lan_ac_mode=0
• 实现细节: 生成 nftables set openclash_lan_black_ip / openclash_lan_black_ip6，在 openclash redirect 链中插入 ip saddr @openclash_lan_black_ip counter return 跳过规则。

lan_ac_black_macs — 不走代理的局域网设备 Mac (LAN Bypassed Mac List)

• UCI 选项: openclash.@openclash[0].lan_ac_black_macs (DynamicList)
• 格式: MAC 地址
• 实现细节: 通过 ebtables（fw3）或 nft add rule bridge（fw4）在 br-lan 网桥上匹配源 MAC，匹配到的流量不进入 Clash 代理链。

lan_ac_white_ips — 走代理的局域网设备 IP (LAN Proxied Host List)

• UCI 选项: openclash.@openclash[0].lan_ac_white_ips
• 依赖: lan_ac_mode=1

lan_ac_white_macs — 走代理的局域网设备 Mac (LAN Proxied Mac List)

• UCI 选项: openclash.@openclash[0].lan_ac_white_macs

wan_ac_black_ips — 不走代理的 WAN IP (WAN Bypassed Host List)

• UCI 选项: openclash.@openclash[0].wan_ac_black_ips
• 说明: Fake-IP 模式下仅支持纯 IP 请求，域名请求需先设置 Fake-IP-Filter

wan_ac_black_ports — 不走代理的 WAN 端口 (WAN Bypassed Port List)

• UCI 选项: openclash.@openclash[0].wan_ac_black_ports
• 格式: 端口号或端口范围

---

2.5 流媒体增强标签页 (stream_enhance)

生效路径: openclash_streaming_unlock.lua 脚本在核心启动后作为守护进程运行， 定期测试各流媒体服务的解锁情况，自动将策略组切换到支持该服务的节点。 配置写入 YAML 的 rule-providers 和 rules，通过 Mihomo 规则引擎匹配流媒体域名。

AI 行为指引: 当用户询问流媒体相关问题时（如"如何解锁 Netflix/Disney+"、"Bilibili 地区选项代表什么"、 "如何添加新的流媒体服务"、"Group Filter 正则怎么写"），AI 应查阅 Mihomo 规则文档 了解 GEOSITE/RULE-SET 等规则类型，并结合 OpenClash 的流媒体增强设置告知用户具体配置步骤。 涉及流媒体解锁检测逻辑时，查阅 OpenClash 源码 中 openclash_streaming_unlock.lua 脚本。 注意：openclash_streaming_unlock.lua 仅负责已配置服务的节点测试和自动切换，不负责 Smart 策略。

所有子选项依赖 stream_auto_select=1。每个流媒体服务有一组独立配置：

服务	启用 UCI	默认	说明
Netflix	stream_auto_select_netflix	0	启用后自动选择支持 Netflix 的节点
Disney Plus	stream_auto_select_disney_plus	0
HBO Max	stream_auto_select_hbo_max	0
YouTube	stream_auto_select_youtube	0
Prime Video	stream_auto_select_prime_video	0
Paramount Plus	stream_auto_select_paramount_plus	0
Discovery Plus	stream_auto_select_discovery_plus	0
Bilibili	stream_auto_select_bilibili	0	解锁地区选项：CN(仅大陆)/HK/MO/TW/TW(仅台湾)
Google Not CN	stream_auto_select_google_not_cn	0	自动选择非中国 Google 节点
OpenAI	stream_auto_select_openai	0
Claude	stream_auto_select_claude	0
Gemini	stream_auto_select_gemini	0

每个服务配置项：

• Group Filter: stream_auto_select_group_key_<service> — 匹配策略组的正则表达式
• Unlock Region Filter: stream_auto_select_region_key_<service> — 解锁地区国家缩写
• Unlock Nodes Filter: stream_auto_select_node_key_<service> — 节点名称正则过滤
• 手动测试按钮: 调用 openclash_streaming_unlock.lua 执行解锁测试
• 实现详解: openclash_streaming_unlock.lua 是一个独立 Lua 脚本，被 /etc/init.d/openclash 以 procd 服务形式启动（与核心并列）。工作流程：
  1. 读取 YAML 中所有策略组和节点，构建节点-策略组映射
  2. 对每个启用的流媒体服务，尝试用各节点连接服务域名（如 netflix.com）
  3. 检查 HTTP 响应码或页面内容判断是否解锁（如 Netflix 返回 200 且不含地区限制页面则解锁）
  4. 找到能解锁的节点后，通过 Mihomo API PUT /proxies/{group} 自动切换策略组到该节点
  5. 定期重新测试（间隔可配置），节点失效时自动切换

---

2.6 外部控制标签页 (Dashboard Settings / dashboard)

生效路径: 仪表盘选项写入 YAML 的 external-controller、secret、external-ui 等字段， 由 Mihomo 内核直接读取并提供 HTTP API。下载/切换通过 openclash_download_dashboard.sh 执行。

选项	UCI Key	默认	说明
控制面板端口 (Dashboard Port)	cn_port	9090	对应 Mihomo external-controller: 0.0.0.0:9090
管理页面登录密钥 (Dashboard Secret)	dashboard_password	空	对应 Mihomo secret，留空则不验证
管理页面公网域名 (Public Dashboard Address)	dashboard_forward_domain	空	用于公网访问面板
管理页面映射端口 (Public Dashboard Port)	dashboard_forward_port	空
管理页面公网 SSL 访问 (Public Dashboard SSL)	dashboard_forward_ssl	0

仪表盘版本管理通过 action_switch_dashboard → openclash_download_dashboard.sh 自动下载切换。

• 实现细节: yml_change.sh 将 cn_port、dashboard_password 写入 YAML → Mihomo 内核启动 HTTP API。openclash_download_dashboard.sh 从 GitHub Releases 下载 Dashboard 静态文件 (yacd/metacubexd/zashboard)，解压到 /usr/share/openclash/ui → 通过 external-ui 配置项使浏览器访问 http://IP:9090/ui/ 即加载 Dashboard。dashboard_forward_* 在 LuCI 控制器中生成反向代理配置，将外部请求转发到内部 API 端口。

---

2.7 IPv6 设置标签页 (ipv6)

注意： 不建议为路由器开启 IPv6 及相关服务。IPv6 方案仅适用于主路由拨号环境（需运营商支持 IPv6-PD 前缀下发），旁路由环境不适用 生效路径: IPv6 选项通过 yml_change.sh 写入 YAML（ipv6、dns.ipv6、dns.fake-ip-range6）， 同时 set_firewall() 生成独立的 IPv6 防火墙规则链（openclash_v6、openclash_mangle_v6 等）。 IPv6 使用单独的 TProxy/Redirect/TUN 规则链，与 IPv4 互不影响。

IPv6 DNS 核心最佳实践：DNS 解析请求（包括 AAAA 记录查询）可以通过 IPv4 链路发送，无需 IPv6 DNS 服务器。推荐策略：① LAN 接口 DHCP 服务器中不分配 IPv6 DNS，强制设备用路由器 IPv4 地址做 DNS 解析；② 取消 过滤 IPv6 AAAA 记录（Dnsmasq 高级设置）；③ 开启 OpenClash 的「允许 IPv6 类型 DNS 解析」选项。效果：DNS 走 IPv4 通道查询（经过 OpenClash 分流），流量走 IPv6 通道传输——既防止 IPv6 DNS 抢答导致的泄露，又保证 IPv6 站点可访问

选项	UCI Key	默认	说明
IPv6 代理 (Proxy IPv6 Traffic)	ipv6_enable	0	开启 IPv6 流量代理。网关和 DNS 须为路由器 IP
IPv6 代理模式	ipv6_mode	TProxy(0)	TProxy/Redirect/TUN/Mix
IPv6 堆栈类型	stack_type_v6	system	system/gvisor/mixed。仅 TUN/Mix 模式
IPv6 UDP 代理	enable_v6_udp_proxy	1	仅 TProxy/Redirect 模式
允许 IPv6 类型 DNS 解析 (IPv6 DNS Resolve)	ipv6_dns	0	对应 Mihomo dns.ipv6 — 控制 Clash DNS 是否返回 AAAA 记录
IPv6 Fake-IP 范围	fakeip_range6	禁用	仅 Fake-IP 模式。对应 dns.fake-ip-range6
### 中国 IPv6 绕行 (China IPv6 Route)	china_ip6_route	0	0=关闭, 1=绕过大陆, 2=绕过海外
本地 IPv6 绕过	local_network6_pass	—	文件: /etc/openclash/custom/openclash_custom_localnetwork_ipv6.list
Chnroute6 绕过	chnroute6_pass	—	文件: /etc/openclash/custom/openclash_custom_chnroute6_pass.list。依赖: ipv6_enable=1 + enable_redirect_dns=1

---

2.8 第三方规则订阅 / GEO 数据库订阅 / 大陆白名单订阅标签页

第三方规则订阅 (Rules Update / rules_update)

自动更新规则文件 (rule-providers 使用的 .yaml/.list 文件)

GEO 数据库订阅 (GEO Update / geo_update)

数据类型	启用 UCI	更新脚本	更新星期 UCI	更新时间 UCI	自定义 URL UCI
GeoIP MMDB (Country.mmdb) (Auto Update GeoIP MMDB)	geo_auto_update	openclash_geo.sh ipdb	geo_update_week_time	geo_update_day_time	geo_custom_url
GeoIP Dat (Auto Update GeoIP Dat)	geoip_auto_update	openclash_geo.sh geoip	geoip_update_week_time	geoip_update_day_time	geoip_custom_url
GeoSite (Auto Update GeoSite)	geosite_auto_update	openclash_geo.sh geosite	geosite_update_week_time	geosite_update_day_time	geosite_custom_url
GeoASN (Auto Update Geo ASN)	geoasn_auto_update	openclash_geo.sh geoasn	geoasn_update_week_time	geoasn_update_day_time	geoasn_custom_url

共享配置项：*_update_week_time (周几): *=每天, 1=周一, 2=周二, …, 0=周日; *_update_day_time (小时): 0-23; *_custom_url (自定义下载地址，留空使用默认)

Mihomo 对应: geox-url 中的各字段 + geo-auto-update + geo-update-interval

• 实现细节:
  • Cron 触发: add_cron() 在 openclash_geo.sh 中为每种 GEO 类型注册 cron 任务
  • 下载流程: openclash_geo.sh 使用自定义 URL（*_custom_url）或默认地址下载，保存到 /etc/openclash/ 目录
  • Mihomo 使用: MMDB 用于 GEOIP 规则匹配（IP→国家），Dat 用于 GEOSITE 规则匹配（域名→类别），ASN 用于 Smart 策略
  • 运行时热加载: GEO 文件更新后 Mihomo 自动重新加载（geo-auto-update: true + geo-update-interval），无需重启

大陆白名单订阅 (Chnroute Update / chnr_update)

选项	UCI Key	默认	说明
自动更新 (Auto Update)	chnr_auto_update	0	启用定时更新大陆 IP 路由表
更新星期 (Update Time Every Week)	chnr_update_week_time	1(周一)	*=每天, 1=周一, …, 0=周日
更新时间 (Update time every day)	chnr_update_day_time	0(0:00)	0-23，每小时一个选项
IPv4 URL (Custom Chnroute Lists URL)	chnr_custom_url	https://ispip.clang.cn/all_cn.txt	中国 IPv4 CIDR 列表下载地址
IPv6 URL (Custom Chnroute6 Lists URL)	chnr6_custom_url	https://ispip.clang.cn/all_cn_ipv6.txt	中国 IPv6 CIDR 列表下载地址

更新脚本: openclash_chnroute.sh

---

2.9 其他标签页

定时重启 (Auto Restart / auto_restart)

此标签页用于设置 OpenClash 定时自动重启。

选项	UCI Key	类型	默认	说明
Auto Restart (定时重启)	auto_restart	Flag	0	0=关闭, 1=开启。开启后将在指定时间自动重启 OpenClash 服务
Restart Time (Every Week) (重启时间/每周)	auto_restart_week_time	ListValue	1(周一)	*=每天 (Every Day), 1=周一 (Every Monday), 2=周二 (Every Tuesday), 3=周三 (Every Wednesday), 4=周四 (Every Thursday), 5=周五 (Every Friday), 6=周六 (Every Saturday), 0=周日 (Every Sunday)
Restart time (every day) (重启时间/每天)	auto_restart_day_time	ListValue	0(0:00)	0-23，每小时一个选项

• 实现细节: add_cron() 在 /etc/crontabs/root 中添加 /etc/init.d/openclash restart 的 cron 条目，按用户选择的时间和星期执行。

版本更新 (Version Update / version_update)

此标签页使用自定义模板，提供核心/插件版本选择和更新操作。

页面要素（页面加载时通过 /update_info 和 /get_last_version API 动态填充）:

要素	显示内容	说明
CPU Architecture	当前设备 CPU 架构	自动检测，只读显示
Last Check Update	上次检查更新的时间	自动显示
[Meta] Current Core	当前 Meta 核心版本	执行 clash_meta -v 获取
[Meta] Latest Core	远程最新 Meta 核心版本	每 300 秒通过 /get_last_version 轮询刷新
Current Client	当前插件版本	从 opkg/apk 数据库读取
Latest Client	远程最新插件版本	同上轮询

版本选择（UCI 持久化）:

选项	UCI Key	类型	默认	说明
Compiled Version (编译版本 / CPU 架构)	core_version	Select	0(未设置 (Not Set))	选择与 CPU 匹配的编译版本：linux-amd64-v1/v2/v3(x86-64)、linux-arm64(armv8)、linux-armv7、linux-mips64 等 ~18 种架构
Release Branch (更新分支)	release_branch	Select	master	master(稳定版) / dev(开发版)
Smart Core (智能核心)	smart_enable	Select	0	0=禁用(使用 Meta 内核) / 1=启用(使用 Smart 内核)

操作按钮（点击时先保存上述选择到 UCI，再触发对应脚本）:

按钮	触发脚本	功能
Update Core (更新内核) → Check And Update (检查并更新)	openclash_core.sh	检查并更新 Meta/Smart 核心到最新版
Download Latest Core (下载最新版本内核)	openclash_core.sh	手动下载指定版本的核心（根据架构/分支/Smart选择）
Update Client (更新客户端) → Check And Update (检查并更新)	openclash_update.sh	检查并更新 luci-app-openclash 插件版本
Download Latest Client (下载最新版本客户端)	openclash_update.sh	手动下载最新客户端 .ipk/.apk
Backup (备份)	前端打包下载	备份配置文件（可选择备份范围：完整/排除核心/仅核心/仅配置/仅规则提供者/仅代理提供者）
Restore Default (还原默认)	清除 UCI 配置	恢复 OpenClash 为默认出厂配置
Remove Core (删除内核)	删除文件	删除所有核心二进制文件
Check Update (检查更新)	在线检查	一键检查更新（走 CDN 加速）

• 实现细节: 所有更新按钮在触发对应脚本前，都会先通过 /save_corever_branch API 保存当前选择的架构、分支和 Smart 启用状态。核心更新通过 openclash_core.sh 从 GitHub Releases 下载对应架构的 .tar.gz 并替换 /etc/openclash/core/clash_meta。插件更新通过 openclash_update.sh 下载 .ipk/.apk 并通过 ubus 后台安装以避免 Web 界面断连。

开发者设置 (Developer Settings / developer)

• 自定义防火墙规则 (firewall_custom): 在 LuCI 的「开发者设置」标签页中直接编辑的文本框，内容保存到 /etc/openclash/custom/openclash_custom_firewall_rules.sh。该脚本不需要定义任何函数——它是一个命令式 Shell 脚本，在所有 OpenClash 内置防火墙规则添加完毕后被直接执行（chmod +x 后运行）。可以在脚本中直接写 iptables -I ... 或 nft add rule ... 命令来追加自定义防火墙规则。
• 实现细节: set_firewall() 函数在所有内置的 REDIRECT/TPROXY/TUN/IPv6/访问控制规则建立完毕后，检查此文件是否存在，若存在则 chmod +x 并执行。由于它在所有内置规则之后运行，自定义规则可以引用 OpenClash 已创建的 nftables 链和 set。每次 OpenClash 启动或防火墙重载时都会重新执行此脚本。

调试日志 (Debug Logs / debug)

此标签页提供三种独立的诊断工具，位于「插件设置 → 调试日志」标签页：

工具	功能	触发方式	后端路由
连接测试 (Connection Test)	测试指定域名是否可达	输入域名 + 点击「Click to Test」(点击测试) 按钮	/diag_connection
DNS 测试 (DNS Test)	测试 DNS 解析结果	输入域名 + 点击「Click to Test」(点击测试) 按钮	/diag_dns
生成调试日志 (Generate Logs)	收集完整诊断报告	点击「Click to Generate」(点击生成) 按钮	/gen_debug_logs

连接测试实现细节: 前端先尝试 Image 加载 https://{domain}/favicon.ico 作为快速预检，若失败则回退到后端 /diag_connection 调用。

调试日志实现细节: openclash_debug.sh 使用文件锁防止并发，收集以下 20+ 个章节并输出到 /tmp/openclash_debug.log：

1. 系统信息（固件版本、内核版本、CPU 架构）
2. 依赖包检查（dnsmasq-full、bash、curl、ruby、ruby-yaml、kmod-tun、kmod-inet-diag、kmod-nft-tproxy 或 kmod-ipt-tproxy 等）
3. 内核运行状态（PID、运行用户、Meta 内核版本 clash_meta -v）
4. 插件设置（所有 UCI 运行模式/代理/DNS/IPv6 配置值）
5. 覆写模块设置（uci show openclash.@overwrite[0]）
6. 自定义规则文件内容
7. 当前 Mihomo YAML 配置（过滤掉 proxies/proxy-providers/secret 保护隐私）
8. 自定义覆写/防火墙脚本内容
9. 完整的 iptables-save dump（nat/mangle/filter 表，含 IPv6）
10. 完整的 nftables 规则（inet fw4 中所有链）
11. ipset 状态
12. 路由表（IPv4/IPv6 route、策略路由表 354、ip rule）
13. TUN 设备状态
14. 端口占用（netstat）
15. DNS 解析测试（nslookup + Mihomo 内核 DNS 测试）
16. 网络连通性测试（curl www.baidu.com + GitHub）
17. 最近运行日志（临时切换日志级别到 debug 后采集 100 行）
18. 活动连接列表（通过 Mihomo API 获取）
19. 隐私处理（IPv4 最后一字节和 IPv6 后半部分模糊化）

oixCloud (oixcloud)

• 第三方云服务，需账号密码登录
• oix_email / oix_passwd → oix_login 获取 token
• oix_checkin — 自动签到 (需 token)
• 登录后自动获取 Oix 专属核心和订阅

---

2.10 来源流量访问控制 (Source Traffic Bypass / lan_ac_traffic)

页面位置：插件设置页面底部（不属于任何标签页，以独立的 TypedSection 形式存在） 生效路径：通过 init.d/openclash 的 firewall_lan_ac_traffic() 函数在代理链 position 0 插入规则， 优先级高于所有其他代理规则。配置通过 config_foreach firewall_lan_ac_traffic "lan_ac_traffic" 遍历执行。

AI 行为指引：当用户询问「如何让某个接口（如 WireGuard/Docker 网桥）的流量完全绕过内核」、 「如何按用户 UID 绕过代理」、「如何精细控制特定来源流量」时，AI 应告知用户使用此功能， 并结合下方字段表和防火墙逻辑给出具体配置方案。涉及底层实现时查阅 OpenClash 源码 中 init.d/openclash 的 firewall_lan_ac_traffic() 函数。

lan_ac_traffic TypedSection

支持按七维度组合匹配流量，匹配后执行 target 动作：

字段	UCI Key	类型	说明
备注	comment	Value	规则说明
启用	enabled	Flag	默认 1
内部地址	src_ip	Value	IP/CIDR/localnetwork（匹配本地网络地址集 @localnetwork）
内部端口	src_port	Value	端口或范围，如 5000 或 1234-2345
协议	proto	ListValue	both(默认)/tcp/udp
地址族	family	ListValue	both(默认)/ipv4/ipv6
接口	interface	ListValue	网络接口名（如 eth1、wg0、docker0），匹配从该接口进入的流量
用户	user	ListValue	Linux UID，匹配该用户进程发出的流量（仅 OUTPUT 链生效）
DSCP	dscp	Value	0-63，匹配 IP 头 DSCP 标记值
目标	target	ListValue	RETURN(默认，跳过代理走直连) / ACCEPT(放行) / DROP(静默丢弃)

防火墙工作逻辑（基于 init.d/openclash → firewall_lan_ac_traffic() 源码）

规则生成流程：

config_foreach firewall_lan_ac_traffic "lan_ac_traffic"
  → 读取每个启用的 section 的 UCI 字段
  → 构建 nftables/iptables 匹配条件
  → 按运行模式 + 协议 + 地址族插入对应链的 position 0

fw4 (nftables) 规则插入的目标链（按运行模式区分）：

运行模式	TCP 进入	TCP 发出	UDP 进入	UDP 发出	旁路由 SNAT
非 TUN（redir-host/fake-ip）	openclash	openclash_output	openclash_mangle	openclash_mangle_output	openclash_post
TUN 模式	openclash_mangle	openclash_mangle_output	openclash_mangle	openclash_mangle_output	openclash_post
IPv6（ipv6_enable=1）	openclash_v6	openclash_output_v6	openclash_mangle_v6	openclash_mangle_output_v6	openclash_post_v6

关键匹配逻辑：

• src_ip=localnetwork：特殊值，nftables 端展开为 ip saddr @localnetwork（匹配整个本地网络地址集），iptables 端使用 -m set --match-set localnetwork src
• 接口匹配：nftables 用 iifname "接口名"，iptables 用 -i 接口名
• 用户匹配：nftables 用 meta skuid UID（仅 OUTPUT 链生效），iptables 用 -m owner --uid-owner UID
• DSCP 匹配：nftables 用 ip dscp 值，iptables 需 dscp 模块（不可用时跳过并输出警告：iptables DSCP module not available）
• Fake-IP 排除：所有规则自动排除 Fake-IP 地址段 ip daddr != {198.18.0.0/16}，避免影响 Fake-IP 内部映射
• drop→return 转换：当 target=DROP 时，nftables 实际动作为 return（因 mangle 链不支持 drop），iptables 保持 DROP

常见场景示例：

需求	规则配置
某接口（如 WireGuard）流量不走代理	interface=wg0, target=RETURN
Docker 网桥流量绕过内核	interface=docker0, target=RETURN
某设备所有流量不走代理	src_ip=192.168.1.100/32, target=RETURN
某端口范围的 TCP 流量不走代理（BT 端口）	src_port=6881-6889, proto=tcp, target=RETURN
某用户进程流量完全丢弃	user=65534, target=DROP
本地网络所有 UDP 流量直连	src_ip=localnetwork, proto=udp, target=RETURN

---

第三部分：覆写设置页面 (Overwrite Settings / config-overwrite)

UCI Section: openclash.config_overwrite 此页面用于覆写订阅配置中的特定字段，设置后通过 openclash.sh 脚本注入到生成的 YAML 中

实现总览

 UCI config_overwrite 写入
        │
        ▼
 yml_change.sh (优先级最高)         yml_rules_change.sh
 ├─ 端口、模式、DNS、TUN            ├─ tolerance / url-test 覆写
 ├─ Sniffer、认证、Meta             ├─ GitHub CDN 替换
 ├─ GEO、Smart、NTP                 ├─ enable_rule_proxy → BT/P2P 直连
 └─ 自定义 DNS servers              └─ 自定义规则注入

关键机制: yml_change.sh 以 YAML 深度合并 + 覆盖的方式修改配置，覆写优先级高于订阅原始值。 yml_rules_change.sh 使用 Ruby YAML 库操作策略组、规则、URL-Test 参数和规则提供者地址。 两个脚本在 start_service() 流程中先于核心启动执行。

3.1 常规设置标签页 (General Settings / settings)

interface_name — 绑定网络接口 (Bind Network Interface)

• UCI: openclash.@config_overwrite[0].interface_name
• 默认: 0 (禁用)
• 说明: 绑定核心出站流量到指定网络接口
• Mihomo 对应: interface-name
• 实现细节: yml_change.sh 将值写入 YAML interface-name。Mihomo 内核所有出站连接（代理节点连接、DNS 查询、GEO 下载）都通过此接口发送。用于多 WAN 环境指定出口。

tolerance — URL-Test 策略组切换灵敏度 (URL-Test Group Tolerance)

• UCI: openclash.@config_overwrite[0].tolerance
• 默认: 0 (禁用)
• 说明: 当前代理与新最快代理的延迟差值大于此值时自动切换。0 表示关闭
• Mihomo 对应: proxy-groups 中 url-test 类型的 tolerance 字段
• 实现细节: yml_rules_change.sh 遍历所有 type: url-test 的策略组，设置其 tolerance 值。Mihomo 内核定期测试组内所有节点延迟，当当前选中节点的延迟与新最快节点的延迟差 > tolerance 时自动切换。设为 0 则每次测试都切换到最快节点。

urltest_address_mod — 测速（连通性）地址修改 (URL-Test Address Modify)

• UCI: openclash.@config_overwrite[0].urltest_address_mod
• 默认: 0 (禁用)
• 预设: http://www.gstatic.com/generate_204 / http://cp.cloudflare.com/ / https://cp.cloudflare.com/ / http://captive.apple.com/
• Mihomo 对应: proxy-groups 中 url-test 类型的 url 字段
• 实现细节: yml_rules_change.sh 替换所有 url-test 策略组的测试 URL。Mihomo 内核周期性向此 URL 发送 HTTP HEAD/GET 请求测量延迟，作为节点选择的依据。

github_address_mod — Github 地址修改 (Github Address Modify)

• UCI: openclash.@config_overwrite[0].github_address_mod
• 说明: 通过代理/CDN 加速 GitHub 文件下载。强烈推荐在 OpenClash 启动前就设置好此项，因为插件和内核更新、GEO 数据库下载、Dashboard 下载均依赖 GitHub 连通性。推荐优先尝试 https://testingcf.jsdelivr.net/（jsDelivr 的 Cloudflare CDN），如不可用再切换其他 CDN
• 预设: 多个 jsdelivr CDN 地址（testingcf / fastly 等）
• 实现细节: yml_rules_change.sh 用 Ruby 正则 /raw\.githubusercontent\.com/ 匹配所有 rule-providers 和 proxy-providers 的 url 字段，将域名替换为 CDN 地址。解决中国大陆无法访问 GitHub 的问题。
• 已知限制: github_address_mod 仅对 rule-providers 和 proxy-providers 的 URL 生效。openclash_download_dashboard.sh（Dashboard 下载）和 openclash_geo.sh（GEO 更新）不使用此变量，这些脚本的下载 URL 为硬编码的 GitHub 直连地址。如需对 Dashboard/GEO 下载使用 CDN，可通过覆写模块的 [General] 段设置 DOWNLOAD_FILE 或使用自定义规则使相关域名直连。

log_level — 日志等级 (Log Level)

• UCI: openclash.@config_overwrite[0].log_level
• 可选值: 0(禁用) / info / warning / error / debug / silent
• Mihomo 对应: log-level
• 0 表示不覆写，使用订阅原有设置
• 实现细节: yml_change.sh 将值写入 YAML log-level。Mihomo 内核根据级别过滤日志输出：silent(无输出) → error(仅错误) → warning(+警告) → info(+一般信息) → debug(+调试详情)。

端口设置

端口用途	UCI Key	默认	Mihomo 对应
DNS 端口 (DNS Port)	dns_port	7874	dns.listen
流量转发端口 (Redir Port)	proxy_port	7892	listeners.redirect (仅 TCP)
TProxy 端口 (TProxy Port)	tproxy_port	7895	listeners.tproxy (TCP+UDP)
HTTP(S) 代理端口 (HTTP(S) Port)	http_port	7890	listeners.http
SOCKS5 代理端口 (SOCKS5 Port)	socks_port	7891	listeners.socks
HTTP(S)&SOCKS5 混合代理端口 (Mixed Port)	mixed_port	7893	listeners.mixed (HTTP+SOCKS)

• 端口实现细节: yml_change.sh 将所有端口写入 YAML 对应字段。Mihomo 内核启动时在这些端口上创建监听器，接受来自 iptables/nftables 重定向的流量或客户端直连的代理请求。修改后需重启核心。

3.2 DNS 设置标签页 (DNS Settings / dns)

生效路径: DNS 覆写通过 yml_change.sh 的 yml_dns_custom() 函数处理， 构建完整的 dns: YAML 段并合并到运行配置。

AI 行为指引: 当用户询问 DNS 配置问题时（如"如何配置 DoH/DoT"、"nameserver-policy 怎么写"、"hosts 格式是什么"、 "fallback-filter 各字段含义"等），AI 应查阅 Mihomo DNS 配置文档 了解各字段的详细含义和用法，涉及 OpenClash 侧 DNS 覆写实现时查阅 OpenClash 源码 中 yml_change.sh 的 yml_dns_custom() 函数， 然后结合 OpenClash 覆写模块的操作方式告知用户如何配置，而非仅给出文档链接。

enable_custom_dns — 自定义上游 DNS 服务器 (Custom DNS Setting)

• UCI: openclash.@config_overwrite[0].enable_custom_dns
• 默认: 0
• 说明: 开启后将通过 TypedSection dns_servers 中的配置覆写 YAML 的 dns 段
• 最佳实践: 在 Fake-IP 模式下推荐以下配置策略：① Nameserver 仅负责直连类域名的解析（使用运营商 DNS 或国内 DoH 如 AliDNS/DNSPod）；② 取消所有 Fallback 服务器——Fake-IP 模式下若无 Fallback，非直连域名的解析请求将交由远端（代理节点侧）完成，解析结果与实际出站链路一致，可获得更一致的 CDN 命中并防止 DNS 泄露；③ 若出站侧解析不可用（罕见），可启用 Fallback 作为兜底并同时开启「遵循规则」功能。不建议套娃其他 DNS 插件（如 MosDNS/SmartDNS/AdGuardHome），多插件叠加会引入缓存一致性问题、增加内网解析延迟，且破坏 Mihomo 向客户端传递的 TTL 值
• 实现细节: 开启后 yml_dns_custom() 遍历所有 dns_servers 条目，按 group 分类（nameserver/fallback/default）构建 DNS 服务器列表，通过 Ruby YAML 合并写入 dns.nameserver、dns.fallback、dns.default-nameserver。

enable_respect_rules — 遵守路由规则 (Enable Respect Rules)

• UCI: openclash.@config_overwrite[0].enable_respect_rules
• 默认: 0
• Mihomo 对应: dns.respect-rules
• 说明: DNS 连接是否遵守 YAML 中的路由规则
• 实现细节: 写入 YAML dns.respect-rules: true。Mihomo 内核的 DNS 解析器发出的连接将经过 rules 规则引擎匹配——意味着 DNS 查询本身也会被代理（通过匹配的代理节点发出），防止 DNS 泄露。需要配合 proxy-server-nameserver 防止鸡生蛋问题。

append_wan_dns — 附加上游 DNS (Append WAN DNS)

• UCI: openclash.@config_overwrite[0].append_wan_dns
• 默认: 1
• 说明: 将 WAN 口自动分配的运营商 DNS 和网关 IP 追加到 nameserver 列表。主路由拨号环境推荐启用：运营商 DNS 对直连类域名的解析延迟通常最低（1-2ms），CDN 命中更接近实际链路，省去手动配置的麻烦。若使用第三方加密 DNS（如 DoH/DoT），则需禁用此项并在 NameServer 中手动添加服务器
• 实现细节: sys_dns_append() 调用 openclash_get_network.lua 获取 WAN 口的 DNS 和网关地址，追加到 /tmp/yaml_config.namedns.yaml，后续被合并到 YAML dns.nameserver。支持 dhcp:// 协议直接从 DHCP 接口获取 DNS。

fakeip_range — Fake-IP 范围 (IPv4) (Fake-IP Range)

• UCI: openclash.@config_overwrite[0].fakeip_range
• 默认: 0 (禁用)
• 预设: 198.18.0.1/16 (标准 Fake-IP 段)
• Mihomo 对应: dns.fake-ip-range
• 仅: Fake-IP 模式显示
• 实现细节: 写入 YAML dns.fake-ip-range。Mihomo 在 Fake-IP 模式下，将 DNS 查询的域名映射到此 CIDR 段中的虚拟 IP。应用连接到虚拟 IP 时内核通过路由表将流量导向 Clash，Clash 根据映射表还原真实域名后进行规则匹配。

store_fakeip — 持久化 Fake-IP (Store Fake-IP)

• UCI: openclash.@config_overwrite[0].store_fakeip
• 默认: 1
• Mihomo 对应: profile.store-fake-ip
• 说明: 缓存 Fake-IP DNS 解析记录到文件，启动后加速响应
• 实现细节: 写入 YAML profile.store-fake-ip: true。Mihomo 将域名→Fake-IP 映射持久化到 cache.db 文件，重启后恢复映射，避免重启后所有域名需要重新解析。

custom_fallback_filter — 自定义 Fallback-Filter (Custom Fallback Filter)

• UCI: openclash.@config_overwrite[0].custom_fallback_filter
• 默认: 0
• 说明: 配置 DNS 防污染回退过滤器
• 配置文件: /etc/openclash/custom/openclash_custom_fallback_filter.yaml
• Mihomo 对应: dns.fallback-filter 段

Fallback-Filter 格式示例:

geoip: true
geoip-code: CN
geosite:
  - gfw
domain:
  - '+.google.com'

custom_fakeip_filter — 自定义 Fake-IP-Filter (Custom Fake-IP Filter)

• UCI: openclash.@config_overwrite[0].custom_fakeip_filter
• 默认: 0
• 仅: Fake-IP 模式显示
• Mihomo 对应: dns.fake-ip-filter

custom_fakeip_filter_mode — Fake-IP-Filter 模式 (Custom Fake-IP Filter Mode)

• UCI: openclash.@config_overwrite[0].custom_fakeip_filter_mode
• 可选: blacklist / whitelist / rule
• 默认: blacklist
• 说明:
  • blacklist: 匹配成功的域名不返回 Fake-IP (黑名单)
  • whitelist: 只有匹配成功的域名返回 Fake-IP (白名单)
  • rule: 规则模式，支持 GEOSITE、RuleSet、DOMAIN* 等语法
• Mihomo 对应: dns.fake-ip-filter-mode

域名过滤文件 (custom_fake_filter)

• 文件: /etc/openclash/custom/openclash_custom_fake_filter.list
• 格式: 每行一个域名通配符，如 *.lan, +.example.com

custom_name_policy — 自定义 Nameserver-Policy (Custom Name Policy)

• UCI: openclash.@config_overwrite[0].custom_name_policy
• 文件: /etc/openclash/custom/openclash_custom_domain_dns_policy.list
• Mihomo 对应: dns.nameserver-policy
• 格式: 每行 域名=DNS服务器组 或使用 geosite/rule-set

custom_proxy_server_policy — 自定义 Proxy-Server-Nameserver-Policy (Custom Proxy Server Policy)

• UCI: openclash.@config_overwrite[0].custom_proxy_server_policy
• 文件: /etc/openclash/custom/openclash_custom_proxy_server_dns_policy.list
• Mihomo 对应: dns.proxy-server-nameserver-policy
• 说明: 仅用于解析代理节点域名的 DNS 策略

custom_host — 自定义 Hosts (Custom Hosts)

• UCI: openclash.@config_overwrite[0].custom_host
• 文件: /etc/openclash/custom/openclash_custom_hosts.list
• Mihomo 对应: dns.hosts

DNS 服务器列表 (dns_servers TypedSection)

AI 行为指引: 当用户询问 DNS 服务器类型（如"DoH 和 DoT 有什么区别"、"quic 类型怎么用"、 "dns 服务器的 #proxy 和 #RULES 后缀是什么意思"）时，AI 应查阅 Mihomo DNS 类型文档 了解每种 DNS 协议的使用方法和参数， 涉及 OpenClash 侧实现时查阅 OpenClash 源码 中 yml_change.sh 的 DNS 相关逻辑，然后告知用户具体的配置写法。

用户可以添加多条 DNS 服务器记录，每条包含：

字段	UCI Key	说明
启用	enabled	Flag，默认 1
分组	group	nameserver(默认DNS) / fallback(后备DNS) / default(默认DNS)
地址	ip	DNS 服务器 IP
端口	port	端口号
类型	type	udp / tcp / tls / https / quic
禁用 IPv6	disable_ipv6	丢弃 AAAA 记录

Mihomo YAML 格式示例:

dns:
  nameserver:
    - 223.5.5.5
    - tls://8.8.4.4
  fallback:
    - tls://1.1.1.1

3.3 Meta 设置标签页 (Meta Settings / meta)

生效路径: Meta 选项通过 yml_change.sh 写入 YAML，所有选项在 Mihomo 启动时加载生效。 部分选项（sniffer）支持运行时通过 API 热修改。

AI 行为指引: 当用户询问 Meta 相关问题（如"tcp-concurrent 和 unified-delay 有什么区别"、 "find-process-mode 各模式的含义"、"sniffer 如何自定义"、"geodata-loader 选哪个"）， AI 应查阅 Mihomo 全局配置文档 和 Mihomo Sniffer 文档 了解各选项的详细含义， 涉及 OpenClash 侧 Meta 选项注入实现时查阅 OpenClash 源码 中 yml_change.sh 的 sniffer/Meta 相关段，然后结合 OpenClash 的覆写设置操作路径告知用户。

enable_tcp_concurrent — 启用 TCP 并发 (Enable Tcp Concurrent)

• UCI: openclash.@config_overwrite[0].enable_tcp_concurrent
• 默认: 0
• Mihomo 对应: tcp-concurrent: true
• 说明: 同时使用 DNS 解析的所有 IP 地址发起连接，使用最先成功的连接
• 实现细节: yml_change.sh 写入 YAML tcp-concurrent: true。Mihomo 对每个目标域名解析出所有 IP 后，同时向所有 IP 发起 TCP 连接，使用第一个 TCP 握手成功的连接，丢弃其余。可大幅降低首次连接延迟，但会增加并发连接数。

enable_unified_delay — 启用统一延迟 (Enable Unified Delay)

• UCI: openclash.@config_overwrite[0].enable_unified_delay
• 默认: 0
• Mihomo 对应: unified-delay: true
• 说明: 消除连接握手等带来的不同类型节点延迟差异
• 实现细节: 写入 YAML unified-delay: true。Mihomo 在 URL-Test 延迟测量时计算 RTT（Round-Trip Time），而非简单的 TCP 握手时间 + HTTP 响应时间。这样 Shadowsocks、Trojan、VMess 等不同协议的节点延迟可公平比较。

find_process_mode — 启用进程规则 (Find Process Mode)

• UCI: openclash.@config_overwrite[0].find_process_mode
• 可选值: 0(禁用) / off / always / strict
• 默认: 0
• Mihomo 对应: find-process-mode
• 说明: 依赖 kmod-inet-diag 内核模块。路由器上推荐 off 以提升性能
• 实现细节: 写入 YAML find-process-mode。控制 Mihomo 是否通过 Netlink INET_DIAG 匹配每个连接的发起进程名（用于 PROCESS-NAME 规则）。路由器上设为 off 可避免内核模块依赖和性能开销。

enable_meta_sniffer — 启用流量（域名）探测 (Enable Sniffer)

• UCI: openclash.@config_overwrite[0].enable_meta_sniffer
• 默认: 1
• Mihomo 对应: sniffer.enable: true
• 说明: 防止域名代理和 DNS 劫持失败。通过嗅探 TLS/HTTP/QUIC 握手获取真实目标域名
• 实现细节: yml_change.sh 写入完整的 sniffer: YAML 段：
  • sniff.TLS.ports: [443, 8443] — 解析 TLS ClientHello 中的 SNI 字段获取域名
  • sniff.HTTP.ports: [80, 8080-8880] — 解析 HTTP Host 头获取域名
  • sniff.QUIC.ports: [443] — 解析 QUIC Initial 包中的 SNI
  • force-dns-mapping: true (仅 Redir-Host) — 对 DNS 解析过的 IP 强制嗅探
  • override-destination: true — 用嗅探到的域名覆盖连接目标，确保规则基于域名匹配
  • 预置 force-domain: [netflix, nflxvideo, amazonaws, media.dssott.com] — 强制嗅探流媒体
  • 预置 skip-domain: [Mijia Cloud, dlg.io.mi.com, oray.com, sunlogin.net, push.apple.com] — 跳过智能家居/推送

enable_meta_sniffer_pure_ip — 探测（嗅探）纯 IP 连接 (Forced Sniff Pure IP)

• UCI: openclash.@config_overwrite[0].enable_meta_sniffer_pure_ip
• 默认: 1
• Mihomo 对应: sniffer.parse-pure-ip: true
• 说明: 对所有未获取到域名的流量进行强制嗅探（如直接 IP 连接）

enable_meta_sniffer_custom — 自定义流量探测（嗅探）设置 (Custom Sniffer Settings)

• UCI: openclash.@config_overwrite[0].enable_meta_sniffer_custom
• 默认: 0
• 说明: 启用后将使用下方文本框中的自定义 sniffer YAML 配置替代默认嗅探设置

sniffer_custom — 自定义 Sniffer 文本框 (Sniffer Custom)

• UCI: openclash.@config_overwrite[0].sniffer_custom
• 存储: /etc/openclash/custom/openclash_custom_sniffer.yaml
• 说明: 多行 YAML 文本框，可自定义完整的 sniffer: 配置段。仅在 enable_meta_sniffer_custom=1 时生效

geodata_loader — Geodata 数据加载方式 (Geodata Loader)

• UCI: openclash.@config_overwrite[0].geodata_loader
• 可选值: 0(禁用) / memconservative / standard
• 默认: memconservative
• Mihomo 对应: geodata-loader
• 说明: memconservative 专为小内存设备优化的加载器（逐段读取），standard 为标准加载器（一次性加载到内存，速度快但占内存）

enable_geoip_dat — 启用 GeoIP Dat 版数据库 (Enable GeoIP Dat)

• UCI: openclash.@config_overwrite[0].enable_geoip_dat
• 默认: 0
• Mihomo 对应: geodata-mode: true
• 说明: 使用 Dat 格式替换 MMDB 格式 GeoIP 文件。Dat 文件较大需单独下载，可通过「GEO 数据库订阅」页面获取

global_ua — 全局 User-Agent (Global UA)

• UCI: openclash.@config_overwrite[0].global_ua
• 默认: 0 (禁用，使用系统默认 clash.meta)
• Mihomo 对应: global-ua
• 预设: clash-verge/v2.4.5 / clash.meta/1.19.20 / Clash
• 说明: 设置 Mihomo 下载外部资源（GEO 文件、规则集等）时使用的 User-Agent

Sniffer YAML 格式示例:

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, 8443]
  force-domain:
    - +.v2ex.com
  skip-domain:
    - Mijia Cloud

3.4 智能设置标签页 (Smart Settings / smart)

生效路径: Smart 策略是智能代理选择引擎，基于 LightGBM 机器学习模型。 yml_change.sh 将 Smart 训练数据收集配置写入 YAML（profile.smart-collector-size）， yml_rules_change.sh 负责将 url-test/load-balance 策略组类型转换为 type: smart 并设置 Smart 相关参数（uselightgbm、collectdata、sample-rate、policy-priority、prefer-asn）。 Smart 策略的运行时节点选择由 Mihomo 内核 Smart 模块内部处理，无需外部脚本干预。

AI 行为指引: 当用户询问 Smart 策略相关问题时（如"Smart 和 url-test 有什么区别"、"如何训练 Smart 模型"、 "prefer-asn 是什么"、"sample-rate 怎么设置"、"LGBM 模型如何自定义下载"），AI 应：

1. 首先查阅下方「智能设置标签页」中对应 UCI 选项的说明，给出 LuCI 操作路径（覆写设置 → 智能设置）
2. Smart 策略组是 Smart 核心源码独有的功能（上游 Mihomo 核心无此特性），所有实现细节均应查阅 Smart 核心源码：
   • 策略组节点选择逻辑 → adapter/outboundgroup/smart.go（selectProxies()、Unwrap()、InitSmart()）
   • LightGBM 模型加载/推理/数据收集 → component/smart/lightgbm/（lightgbm.go、collector.go、transform.go）
   • Smart 持久化存储与权重计算 → component/smart/cachefile.go、component/smart/weight.go
3. Smart 节点选择逻辑简述（adapter/outboundgroup/smart.go → selectProxies()）： ① 获取目标 IP/域名的 ASN 信息 → ② 优先检查用户手动选择的节点 → ③ 查持久化缓存 （boltDB 存储的历史最优结果）→ ④ 查预取缓存（周期性后台预计算）→ ⑤ 实时调用 store.GetBestProxyForTarget() 综合历史延迟、抖动、丢包率及 LightGBM 模型预测权重 计算最优节点 → ⑥ filterProxies() 按权重排序过滤。后台定时任务持续维护排名 （updateNodeRanking）、预取（runPrefetch）、稳定性检查（checkNodesStable）、 被封节点恢复检测（checkBlockedNodes）、主机状态检查（checkHostStatus）。
4. 关于"如何训练 Smart 模型"：用户如需自行训练模型（而非使用预训练模型），AI 应主动读取 Smart 核心源码 中 component/smart/lightgbm/ 目录， 了解并告知用户以下信息：
   • 数据来源：component/smart/lightgbm/collector.go — 开启 smart_collect 后核心会在 /etc/openclash/ 下生成 CSV 训练数据文件（含延迟、抖动、丢包率等特征；特征工程见 transform.go）
   • LightGBM 版本：查阅 go.mod 中 vernesong/leaves 依赖确认支持的 LightGBM 版本
   • 环境搭建：在 PC/服务器上安装对应版本的 LightGBM Python 包，准备训练环境
   • 训练脚本：参考 component/smart/lightgbm/ 中的特征处理与模型结构，为用户创建可运行的示例训练脚本（读取 CSV → 特征变换 → 训练 LightGBM → 导出 Model.bin）
   • 模型部署：训练完成后将 Model.bin 上传到可访问的 URL，通过 lgbm_custom_url 指定；或替换 /etc/openclash/Model.bin；模型加载与推理见 lightgbm.go 中的 WeightModel
   • 日常使用：大多数用户无需自行训练，开启 lgbm_auto_update 即可自动下载预训练模型 关键提醒：Smart 策略使用 LightGBM 模型进行节点质量预测，需要在配置文件中将策略组类型设为 smart 才能启用（通过 auto_smart_switch 自动转换或手动修改 YAML）。Smart 核心在运行时根据模型预测结果 和实时延迟数据综合选择最优节点，无需外部脚本干预。

auto_smart_switch — Smart 策略自动切换 (Smart Auto Switch)

• UCI: openclash.@config_overwrite[0].auto_smart_switch
• 默认: 0
• 说明: 自动将 url-test/load-balance 类型的策略组切换为 Smart 智能策略组
• 实现细节: yml_rules_change.sh 遍历所有策略组，将 type: url-test 或 type: load-balance 替换为 type: smart。Smart 策略组综合延迟、丢包率、历史表现等多维指标选择最优节点。

smart_policy_priority — 策略优先级 (Policy Priority)

• UCI: openclash.@config_overwrite[0].smart_policy_priority
• 格式: 策略名:系数;策略名:系数，如 Premium:0.9;SG:1.3
• 说明: <1 降低优先级，>1 提高优先级，默认权重为 1。支持正则和字符串匹配策略组名称

smart_prefer_asn — 优先 ASN 查询 (Smart Prefer ASN)

• UCI: openclash.@config_overwrite[0].smart_prefer_asn
• 默认: 0
• 说明: 强制查询并使用目标 ASN（自治系统号）信息，优先选择同一 ASN 的更稳定节点

smart_enable_lgbm — 启用 LightGBM 模型 (Enable LightGBM Model)

• UCI: openclash.@config_overwrite[0].smart_enable_lgbm
• 默认: 0
• 说明: 使用 LightGBM 机器学习模型预测节点权重
• 实现细节: yml_change.sh 配置 YAML 中的模型下载 URL 和更新间隔。openclash_lgbm.sh 定期下载训练好的 LightGBM 模型文件到 /etc/openclash/Model.bin（小闪存模式下为 /tmp/etc/openclash/Model.bin）。Mihomo Smart 模块加载模型后，根据节点历史延迟、抖动、丢包率等特征预测最优节点。

smart_collect — 收集训练数据 (Collectdata)

• UCI: openclash.@config_overwrite[0].smart_collect
• 默认: 0
• 说明: 收集延迟/抖动等数据供 LightGBM 模型训练

smart_collect_size — 数据收集文件大小 (Smart Collect Size)

• UCI: openclash.@config_overwrite[0].smart_collect_size
• 默认: 100 (MB)
• 依赖: smart_collect=1

smart_collect_rate — 数据采样率 (Smart Collect Rate)

• UCI: openclash.@config_overwrite[0].smart_collect_rate
• 默认: 1 (0-1)
• 依赖: smart_collect=1

lgbm_auto_update — 自动更新 LightGBM 模型 (LGBM Auto Update)

• UCI: openclash.@config_overwrite[0].lgbm_auto_update
• 默认: 0

lgbm_update_interval — 模型更新间隔 (LGBM Update Interval)

• UCI: openclash.@config_overwrite[0].lgbm_update_interval
• 默认: 72 (小时)
• 依赖: lgbm_auto_update=1

lgbm_custom_url — 自定义模型下载地址 (LGBM Custom URL)

• UCI: openclash.@config_overwrite[0].lgbm_custom_url
• 默认: https://github.com/vernesong/mihomo/releases/download/LightGBM-Model/Model.bin（轻量版）
• 可选: 中量版 (Model-middle.bin)、重量版 (Model-large.bin) — 模型越大预测越准确但占用更多内存
• 依赖: lgbm_auto_update=1

手动更新模型按钮

• 功能: 点击触发 openclash_lgbm.sh 立即下载最新模型并显示当前模型文件时间戳

刷新 Smart 缓存按钮

• 功能: 通过 Mihomo API POST /cache/smart/flush 清空 Smart 策略缓存，强制重新评估所有节点

---

3.5 规则设置标签页 (Rules Settings / rules)

此标签页用于管理自定义 Clash/Mihomo 路由规则。Mihomo 支持多种规则类型， 用户在 LuCI 文本框中编写规则时需遵循特定格式。

enable_rule_proxy — 仅代理命中规则流量 (Rule Match Proxy Mode)

• UCI: openclash.@config_overwrite[0].enable_rule_proxy
• 默认: 0
• 说明: 开启后向配置追加 PROCESS-NAME 和 DST-PORT 规则，仅允许匹配规则的流量走代理，其余流量（如 BT/P2P）直连

enable_custom_clash_rules — 自定义规则 (Custom Clash Rules)

• UCI: openclash.@config_overwrite[0].enable_custom_clash_rules
• 默认: 0
• 说明: 开启后将在运行配置的 rules: 段注入自定义规则文件中的内容

custom_rules — 优先规则编辑框 (Custom Rules Priority)

• UCI: openclash.@config_overwrite[0].custom_rules
• 存储: /etc/openclash/custom/openclash_custom_rules.list
• 格式: 每行一条 Mihomo 规则，插入到规则列表顶部（优先匹配）
• 依赖: enable_custom_clash_rules=1

custom_rules_2 — 扩展规则编辑框 (Custom Rules Extended)

• UCI: openclash.@config_overwrite[0].custom_rules_2
• 存储: /etc/openclash/custom/openclash_custom_rules_2.list
• 格式: 每行一条 Mihomo 规则，插入到规则列表底部
• 依赖: enable_custom_clash_rules=1

规则编写指南

当用户描述需求（如"我想让某个域名走代理"、"禁止某个 IP 走代理"）时，AI 应查阅 Mihomo 路由规则文档 了解各规则类型的作用，涉及规则注入实现时查阅 OpenClash 源码 中 yml_rules_change.sh 和 custom_rules*.list 的处理逻辑，然后告知用户具体的规则写法。

Mihomo 支持的规则类型速查:

规则类型	格式	用途	示例
DOMAIN	DOMAIN,域名,策略	精确匹配域名	DOMAIN,www.google.com,Proxy
DOMAIN-SUFFIX	DOMAIN-SUFFIX,域名后缀,策略	匹配域名后缀（含所有子域名）	DOMAIN-SUFFIX,google.com,Proxy
DOMAIN-KEYWORD	DOMAIN-KEYWORD,关键词,策略	匹配域名含关键词	DOMAIN-KEYWORD,youtube,Proxy
DOMAIN-REGEX	DOMAIN-REGEX,正则,策略	域名正则匹配	DOMAIN-REGEX,^api\.example\.com$,Proxy
GEOSITE	GEOSITE,类别,策略	按 GeoSite 类别匹配域名	GEOSITE,netflix,NETFLIX
GEOIP	GEOIP,国家代码,策略	按 GeoIP 国家匹配 IP	GEOIP,CN,DIRECT
IP-CIDR	IP-CIDR,IP/掩码,策略	IP 段匹配	IP-CIDR,10.0.0.0/8,DIRECT
IP-CIDR6	IP-CIDR6,IPv6/掩码,策略	IPv6 段匹配	IP-CIDR6,::1/128,DIRECT
IP-ASN	IP-ASN,ASN号,策略	自治系统号匹配	IP-ASN,13335,Proxy
RULE-SET	RULE-SET,规则集名,策略	引用 rule-provider 规则集	RULE-SET,reject,REJECT
PROCESS-NAME	PROCESS-NAME,进程名,策略	按进程名匹配	PROCESS-NAME,aria2c,DIRECT
DST-PORT	DST-PORT,端口,策略	目标端口匹配	DST-PORT,80,Proxy
SRC-PORT	SRC-PORT,端口,策略	源端口匹配	SRC-PORT,8080,DIRECT
SRC-IP-CIDR	SRC-IP-CIDR,IP/掩码,策略	源 IP 段匹配	SRC-IP-CIDR,192.168.1.0/24,DIRECT
MATCH	MATCH,策略	兜底匹配所有流量	MATCH,Proxy

可用策略目标: DIRECT(直连)、Proxy(走默认代理组)、REJECT(拒绝)、REJECT-DROP(静默丢弃)、GLOBAL(走全局组)、任意自定义策略组名称

编写格式: 不区分大小写，逗号分隔。每行一条规则。规则按顺序从上到下匹配，命中后不再继续。

常见需求 → 规则示例:

用户需求	规则写法
Google 走代理	DOMAIN-SUFFIX,google.com,Proxy
国内域名直连	GEOSITE,cn,DIRECT
Netflix 走专用策略组	GEOSITE,netflix,NETFLIX
禁止访问某域名	DOMAIN-SUFFIX,badsite.com,REJECT
BT 下载直连	PROCESS-NAME,qbittorrent,DIRECT
特定 IP 段直连	IP-CIDR,192.168.0.0/16,DIRECT
GitHub 直连加速	DOMAIN-SUFFIX,github.com,DIRECT
所有流量走代理	MATCH,Proxy
排除某设备走代理	SRC-IP-CIDR,192.168.1.100/32,DIRECT

进阶规则类型（如 AND/OR/NOT 逻辑规则、SUB-RULE 子规则等）请查阅 Mihomo 路由规则文档。

---

3.6 认证设置 (Authentication)

位于常规设置标签页中，为 SOCKS/HTTP/Mixed 代理添加用户认证：

字段	UCI Key	说明
启用	enabled	Flag, 默认 1
用户名	username	代理认证用户名
密码	password	代理认证密码

Mihomo 对应: authentication 列表，格式 ["user:pass"]

---

第四部分：配置订阅页面 (Config Subscribe / config-subscribe)

UCI Section: openclash.config_subscribe (多条)

AI 行为指引: 当用户询问订阅相关问题（如"如何过滤节点"、"订阅转换怎么用"、"订阅 URL 格式不对怎么办"、 "keyword 和 ex_keyword 的区别"、"Age 加密是什么"），AI 应查阅 Mihomo 代理协议文档 了解节点名称的命名规范和常见格式，涉及订阅处理实现细节时查阅 OpenClash 源码 中 openclash.sh 的 sub_info_get()、config_cus_up()、server_key_match() 等函数， 然后告知用户具体的配置方法。对于订阅转换后端问题， 告知用户转换后端的地址格式和模板 URL 的作用。

实现总览

 Cron / Web UI「更新配置」
        │
        ▼
 openclash.sh (订阅更新主脚本)
        │
        ├─ config_download()     → curl 下载订阅 URL (支持代理/直连回退)
        ├─ sub_convert           → 可选: 发送到订阅转换后端
        ├─ config_cus_up()       → Ruby YAML 解析 + 节点关键字过滤/排除
        ├─ config_test()         → clash -t 验证 YAML 语法
        └─ config_su_check()     → 新旧对比，有更新则替换 + 标记重启

核心流程 (openclash.sh 中的 sub_info_get()):

1. 遍历所有启用的 config_subscribe 条目
2. 对每条订阅构建下载 URL（添加 custom_params、设置 sub_ua）
3. 如果设置了 sub_convert，将 URL 发到转换后端获取处理后的配置
4. 如果设置了 secret_key (Age 加密)，先用 age 解密
5. 用 Ruby YAML 解析订阅配置 → 获取所有代理节点
6. 根据 keyword / ex_keyword 正则匹配过滤节点：
   • & = AND: 节点名必须同时包含所有关键字
   • | = OR: 节点名包含任一关键字即保留
7. 将过滤后的节点合并到当前配置的 proxies 和 proxy-groups 中
8. 写入 /etc/openclash/config/<name>.yaml，标记核心需重启

关键字匹配实现 (server_key_match()): 将用户输入的关键字转换为 Ruby 正则表达式。& 分隔的转为正向预查链 (?=.*kw1)(?=.*kw2)，| 分隔的转为择一匹配 (kw1|kw2)。

自动更新 (Auto Update)

选项	UCI Key	说明
自动更新 (Auto Update)	auto_update	Flag，默认 0
更新模式	config_auto_update_mode	0=预约模式(指定周几几点), 1=循环模式(每隔N分钟)
更新日 (Update Time Every Week)	config_update_week_time	*=每天 (Every Day), 1=周一, …, 0=周日
更新时间 (Update time every day)	auto_update_time	0-23 点
更新间隔/分钟 (Update Interval min)	config_update_interval	仅循环模式，默认 60

每条订阅 (config_subscribe TypedSection)

字段	用途
订阅名称 (Config Alias)	name
订阅地址 (Subscribe Address)	address
User-Agent (UA)	sub_ua
在线订阅转换 (Subscribe Convert Online)	sub_convert
订阅转换模板 (Template Name)	sub_template
筛选节点 (Keyword Match)	keyword
排除节点 (Exclude Keyword Match)	ex_keyword
自定义参数 (Custom Params)	custom_params
Age 加密密钥 (Secret Key)	secret_key

关键字格式: 使用 & 表示 AND (同时满足)，使用 | 表示 OR

• 例：香港&01 → 节点名同时包含"香港"和"01"
• 例：香港|台湾 → 节点名包含"香港"或"台湾"

---

第五部分：配置管理页面 (Config Manage / config)

LuCI 路径: 服务 → OpenClash → 配置管理 (顺序第 80) UCI 映射: openclash.config.config_path

实现总览

配置管理页面是一个多功能综合页面，提供配置文件的上传、切换、编辑、重命名、删除以及提供商文件管理功能。

核心功能区块:

区块	功能	后端路由
文件上传 (Upload)	上传配置文件、代理/规则提供商、核心二进制、备份恢复	/upload_config + file_type 参数区分
配置文件列表	查看/切换/编辑/重命名/复制/下载/删除配置	/switch_config、/config_file_list、/config_file_save 等
提供商文件管理	跳转到代理提供商和规则提供商管理子页	跳转链接
配置文件编辑器	双栏 YAML 编辑器（左侧可编辑用户配置，右侧只读默认模板）	/config_file_read + /config_file_save

5.1 文件上传

上传类型	file_type 值	目标目录	说明
配置文件 (Config)	config	/etc/openclash/config/	.yaml/.yml 格式，上传后自动设为当前启用配置
代理集文件 (Proxy Provider File)	proxy-provider	/etc/openclash/proxy_provider/	订阅中 proxy-providers 的节点文件
规则集文件 (Rule Provider File)	rule-provider	/etc/openclash/rule_provider/	订阅中 rule-providers 的规则文件
内核文件 (Core File)	clash_meta	/etc/openclash/core/	支持 .tar.gz/.gz 格式自动解压，chmod 4755
备份恢复	backup-file	恢复到 /etc/config/openclash	上传备份并恢复 UCI 配置

5.2 配置文件列表

操作	功能	说明
SwiTch (切换)	切换启用配置	修改 config_path UCI + commit，自动重启核心
Edit (编辑)	在线编辑配置	跳转到双栏 YAML 编辑器
Rename (重命名)	重命名	输入新名称，mv 重命名文件
Copy (复制配置)	复制配置	生成 <文件名>(N).yaml 副本
Download (下载配置)	下载配置文件	HTTP 下载原始配置文件
Download Run (下载运行配置)	下载运行时配置	下载 /etc/openclash/<name>（经脚本处理后的实际运行配置）
Remove (移除)	删除配置	删除 YAML 文件 + 历史缓存 /etc/openclash/history/<name>.db + 运行时配置，自动切换到其他配置

5.3 配置文件编辑器

双栏 YAML 编辑器：

• 左栏 (可编辑): 读写当前 config_path 指向的配置，保存时自动 \r\n → \n 转换
• 右栏 (只读): 展示运行时配置 /etc/openclash/<name> 或默认模板 /usr/share/openclash/res/default.yaml
• 操作按钮: Commit (保存配置 (Commit Settings))、Create (新建配置)、Apply (应用配置 (Apply Settings))
• 快捷键: F10 diff 控制、F11 全屏模式

5.4 提供商子页面

通过配置管理页面可跳转到以下子页面（独立 CBI 页面）：

• servers — 代理节点管理（编辑/新增/删除节点）
• servers-config — 节点配置编辑器
• groups-config — 策略组配置编辑器
• proxy-provider-config — 代理提供商配置
• proxy-provider-file-manage — 代理提供商文件管理
• rule-providers-file-manage — 规则提供商文件管理

---

第六部分：运行日志页面 (Server Logs / log)

LuCI 路径: 服务 → OpenClash → 运行日志 (顺序第 90) UCI 映射: openclash.openclash.clog

实现总览

运行日志页面是一个双标签页的日志查看器。页面布局包含以下区域：

标签页 1 — OpenClash Log (默认激活)：展示 OpenClash 插件自身日志（Shell/Ruby/Lua 脚本输出），通过 XHR 轮询 (/refresh_log) 每秒刷新。

标签页 2 — Core Log (可切换)：展示 Mihomo 内核实时日志，通过 WebSocket 连接到内核 API (/logs?token=...&level=...)。该标签页内嵌 5 个日志等级单选按钮：

按钮	功能	后端操作
Info (信息)	默认等级，显示一般信息及以上	GET /log_level → 设置 WebSocket level
Warning (警告)	只显示警告及以上	GET /switch_log + WebSocket 重连
Error (错误)	只显示错误及以上	同上
Debug (调试)	显示所有调试信息	同上
Silent (静默)	静默模式，不显示内核日志	同上

底部操作按钮栏（两个标签页共用）：

按钮	功能	后端操作
Stop Refresh (停止刷新)	暂停日志刷新（XHR 轮询 + WebSocket 均停止）	停止 poll_log() 和 coreLogWebSocketStop()
Start Refresh (开始刷新)	恢复日志刷新	重新启动轮询和 WebSocket
Clean (清理日志)	清空日志文本框	GET /del_log
Download Log (下载日志)	下载完整日志文件（OC 日志 + Core 日志合并）	前端拼接下载

日志来源: OpenClash 日志由后端将 UCI clog 字段内容写入 CodeMirror 日志编辑器。内核日志通过 WebSocket 实时推送到前端 textarea#core_log。

附加组件: 页面同时加载 openclash/toolbar_show（配置切换工具栏：下拉选择当前配置文件 + Switch 按钮）和 openclash/config_editor（页面内嵌 CodeMirror 编辑器，预加载 CodeMirror CSS/JS 资源并通过全局 merge_editor() 函数对外开放合并视图功能，非日志渲染用途，仅作文件编辑功能复用）。

注意: 如需修改 OpenClash 自身日志级别，请在「覆写设置 → 常规设置」中调整 log_level。Core Log 标签页内可直接切换内核日志等级。

---

第七部分：常见需求 → 操作映射

当用户说"我想实现XX"时，AI 应推荐以下选项组合

用户需求	需启用/设置的选项	位置
所有设备都能翻墙	en_mode=redir-host/fake-ip (默认已配好)	插件设置→模式设置
某台设备不走代理	lan_ac_mode=0 (黑名单模式 (Black List Mode)) + lan_ac_black_ips (不走代理的局域网设备 IP) 添加该设备IP	插件设置→黑白名单
某个接口流量绕过内核	插件设置页面底部「来源流量访问控制」添加规则：interface=接口名, target=RETURN	插件设置
仅某台设备走代理	lan_ac_mode=1 (白名单模式 (White List Mode)) + lan_ac_white_ips (走代理的局域网设备 IP) 添加该设备IP	插件设置→黑白名单
禁止 BT 下载走代理	common_ports (仅允许常用端口流量) 设为预设常用端口	插件设置→流量控制
国内网站直连加速	china_ip_route=1 (绕过中国大陆 (Bypass Mainland China))	插件设置→流量控制
看 Netflix/Disney+	stream_auto_select=1 + 对应服务子选项	插件设置→流媒体增强
路由器自身走代理	router_self_proxy=1 (本机代理)	插件设置→流量控制
路由器自身不走代理	router_self_proxy=0 (本机代理)	插件设置→流量控制
禁止 YouTube 走 QUIC	disable_udp_quic=1 (禁用 QUIC，默认已开)	插件设置→流量控制
外网访问 Dashboard	dashboard_forward_domain + dashboard_forward_port 配置	插件设置→外部控制
换一个 Dashboard	在插件设置-外部控制页切换	插件设置→外部控制
DNS 解析异常	先点"清空 DNS 缓存"，不行用"Dnsmasq 修复"	插件设置→DNS
停止后上不了网	点击"Dnsmasq 修复"按钮	插件设置→DNS
开启 IPv6	ipv6_enable=1 (不推荐)	插件设置→IPv6
定时重启	auto_restart=1 + 设置时间	插件设置→定时重启
定时更新订阅	auto_update=1 + 设置时间和模式	配置订阅
定时更新 GEO	geo_auto_update=1 (等) + 设置时间	插件设置→GEO 数据库订阅
过滤订阅节点	编辑订阅 → keyword (筛选节点) / ex_keyword (排除节点) 设置	配置订阅
更改代理端口	http_port / socks_port / mixed_port 修改	覆写设置→常规
覆写订阅 DNS	enable_custom_dns=1 (自定义 DNS 设置 (Custom DNS Setting)) + 添加 dns_servers	覆写设置→DNS
添加代理认证	添加 authentication 条目 (用户名/密码)	覆写设置→常规
添加自定义规则	enable_custom_clash_rules=1 (自定义规则 (Custom Clash Rules)) + 编辑规则文件	覆写设置→规则
加速 Github 下载	github_address_mod 选 CDN 地址	覆写设置→常规
开启域名嗅探	enable_meta_sniffer=1 (启用域名嗅探 (Enable Meta Sniffer)，默认已开)	覆写设置→Meta
TCP 并发提速	enable_tcp_concurrent=1 (启用 TCP 并发 (Enable TCP Concurrent))	覆写设置→Meta
生成 PAC 文件	运行状态页 → 混合代理卡片 → 获取 PAC 配置	运行状态

---

后台命令速查

# 启动/停止/重启
/etc/init.d/openclash start|stop|restart

# 查看 UCI 配置
uci show openclash

# 修改 UCI 配置 (例: 切换代理模式为全局)
uci set openclash.@openclash[0].proxy_mode='global'
uci commit openclash

# 手动更新订阅
/usr/share/openclash/openclash.sh

# 更新 GEO 数据
/usr/share/openclash/openclash_geo.sh ipdb    # GeoIP MMDB
/usr/share/openclash/openclash_geo.sh geoip   # GeoIP Dat
/usr/share/openclash/openclash_geo.sh geosite # GeoSite
/usr/share/openclash/openclash_geo.sh geoasn  # GeoASN

# 更新大陆路由表
/usr/share/openclash/openclash_chnroute.sh

# 更新核心
/usr/share/openclash/openclash_core.sh

# 更新插件
/usr/share/openclash/openclash_update.sh

# 一键更新 (核心+订阅+GEO)
/usr/share/openclash/openclash_update.sh one_key_update

# 生成调试日志
/usr/share/openclash/openclash_debug.sh

# 查看运行日志
cat /tmp/openclash.log

# 查看启动日志
cat /tmp/openclash_start.log

# 测试配置文件语法
/etc/openclash/clash -t -d /etc/openclash -f /etc/openclash/config/xxx.yaml

# 清空 DNS 缓存 (通过 API)
curl -X POST http://127.0.0.1:9090/cache/fakeip/flush
curl -X POST http://127.0.0.1:9090/cache/dns/flush

---

Mihomo Wiki 参考链接

• 全局配置 (General) — mode, log-level, ipv6, tcp-concurrent 等
• DNS 配置 — enhanced-mode, nameserver, fallback, fake-ip-filter 等
• TUN 配置 — stack, auto-route, dns-hijack 等
• 域名嗅探 (Sniffer) — sniffer 各项参数
• 完整配置示例

---

第八部分：LuCI API 端点参考 (后台直接调用)

用户登录路由器后，可通过 curl/XHR 直接调用以下端点实现自动化操作 所有端点基础路径: http://路由器IP/cgi-bin/luci/admin/services/openclash

8.1 状态查询类 (GET)

端点	返回	用途
/status	JSON {clash, daip, dase, cn_port, core_type, ...}	获取核心运行状态、Dashboard 地址、密钥
/op_mode	JSON {op_mode}	当前页面模式 (redir-host/fake-ip)
/get_run_mode	JSON {en_mode}	当前运行模式
/rule_mode	JSON {proxy_mode}	当前代理模式 (rule/global/direct)
/log_level	JSON {log_level}	当前日志级别
/toolbar_show	JSON {upload, download, connect, mem, cpu, load_avg}	实时流量统计
/oc_settings	JSON {meta_sniffer, respect_rules, oversea, stream_unlock}	快捷设置状态
/config_name	JSON {current, list[]}	配置文件列表及当前选中
/config_file_list	JSON {files[], current}	配置文件详细列表 (含修改时间)
/update_info	JSON {corever, release_branch, smart_enable}	用户选择的核心版本号 (UCI core_version)、发行分支、Smart 启用状态。注意 corever 是用户在更新页面选择的版本配置，非当前运行版本
/update	JSON {coremodel, coremetacv, corelv, opcv, oplv, upchecktime}	完整版本信息：CPU 架构、当前核心版本（执行 clash_meta -v 解析）、远程最新核心版本、当前/最新插件版本、更新检查时间
/dashboard_type	JSON {dashboard_type, yacd_type, default_dashboard}	仪表盘类型和可用性
/proxy_info	JSON {mixed_port, auth_user, auth_pass}	混合代理地址和认证信息
/sub_info_get?filename=xxx	JSON	订阅流量/到期信息
/myip_check	JSON {upaiyun, ipip, ipsb, ipify}	并行查询当前出口 IP
/startlog	JSON {startlog}	最后一行启动日志
/announcement	JSON	项目公告 (24h 缓存)
/get_subscribe_data	JSON	所有订阅配置详情
/oix_info	JSON	oixCloud 账户信息

8.2 操作修改类 (POST/GET)

端点	参数	效果
/action	{action: "start"|"stop"|"restart"}	启动/停止/重启核心 (POST)
/switch_mode	—	切换页面模式 redir-host↔fake-ip
/switch_run_mode	{mode: ""|"-tun"|"-mix"}	切换运行模式 (POST, 运行中自动重启)
/switch_rule_mode	{mode: "rule"|"global"|"direct"}	切换代理模式 (POST, 热生效)
/switch_config	{config: "文件名.yaml"}	切换当前配置文件 (POST, 自动重启)
/switch_oc_setting	{setting, value}	快捷设置切换。setting=meta_sniffer/respect_rules/oversea/stream_unlock
/switch_log	{level: "info"|"debug"|...}	修改日志级别 (POST, 热生效)
/switch_dashboard	{name, type}	下载/切换仪表盘
/delete_dashboard	{name}	删除仪表盘
/default_dashboard	{name}	设为默认仪表盘
/coreupdate	—	更新核心二进制 (POST)
/opupdate	—	更新插件本身 (POST)
/one_key_update	—	一键更新 (POST)
/update_config	{filename}	更新指定订阅配置 (POST)
/flush_dns_cache	—	清空 DNS 缓存 (POST)
/flush_smart_cache	—	清空 Smart 缓存 (POST)
/close_all_connection	—	断开所有连接 (POST)
/reload_firewall	—	重载防火墙规则 (POST)
/restore	—	还原默认配置 (POST)
/generate_pac	—	生成 PAC 文件 (POST)
/save_corever_branch	{core_version, release_branch, smart_enable}	保存核心版本选择 (POST)
/upload_config	(multipart)	上传配置文件 (POST)
/config_file_save	{filename, content}	保存配置文件 (POST)
/config_file_read	{filename}	读取配置文件内容
/add_subscription	(表单数据)	添加/编辑订阅 (POST)
/generate_age_key	—	生成 Age 加密密钥对 (POST)
/cal_age_public_key	—	计算 Age 公钥 (POST)
/oix_login	{email, passwd}	oixCloud 登录 (POST)
/oix_logout	—	oixCloud 登出 (POST)
/oix_checkin	—	oixCloud 签到 (POST)

8.3 诊断类 (GET)

端点	参数	用途
/diag_connection	{addr}	连接诊断 (返回 text/plain)
/diag_dns	{hostname}	DNS 解析诊断
/gen_debug_logs	—	生成完整调试日志
/manual_stream_unlock_test	{type}	手动流媒体解锁测试
/refresh_log	{seek, include_core}	获取新日志行
/del_log	—	清空日志文件

8.4 Mihomo 原生 API (直连核心)

核心运行时可直调 (http://127.0.0.1:9090):

端点	方法	用途
/configs	GET/PATCH/PUT	读取/修改运行时配置 (热生效)
/proxies	GET	获取所有代理节点
/proxies/{name}	PUT	切换策略组选择
/rules	GET	获取路由规则
/connections	GET/DELETE	查看/关闭连接
/cache/fakeip/flush	POST	清空 Fake-IP 缓存
/cache/dns/flush	POST	清空 DNS 解析缓存
/cache/smart/flush	POST	清空 Smart 策略缓存
/traffic	GET	实时流量数据
/logs	WebSocket	实时日志流
/version	GET	核心版本信息

---

第九部分：Shell 脚本功能映射

每个脚本被哪个 UI 操作触发、读取哪些 UCI、完成什么功能

9.1 主服务脚本 /etc/init.d/openclash

触发方式: start|stop|restart|reload|enable|disable 命令 / Web UI 启停按钮 / 开机自启

函数	功能
start_service	完整启动流程: 配置覆写→内核检查→YAML验证→yml修改→防火墙→DNS劫持→cron→看门狗
stop_service	停止流程: 备份历史→恢复防火墙→kill 进程→恢复DNS→清理cron
reload_service	重载防火墙规则 (不重启核心)
set_firewall	建立 iptables/nftables 规则 (REDIRECT/TPROXY/TUN/访问控制)
revert_firewall	清除所有防火墙规则
change_dnsmasq	DNS 劫持 (修改 dnsmasq 配置指向核心 DNS)
revert_dnsmasq	恢复原始 dnsmasq 配置
add_cron	添加定时任务 (订阅更新/GEO更新/Chnroute更新/重启)
del_cron	删除所有 OpenClash 定时任务
overwrite_file	执行覆写模块 (处理自定义覆写脚本)
config_choose	自动选择配置文件
do_run_file	检查并下载缺失的核心/GEO/Chnroute 文件

9.2 订阅更新脚本 openclash.sh

触发: Web UI「更新配置」按钮 / Cron /usr/share/openclash/openclash.sh

函数	功能
sub_info_get	遍历所有订阅→解析设置→构建下载URL→关键字匹配正则
config_download	curl 下载订阅配置
config_test	clash -t 语法验证
config_cus_up	Ruby YAML 解析→节点关键字过滤/排除
config_su_check	新旧配置对比→有更新则替换+标记重启
config_download_direct	代理下载失败时回退直连下载
server_key_match	构建节点匹配正则 (&=AND, `

9.3 核心更新脚本 openclash_core.sh

触发: Web UI「更新内核」按钮

• 确定核心类型 (Meta/Smart/Oix)
• 调用 clash_version.sh 获取最新版本
• 下载核心二进制→解压→验证→替换
• 标记需重启

9.4 插件更新脚本 openclash_update.sh

触发: Web UI「更新插件」按钮 /「一键更新」

• 下载 luci-app-openclash IPK/APK
• 预安装测试通过后动态生成安装脚本
• 通过 ubus 服务方式后台安装 (避免 Web 断连)
• 一键更新模式: 先调用 openclash_core.sh

9.5 GEO 更新脚本 openclash_geo.sh

触发: Web UI「更新 GEO 数据库」按钮 / Cron

参数	下载目标
ipdb	Country.mmdb (GeoIP MMDB)
geoip	geoip.dat
geosite	geosite.dat
geoasn	GeoLite2-ASN.mmdb
all	以上全部

9.6 大陆路由更新 openclash_chnroute.sh

触发: Web UI「更新大陆路由」按钮 / Cron

• 下载中国 IPv4/IPv6 CIDR 列表
• 转换为 nftables set 或 ipset 格式

9.7 其他脚本速查

脚本	触发来源	功能
openclash_debug.sh	Web UI「生成调试日志」	收集完整诊断信息
openclash_download_dashboard.sh	Web UI 仪表盘切换	下载/切换 Dashboard
openclash_debug_getcon.lua	连接诊断	获取当前活动连接
openclash_debug_dns.lua	DNS 诊断	测试 DNS 解析
openclash_streaming_unlock.lua	流媒体测试/看门狗	自动选择解锁节点
openclash_history_get.sh	停止服务/看门狗/「关闭所有连接」	同步缓存/关闭连接
openclash_custom_domain_dns.sh	init.d 启动流程	自定义域名 DNS 配置
yml_change.sh	init.d 启动流程	Ruby 修改 YAML (端口/模式/DNS/TUN/认证)
yml_rules_change.sh	init.d 启动流程	Ruby 修改 YAML (规则/Provider CDN/URL-Test覆写)
yml_groups_set.sh	Web UI 保存策略组	策略组写入 YAML
yml_proxys_set.sh	Web UI 保存节点	节点/代理集写入 YAML
openclash_sub_parser.lua	看门狗	解析 base64/vmess/ss 等订阅格式
openclash_watchdog.sh	init.d 启动后	守护进程: 核心存活监控/流媒体解锁/订阅更新/UPNP + 每60秒检查防火墙规则完整性（规则乱序/TUN路由表丢失自动重载，每周期最多重载3次）
openclash_lgbm.sh	Web UI 模型更新	LightGBM 模型下载

---

第十部分：覆写模块详解

覆写模块 (Overwrite Module) 是 OpenClash 的高级自定义功能 入口: 运行状态页顶部「覆写模块」按钮（弹出覆写编辑器，与启动/停止开关并列），或菜单 服务→OpenClash→覆写设置（独立 CBI 页面） UCI Section: openclash.config_overwrite (支持多条，按 order 排序) 覆写文件存储: /etc/openclash/overwrite/<名称> (本地) 或通过 HTTP 远程拉取

10.1 覆写模块是什么

AI 行为指引: 当用户询问覆写模块相关问题（如"如何通过覆写添加配置"、"[YAML] 操作符怎么用"、 "如何覆盖订阅中的 DNS 设置"、"覆写和 LuCI 设置哪个优先级高"），AI 应：

1. 首先在本章节查找答案（10.2 格式说明、10.2.3 操作符、10.5 实战示例）
2. 如果涉及具体的 Mihomo YAML 字段用法，查阅 Mihomo 配置文档
3. 如果涉及覆写模块的执行机制和排序逻辑，查阅 OpenClash 源码 中 init.d/openclash 的 overwrite_file() 函数和 /tmp/yaml_overwrite.sh 生成逻辑。
4. 关键提醒：覆写模块分两阶段执行——[General] 段在 yml_change.sh 之前写入 UCI（可影响 yml_change.sh 行为），[Overwrite] 和 [YAML] 段在 yml_change.sh 和 yml_rules_change.sh 之后执行，因此可以覆盖这两个脚本写入的所有内容（包括「插件强制覆盖/禁用的设置」表格中的硬编码项）。覆盖硬编码项可能导致 OpenClash 工作异常（如 allow-lan: false 会使局域网设备无法使用代理端口），请提醒用户谨慎操作。 「服务→OpenClash→覆写设置」CBI 页面的选项均由 yml_change.sh 和 yml_rules_change.sh 执行，同样会被覆写模块的 [Overwrite] 和 [YAML] 段覆盖。 此外，覆写文件必须包含至少一个段头（[General]、[Overwrite]、[YAML] 之一），否则所有内容被跳过，覆写不生效。 如果用户发现覆写不生效，告知用户：①检查段头是否存在；②检查文件是否匹配当前配置（config 字段）。
5. 示例优先原则：当用户询问「如何添加/覆写某个配置」时，优先使用 [YAML] 段格式给出示例（语法清晰、不易出错）；仅当需要动态逻辑（如条件判断、循环处理）时才推荐 [Overwrite] 段。在 [YAML] 段优先的前提下，应先明确或询问用户的具体需求（如：要追加还是替换？作用于哪个键路径？目标是数组还是哈希？期望匹配条件是什么？），然后结合 10.2.3 节的操作符语法（! 强制覆盖 / + 数组追加 / - 数组删除 / * 批量条件更新等）给出精准的、可直接使用的 YAML 片段示例，而非仅给出泛泛的描述或通用模板。

核心机制: OpenClash 的覆写模块分两个阶段执行（均在 /etc/init.d/openclash start_service 流程中）：

第一阶段 — UCI 预处理（overwrite_file() 函数，在 yml_change.sh 之前执行）：

1. 遍历 UCI 中所有 config_overwrite 条目（按 order 排序）
2. 检查覆写是否匹配当前配置文件（config 字段支持 all 或指定文件名）
3. 读取 /etc/openclash/overwrite/<名称> 文件内容
4. 解析 [General] 段 → 将键值对写入 UCI openclash.@overwrite[0]（如 EN_MODE、DNS_PORT 等），供后续 yml_change.sh 读取
5. 处理 DOWNLOAD_FILE 指令 → 下载外部文件
6. 生成 /tmp/yaml_overwrite.sh 脚本（包含 [Overwrite] 和 [YAML] 段的内容，暂不执行）

第二阶段 — YAML 覆写（/tmp/yaml_overwrite.sh，在 yml_change.sh 和 yml_rules_change.sh 之后执行）： 7. 执行 [Overwrite] 段的 Shell 命令（可使用 ruby_* 函数族修改 YAML） 8. 将 [YAML] 段的 YAML 内容深度合并到运行配置

执行顺序含义：[General] 段在 yml_change.sh 之前生效（因为写入 UCI），因此可以影响 yml_change.sh 的行为；[Overwrite] 和 [YAML] 段在 yml_change.sh 和 yml_rules_change.sh 之后执行，因此可以覆盖这两个脚本的所有输出——包括「插件强制覆盖/禁用的设置」表格中的硬编码项（如 allow-lan、bind-address、sniffer.sniff 等）。⚠️ 覆盖这些硬编码项可能导致功能异常，请谨慎使用。

覆写模块能做什么:

• 给订阅配置追加/覆盖任意 Mihomo YAML 字段（如 DNS、Sniffer、TUN、规则等）
• 设置环境变量供 yml_change.sh 等后续脚本使用
• 下载外部文件（通过 DOWNLOAD_FILE 指令）
• 对未提供 UI 选项的 Mihomo 高级功能进行配置

10.2 覆写文件的格式

覆写文件使用 INI 风格的分段格式，支持三个段：

[General]
# 键值对，将作为环境变量导出
# 支持的 key 列表见下方

[Overwrite]
# Shell 命令，可使用 ruby_* 函数族操作 YAML

[YAML]
# 原始 YAML 片段，将合并到运行配置

⚠️ 强制要求：覆写文件必须包含至少一个段头（[General]、[Overwrite]、[YAML] 之一），否则所有内容将被忽略，覆写模块不会生效。这是因为 overwrite_file() 函数（/etc/init.d/openclash）按段头解析文件内容——所有标志位 in_general/in_overwrite/in_yaml 初始为 0，仅在遇到对应段头时才设为 1。段头之前、之后无段头的内容均被跳过。空行和以 #/; 开头的注释行会被安全忽略，不影响段头解析。

10.2.1 [General] 段 — 键值对/环境变量

每行格式: KEY = VALUE（大小写不敏感，会自动转大写）

允许的所有 Key (共 ~85 个，由 overwrite_file() 函数中的 allowed_keys_types 定义):

类别	Key 示例	类型	说明
端口	DNS_PORT, PROXY_PORT, TPROXY_PORT, HTTP_PORT, SOCKS_PORT, MIXED_PORT	int	覆写端口号
模式	EN_MODE, PROXY_MODE, STACK_TYPE	string	覆写运行/代理模式
DNS	ENABLE_CUSTOM_DNS, ENABLE_RESPECT_RULES, APPEND_WAN_DNS, APPEND_DEFAULT_DNS	int_bool	DNS 覆写
Fake-IP	FAKEIP_RANGE, FAKEIP_RANGE6, STORE_FAKEIP, CUSTOM_FAKEIP_FILTER, CUSTOM_FAKEIP_FILTER_MODE	string/int_bool	Fake-IP 相关
Meta	ENABLE_TCP_CONCURRENT, ENABLE_UNIFIED_DELAY, ENABLE_META_SNIFFER, ENABLE_META_SNIFFER_PURE_IP, ENABLE_GEOIP_DAT	int_bool	Meta 内核
流量	ROUTER_SELF_PROXY, DISABLE_UDP_QUIC, SKIP_PROXY_ADDRESS, COMMON_PORTS, CHINA_IP_ROUTE	int_bool/int/string	流量控制
IPv6	IPV6_ENABLE, IPV6_MODE, IPV6_DNS	int_bool/int	IPv6
GEO	GEO_AUTO_UPDATE, GEOIP_AUTO_UPDATE, GEOSITE_AUTO_UPDATE, GEOASN_AUTO_UPDATE	int_bool	GEO 更新
自定义	ENABLE_CUSTOM_CLASH_RULES, ENABLE_RULE_PROXY	int_bool	规则
Smart	AUTO_SMART_SWITCH, SMART_ENABLE_LGBM, SMART_POLICY_PRIORITY	int_bool/string	Smart 策略
特殊	CONFIG_FILE	string	覆写 config_path（切换配置）
特殊	AGE_SECRET_KEY, AGE_PUBLIC_KEY	string	Age 加密密钥
特殊	SUB_INFO_URL	string	订阅信息 URL
特殊	DOWNLOAD_FILE	string	下载外部文件（见单独说明）
特殊	DA_PASSWORD	string	Dashboard 密码
特殊	GLOBAL_UA	string	全局 User-Agent
特殊	RESTART	bool	覆写变更后是否重启

类型说明: int=整数, int_bool=0/1, bool=true/false, string=任意字符串

这些环境变量在 yml_change.sh、yml_rules_change.sh 及自定义覆写脚本中可通过 $KEY_NAME 直接引用。

10.2.2 [Overwrite] 段 — Shell 脚本

此段内容直接作为 Shell 命令执行。可用的函数：

• ruby_read <file> <key_path> — 读取 YAML 值
• ruby_cover <file> <key_path> <value> — 覆盖 YAML 值
• ruby_merge <file> <key_path> <value> — 合并 YAML 哈希
• ruby_delete <file> <key_path> — 删除 YAML 键
• ruby_arr_add_file <file> <key_path> <list_file> — 从文件添加数组元素
• ruby_uniq <file> <key_path> — 数组去重
• ruby_edit <file> <key_path> <value> — 编辑数组元素
• uci_get_config <key> — 读取 UCI 配置（覆写优先）

10.2.3 [YAML] 段 — 原始 YAML 注入（含操作符）

[YAML] 段使用 Ruby 将内容深度合并到运行配置文件。支持多种操作符后缀实现精细控制：

操作符速查表：

操作符	写法	行为
默认合并	key 或 <key>	Hash 递归合并，标量直接覆盖，键不存在则添加
强制覆盖	key! 或 <key>!	强制替换整个值（不做递归合并）
数组后置追加	key+ 或 <key>+	将新元素追加到数组末尾
数组前置插入	+key 或 +<key>	将新元素插入到数组开头
数组差集删除	key- 或 <key>-	从数组中删除指定元素；非数组则删除整个键
批量条件更新	key* 或 <key>*	按 where 条件匹配，用 set 子句更新（见下）

<key> 语法用于键名含特殊字符或与操作符冲突时。

操作符详解与示例

1. 默认合并 (key / <key>)

Hash 值递归合并，键不存在则添加，标量直接覆盖。

dns:
  enable: true           # 修改现有键
  cache-algorithm: lru   # 添加新键
mixed-port: 10802        # 直接覆盖标量
tun:
  enable: true           # 合并 Hash（仅改指定字段，其余保留）
  stack: gvisor

2. 强制覆盖 (key! / <key>!)

强制替换整个值，不做递归合并。

dns:
  fake-ip-filter!:         # 替换整个 fake-ip-filter 数组
    - '*.lan'
    - 'new.domain.com'
rules!:                    # 强制覆盖整个 rules 数组
  - DOMAIN-SUFFIX,example.com,DIRECT
  - MATCH,PROXY
<dns>!:                    # <> 语法：强制覆盖整个 dns 配置
  enable: false
  nameserver:
    - '114.114.114.114'

3. 数组后置追加 (key+ / <key>+)

将新元素追加到数组末尾。

dns:
  nameserver+:
    - '1.1.1.1'
    - '8.8.8.8'
rules+:
  - DOMAIN-SUFFIX,example.com,REJECT
<nameserver>+:
  - '8.8.8.8'

4. 数组前置插入 (+key / +<key>)

将新元素插入到数组开头（优先匹配）。

dns:
  +nameserver:
    - '223.5.5.5'
+rules:
  - DOMAIN-SUFFIX,priority.com,DIRECT
+<nameserver>:
  - '119.29.29.29'

5. 数组删除/键删除 (key- / <key>-)

从数组中移除指定元素；对非数组删除整个键。值为空(null/~)时删除整个键。

dns:
  nameserver-:
    - '8.8.8.8'
    - '8.8.4.4'
rules-:
  - DOMAIN-SUFFIX,old.com,REJECT
  cache-algorithm-:         # 删除整个 cache-algorithm 键

6. 批量条件更新 (key* / <key>*)

按 where 条件匹配集合元素，用 set 子句更新指定字段。

支持的集合类型: Hash 值数组 (如 proxy-groups)、字符串数组 (如 rules) where 条件格式: 字段名: 值，支持正则 /pattern/

set 子句支持的操作符: 同顶层（默认覆盖、!、+、-）

# === 对 proxy-groups (Hash 数组) ===

# 按 type 匹配，替换整个 proxies 列表
proxy-groups*:
  where:
    type: select
  set:
    proxies:
      - 'new-proxy1'
      - 'new-proxy2'

# 按 name 正则匹配，向 proxies 开头插入
proxy-groups*:
  where:
    name: '/^HK/'
  set:
    +proxies:
      - 'hk-new-proxy'

# 按 type 匹配，从 proxies 中移除指定节点
proxy-groups*:
  where:
    type: select
  set:
    proxies-:
      - 'old-proxy1'

# 使用数组包含条件（proxies 须包含指定元素）
proxy-groups*:
  where:
    type: select
    proxies:
      - 'old-proxy1'
  set:
    proxies:
      - 'new-proxy1'

# 修改 url-test 组的 interval
<proxy-groups>*:
  where:
    type: url-test
  set:
    interval: 300

# === 对 proxies (节点数组) ===

# 修改 socks5 节点端口
proxies*:
  where:
    type: socks5
  set:
    port: 1080

# === 对 rules (字符串数组) ===

# 替换匹配的规则
rules*:
  where:
    value: 'DOMAIN-SUFFIX,old.com,REJECT'
  set:
    value: 'DOMAIN-SUFFIX,new.com,DIRECT'

# 正则匹配删除规则（set value 为空/不写）
rules*:
  where:
    value: '/,REJECT$/'
  set:
    value:

# === 对 hosts (Hash 集合) ===

# 更新指定 hosts 键
hosts*:
  where:
    key: '*.mihomo.dev'
  set:
    '*.mihomo.dev': '::1'

# 删除指定 hosts 键
hosts*:
  where:
    key: '*.old.dev'
  set:
    key-:

7. 组合操作

同一块内可同时使用多个操作符：

dns:
  nameserver-:         # 先删除
    - '8.8.8.8'
  +nameserver:         # 再前置插入
    - '223.5.5.5'
  nameserver+:         # 再后置追加
    - '1.0.0.1'

10.2.4 DOWNLOAD_FILE 特殊指令（[General] 段）

格式: DOWNLOAD_FILE = url=..., path=..., cron=..., force=..., ua=..., restart=...

用于在覆写模块中下载外部文件。字段说明：

• url — 下载地址 (必填)
• path — 保存路径 (必填)
• cron — cron 表达式，0 表示不添加定时任务
• force — true 强制重新下载
• ua — 自定义 User-Agent
• restart — true 下载后重启核心

10.3 覆写模块的两种获取方式

类型	UCI type 值	说明
本地文件	file	读取 /etc/openclash/overwrite/<名称>
远程模块	http	从 URL 下载到 /etc/openclash/overwrite/<名称>，支持 cron 定时更新

远程模块可设置 update_days 和 update_hour 实现定时自动拉取。

10.4 覆写与配置文件的匹配

每个覆写条目可指定目标配置文件（config 字段，ListValue）:

• all — 对所有配置文件生效
• /etc/openclash/config/xxx.yaml — 仅对该配置文件生效

10.5 实战示例

示例1: 强制启用 TUN 模式 + 设置 DNS

[General]
EN_MODE = fake-ip-tun
STACK_TYPE = mixed

示例2: 通过 [Overwrite] 段添加自定义代理组

[Overwrite]
ruby_merge "$CONFIG_FILE" "proxy-groups" '{"name":"手动切换","type":"select","proxies":["DIRECT","Proxy"]}'

示例3: 通过 [YAML] 段覆写完整 DNS 配置

[YAML]
dns:
  enable: true
  enhanced-mode: fake-ip
  nameserver:
    - https://doh.pub/dns-query
    - https://dns.alidns.com/dns-query
  fallback:
    - tls://8.8.4.4
    - tls://1.1.1.1
  fallback-filter:
    geoip: true
    geoip-code: CN

示例4: 通过 [YAML] 段覆写 Sniffer

[YAML]
sniffer:
  enable: true
  force-dns-mapping: true
  parse-pure-ip: true
  sniff:
    TLS:
      ports: [443, 8443]
    HTTP:
      ports: [80, 8080-8880]

示例5: 通过 [YAML] 段添加自定义规则

[YAML]
rules:
  - DOMAIN-SUFFIX,google.com,Proxy
  - DOMAIN-KEYWORD,youtube,Proxy
  - GEOSITE,netflix,NETFLIX
  - GEOIP,CN,DIRECT
  - MATCH,Proxy

示例6: 通过 [Overwrite] + ruby 函数动态修改

[Overwrite]
# 追加规则文件
ruby_arr_head_add_file "$CONFIG_FILE" "rules" "/etc/openclash/custom/openclash_custom_rules.list"
# 删除 proxy-providers 中特定的条目
ruby_delete "$CONFIG_FILE" "proxy-providers.低质量节点"
# 修改 DNS nameserver
ruby_cover "$CONFIG_FILE" "dns.nameserver" '[223.5.5.5, 119.29.29.29]'

示例7: 使用 CONFIG_FILE 切换配置 + 设置 Age 密钥

[General]
CONFIG_FILE = /etc/openclash/config/my_custom.yaml
AGE_SECRET_KEY = AGE-SECRET-KEY-xxxxxxxxx

示例8: 下载外部规则文件

[General]
DOWNLOAD_FILE = url=https://example.com/rules.yaml, path=/etc/openclash/rule_provider/custom_rules.yaml, ua=clash-verge/v2.4.5, cron=0 2 * * *

10.6 自定义覆写脚本（旧方式，兼容保留）

文件: /etc/openclash/custom/openclash_custom_overwrite.sh 执行时机: 在 yml_change.sh 和 yml_rules_change.sh 之间执行 特点: 可以使用项目提供的 ruby_* 函数族

#!/bin/bash
. /usr/share/openclash/ruby.sh

CFG_FILE=$(uci_get_config "config_path")
if [ -f "$CFG_FILE" ]; then
    ruby_arr_head_add_file "$CFG_FILE" "rules" "/etc/openclash/custom/openclash_custom_rules.list"
fi

10.7 UCI 覆写条目结构速查

每个 config_overwrite 条目的 UCI 字段：

UCI Key	类型	说明
name	string	唯一标识（对应 /etc/openclash/overwrite/<name> 文件名）
enabled	bool	是否启用
type	string	file 或 http
url	string	HTTP 类型时的下载地址
config	ListValue	目标配置文件（all 或具体路径）
param	string	额外键值对（KEY1=VALUE1;KEY2=VALUE2 格式）
order	int	排序权重（越大越先执行）
update_days	string	HTTP 类型的 cron 天 (0-7, *)
update_hour	string	HTTP 类型的 cron 小时 (0-23, *)

---

第十一部分：status.htm 前端 JS 交互速查

运行状态页面 (/cgi-bin/luci/admin/services/openclash/client) 的前端逻辑

UI 元素	JS 函数	API 调用
插件开关	togglePlugin(this)	/action POST {action: "start"/"stop"}
重启按钮	restartCore()	/action POST
覆写模块按钮	editOverwrite()	在运行状态页弹出覆写编辑模态框
Compat/TUN/Mix 单选	switch_run_mode(val)	/switch_run_mode POST
Rule/Global/Direct 单选	switch_rule_mode(val)	/switch_rule_mode POST
Area Bypass 单选	switch_oc_setting_oversea(val)	/switch_oc_setting POST {setting: "oversea"}
Sniffer 单选	switch_meta_sniffer(val)	/switch_oc_setting POST {setting: "meta_sniffer"}
DNS Proxy 单选	switch_respect_rules(val)	/switch_oc_setting POST {setting: "respect_rules"}
Stream Unlock 单选	switch_stream_unlock(val)	/switch_oc_setting POST {setting: "stream_unlock"}
切换配置	switchConfig()	/switch_config POST
更新配置	updateConfig()	/update_config POST
编辑配置	editConfig()	弹出 config_edit.htm 模态框
编辑订阅	editSubscribe()	跳转 config-subscribe-edit
上传配置	uploadConfig()	config_upload.htm 模态框
复制面板地址	copyAddress()	复制到剪贴板
复制密钥	copySecret()	复制到剪贴板
获取 PAC	generatePacConfig()	/generate_pac POST
仪表盘按钮	新窗口打开	http://IP:9090/ui/ 等
关闭所有连接	closeAllConnections()	/close_all_connection POST
重载防火墙	reloadFirewall()	/reload_firewall POST
清空 DNS 缓存	flushDNSCache()	/flush_dns_cache POST
一键更新	oneKeyUpdate()	/one_key_update POST
统计轮询	StateManager 自动轮询	/toolbar_show + /status

初始加载: 页面加载时同时请求 /status、/toolbar_show、/config_file_list、/oc_settings、/dashboard_type、/rule_mode、/proxy_info、/myip_check、/announcement

---

超出本文档范围的查询

强制规则：当用户询问本文档未覆盖的 Mihomo/OpenClash 配置或实现细节时，禁止自行猜测或编造回答。 AI 必须主动查询外部资源获取准确信息后回复用户。

本文档仅覆盖 OpenClash LuCI 插件 UI 中可直接配置的选项及其实现。当遇到本文档未覆盖的问题时，AI 必须主动使用以下资源查询答案，而非让用户自己去查阅文档：

AI 必须主动查询的外部资源：

优先级	资源	查询方式	适用场景
1	Mihomo Wiki https://wiki.metacubex.one/config/	使用 fetch_webpage 抓取相关页面	Mihomo YAML 配置字段的含义、可选值、用法
2	Meta-Docs 仓库 github.com/MetaCubeX/Meta-Docs	使用 github_text_search 搜索 docs/config/ 目录	需要精确的字段类型、默认值、完整配置示例
3	OpenClash Issues https://github.com/vernesong/OpenClash/issues	使用 fetch_webpage 打开 Issue 搜索页面或具体 Issue 页面	插件侧功能异常/报错（配置/订阅/防火墙/UI等），搜索已知问题和社区方案（优先作者 vernesong 回复和高赞回答）
4	Mihomo Issues https://github.com/MetaCubeX/mihomo/issues	使用 fetch_webpage 打开 Issue 搜索页面或具体 Issue 页面	内核侧功能异常/报错（代理协议/TUN/DNS解析/规则引擎等），搜索已知问题和社区方案
5	OpenClash 源码 github.com/vernesong/OpenClash/tree/dev	使用 github_text_search 搜索对应脚本/函数	需要了解插件侧的实现逻辑、UCI 到 YAML 的转换细节
6	Mihomo 核心源码 github.com/MetaCubeX/mihomo/tree/Alpha	使用 github_text_search 搜索核心代码	代理协议实现、规则引擎、DNS 解析、TUN 栈等核心底层逻辑
7	Smart 核心源码 github.com/vernesong/mihomo/tree/Alpha	使用 github_text_search 搜索核心代码	Smart 策略、LightGBM 模型的底层实现

具体触发条件（满足任一即主动查询）：

• 用户询问的配置字段在本文档任何章节中均未出现
• 用户询问特定代理协议的详细参数（Hysteria2/TUIC/WireGuard/SSH/MASQUE 等的完整 TLS/传输层选项）
• 用户询问 experimental、tunnel、sub-rule 等插件 UI 中无直接对应选项的 Mihomo 顶级配置段
• 用户需要编写超出覆写模块 8.2 节示例范围的自定义脚本或 YAML 配置
• 用户询问 Mihomo 最新版本引入的新特性（本文档基于 Mihomo v1.19.x）
• 用户询问 OpenClash 插件本身的开发、编译、打包相关问题
• 用户询问本文档各选项中「实现细节」的更深层逻辑

AI 工作流程：

1. 确认问题超出本文档覆盖范围
2. 根据问题类型选择对应的外部资源
3. 优先搜索 Issues：如果用户遇到的是功能异常/报错类问题（而非配置字段查询），应先搜索 Issues 查找类似问题。根据问题类型选择：插件侧（配置/订阅/防火墙/UI）→ OpenClash Issues；内核侧（代理协议/TUN/DNS/规则引擎）→ Mihomo Issues。读取 Issue 时重点关注：① 维护者的诊断命令和结论；② 👍 反应数高的社区回复；③ Issue 最终是否被关闭及关闭原因（completed=已修复，not planned=不在计划内）
4. 主动查询：使用 fetch_webpage 抓取 Mihomo Wiki 页面，或使用 github_text_search 搜索 Meta-Docs/OpenClash/Mihomo 核心/Smart 核心源码
5. 将查询到的信息翻译、整理后告知用户，而非直接丢链接
6. 在回复末尾注明信息来源（如「以上信息来自 OpenClash Issues #xxx / Mihomo Wiki」），让用户知道信息的权威来源