clash-for-linux

✨ 核心特性

• 🚀 自动识别系统架构：自动下载并使用对应 Clash 内核
• 🧪 端口自动检测与分配：避免冲突
• 🔄 多订阅管理：可以保存多个订阅，通过 clash use 切换当前主订阅。
• 💫 节点选择：使用编号交互选择策略组和节点。
• 🌐 Tun 模式：用于透明代理接管场景（需root方式安装）。
• 🧠 Mixin 机制：可按需追加/覆盖 Clash 配置
• 👤 不同权限：兼容 root 与普通用户环境。
• 🔐 安全默认配置：自动生成或自定义 Secret
• 🩺 内置诊断工具（doctor）：快速排障

适用场景

• Linux 云服务器（VPS / 远程开发环境）
• 本地开发环境（Ubuntu / Debian / WSL）
• 路由 / 轻量系统（OpenWrt / NAS / 小主机 x86 / ARM）
• 需要稳定访问 GitHub、Go / Node / Docker 生态的开发者
• 不希望手动维护 Clash 运行状态的用户

🚀 一键安装（推荐）

在终端中执行以下命令即可完成安装：

git clone --branch master --depth 1 https://ghfast.top/https://github.com/wnlen/clash-for-linux.git
cd clash-for-linux
bash install.sh

