---

👋 项目简介

ClashBar 是一款基于 mihomo 内核的原生 macOS 菜单栏代理客户端，专注于轻量、稳定、可观测的代理管理体验。
在不打开复杂主窗口的前提下，你可以在菜单栏中完成配置管理、节点切换、规则刷新、连接排障与系统代理控制。 ✨

🤖 项目说明

ClashBar 是一个「纯 AI vibe coding」驱动的自用项目。
项目在需求整理、实现迭代、文档维护等环节持续与 Codex 协作，以更快验证想法并沉淀可复用实践。 🚀

🎯 项目初心

ClashBar 的设计目标始终围绕两个关键词：轻量 与 稳定。

• 🪶 轻量化优先：在打包 mihomo Core 的前提下，应用体积目标控制在 15 MB 以内。
• 📦 可裁剪交付：移除 Core 后，应用体积目标控制在 3 MB 以内，便于快速分发与集成。
• 🛡️ 稳定性优先：优先保证日常可用性与长期运行稳定，避免为短期功能堆叠牺牲可靠性。

📏 App 体积对比（macOS）

客户端	应用体积	相对 ClashBar
ClashBar.app (No Core)	2.7 MB	1.0x
ClashBar.app	14.2 MB	5.2x
ClashMac.app	75.2 MB	27.8x
Clash Verge.app	128.4 MB	47.5x
Clash Party.app	496.7 MB	183.9x
Sparkle.app	519.8 MB	192.5x

✨ 核心能力

领域	能力说明	业务价值
🟢 Core 生命周期	Start / Stop / Restart	快速恢复网络可用性，降低中断时间
🧩 配置管理	本地导入、远程导入、批量更新、重载配置	多订阅场景下保持配置一致性
🚦 流量策略	Rule / Global / Direct 模式切换	针对不同网络场景快速切换策略
🌍 节点运维	Proxy Group 切换、延迟测试、Provider 更新	提升线路质量与稳定性
📊 可观测性	实时速率、连接数、内存、活动连接、日志过滤	快速定位“慢、断、不通”等问题
🔐 系统集成	系统代理开关、开机启动、权限协同	与 macOS 深度协作，降低操作成本
🌐 国际化	简体中文 / English	支持团队协作与跨语言使用

📦 安装

要求

• macOS Ventura (13.0) 及以上

Homebrew（推荐）

brew tap Sitoi/tap
brew install --cask clashbar

手动安装

从 GitHub Releases 下载最新 .dmg，挂载后将 ClashBar.app 拖入 /Applications。

卸载

brew uninstall --cask clashbar

# 彻底清除所有数据
brew uninstall --zap --cask clashbar

⚠️ 安装与使用前注意事项

先说人话。这些不是“可选建议”，很多时候是能不能正常用的前提：

• 同一时间只保留一个 mihomo / Clash 系客户端接管系统代理。请先退出其他同类软件，例如 ClashX、Clash Verge、Clash Nyanpasu、Clash Party、FlClash 等，避免端口、系统代理或 Helper 状态互相覆盖。
• 系统代理功能依赖打包后的应用与 macOS 后台项目授权。请优先使用 Release 页面提供的 .app / .dmg，并将 ClashBar.app 放到 /Applications 后再打开。
• 第一次启用系统代理或开机启动时，如果 macOS 弹出后台项目/登录项相关提示，需要去 系统设置 → 通用 → 登录项 里允许 ClashBar。
• 如果你刚升级、替换了 App，或者系统代理开关点了没反应，最常见的问题不是代码坏了，是 macOS 的后台项目状态卡住了。先去 系统设置 → 通用 → 登录项，把 ClashBar 后台项目关闭再打开一次，然后回到应用里重试。
• 切换配置、替换 mihomo 内核、远程订阅批量更新后，如果行为异常，先执行一次 Restart。别急着怀疑规则，先把运行态清干净。

🚀 快速上手（用户）

1. 点击菜单栏图标打开 ClashBar 面板。 🖱️
2. 在 Proxy 页面选择配置，或导入本地/远程配置。 📥
3. 点击 Start 启动 Core；如果刚改过配置或内核，直接用 Restart 更稳。 ▶️
4. 选择代理模式：Rule / Global / Direct。 🎛️
5. 在 Proxy Group 中切换节点并执行延迟测试，先确认节点真的通。 📶
6. 验证连通性后再开启系统代理；如果开关未生效，先检查登录项里的 ClashBar 后台项目。 ✅

🗺️ 功能导航

• 🧭 Proxy：实时速率、连接数、内存、配置入口、系统代理开关
• 📚 Rules：规则统计、规则刷新、Provider 更新
• 🌐 Connections：连接过滤、关闭单连接、关闭全部连接
• 🪵 Logs：日志级别过滤、关键词检索、日志复制
• ⚙️ System：语言、状态栏样式、allow-lan / ipv6 / log-level、端口设置

🎯 典型场景

• 🏠 日常办公：根据网络环境快速切换配置与节点，保障在线稳定性。
• 🧪 故障排查：结合 Connections + Logs 分析连接异常与规则命中问题。
• 🔁 订阅维护：批量更新远程配置后，一键重载并复核节点延迟。
• 🛡️ 安全优先：敏感信息写入 Keychain，日志内容自动脱敏。

📁 数据目录

运行时根目录：

• ~/Library/Application Support/clashbar

目录结构与职责：

