原生 HarmonyOS NEXT 代理客户端。界面用 ArkTS/ArkUI 编写,内核是 mihomo,手机端交互以 FlClash v0.9.3 为对齐基准。
早期版本:已接入仪表盘、代理和多配置管理。本分支新增业务尚待统一真机验收;连接、日志等完整手机功能仍在开发。
目标是比同类客户端打开更快、更省电、更稳定、连接更快。
- 内核运行在系统 VPN 扩展进程,界面经 controller 和沙箱文件控制。扩展被销毁后不承诺继续代理。
- 界面进程不加载内核,打开应用时不用等内核启动。
- 内置 Geo 数据,第一次连接不用现场去 GitHub 下载。
- 默认使用 fake-ip DNS,关闭手机上用不到的进程查找。
衡量标准是在同一台手机上和同类客户端对比四项:冷启动到可操作的耗时、开着代理待机 8 小时的耗电、新连接的建立延迟、内核连续 24 小时不重启。测量方法和数据会随版本公布。
- 仪表盘:连接与停止、出站模式、实时速率与连接统计、出口 IP 和服务连通性检查。
- 代理:分组与节点浏览、按配置保存选择、测速、搜索排序及列表/标签视图。
- 配置:订阅与本地文件导入、切换、更新、重命名、复制、删除和内容编辑。
- 基础 VPN 连接曾在 Pura 70 Ultra(API 26)验证;本次三页改动及性能指标尚未实机验证。
开发计划和进度见 Issues。
需要 HarmonyOS 7(API 26)及以上的 ARM64 设备。
HarmonyOS 只能安装签过名的应用,目前还没有面向普通用户的安装渠道。安装包分为两种,发布附件见 Releases:
| 文件 | 适用于 |
|---|---|
ArkClash-<版本>-unsigned.hap |
有华为开发者账号的用户:用自己的调试证书签名后安装,方法见下面的「从源码构建」 |
ArkClash-<版本>-debug-signed.hap |
维护者的设备:用维护者的调试证书签名,只能装在证书里登记过的设备上 |
下载后可以用同一个 Release 里的 SHA256SUMS 校验文件。
- 在「配置」添加订阅,或导入本地 Clash / mihomo YAML 文件,选中要使用的配置。
- 回到仪表盘点「连接」。首次连接需在系统授权框中允许 VPN;启动过程中可以取消。
- 在「代理」选择分组内的节点,或发起节点/分组测速;断开后仍可保存选择供下次连接使用。
- 在「配置」更新订阅。连接中会尝试热切换,失败时保留原来正在运行的配置并显示错误。
需要 DevEco Studio 或 Command Line Tools(带 HarmonyOS SDK API 26)、Go(版本见 .go-version)和 Python 3。使用 Command Line Tools 时设置 HARMONYOS_TOOLS_HOME;纯命令行编译内核还需设置 OHOS_SDK 指向其 OpenHarmony SDK 目录。
make geodata # 下载 Geo 数据,打包进 HAP
make core # 交叉编译 mihomo 内核
make hap # 打包 HAP 到 dist/
make run # 安装到连着的手机并启动安装到手机前需要签名:用 DevEco Studio 打开项目,在 File → Project Structure → Signing Configs 里用华为账号自动签名。make help 列出全部命令。第一次搭环境时,按 docs/agents/fork-setup.md 逐步完成。
默认构建 ARM64。开发用 x86_64 模拟器可显式选择 ABI:
make core ABI=x86_64
make core-smoke ABI=x86_64 # 已连接的模拟器;仅验证原生加载和多线程 C API
make hap ABI=x86_64
# 配置签名后:
make run ABI=x86_64x86_64 包为 dist/ArkClash-<版本>-debug-x86_64-unsigned.hap,不会覆盖 ARM64 包。不同 ABI 的 HAP 不要并发构建。模拟器原生加载已验证,签名后的应用/VPN 验收仍待完成;模拟器结果不能替代 ARM 真机性能和稳定性验证。
| 文档 | 内容 |
|---|---|
| 架构 | 进程划分、连接流程、目录分层 |
| 决策记录 | 关键技术取舍和理由 |
| CI/CD | 流水线、密钥配置、发版流程 |
| AGENTS.md | 开发规范,人和 AI agent 共用 |
欢迎提 issue 和 PR,先读贡献指南。安全漏洞请按安全策略私密报告。
- mihomo:代理内核
- FlClash:交互设计参考
- sing-tun 和 gVisor:TUN 协议栈
- meta-rules-dat:内置的 Geo 数据
本项目仅用于学习和研究网络技术。请遵守你所在地区的法律法规,使用本软件产生的后果由使用者自行承担。