| name | openclash-user-guide |
| description | OpenClash 用户功能指南。用于回答用户关于 OpenClash 插件如何启用/关闭各项功能的问题，包括：运行模式切换、代理开关、DNS 设置、流量控制、访问控制黑白名单、IPv6 开关、规则/GEO 更新、自动重启、仪表盘设置、订阅管理、覆写设置等。每个选项均标注了对应的 UCI 配置项、修改的 Mihomo YAML 配置段、以及触发的脚本。Use when user asks how to enable, disable, configure, or troubleshoot any OpenClash feature on OpenWrt. |
| instructions | 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.
|
| type | knowledge-base |
| tags | ["openclash","openwrt","mihomo","clash","proxy","networking"] |
| argument-hint | 询问 OpenClash 功能如何开启/关闭 |
| user-invocable | true |
| disable-model-invocation | 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() 函数以四级回退方式检查和加载内核模块：
- 容器检测 — 检测 Docker/LXC/Podman 等容器环境，容器内直接返回成功（无法加载内核模块）
- 内核编译检查 — 检查
/proc/config.gz 中是否有 CONFIG_<MODULE>=y（静态编译进内核，无需 modprobe）
- 已加载检查 —
lsmod | grep 检查模块是否已在内核中加载
- 动态加载尝试 —
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()):
- 备份策略组状态历史 → 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"
SKIP_GROUP="65534"
一、fw4 (nftables) 链结构 — inet fw4 表
A. DNS 劫持链
enable_redirect_dns=1 (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"
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):
nft add rule inet fw4 openclash ip daddr @localnetwork counter return
nft add rule inet fw4 openclash ct direction reply counter return
nft add rule inet fw4 openclash ip protocol tcp \
ip daddr {198.18.0.0/16} counter redirect to $proxy_port
nft add rule inet fw4 openclash ip daddr @wan_ac_black_ips counter return
nft add rule inet fw4 openclash th dport @wan_ac_black_ports counter return
nft add rule inet fw4 openclash ip saddr @lan_ac_black_ips counter return
nft add rule inet fw4 openclash ether saddr @lan_ac_black_macs counter return
nft add rule inet fw4 openclash th dport != @common_ports counter return
nft add rule inet fw4 openclash ip protocol tcp counter redirect to $proxy_port
openclash_mangle 链规则排序 (UDP TPROXY): 同上 #1-#10，最终规则：
nft add rule inet fw4 openclash_mangle ip protocol udp counter jump openclash_upnp
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 模式):
nft add rule inet fw4 openclash_mangle meta l4proto {tcp,udp} \
iifname utun counter return
nft add rule inet fw4 openclash_mangle ip protocol icmp \
icmp type echo-request counter meta mark set $PROXY_FWMARK
nft add rule inet fw4 openclash_mangle ip protocol udp counter jump openclash_upnp
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 虚拟网卡：
nft add rule inet fw4 openclash_mangle ip protocol icmp \
icmp type echo-request mark set "$PROXY_FWMARK" counter accept
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：
nft insert rule inet fw4 input position 0 ip protocol icmp \
icmp type echo-request ip daddr { 198.18.0.0/16 } counter reject
nft insert rule inet fw4 forward position 0 ip protocol icmp \
icmp type echo-request ip daddr { 198.18.0.0/16 } counter reject
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 内核按以下优先级处理：
- 目标是 Fake-IP 地址（
resolver.IsFakeIP(addr)） → 返回 nil, nil，内核用伪造的 echo-reply 回复。上层看到 "ping 成功" 但实际未经过网络，延迟显示为虚假的 ~0ms
- 目标是 TUN 接口自身 IP（
inet4_address / inet6_address 范围内） → 同上，伪造回复
disable-icmp-forwarding: true → 所有 ICMP 均伪造回复- 以上均不满足（真实 IP 且未禁用转发） → 通过
ping.ConnectDestination() 以 DIRECT 模式发出真实 ICMP 包，等待真实 reply。延迟为本地网络到目标的实际 RTT
- 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"
noowner="-m mark ! --mark 0x1a0a"
else
owner="-m owner --gid-owner 65534"
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 | 全部模式在 filter INPUT 链插入 QUIC REJECT 规则 (udp dport 443，根据 china_ip_route 匹配或排除中国 IP)，同时拦截下游客户端和路由器自身的 QUIC。IPv6 TUN 模式额外在 forward oifname utun 插入同规则以覆盖经 utun 转发的 IPv6 流量。规则触发仅依赖 disable_udp_quic，与 enable_udp_proxy/enable_v6_udp_proxy 无关。Mihomo 内核自身 QUIC（如 Hysteria 节点、DNS h3）不受影响——内核出站走 OUTPUT 链，不在规则范围内。 |
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 链，REJECT 来自 WAN 口对全部服务端口的访问：$proxy_port(7892)、$tproxy_port(7895)、$cn_port(9090)、$http_port(7890)、$socks_port(7891)、$mixed_port(7893)、$dns_port(7874) |
bypass_gateway_compatible (旁路网关（旁路由）兼容 / Bypass Gateway Compatible) | 1 | 创建 openclash_post 链，对已标记流量执行 MASQUERADE SNAT，解决旁路由回流问题 |
skip_proxy_address (绕过服务器地址 / Skip Proxy Address) | 1 | 看门狗定时调用 skip_proxies_address() 通过内核 API 解析代理节点 server 地址并加入 localnetwork nft set，复用链首 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 不被绕行规则跳过） |
UPNP 流量排除（无 UCI 选项，自动检测 /etc/config/upnpd 租约文件） | 系统已安装 upnpd | 创建 openclash_upnp 链，看门狗自动同步 upnpd 租约中的端口映射，匹配的 UDP 流量 RETURN 跳过代理，防止 BT/游戏等 UPnP 端口被错误代理 |
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 时执行):
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)"
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
uci set dhcp.@dnsmasq[0].filter_aaaa=0
load_ip_route_pass()
/usr/share/openclash/openclash_custom_domain_dns.sh
/etc/init.d/dnsmasq restart
恢复流程 (revert_dnsmasq()):
uci del dhcp.@dnsmasq[-1].server
for server in $(uci get openclash.config.dnsmasq_server); do
uci add_list dhcp.@dnsmasq[0].server="$server"
done
uci set dhcp.@dnsmasq[0].noresolv="$saved_noresolv"
uci set dhcp.@dnsmasq[0].resolvfile="$saved_resolvfile"
uci set dhcp.@dnsmasq[0].cachesize="$saved_cachesize"
if nslookup www.apple.com 127.0.0.1:<dnsmasq_port> 失败; then
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 尊重规则 (DNS Proxy) | 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-controllerdashboard_password — API 密钥，对应 Mihomo secretdashboard_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
- 前端访问地址（
status.htm JS 按 3 种场景构造）：
- 本地访问（浏览器 hostname 匹配 LAN IP）：
http://<lan_ip>:<cn_port>/ui/<dashboard>/
- 公网访问（设置了
dashboard_forward_domain + dashboard_forward_port）：http[s]://<domain>:<port>/ui/<dashboard>/（协议由 dashboard_forward_ssl 决定）
- 其他情况：取当前页面协议 +
lan_ip + cn_port
- 各仪表盘子路径：
/ui/dashboard/、/ui/yacd/、/ui/metacubexd/、/ui/zashboard/
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] 段和 [Overwrite] 段尝试覆盖，插件不保证覆写后的效果及工作逻辑正常。
| 强制设置 | 硬编码值 | 说明 |
|---|
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/Hysteria2/TUIC 等 QUIC 出站连接，无需因使用此类节点而关闭该选项。原因：所有模式（TUN/非TUN）下 QUIC REJECT 规则均在 filter INPUT 链 + IPv6 TUN 模式下额外在 FORWARD -o utun 链，Mihomo 内核自身出站 QUIC 走 OUTPUT 链，回复包的目标端口为临时端口（非 443），均不命中拦截规则。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()):
get_config() 读取 UCI en_mode，解析出 en_mode_tun（TUN 标记）、en_mode_fakeip（Fake-IP 标记）、en_mode_mix（混合标记）- 将这些传递给
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 (关闭)
- 说明: 绕过配置中服务器地址的代理，防止重复代理 (代理嵌套)
- 实现细节: 开启后看门狗脚本
openclash_watchdog.sh 中的 skip_proxies_address() 函数（每 30 个看门狗周期执行一次）解析 YAML 中所有代理节点（proxies 和 proxy-providers）的 server 地址，域名通过 openclash_debug_dns.lua 调用 Mihomo 内核 API（/dns/query）解析为 IP 后，加入已存在的 localnetwork nft set（或 ipset）。由于 openclash 链首条规则为 ip daddr @localnetwork counter return，这些代理服务器 IP 自动被跳过代理，防止代理嵌套。
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
- 说明: 强烈推荐启用「绕过中国大陆」。启用后，会在
fake-ip-filter 添加 rule-set:oc-cn-domain 规则集 (旧版本为 GeoSite 数据库中分类为 CN 的域名)，且解析 IP 位于大陆 IP 段范围内的流量将不进入内核，显著降低内核性能开销。旁路由模式下如果遇到大陆域名无法访问可尝试开启"旁路由兼容"选项
- Mihomo 对应: 通过
dns.fake-ip-filter 添加 rule-set:oc-cn-domain 规则集，使中国大陆域名返回真实 IP 而非 Fake-IP；同时自动注册对应的 rule-providers 条目指向 MetaCubeX geosite CN MRS 文件
- 实现细节（双重机制）: 1) YAML 层面:
yml_change.sh 修改 dns.fake-ip-filter——blacklist 模式（默认）追加 rule-set:oc-cn-domain，whitelist 模式移除 CN 相关过滤器，rule 模式前置 RULE-SET,oc-cn-domain,real-ip。效果：匹配的中国大陆域名返回真实 IP，绕过 Fake-IP 机制。2) 防火墙层面: set_firewall() 使用 chnroute IP 列表构建 nftables set（china_ip_route 或者 china_ip6_route），在 redirect/TPROXY 链中匹配国内真实 IP 直连 return。两层面互为补充——YAML fake-ip-filter 确保大陆域名获得真实 IP，防火墙 nft set 匹配这些真实 IP 使其跳过代理。
intranet_allowed — 仅允许内网 (Only Intranet Allowed)
- UCI 选项:
openclash.@openclash[0].intranet_allowed
- 默认: 1 (开启)
- 说明: 开启后控制面板和连接代理端口仅能从内网访问，不暴露到公网
- Mihomo 对应:
allow-lan: true + bind-address: "*"
- 实现细节: 双重保护——1) YAML 层面：
yml_change.sh 设置 allow-lan: true + bind-address: "*" 使内核监听所有接口。2) 防火墙层面：创建 openclash_wan_input 链，匹配来自 WAN 口（非 @localnetwork 源 IP）的流量，REJECT 全部 7 个服务端口（$proxy_port/$tproxy_port/$cn_port/$http_port/$socks_port/$mixed_port/$dns_port）。关闭时 allow-lan: false，内核仅监听 127.0.0.1，同时不创建 openclash_wan_input 链。
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 接口名称，用于通过
ip address show <接口> 获取路由器 LAN IP 地址（供控制面板地址显示、API 调用、调试日志等使用）。设为 0 则自动检测
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 — 绕过指定区域 IPv4 黑名单 (Chnroute Bypassed List)
- 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）和规则匹配（自定义规则走代理）两方面入手，详见错误速查表 §十四
UPNP 流量排除（无 UCI 选项，自动生效）
- 触发条件: 系统已安装并运行
upnpd（/etc/config/upnpd 存在且 upnp_lease_file 指向有效租约文件）
- 说明: 自动读取 upnpd 租约文件，为 UPnP 端口映射创建防火墙绕过规则，防止 BT/PT 下载、游戏主机等 UDP UPnP 流量被 TPROXY 错误代理
- 实现细节: 防火墙初始化阶段
set_firewall() 创建 openclash_upnp 链并在 openclash_mangle 链中通过 jump openclash_upnp（规则位置在最终 TPROXY 之前）。upnp_exclude() 函数读取 upnpd 租约文件（格式 UDP:<ext_port>:<int_ip>:<int_port>），为每条租约在 openclash_upnp 链中添加 ip saddr <int_ip> <proto> sport <int_port> counter return 规则。看门狗 openclash_watchdog.sh 每 30 个周期（首周期立即执行，之后每 UPNP_INTERVAL=30 即约 30 分钟）执行 UPNP 规则同步：① 清理过期规则——遍历 openclash_upnp 链现有规则，删除租约文件中已不存在的条目；② 添加新规则——读取租约文件，为新增的 UPnP 映射补充 RETURN 规则。
2.3 DNS 设置标签页 (dns)
生效路径: DNS 选项通过三条路径生效：
yml_change.sh 修改 YAML dns: 段 → Mihomo 内核使用change_dnsmasq() 修改系统 dnsmasq → LAN 客户端 DNS 被劫持到 Clashopenclash_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 默认配置:
- 设置
noresolv=0, localuse=1
- 恢复
resolvfile 为有效的 DNS 配置文件
- 若无有效配置则创建
/tmp/resolv.conf.d/resolv.conf.auto (114.114.114.114, 8.8.8.8)
- 重启 dnsmasq
enable_custom_domain_dns_server — 启用第二 DNS 服务器 (Enable Specify DNS Server)
- UCI 选项:
openclash.@openclash[0].enable_custom_domain_dns_server
- 默认: 0
- 说明: 为自定义域名列表指定专用 DNS 服务器，完全独立于内核 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 脚本在核心启动后被守护进程调用，
定期测试各流媒体服务的解锁情况，自动将策略组切换到支持该服务的节点。
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 服务形式启动（与核心并列）。工作流程：
- 读取 YAML 中所有策略组和节点，构建节点-策略组映射
- 对每个启用的流媒体服务，尝试用各节点连接服务域名（如
netflix.com）
- 检查 HTTP 响应码或页面内容判断是否解锁（如 Netflix 返回 200 且不含地区限制页面则解锁）
- 找到能解锁的节点后，通过 Mihomo API
PUT /proxies/{group} 自动切换策略组到该节点
- 定期重新测试（间隔可配置），节点失效时自动切换
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 enabled) | dashboard_forward_ssl | 0 | |
仪表盘版本管理通过 action_switch_dashboard → openclash_download_dashboard.sh 自动下载切换。