路径	作用	管理建议
config/	存放用户配置文件（.yaml / .yml）与订阅导入结果	建议纳入备份；可手动维护文件命名
logs/	运行日志与排障信息输出目录	排障完成后可按需清理
state/	应用运行状态与会话相关数据	建议由程序维护，不建议手动编辑
core/	运行时 Core 二进制（如 mihomo）	升级/替换前先停止 Core

配置发现规则：

• 仅识别 .yaml / .yml 文件
• 按文件名排序加载
• 未手动指定时，默认选中首个配置

🔄 内核目录与切换

运行时内核路径：

• ~/Library/Application Support/clashbar/core/mihomo

首次启动会将应用内置内核复制到上述目录。后续运行统一使用该路径，避免改写已签名的 app bundle。

切换内核步骤：

1. 在 ClashBar 中执行 Stop，确保当前内核进程已停止。
2. 准备目标内核可执行文件（如 mihomo，命名需要保存一致）。
3. 返回 ClashBar，执行 Start 或 Restart。

异常处理：

• 若切换后出现缓存兼容问题，可清理缓存后重试：

rm -f "$HOME/Library/Application Support/clashbar/cache.db"

• 使用 TUN 模式时，切换内核后可能需要重新授权相关权限（root + setuid）。

❓ 常见问题

1) macOS 提示“已损坏”或“无法验证开发者” 🔒

现象：应用首次启动被系统拦截。
原因：macOS Gatekeeper 对未公证应用的默认安全策略。

处理步骤

1. 将应用放置到 /Applications/ClashBar.app。
2. 打开 系统设置 → 隐私与安全性，点击「仍要打开（Open Anyway）」。
3. 若仍被拦截，可移除隔离标记后重试：

sudo xattr -r -d com.apple.quarantine /Applications/ClashBar.app

2) 系统代理开启失败 ⚙️

现象：点击系统代理开关后未生效或立即回退。
原因：通常与权限授权、Helper 状态、应用安装位置，或 macOS 后台项目状态卡住有关。

处理步骤

1. 确认使用的是打包后的应用，并位于 /Applications。
2. 在 系统设置 → 通用 → 登录项 中允许 ClashBar 后台项目；如果已经允许但仍异常，先手动关闭再重新打开一次。
3. 确认没有其他 mihomo / Clash 系客户端正在接管系统代理。
4. 回到应用执行一次 Restart Core 后再次开启系统代理。
5. 如仍失败，打开 Logs 检查关键错误并提交 Issue。

3) 切换节点后网络无变化 🌐

现象：已切换 Proxy Group 或节点，但访问效果未变化。
原因：常见于模式不匹配、节点未生效或配置未重载。

处理步骤

1. 执行一次延迟测试，确认目标节点可用。
2. 确认当前模式为 Rule 或 Global（避免误处于 Direct）。
3. 重新选择目标 Proxy Group/节点，并执行 Restart Core。

4) 远程配置更新后未生效 🔁

现象：远程更新成功，但节点或规则未刷新。
原因：配置列表未重载或当前生效配置未切换到最新版本。

处理步骤

1. 先执行远程更新，再点击 重载配置。
2. 重新选择目标配置，确认当前生效项已切换。
3. 如仍异常，检查 Logs 中是否存在拉取失败或解析错误。

5) 请求没有按预期走代理 🧭

现象：部分域名/IP 走向与预期策略不一致。
原因：通常是规则命中顺序、分流策略、配置内容，或者系统当前实际生效的代理并不是 ClashBar 导致。

处理步骤

1. 先退出其他 mihomo / Clash 系客户端，排除系统代理被别的软件覆盖。
2. 在 Rules 页面检查命中规则与策略结果。
3. 在 Connections 定位对应连接，核对目标地址与链路。
4. 在 Logs 通过关键词过滤交叉验证最终路由决策。

6) 日志出现 "can't find MMDB, start download" 🗺️

现象：Core 启动后日志中出现 can't find MMDB, start download，网络访问异常或规则不生效。
原因：GeoIP 数据库文件（Country.mmdb）缺失，Core 正在自动下载，首次启动或数据目录被清理后常见。

处理步骤

1. 使用默认配置启动一次，等待 Core 自动下载完成（需要网络可达）。
2. 下载完成后重新启动 Core，问题一般自动消失。
3. 若网络受限无法下载，可手动将 Country.mmdb 放入 ~/Library/Application Support/clashbar/ 目录后再启动。

7) 出现 "There was a bad response from the server" 或 API request failed (401) ⚠️

现象：操作时弹出 There was a bad response from the server 或 API request failed (401) 错误提示。
原因：通常是其他 Clash/mihomo 系客户端残留进程占用了同一端口，导致 API 鉴权失败。

处理步骤

1. 退出所有其他 mihomo / Clash 系客户端（ClashX、Clash Verge、Clash Nyanpasu、Clash Party 等）。
2. 在 ClashBar 中执行 Restart，确认 Core 由 ClashBar 独立拉起。
3. 若退出所有软件后仍复现，说明有残留进程在后台占用端口，重启电脑后重试即可彻底清除。

🙌 反馈与支持

• Telegram 社区：https://t.me/clashbars
• Issue / PR：欢迎提交功能建议、稳定性问题与文档修正。 💬

👥 贡献者

感谢所有参与贡献的开发者：

🙏 致谢

• 感谢 OpenAI Codex 在需求拆解、工程实现与文档优化中的持续协作。 🤝
• 感谢 MetaCubeX/mihomo 提供稳定可靠的 Core 能力。

✨ Star 数

📄 许可证

本项目采用 GPL-3.0 license，详见 LICENSE。