常见问题
安装、内核、系统代理、节点、订阅、GEO 与 API 鉴权等问题排查。
按现象查找；先确认是否完成 快速开始 中的安装与登录项设置。数据目录见 配置与订阅，网络接管见 系统代理与 TUN。
无法启动内核
确认：
- 文件位于
~/Library/Application Support/clashbar/core/mihomo。 - 文件名为
mihomo，并具有可执行权限。 - 当前已选中一份有效配置（见配置发现规则）。
- 「日志」中无配置校验失败或端口占用错误。
含 Core / 无 Core 构建差异见 快速开始 · 准备 Mihomo 内核。可用「打开内核目录」核对路径。
macOS 提示「已损坏」或「无法验证开发者」
现象：首次启动被系统拦截。
原因：Gatekeeper 对未公证应用的默认策略。
- 将应用放到
/Applications/ClashBar.app。 - 打开 系统设置 → 隐私与安全性，选择「仍要打开」。
- 仍被隔离标记拦截时（确认来源可信）：
sudo xattr -r -d com.apple.quarantine /Applications/ClashBar.app系统代理开启失败 / 开关没有反应
现象：点击系统代理未生效或立即回退。
原因：权限、Helper、安装位置，或登录项后台项目卡住；也可能被其它客户端抢占。
- 使用打包后的应用，并位于
/Applications。 - 系统设置 → 通用 → 登录项：允许 ClashBar 后台活动；已允许仍异常时，关闭再打开一次。
- 退出其它 mihomo / Clash 系客户端。
- 执行一次 重启内核，再开系统代理。
- 仍失败时在「日志」中查看关键错误并提交 Issue。
配置导入或重载失败
ClashBar 会调用 Mihomo 校验 YAML。请在「日志」中查看错误行号，检查缩进、代理组引用、规则提供者与端口冲突。修正后重新导入或「重新加载配置」。
订阅更新失败
检查链接是否可从当前网络访问，以及服务商是否过期、限流。单个订阅失败不会阻止其它订阅更新；日志中会有成功/失败数量。
远程配置更新后未生效
现象：远程更新成功，但节点或规则未刷新。
- 更新完成后点击 重新加载配置（或重启内核）。
- 重新选择目标配置，确认当前生效项已切换。
- 在「日志」中检查拉取失败或解析错误。
开启 TUN 失败
常见原因：找不到/无法执行 mihomo、管理员授权取消、内核重启后 TUN 未生效。确认内核路径与权限后重试；切换内核后可能需重新授权。详见 系统代理与 TUN。
切换节点后网络无变化
现象：已切换代理组或节点，访问效果不变。
- 执行延迟测试，确认目标节点可用。
- 确认模式为 规则 或 全局（勿误停在 直连）。
- 重新选择节点，并 重启内核。
请求没有按预期走代理
现象：部分域名/IP 与预期策略不一致。
- 退出其它 mihomo / Clash 系客户端，排除系统代理被覆盖。
- 在「分流」检查命中规则与策略。
- 在「连接」核对目标地址与链路。
- 在「日志」用关键词交叉验证路由决策。
浏览器仍无法联网
- 内核是否为「运行中」。
- 系统代理或 TUN 是否已开启。
- 节点是否可用并完成延迟测试。
- 「连接」「日志」中是否有错误规则、错误组或 DNS 错误。
日志提示找不到 MMDB 并开始下载
现象：日志含 can't find MMDB, start download，网络或规则异常。
原因：GeoIP 数据库（如 Country.mmdb）缺失，内核正在自动下载；首次启动或数据目录被清理后常见。
- 使用默认配置启动一次，等待自动下载完成（需网络可达）。
- 下载完成后重新启动内核。
- 网络受限时，可手动将
Country.mmdb放入~/Library/Application Support/clashbar/后再启动。
也可在设置中尝试「更新 Geo 数据库」（内核运行中）。见 设置与维护。
出现 bad response 或 API 鉴权失败（401）
现象：弹出 There was a bad response from the server 或 API request failed (401)。
原因：其它 Clash/mihomo 客户端残留进程占用同一端口，导致 API 鉴权失败。
- 退出所有其它 mihomo / Clash 系客户端。
- 在 ClashBar 中 重启内核，确认由本应用独立拉起。
- 若仍复现，可能有残留进程占端口——重启电脑后重试。
Wi‑Fi 自动切换不生效
- 已开启「Wi‑Fi 自动切换」。
- 已授予 Wi‑Fi / 定位相关权限，系统定位服务已打开。
- 当前 SSID 已绑定到仍存在的配置。
- 日志中是否有权限不足或配置缺失记录。
详见 SSID 策略。
远程机器连不上
- 主机、端口与 secret 与远端 External Controller 一致。
- 本机网络可达该地址。
- 在机器切换器中查看失败原因。
详见 远程机器。
配置、日志和状态文件在哪里
根目录：~/Library/Application Support/clashbar。分项职责与配置发现规则见 配置与订阅。
如何提交问题
- GitHub Issues
- Telegram 社区：t.me/clashbars
请附上 ClashBar 版本、macOS 版本、本机或远程内核，以及已脱敏日志。勿上传订阅链接与密钥。