# ClashBox 鸿蒙原生客户端介绍与侧载安装说明

规范地址 https://jichangboke.org/clients/clashbox/
发布 2026-09-18，更新 2026-09-18
作者 塔台君，机场博客

> ClashBox 是鸿蒙原生的 Clash 系客户端，改版 Mihomo 内核，免费，项目仍在维护。大陆区应用市场搜不到它，要么从海外区 AppGallery 安装，要么到 GitHub 下载未签名 HAP，在电脑上签名后侧载。

## 官方来源与下载

- 维护状态 维护中
- 内核 Mihomo 内核
- 源码 源码不完整
- 价格 免费
- 最新版本 1.7.4，核对于 2026-09-18
- 许可证 GPL-3.0
- 官方仓库 https://github.com/xiaobaigroup/ClashBox
- 鸿蒙 HarmonyOS 官方下载页 https://github.com/xiaobaigroup/ClashBox/releases

ClashBox 的仓库在 xiaobaigroup 名下，2025 年 2 月建立，早期版本叫 ClashNEXT。它的前身是 likuai2010/ClashMeta，那个仓库的 README 已经写明永久停更并指向 ClashBox。README 自述前端用鸿蒙的 ArkTS 写，内核是改版的 [mihomo](/glossary/#mihomo)，界面适配手机、平板、折叠屏和鸿蒙电脑。MetaCubeX 文档的客户端目录里，HarmonyOS NEXT 一栏只列了它一个。本站 2026 年 9 月 18 日核对，master 分支最近一次提交在 8 月 15 日，维护者 9 月 11 日还在回复 issue。

### 安装渠道与门槛

它没有上架大陆区的华为应用市场。维护者在 issue 里说过，早先上过内测尝鲜，被举报后下架。2025 年 5 月的 1.4.7 发布说明写它已经上架鸿蒙海外市场，按维护者后来的回复，商店版在 2026 年已经到 2.x。GitHub 的 Releases 页上，最新一条是 2026 年 4 月 2 日的 1.7.4，标题写着 ClashBox LTS (V1)，文件名 `ClashBox_LTS_V1_unsigned.hap`，没有签名，传到手机上点开装不了。README 给的办法是在电脑上用小白调试助手这类工具签名后侧载，自签名默认 14 天有效，做了华为开发者实名认证是 180 天，到期要重装。

### 源码和侧载工具

许可证是 GPL-3.0。README 说大部分代码已开源，放在 master 分支，那个分支自带的 README 又写着只含前端。本站翻了 master 的目录，内核部分有 Go 桥接源码，也带着一个一百兆左右的预编译 `libflclash.so`，MetaCubeX 目录给它的备注是前端开源，构建不可复现。侧载用的小白调试助手，仓库里没有源码，用的时候却要登录华为账号，装之前想清楚能不能接受。

手机还停在 HarmonyOS 4 的话用不着它，直接装安卓版的 [FlClash](/clients/flclash/) 或 [Clash Meta for Android](/clients/clash-meta-for-android/) 更省事，两条路线怎么分写在[鸿蒙平台页](/clients/harmonyos/)。订阅还没着落，可以先看[机场榜单](/jichang-tuijian/)。

## 适合

- 手机、平板或电脑已经是 HarmonyOS 5 及以上，装不了安卓 APK 的人
- 手里的机场订阅是 Clash 或 Mihomo 格式，想在鸿蒙上继续用规则分流的人
- 有一台 Windows 或 Mac 电脑，能接受隔一段时间重新签名安装一次的人

## 要注意

- GitHub 上只有未签名的 HAP，手机上点开装不了，要在电脑上签名后侧载。README 写自签名默认 14 天有效，做了华为开发者实名认证是 180 天，到期后打开会提示应用过期，维护者的答复是重新安装
- README 写可以用 DevEco Testing 安装，维护者 2026 年 1 月和 4 月在 issue 里的说法是它装不了没签名的 HAP，让大家改用小白调试助手，或者拉源码自己编译
- 小白调试助手的仓库里只有 README 和安装包，没有源码，使用时要登录华为账号。README 还写华为的签名服务器屏蔽非中国大陆 IP，人在境外签名会失败
- 源码不算完整。master 分支自带的 README 写着只含前端，内核部分带着预编译的 `libflclash.so`，MetaCubeX 目录的备注是构建不可复现
- 维护者 2026 年 6 月在 issue 里说，想要长期证书只有从华为海外应用市场安装这一条路。大陆区账号在应用市场搜不到它，怎样才能搜到官方没有写明，本站也没有验证过
- README 承认鸿蒙的后台调度会把它的进程关掉，要到设置的后台运行里打开模拟画中画之类的选项保活，应用内提示这样会更费电

## ClashBox 鸿蒙 HarmonyOS 使用教程

这份教程暂时没有配截图。本站手头没有 HarmonyOS 5 以上的设备，拿不到自己的实机截图，下面每一步的依据是 ClashBox 官方仓库的 README、发布说明、维护者在 issue 里的答复和 master 分支的中文界面资源，系统侧的操作依据华为开发者文档。流程分两段，先在电脑上给 HAP 签名并侧载，再到手机上导入订阅、启动、验证。界面文字取自 1.7.4 的源码，海外区应用市场的 2.x 版可能有出入。

开始前准备

- 一台 HarmonyOS 5 及以上的华为设备。系统还是 HarmonyOS 4 的不用看这一段，去看 [FlClash 的安卓教程](/clients/flclash/#android)
- 一台 Windows 或 Mac 电脑，用来运行小白调试助手，手机和电脑要能连到同一个 Wi-Fi
- 一个华为账号，电脑走中国大陆的网络。ClashBox 的 README 写华为签名服务器屏蔽非中国大陆 IP
- 机场用户中心里标着 Clash 的订阅链接，还没有订阅可以先看[机场榜单](/jichang-tuijian/)

### 第 1 步 确认系统是 HarmonyOS 5 以上

华为开发者文档写的位置是设置里的设备名称页，里面有软件版本一行。数字是 5.0 及以上才需要 ClashBox。仓库 master 分支的构建配置把最低兼容版本写成 5.0.5(17)，比这低的先升级系统。看到的是 HarmonyOS 4，说明手机还能装安卓 APK，回到[鸿蒙平台页](/clients/harmonyos/)看另一条路线。

### 第 2 步 从官方 Releases 页下载 HAP

到 xiaobaigroup/ClashBox 仓库的 Releases 页，下载 1.7.4 里的 `ClashBox_LTS_V1_unsigned.hap`，约 103 MB，2026 年 4 月 2 日发布。文件名里的 unsigned 表示没有签名，传到手机上点开装不了，先存在电脑里。GitHub 在文件旁边给了 SHA-256，下载后可以核对。能用海外区 AppGallery 的人直接在商店里装，后面的签名步骤都可以跳过。

### 第 3 步 在手机上打开开发者选项

按华为开发者文档，先看设置的系统里有没有开发者选项。没有就回到设备名称页，连续点七次软件版本，出现开启开发者选项的提示后确认，输入 PIN 码，手机会自动重启。重启后进开发者选项，打开 USB 调试或无线调试。无线调试页会显示手机的 IP 地址和端口，手机和电脑要连同一个 Wi-Fi，第一次连接时手机上要点授权。

### 第 4 步 在电脑上准备小白调试助手

README 点名的侧载工具是 Auto-installer，中文名小白调试助手。到 likuai2010/auto-installer 的 Releases 页下载 3.1.0，Windows 用 `hap_installer-Windows-3.1.0.zip`，Mac 用 `hap_installer-Mac-3.1.0.zip`。它的 README 写 Mac 首次运行前要在终端执行 `xattr -d com.apple.quarantine` 加程序路径。这个工具没有公开源码，用它要登录华为账号，介意的话就停在这一步。

### 第 5 步 用助手签名并安装 HAP

助手的仓库没有图文说明，README 的演示进展一节只有一个视频链接，具体点哪里以那段视频和 Releases 页 3.1 的更新说明为准。从更新说明能看出，它要登录华为账号，通过无线调试连接手机，端口默认设成 12345，然后安装你选中的 HAP。账号文件和备份存在下载目录的小白调试助手文件夹里，别删。装完桌面上会出现 ClashBox 的图标。

### 第 6 步 打开 ClashBox 添加订阅

打开 ClashBox，底部是主页、代理、配置、更多四个标签。进配置页找添加配置，里面有从URL(链接)导入、从二维码导入、从文件导入和新建空白配置。机场订阅选从URL(链接)导入，填一个配置名，把订阅链接粘到写着输入链接的那一栏，下面还有自动更新和自动更新间隔两项。保存后它会去下载配置，成功时提示下载成功。

### 第 7 步 到代理页选节点并测延迟

切到代理页，机场配置里的策略组和节点会列在这里，点一个节点就是选中。页面上有延迟测试的按钮，测完能看到每个节点的延迟，显示 TIMEOUT 的别选。长按节点可以收藏。主页上的分流模式有规则、全局、直连三档，平时用规则。

### 第 8 步 回主页启动并允许 VPN 连接

回到主页点启动按钮，没导入配置时它会提示导入配置并成功加载后才可以启动。按华为开发者文档，第三方 VPN 应用第一次启动连接之前，系统会弹出 VPN 连接授权对话框，问你是否信任这个应用，看清是 ClashBox 发起的再同意。连接成功后状态栏会出现钥匙形状的 VPN 图标。系统同一时间只支持一个 VPN 连接，别的 VPN 要先断开。

### 第 9 步 打开后台运行防止被回收

README 承认 HarmonyOS NEXT 会在后台关掉它的进程，所以内置了核心恢复，打开后台运行里的模拟画中画后自动启用。入口在更多页的设置里，后台运行下面有模拟定位、模拟画中画、模拟下载和任务保持，应用内提示平板和电脑建议用任务保持，开了会更费电。选模拟定位的话，要授予位置权限并保持位置开关打开。

### 第 10 步 验证能否上网并记下到期日

打开浏览器访问一个平时打不开的网站，能加载就说明通了，主页的 IP地址卡片可以用来看出口有没有变。侧载版要记到期日。README 写自签名默认 14 天有效，实名认证过的开发者账号是 180 天。到期后打开会提示应用过期，维护者的答复是重新安装，小白调试助手 3.1 的更新说明里有一键续期和日历提醒。

### 鸿蒙 HarmonyOS 上常见的问题

**用 hdc 或 DevEco Testing 安装，提示 no signature file**

Releases 里的 HAP 没有签名。华为 bm 工具文档里，错误码 9568320 的意思就是签名文件不存在。这两个工具只管安装，不管签名。维护者 2026 年 4 月在 issue 里的答复是改用小白调试助手。更早还有一条答复让人拉源码自己编译安装，那要用华为官方的 DevEco Studio，登录华为账号自动签名后运行到手机上。

**签名一直失败**

先看网络。README 写明华为的签名服务器屏蔽非中国大陆的 IP，人在境外签不了。电脑上如果开着代理，让签名请求走了境外出口，也可能被拒，关掉再试。华为的自动签名文档还提到，电脑的系统时间要和北京时间一致，否则签名失败。助手从旧版升上来的，2.5.0 的更新说明要求到更多里点一次重置证书。

**打开 ClashBox 提示应用过期**

这是调试证书到期了。维护者在 issue 里的答复是重新安装。用小白调试助手 3.1 装的，可以试它的一键续期。想摆脱到期这件事，维护者说只有从华为海外应用市场安装这一条路。如果要先卸载再装，本地配置会跟着清空，订阅链接提前另存一份。

**连上几分钟就断，或者锁屏后断流**

应用内常见问题的解释是当前系统的后台管理非常严格，建议打开通知和模拟后台功能。到更多页的设置里打开后台运行，选一种模拟方式。应用内还有一条特别提示，经常掉线的话推荐在内核设置里用前台模式，再配合模拟后台。2026 年 8 月的 issue 158 还在讨论锁屏后断流，当时没有结论。

**导入订阅后节点很少，或者代理页是空的**

应用内常见问题给了办法。节点变少，是因为部分机场对 ClashBox 的 UA 支持很少，可以在订阅链接末尾加上 `&flag=meta` 再导入。导入失败或为空，多试几次，或者换机场用户中心里标着 Clash 的那条订阅。节点测速全部 TIMEOUT 的，到更多页的覆写里打开覆写DNS，然后重启 ClashBox。

## 常见问题

### ClashBox 在华为应用市场能下载吗

大陆区的应用市场里搜不到。项目方在 1.4.7 的发布说明里说它已经上架鸿蒙海外市场，维护者后来又说长期可用的版本只能从海外应用市场装。怎样切到海外区，官方没有给步骤，issue 里用户的说法也不一致，本站没有验证过。装不了商店版，就只剩侧载 GitHub 上的 HAP 这一个办法。

### ClashBox 装好后过几天提示应用过期怎么办

重新签名安装一次。维护者在 issue 里解释过，提示过期是调试证书到期了。README 写自签名侧载默认只有 14 天有效期，完成华为开发者实名认证后是 180 天。小白调试助手 3.1 的更新说明里有一键续期和到期日历提醒，可以提前处理。重装之前把订阅链接另存一份。

### 用 hdc 或 DevEco Testing 安装提示 no signature file 是怎么回事

Releases 里的 HAP 没有签名，所以装不进去。华为 bm 工具文档里，错误码 9568320 的含义就是签名文件不存在。hdc 和 DevEco Testing 只负责把包装进手机，不会替你签名。维护者给的办法是用小白调试助手，或者拉源码自己编译安装，后一种要装华为官方的 DevEco Studio。

### ClashBox 支持哪些订阅和协议

它读 Clash 或 Mihomo 格式的配置，可以从 URL、二维码或本地文件导入。README 说功能基本对齐 Mihomo，1.3.3 的更新日志提到支持 AnyTLS 节点和 IPv6 节点。应用内的常见问题写着，导入后节点变少可以在订阅链接后面加 `&flag=meta` 再试。V2Ray 分享链接和 sing-box 格式，仓库里没有提到支持。

### 开了 ClashBox，卓易通里的安卓应用为什么上不了网

这是已知问题，官方还没有彻底解决。维护者在 issue 里说，系统的 DNS 设置传不进卓易通这类容器环境。给的缓解办法是到更多页的覆写里打开覆写DNS，或者在覆写的网络里打开兼容模式，改完重启应用，并说明不一定有效。应用内的访问控制也注明只能管理非容器应用。