• 上述命令使用了加速前缀，如失效可更换其他可用链接。
• 可通过 .env 文件或脚本参数自定义安装选项。
• 在 WSL 环境中，不支持放在 Windows 挂载目录**/mnt/c/**下，请安装到 Linux 原生目录。

---

⌨️ 命令一览

〽️ 常用命令
  clashon           🚀 开启代理
  clashoff          ⛔ 关闭代理
  clash select      💫 选择节点
  clash mode        🧭 查看或切换路由模式
  clashtest         🌐 测试当前节点访问 Google / YouTube
🕹️  控制台
  clashui           🕹️  查看 Web 控制台
📦 订阅
  clash add          ➕ 添加订阅
  clash add local    ➕ 从 runtime/subscriptions 导入本地订阅
  clash use          💱 切换订阅
  clash ls           📜 查看订阅列表
🔐 密钥管理
  clash secret       🔑 查看密钥
  clash secret 123   🔐 设置密钥
📌 高级
  clash lan          🏠 局域网代理管理
  clash ipv6         🌐 IPv6 / IPv6-only 节点管理
  clash tun          🧪 Tun 模式管理（需root方式安装）
  clash boot         🚦 开机代理接管管理
  clash mixin        🧩 Mixin 配置管理
  clash relay        🔗 多跳节点管理
  clash sub          🧩 订阅高级管理（启用 / 禁用 / 重命名 / 删除）
  clash upgrade      🚀 升级当前或指定内核
  clash update       🔄 更新项目代码
📜 日志
  clash doctor       🩺 诊断面板
  clash log/logs     📜 查看日志

💡 显示更多帮助命令：clash -h

clashctl 旧入口继续保留兼容；新文档、帮助和终端提示统一使用更简洁的 clash。

---

🧭 路由模式与节点连通性

clash mode
clash mode global
clash mode rule
clash mode direct

clash test
clashtest
clashtest "节点选择"

• clash mode 查看当前的 Clash 路由模式，支持切换 rule、global、direct。
• global 模式使用 GLOBAL 策略组当前选择的策略组或节点；如需调整可执行 clash select。
• clash test 与 clashtest 等价，默认测试当前路由模式对应的策略组当前选择能否访问 Google 和 YouTube，并显示延迟。
• 连通性测试不会切换节点；任一目标不可访问时命令返回非零状态，便于脚本判断。

---

🌐 Web 控制台

$ clashui
╔═══════════════════════════════════════════════╗
║                🐱 Web 控制台                  ║
║═══════════════════════════════════════════════║
║                                               ║
║     🔓 注意放行端口：9090                      ║
║     📶 状态：可访问                            ║
║     🏠 内网：http://192.168.0.1:9090/ui       ║
║     ☁️ 公共：http://board.zash.run.place      ║
║     🌏 公网：http://8.8.8.8:9090/ui           ║
║     🔑 密钥：dada289edb457b59                 ║
║                                               ║
╚═══════════════════════════════════════════════╝

$ clashsecret mysecret
🐱 密钥更新成功，已重启生效

$ clashsecret
🐱 当前密钥：mysecret

• 可通过浏览器打开 Web 控制台进行可视化操作，例如切换节点、查看日志等。
• clash secret 与 clashsecret 都支持无参数查看、有参数直接设置。
• 默认使用 zashboard 作为控制台前端，如需更换可自行配置。
• 控制台中的“浏览器出口 IP”由访问面板的浏览器发起查询，可能与远端 Mihomo 的代理出口不同；远端出口请在服务器上通过本地代理端口查询。
• 运行配置会把 external-ui 指向本地 Dashboard 目录，并把 external-ui-url 指向 zashboard 的 dist.zip 下载地址；面板内 /upgrade/ui 会使用该地址更新前端。
• 若需将控制台暴露到公网，建议定期更换访问密钥，或通过 SSH 端口转发方式进行安全访问。

---

🏠 局域网代理

项目默认开启局域网代理：运行配置会写入 allow-lan: true，并把 external-controller 绑定到 0.0.0.0，避免订阅文件里的 allow-lan: false 覆盖项目默认值。

clash lan status
clash lan on
clash lan off

开启后，同一局域网设备可把 HTTP / SOCKS 代理地址设置为 http://<本机局域网IP>:<mixed-port>，端口默认是 7890；如访问不了，请检查系统防火墙是否放行该端口。

---

🌐 IPv6 / Hysteria2

Mihomo 支持 Hysteria2。若节点服务端只有 IPv6 地址，需要同时启用内核 IPv6 与 DNS AAAA：

clash config kernel mihomo
clash ipv6 on
clash ipv6 status

其他可用操作：

clash ipv6 off
clash ipv6 auto

• on：同时写入 ipv6: true 和 dns.ipv6: true。
• off：同时关闭内核 IPv6 与 DNS AAAA。
• auto：保留订阅原有的 IPv6 设置；订阅未配置时继续使用兼容默认值。
• 使用 IPv6-only 节点前，宿主机仍需具备可用的 IPv6 默认路由。HY2 使用 UDP / QUIC，网络或防火墙也必须允许相应 UDP 流量。

也可以在 .env 中设置 CLASH_IPV6=true、false 或 auto，然后执行 clash config regen。

---

OpenWrt 下 root/system 安装会把 clash、clashon、clashoff 等命令入口写入 /usr/bin，运行状态、日志和内核二进制仍保存在项目目录的 runtime/ 下。仅脚本模式不会注册开机自启，设备重启后需要重新执行 clashon。

🧰 常用管理命令

多订阅管理

clash add <订阅链接> <名称>
clash use
clash ls
clash sub update
clashsub update                 # 兼容旧版命令
clash sub
clash sub list
clash sub enable <名称>
clash sub disable <名称>
clash sub rename <旧名称> <新名称>
clash sub remove <名称>

WSL / 普通用户如果无权写入 /etc/environment，clashon 会自动降级：运行时照常启动，当前 Shell 代理变量生效；系统代理持久接管和开机代理保持不可用。

本地配置导入

推荐使用交互导入，放置目录为：$PROJECT_DIR/runtime/subscriptions/

clash add local
# 输入：clash.yaml

实际等价于：

clash add "file://$PROJECT_DIR/runtime/subscriptions/clash.yaml"

进阶用法：也可以直接使用 file:// 绝对路径导入：

clash add "file:///绝对路径/clash.yaml" home

支持格式：

• Clash / Mihomo YAML
• Base64 订阅
• 分享链接（vmess / vless / trojan / tuic / hysteria2 / hy2 / anytls）

开机接管（内核 + 代理）

clash boot status
clash boot on
clash boot off
clash boot runtime on|off|status
clash boot proxy on|off|status

• boot runtime：只管理内核开机自启（systemd / systemd-user 可用，script 后端为 unsupported）。
• boot proxy：只管理 /etc/environment 中的代理持久块（决定开机后是否自动保持代理变量）。
• boot：整体接管开关，等价于同时编排 runtime + proxy 两层状态。

---

OpenWrt 脚本模式

当前提供 OpenWrt 脚本模式兼容，适合 x86_64/amd64 与 aarch64/arm64 软路由或设备。该模式复用现有 script 运行后端，不包含 procd 开机自启、LuCI、UCI 或 opkg 包化支持，也不承诺 MIPS 与 armv7 设备可用。

建议先将项目放到持久化目录，避免放在 /tmp、/run 等重启会丢失的位置：

cd /root
git clone --branch master --depth 1 https://ghfast.top/https://github.com/wnlen/clash-for-linux.git
cd clash-for-linux

安装依赖：

opkg update
opkg install bash curl tar gzip coreutils-readlink unzip

安装与手动管理：

bash install.sh
clashon
clash status
clashoff

OpenWrt 下 root/system 安装会把 clash、clashon、clashoff 等命令入口写入 /usr/bin，运行状态、日志和内核二进制仍保存在项目目录的 runtime/ 下。仅脚本模式不会注册开机自启，设备重启后需要重新执行 clashon。

🏗️ 架构设计架构简述

项目当前可以按三层理解：

Control

用户入口层。

• clash
• clashon
• clashoff
• status
• doctor
• ui
• select

Control 层负责把常用动作收口成可理解的命令和反馈。

Build

配置生成层。

• 多订阅保存
• 单 active 主订阅
• active-only 编译链
• 订阅下载 / 转换 / 校验
• runtime/mixin.yaml 运行补丁（兼容读取 config/mixin.yaml）
• 输出 runtime/config.yaml

当前规则很明确：generate_config 只处理当前 active 主订阅。

Runtime 说明（重要）

runtime/ 是运行时目录，不是配置目录。

它的作用是作为“唯一运行容器”，用于存放：

- 运行内核（mihomo / clash） - 运行配置（config.yaml） - 订阅状态（subscriptions.yaml） - dashboard 前端 - 日志（logs） - 构建中间文件（tmp）

这些内容都是 install / 运行过程中动态生成的，不会作为仓库内容长期维护。

配置说明

.env

.env 用于覆盖安装和运行参数。常用项包括：

KERNEL_TYPE=mihomo
MIXED_PORT=7890
EXTERNAL_CONTROLLER=0.0.0.0:9090
CLASH_CONTROLLER_SECRET=your-secret
CLASH_SUBSCRIPTION_URL=https://example.com/sub
MIHOMO_VERSION=v1.19.23
CLASH_VERSION=v1.18.0
YQ_VERSION=v4.52.4
SUBCONVERTER_VERSION=v0.9.9
MIHOMO_DOWNLOAD_BASE=https://github.com/MetaCubeX/mihomo/releases/download
CLASH_DOWNLOAD_BASE=https://github.com/WindSpiritSR/clash/releases/download
CLASH_BUNDLED_ASSET_ENABLED=true
CLASH_GH_PROXY_ENABLED=true
CLASH_OFFLINE=false
CLASH_SHELL_AUTO_RESTORE_PROXY=true
CLASH_PREDOWNLOAD_GEO=true
CLASH_IPV6=auto

按需设置即可，不需要每项都写。

• CLASH_SHELL_AUTO_RESTORE_PROXY：控制登录 Shell 是否自动恢复上次 clashon 写入的代理变量。默认 true 保持兼容；如果不希望 SSH 远程登录后自动带上 http_proxy / https_proxy，设为 false，之后仍可手动执行 clashon。
• CLASH_PREDOWNLOAD_GEO：控制安装期是否预下载 GEO 数据。默认 true，会提前下载 Country.mmdb、geoip.metadb、GeoIP.dat、GeoSite.dat 等规则分流常用资源；临时部署、只想先跑起来时可设为 false 跳过安装期预下载。注意：当最终运行配置实际使用 GEOIP 规则时，启动前仍会按需准备 Country.mmdb，否则 Mihomo 无法可靠加载该配置。
• CLASH_IPV6：可设为 true、false 或 auto。true 同时启用内核 IPv6 与 DNS AAAA，适用于 IPv6-only 节点；auto 保留订阅中的 IPv6 设置。
• CLASH_SUBSCRIPTION_UA：覆盖拉取订阅时的 User-Agent。默认使用 clash-verge/v2.4.0，以便订阅服务返回 Mihomo 支持的 Hysteria2、AnyTLS 等现代协议节点；如果服务商有专用 UA 要求，可在此显式设置。

GitHub 下载加速

所有来自 GitHub 的资源（内核、按需 GEO 数据、yq、subconverter、Dashboard）在下载时会自动尝试内置镜像池（gh-proxy.org、ghfast.top、ghproxy.net、kkgithub.com），无需额外配置即可加速。

如果当前网络可以稳定直连 GitHub，可在 .env 中关闭镜像，只使用 GitHub 原站：

CLASH_GH_PROXY_ENABLED=false

如果默认镜像不满足需求，可在 .env 中指定自定义加速前缀：

# 单个自定义镜像（优先于内置镜像池）
CLASH_GH_PROXY=https://ghfast.top

# 自定义镜像池（完全替换内置池，格式：label|prefix|mode，mode 可选 full/hostpath）
# CLASH_GH_PROXY_POOL="mymirror|https://mirror.example.com|full"

可用镜像列表参考：https://ghproxy.link/
当前镜像使用状态可通过 clash doctor 查看。

该开关只控制 bash install.sh、clash update、clash upgrade 等脚本下载的 GitHub 资源，不会改变此前用于获取项目代码的 git clone 地址。如需从原站克隆，请使用：

git clone --branch master --depth 1 https://github.com/wnlen/clash-for-linux.git

内置运行依赖

当前正式支持的架构为 amd64、arm64、armv7。超出这三种架构时会明确失败，不会伪装成已支持。

如果安装环境访问 GitHub 很慢，可以把 Mihomo/Clash、yq、subconverter 的刚需文件跟随项目一起分发。安装和 clash upgrade 会优先读取 resources/bin 中与当前版本、架构对应的精确文件名；普通在线模式下，本地没有对应文件时会回退到远程下载。

推荐路径直接放在分类目录下：

resources/bin/mihomo/mihomo-linux-amd64-compatible-v1.19.23.gz
resources/bin/mihomo/mihomo-linux-arm64-v1.19.23.gz
resources/bin/mihomo/mihomo-linux-armv7-v1.19.23.gz
resources/bin/clash/clash-linux-amd64-v1.18.0.gz
resources/bin/clash/clash-linux-arm64-v1.18.0.gz
resources/bin/clash/clash-linux-armv7-v1.18.0.gz
resources/bin/yq/yq_linux_amd64.tar.gz
resources/bin/yq/yq_linux_arm64.tar.gz
resources/bin/yq/yq_linux_arm.tar.gz
resources/bin/subconverter/subconverter_linux64.tar.gz
resources/bin/subconverter/subconverter_aarch64.tar.gz
resources/bin/subconverter/subconverter_armv7.tar.gz
resources/geo/Country.mmdb

版本仍由 .env 中的 MIHOMO_VERSION、CLASH_VERSION、YQ_VERSION、SUBCONVERTER_VERSION 控制。脚本不会扫描目录，也不会自动选择最高版本；如果升级版本，请同步放入新版本对应文件，或让脚本回退到远程下载。

也可以设置 CLASH_BUNDLED_ASSET_ENABLED=false 强制跳过内置文件，或用 CLASH_BUNDLED_ASSET_DIR=/path/to/assets 指向项目外的资源目录。Mihomo、yq、subconverter 兼容旧路径 resources/bin/<category>/<version>/<file>。

离线资源包

推荐在有代理或网络较好的设备上，按目标主机架构生成资源包：

# 查看将要下载的文件，不产生网络请求
bash scripts/prefetch-assets.sh --arch amd64 --dry-run

# 生成 amd64 + Mihomo 资源包
bash scripts/prefetch-assets.sh \
  --arch amd64 \
  --kernel mihomo \
  --output clash-assets-mihomo-amd64.tar.gz

支持的目标架构为 amd64、arm64、armv7。脚本默认包含内核、yq、subconverter 和五个 GEO 文件，只打包 resources/ 静态资源，不会把本机的订阅、日志、密钥或其他 runtime/ 状态带入资源包。压缩包同时包含版本/架构清单与 SHA256SUMS。

把项目和资源包复制到目标主机，在项目根目录执行：

tar -xzf clash-assets-mihomo-amd64.tar.gz
bash install.sh --offline

--offline 等价于本次安装设置 CLASH_OFFLINE=true。安装脚本会先集中检查架构、版本、校验和及所有必需文件；有任何缺失都会明确列出并停止，不会静默回退到 GitHub。也可以和安装范围一起使用：

bash install.sh system --offline
bash install.sh user --offline

严格离线安装时，订阅也不能使用远程 URL。可暂时不配置订阅，或者提前准备 Clash YAML 并通过 file:///绝对路径/config.yaml 导入。使用 --no-geo 生成精简资源包时，目标项目还需要设置 CLASH_PREDOWNLOAD_GEO=false；若最终配置使用 GEOIP，仍须提供 Country.mmdb。

runtime/mixin.yaml（兼容 config/mixin.yaml）

用于对最终运行配置做补丁：

• override 覆盖字段
• prepend 把数组项放到原始配置前面
• append 把数组项放到原始配置后面

查看当前模板：

clash mixin

编辑：

clash mixin edit

查看最终运行配置：

clash mixin runtime

---

🔄 更新

clash update
clash upgrade
clash upgrade mihomo
clash upgrade clash

update 用于更新项目代码与运行依赖。upgrade 用于升级当前或指定代理内核。

---

🧩 Mixin 配置

clash mixin
clash mixin edit
clash mixin raw
clash mixin runtime

Mixin 是运行配置补丁，不是订阅管理。它优先通过 runtime/mixin.yaml（兼容读取 config/mixin.yaml）对当前 active 订阅生成的运行配置执行：

• override
• prepend
• append

示例：

override:
  dns:
    enable: true

prepend:
  proxies: []
  proxy-groups: []
  rules:
    - DOMAIN-SUFFIX,example.com,DIRECT

append:
  proxies: []
  proxy-groups: []
  rules:
    - MATCH,节点选择

编辑后执行：

clash mixin edit

它会重新生成配置；如果代理正在运行，会自动重启应用。

多跳节点

多跳节点会写入 runtime/mixin.yaml（兼容读取 config/mixin.yaml），通过 Mihomo/Clash 的 relay 策略组串联已有订阅节点。节点名称必须与订阅生成的节点名完全一致，可先通过 Web 控制台确认：

clashon
clashui

按域名小范围测试：

clash relay add 多跳-示例 节点A 节点B --domain example.com
clash relay list

也可以使用快捷入口：clashrelay list。

全局接管：

clash relay add 全局多跳 节点A 节点B --match

--match 会让所有未提前命中的流量走多跳，建议先用 --domain 验证链路。删除多跳配置：

clash relay remove 多跳-示例

---

🌐 Tun 模式

clash tun on
clash tun off
clash tun on-proxy-off
clash tun off-proxy-on
clash tun doctor
clash tun logs

Tun 用于透明接管链路。tun on 只负责开启 Tun，不会自动关闭系统代理；如需切换到 Tun 接管并关闭系统代理，使用 clash tun on-proxy-off。如需关闭 Tun 并恢复普通系统代理模式，使用 clash tun off-proxy-on。

clash doctor 会检查 Tun 与系统代理是否同时开启；如果同时开启，会提示 clash tun on-proxy-off，避免流量接管路径重复或排障混淆。

tun on 是动作反馈，展示当前关键配置和简短状态；完整证据请看：

clash tun doctor

Tun 判断不会简单把 root 等同于拥有 CAP_NET_ADMIN，也不会把 main table 默认路由未切换直接等同于 Tun 未生效。诊断会结合运行后端、容器环境、进程能力、Tun adapter、policy routing、路由表和日志证据。

---

🧹 卸载

bash uninstall.sh

默认执行完整卸载：停止 mihomo/subconverter，关闭系统代理持久接管，删除 systemd/脚本入口、clash、命令补全、shell alias、shell proxy 持久状态、controller secret 和运行目录。完整卸载完成后，脚本会提示其他卸载方式。

--purge-runtime 保留为兼容别名；默认卸载已经会清理运行目录。

如需只移除入口并保留 runtime/ 数据：

bash uninstall.sh --keep-runtime

开发调试时只清安装状态、保留订阅与下载缓存：

bash uninstall.sh --dev-reset

如需完整卸载后连项目目录也移走：

bash uninstall.sh --remove-project

该命令会要求输入完整项目路径确认，并把项目目录移动到 ~/.local/share/clash-for-linux-backups/ 下，便于误操作恢复。非交互脚本可显式传入 --yes。

设置代理

1. 开启 IP 转发

echo "net.ipv4.ip_forward = 1" | tee -a /etc/sysctl.conf
sysctl -p

2.配置iptables

# 先清空旧规则
iptables -t nat -F

# 允许本机访问代理端口
iptables -t nat -A OUTPUT -p tcp --dport 7890 -j RETURN
iptables -t nat -A OUTPUT -p tcp --dport 7891 -j RETURN
iptables -t nat -A OUTPUT -p tcp --dport 7892 -j RETURN

# 让所有 TCP 流量通过 7892 代理
iptables -t nat -A PREROUTING -p tcp -j REDIRECT --to-ports 7892

# 保存规则
iptables-save | tee /etc/iptables.rules

3. 让 iptables 规则开机生效 在 /etc/rc.local（或 /etc/rc.d/rc.local）加上：

#!/bin/bash
iptables-restore < /etc/iptables.rules
exit 0

chmod +x /etc/rc.local

🔗 引用

• clash
• mihomo
• subconverter
• zashboard

参考与致谢

本项目在持续优化 Linux Clash / Mihomo 使用体验的过程中，参考了社区中一些优秀项目的命令行交互风格与目录组织方式，其中包括：

• nelvko/clash-for-linux-install

本项目并非上述项目的 fork，也不是基于其代码直接二次开发；核心实现为独立编写，并在后续维护中逐步演进为当前架构。

感谢相关开源项目对 Linux Clash / Mihomo 使用体验的探索。

常见问题

1. 部分Linux系统默认的 shell /bin/sh 被更改为 dash，运行脚本会出现报错（报错内容一般会有 -en [ OK ]）。建议使用 bash xxx.sh 运行脚本。

2. 部分用户在UI界面找不到代理节点，基本上是因为厂商提供的clash配置文件是经过base64编码的，且配置文件格式不符合clash配置标准。

   目前此项目已集成自动识别和转换clash配置文件的功能。如果依然无法使用，则需要通过自建或者第三方平台（不推荐，有泄露风险）对订阅地址转换。

3. 程序日志中出现error: unsupported rule type RULE-SET报错，解决方法查看官方WIKI

⭐ Star History

⚠️ 特别声明

1. 编写本项目主要目的为学习和研究 Shell 编程，不得将本项目中任何内容用于违反国家/地区/组织等的法律法规或相关规定的其他用途。
2. 本项目保留随时对免责声明进行补充或更改的权利，直接或间接使用本项目内容的个人或组织，视为接受本项目的特别声明。