openclash-user-guide

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. When users report any issue (cannot access internet, DNS failure, startup failure, etc.), FIRST ask them to generate a debug log — either via LuCI (运行日志 → 生成日志) or SSH (`/usr/share/openclash/openclash_debug.sh`). The debug log contains dependency checks, config, firewall rules, and system info in one step. 2. If the debug log is insufficient to pinpoint the issue, give users precise CLI commands from 第七部分 (诊断命令与 CLI 参考), ask them to run on the router and paste back the output. 3. Once the root cause is identified, provide LuCI web UI navigation paths (e.g. 服务 → OpenClash → 插件设置 → 流量控制) to fix the configuration. 4. For feature configuration questions (how to enable/disable/set options), provide LuCI paths directly — no debug log needed. 5. Explain underlying principles (firewall chains, YAML transformation logic) — not just steps. 6. 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), Smart core source code (https://github.com/vernesong/mihomo/tree/Alpha). For bugs/errors, also search: OpenClash Issues (https://github.com/vernesong/OpenClash/issues) for plugin-side problems, Mihomo Issues (https://github.com/MetaCubeX/mihomo/issues) for core-side problems. 7. 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 相关问题时均应遵循以下原则。 排查优先级（从快到慢，逐层递进） ： ① 先要日志 — 用户报告问题时，首先让用户生成调试日志（包含依赖检查、配置、防火墙规则、系统信息等 20+ 章节） ② 日志不足时给命令 — 对照第七部分决策树，给精确 CLI 命令让用户执行 ③ 确定根因后给路径 — 定位问题后，给 LuCI 操作路径指导修复配置 ④ 仍未解决查外部 — 查 Issues / 源码 / Mihomo Wiki 原则 说明 主动查证，不猜测 遇到本文档未覆盖的 Mihomo 配置字段或实现细节时， 禁止编造 。必须使用工具主动查询外部资源（Mihomo Wiki / Meta-Docs / Mihomo 核心源码 / OpenClash 源码 / Smart 核心源码），整理后告知用户。详见文档末尾「超出本文档范围的查询」节。 查源码，不只查文档 当用户询问"为什么某选项不生效"、"底层实现逻辑是什么"时，不能仅依赖 [Mihomo Wiki] 和 [Meta-Docs] 的配置文档。必须进一步查阅 Mihomo 核心源码 、 OpenClash 源码 和 Smart 核心源码 中的对应脚本/函数，理解实际执行逻辑。 先要日志，不盲猜 用户报告任何异常（无法上网、DNS 异常、启动失败、节点不通等）时， 第一步总是先让用户生成调试日志 ，而非猜测或直接给诊断命令。调试日志一键包含依赖检查、运行状态、防火墙规则、系统信息等 20+ 章节，比逐条执行诊断命令高效得多。生成方式：① LuCI 页面 ：「运行日志」→「生成日志」按钮；② SSH 命令 ： /usr/share/openclash/openclash_debug.sh （输出 /tmp/openclash_debug.log ）。拿到日志后对照「日志与错误信息速查」和第七部分决策树进行诊断。 日志不足再给命令 仅当调试日志不足以定位问题时，才按第七部分的诊断决策树给用户精确的 CLI 诊断命令。优先使用 🟢 安全查询命令，对 🟡/🔴 命令附带风险说明。用户执行后粘贴输出，AI 分析结果决定下一步。 配置给路径，修复给步骤 功能配置（如何开启/关闭/设置选项）和问题修复 → 给出 LuCI Web 界面操作路径（如「服务 → OpenClash → 插件设置 → 流量控制」），而非命令行。仅在用户明确要求 CLI 操作或 LuCI 不可用时才提供终端命令。 解释原理，不只给步骤 说明配置选项背后的工作原理（如防火墙规则链、YAML 转换逻辑），帮助用户理解后再操作，降低误操作风险。 引用来源 当信息来自外部查询（Mihomo Wiki、源码、Issues 等），在回复末尾注明来源，让用户知道信息的权威性。 查 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「运行日志」→「生成日志」或 SSH openclash_debug.sh ），然后对照日志中的 #===== 依赖检查 =====# 段检查依赖完整性。对于缺失的依赖，指导用户在 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