kenzok8/openwrt-clashoo/clashoo-user-guide

Clashoo 专家指南

Clashoo 是 kenzok8 维护的 OpenWrt 代理管理插件，一个界面管三种内核：mihomo（稳定/Alpha）、Smart、sing-box（稳定/Alpha）。mihomo/Smart 走 YAML，sing-box 走 JSON，同一套 UCI 配置自动适配两端。

本指南分两层：

• 本文件：AI 排障要用、但用户向 Wiki 不该有的东西——系统架构、启动流程、防火墙/DNS 内部机制、日志报错解码、双内核内幕、排障方法论。
• `references/`：13 篇用户向 how-to（安装、导入配置、选内核、各页操作），与项目 GitHub Wiki 同源。回答「怎么操作」时查这里。

AI 行为准则

回答 Clashoo 问题前，先守住这几条：

1. 验证优先，不臆测。拿不准就查源码：核心逻辑在 clashoo/files/usr/share/clashoo/ 和 clashoo/files/etc/init.d/clashoo，UI 选项的真名在 clashoo/files/etc/config/clashoo（UCI），界面在 luci-app-clashoo/htdocs/luci-static/resources/view/clashoo/*.js。
2. 给 LuCI 操作路径，而非裸命令。用户多数不是工程师，先说「服务 → Clashoo → 概览 / 配置 / 系统」里点哪里，再在必要时补命令行。
3. 先看日志再下结论。三类日志（见下方「日志报错解码」）；让用户先贴 概览 状态行 + 系统 → 日志，再判断。
4. 双内核分开对待。同一个问题在 mihomo 和 sing-box 下机制不同（配置格式、DNS 接管、预检命令都不一样）。先确认 核心类型 = mihomo/Smart 还是 sing-box，再回答。
5. 隐私意识。让用户贴日志时提醒打码订阅链接、节点地址、dash_pass 等敏感信息。

系统架构速查

数据流向

LuCI 视图(.js: overview/config/system)
   │  通过 RPC
   ▼
ucode RPC 后端 (root/usr/share/rpcd/ucode/luci.clashoo)
   │  读写
   ▼
UCI 配置 (/etc/config/clashoo)
   │  init.d 与 runtime 脚本读取
   ▼
init.d/clashoo  ──►  runtime/*、net/*、update/*、lib/* 脚本
   │                      │
   │                      ├─ mihomo 路线：生成 /etc/clashoo/config.yaml → mihomo -t 预检 → procd 拉起
   │                      └─ sing-box 路线：normalize /etc/sing-box/config.json → sing-box check → /etc/init.d/sing-box
   ▼
内核进程 (mihomo / smart / sing-box)
   +  fw4 防火墙规则  +  dnsmasq 转发  +  健康检查

关键目录与文件

内核选择的两套字段（重要）

界面选内核写的是 `core_type` + `dcore`，启动时再同步出一个遗留字段 `core` 供老逻辑用（见 sync_legacy_core_field）：

排障要点：新安装默认选 mihomo 稳定版；/usr/bin/mihomo 和 /usr/bin/clash-meta 是随包稳定版的兼容软链。旧配置选 Alpha 时必须存在独立 Alpha 文件，否则启动前会提示缺少内核。sing-box 稳定/Alpha 通过软链 /usr/bin/sing-box 共存切换。

procd 进程身份（为什么不能 pidof）

OpenClash / nikki / passwall 可能和 Clashoo 共用同名二进制（mihomo、sing-box）。Clashoo 从不用 `pidof` 判断进程，一律查 ubus call service list：

• mihomo 路线：进程注册在 procd 服务名 `clashoo` 下（_clashoo_instance_pid）。
• sing-box 路线：Clashoo 不自己拉起，而是托管系统的 `/etc/init.d/sing-box`（procd 服务名 sing-box，_singbox_instance_pid），启动前把 sing-box.main.enabled 置 1、停止时置 0。boot() 阶段会先把它强制置 0，避免它在 Clashoo 准备好配置/防火墙前抢跑。

系统启动完整流程

/etc/init.d/clashoo start → start_service()，按所选内核分两条路。

公共前置

1. sync_legacy_core_field：由 core_type/dcore 同步出 core。
2. _detect_selected_core：按上表探测可用二进制。
3. cleanup_legacy_startup_backups + migrate_legacy_clash_dir：清理历史残留、把老的 /etc/clash 迁到 /etc/clashoo。
4. resolve_effective_tp_modes：算「生效的」TCP/UDP 模式。选了 TUN 但设备无 `/dev/net/tun` → 自动降级（TCP→redirect、UDP→tproxy），并在状态机记 degraded=1。
5. runtime_state_record_preflight：把生效模式、是否有 tun、降级原因写进 /tmp/clashoo/runtime_state。

mihomo / Smart 路线

1. select_config：把所选配置文件拷为 /etc/clashoo/config.yaml，空/缺直接失败。
2. _require_runtime_network_stack：检查 fw4 / nft / ip 齐全。
3. _start_validate_core：对应内核二进制不存在就报错退出。
4. _start_prepare_config（core-only 模式跳过整段）：

• check：把 Proxy: / Rule: 等老式大写键名 sed 成标准 proxies: / rules:。
• 展开 YAML merge anchor（<<:，yq 4.53+ 会破坏，先 explode(.)）。
• yml_change：用 runtime/mixin.uc 生成 mixin 片段，yq 深合并进 config.yaml（端口、allow-lan、external-controller、DNS 等运行参数注入）。
• dns_mihomo_apply_leak_protect：若开 DNS 防泄漏，改写 DNS 段。
• smart_inject：仅 `core=1`（Smart） 时把 url-test/load-balance 组改成 type: smart 并注入 policy-priority / prefer-asn / uselightgbm / collectdata / sample-rate、profile.smart-collector-size、顶层 lgbm-*。非 Smart 内核会反向清除这些字段。
• _prepare_geo_bootstrap_mode：若配置需要 GeoIP/GeoSite 但本地数据缺失/损坏，临时剥离 geo 规则先启动（bootstrap 模式），并记 /var/run/clashoo_bootstrap_pending。
• yml_dns_change：按 dnsforwader/dnscache/listen_port 改 dnsmasq（先 backup_dnsmasq_state 存原状）。
• 拷到工作目录 + ip_rules。

1. _start_launch_core：

• `mihomo -t` 预检（15s 看门狗）。失败不碰防火墙/dnsmasq；超时（退出码 124）多半是在下载 geo 数据，会异步补 geo 并稍后重试。
• procd_open_instance 拉起内核（disable_quic_gso=1 时注入 QUIC_GO_DISABLE_GSO=1，只影响 quic-go GSO；core-only 注入 SAFE_PATHS=/）。
• 非 core-only：fw4.sh apply → 重启 dnsmasq → restore → add_cron。
• 后台看门狗等内核出现：出现则跑健康检查 + 立即触发访问检查 + 完成 bootstrap geo 补全；超时未出现则 `_rollback_failed_start` 回滚防火墙与 DNS（否则会留下指向无人监听端口的劫持 DNS）。

sing-box 路线

1. start_singbox_service：

• _sync_singbox_binary：按 dcore 把 /usr/bin/sing-box 软链到 stable/alpha。
• prepare_singbox_runtime：把所选 profile 拷为 /etc/sing-box/config.json，删旧 cache.db；非 core-only 用 ucode normalize_singbox_config.uc 改写端口/routing_mark=6666/DNS 端口/面板端口密码/tun 探测；core-only 只跑 migrate_singbox.uc 做版本迁移。写 sing-box.main（conffile/workdir/user）。
• `sing-box check` 预检（15s 看门狗）。失败/超时不碰防火墙与 DNS。
• /etc/init.d/sing-box start。

1. 非 core-only：fw4.sh apply → singbox_dns_change → add_cron。
2. _wait_core_alive ... sing-box：窗口内死掉就 _rollback_failed_start。
3. 健康检查（settle 异步复检）。

启动等待窗口

_compute_start_wait：TUN 模式 15s、其它 6s（TUN 要等 utun 建好 + fake-ip 池初始化）。慢设备可 uci set clashoo.config.start_wait_secs=N 覆盖。

core-only（仅内核）模式

core_only=1 时 Clashoo 只保活内核进程，原样运行用户导入的配置，不接管防火墙/DNS/cron，并放宽 SAFE_PATHS=/（信任用户自带配置里的绝对路径，如 OpenClash 的 external-ui）。详见 references/仅内核.md。

防火墙与 DNS 内部机制

fw4 防火墙（net/fw4.sh）

只支持 fw4 + nft（无 iptables 后端）。通过 UCI firewall.* include 段挂三张表，apply/remove 成对操作：

另有本机出站表 clashoo_local（ip 族，仅 redirect 模式），让路由器自身流量也走代理。

QUIC 两个开关不重叠：

• disable_quic_gso=1：启动 mihomo / Smart 时注入 QUIC_GO_DISABLE_GSO=1，关闭 quic-go 的 GSO 批量发送能力。它是核心兼容性开关，用来绕过部分内核、网卡、虚拟化环境的 UDP GSO 问题，不会阻断 QUIC。
• block_quic=1：创建防火墙表 clashoo_quic，拒绝走代理链路里的 UDP 443，让客户端尽快回落 TCP。它是访问兼容性开关，只在下载、视频或应用卡在 QUIC 时尝试。

QUIC 阻断表 `clashoo_quic`（block_quic=1 时建，inet 族，prerouting hook priority mangle - 1 + forward hook priority -10）：ip daddr <fake-ip 段> udp dport 443 reject with icmpx type port-unreachable。

• 必须 reject 发 ICMP，不能 drop：drop 与「机场黑洞掉 UDP 443」无法区分，客户端照样干等。mihomo 规则里的 REJECT 对 UDP 也是静默丢包，同样无效。
• 优先级要抢在 fw4 之前：mihomo 的 auto-redirect 会在 fw4 forward 链顶部 accept 所有 tun 流量。
• 只挂 forward，不能挂 output：output 会打死内核自己连 Hysteria2/TUIC 节点的 UDP 443。
• 限定 fake-ip 目标 = 只拦走代理的 QUIC，国内直连 QUIC 不受影响（非 fake-ip 模式回退用 clashoo_china 集合排除）。

两个关键 fwmark（不能混用）：

• PROXY_FWMARK = 0x162：入站 TProxy 标记 → ip rule fwmark 0x162 table 0x162 → local 0.0.0.0/0 dev lo。
• CORE_ROUTING_MARK = 0x1a0a（=6666）：内核出站 SO_MARK（= mihomo routing-mark / sing-box routing_mark）。
• 两者必须不同，否则内核出站被拉回 lo → 全网不可达。改其一须同步 fw4.sh 与 normalize_singbox_config.uc。

透明代理模式如何落到规则：

• redirect：DSTNAT 链 redirect to :redir_port（默认 7891）。
• tproxy（TCP/UDP）：mangle 链 tproxy to :tproxy_port（默认 7982）+ 打 0x162 + ip rule/ip route。
• tun：内核自己接管；启用分组 ACL 时 nft 只写分组匹配和直连绕过标记，无 tun 设备时自动回落 redirect/tproxy。
• tcp_mode、udp_mode 和 stack 是独立字段；stack 只在 TCP 或 UDP 至少一个为 tun 时生效。常见组合：默认 TCP Redirect + UDP TProxy + gVisor，也可用 TCP Redirect + UDP TUN + Mixed，或 TCP TUN + UDP TUN + System/Mixed/gVisor。

绕行（bypass）：本地网段、中国 IP（bypass_china=1 控制 IPv4 geoip_cn.nft，bypass_china_ipv6=1 控制 IPv6 geoip6_cn.nft；IPv6 字段缺失时回退旧 bypass_china）、分组 ACL、自定义端口（bypass_port_mode：all/common/custom）、DSCP、fwmark。分组 ACL 按从上到下匹配，行内 IPv4、IPv6、MAC 任一命中即采用该组的 DNS 和代理开关；空匹配项代表全部设备，未命中默认接管 DNS 并走代理。旧白名单会迁移成“名单代理 + 其余直连”，旧黑名单会迁移成“名单直连 + 其余代理”。共存：自动把 passwall(0x1)/passwall2(0xff)/nikki(tproxy/tun mark) 的标记并入 bypass，避免互相截流。

三个 IPv6 / 绕过开关怎么选（回答用户提问用）

IPv6 DNS 必须开（默认已是 true）。它关着而 ipv6_proxy=1 时，防火墙把 v6 交给内核、内核却不认 v6，境内外 IPv6 全部失效。

两个绕过必须同开或同关，不要一开一关：混搭会让同一站点的 v4 走直连、v6 走代理，对外露出两个不同源地址。

「都勾」成立的前提：「Fake-IP 过滤域名」里要有 rule-set:cn_domain（默认带）。它让国内域名返回真实 IP，从而与游戏等下发的硬编码 IP 走同一条直连路径；缺了它国内域名会走 fake-ip 进内核，同一应用的连接被分到两条路上，端游可能偶发掉线。

DNS 接管