ClashMac

Appearance

故障排障与常见错误诊断 ​

ClashMac 运行在 macOS 严格的沙盒与隐私安全策略下，同时与底层的网络核心引擎和系统级的后台网络辅助服务紧密协作。这可能导致在特殊环境下出现权限脱节、网络挂起或配置死锁等异常。

本指南提供了针对 ClashMac 系统运行环境的常见排障方案，直击系统使用过程中的痛点。

目录 ​

  1. 系统网络辅助服务状态异常与安装卡死
  2. 增强模式(TUN)故障与域名解析异常
  3. 浏览器自动化权限异常修复
  4. 清除历史数据后磁盘空间释放异常
  5. 终端命令行工具未找到
  6. 高并发流量下载时系统网络挂起
  7. 如何彻底卸载客户端

1. 系统网络辅助服务状态异常与安装卡死 ​

  • 问题描述：系统服务提示“需要批准”，但在系统的“登录项”列表中找不到 ClashMac 的激活开关。
  • 原因分析：macOS 后台服务注册表缓存损坏或被第三方清理工具误删。

排障与修复步骤 ​

  1. 在客户端重新注册： 打开 ClashMac 的 系统权限 设置页面，点击 重装核心服务。
  2. 刷新后台服务注册表： 如果开关仍未出现，可在终端中执行以下命令刷新系统登录项缓存：
    bash
    sudo sfltool resetbtm
    重置后，重启 Mac 并在系统的“登录项与延伸功能”中重新开启 ClashMac 开关。

2. 增强模式(TUN)故障与域名解析异常 ​

  • 问题描述：开启增强模式(TUN)后，网络中断或域名无法解析。
  • 原因分析：
    1. 最大传输单元适配冲突：默认的虚拟网卡 MTU 设置过高，导致数据包被网关拦截。
    2. DNS 重定向锁死：本地 DNS 解析请求未正确接管，导致路由死锁。
    3. 虚拟网卡命名冲突：系统中残留有其他虚拟网卡的路由配置。

排障与修复步骤 ​

  1. 调整 MTU 数值： 前往 控制台 -> 引擎配置 -> 增强模式(TUN)，将 MTU 修改为标准的 1500 或 1400。
  2. 清除 Fake-IP 与域名解析缓存： 前往 高级设置 页面，点击 清除 Fake-IP 缓存 与 清除 DNS 缓存，并在终端中清理 macOS 系统解析缓存：
    bash
    sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder
  3. 关闭其他网络接管服务： 确保已彻底退出其他代理或虚拟网络软件，避免虚拟网卡冲突。

3. 浏览器自动化权限异常修复 ​

  • 问题描述：在偏好设置中，浏览器自动化权限状态卡在“已拒绝”，重新请求权限无弹窗响应。
  • 原因分析：macOS 隐私安全机制限制，一旦首次点击过拒绝，系统将不再主动弹出授权窗口。

排障与修复步骤 ​

  1. 手动恢复系统授权： 前往 macOS 系统设置 -> 隐私与安全性 -> 自动化，在应用列表中找到 ClashMac，确保其下对应浏览器（如 Safari、Chrome）的开关均处于开启状态。
  2. 重置系统自动化授权库： 如果在系统自动化设置列表中找不到 ClashMac，可在终端中执行以下命令重置自动化隐私库记录：
    bash
    tccutil reset AppleEvents
    执行后重启客户端，重新在权限设置中点击“请求权限”即可重新唤醒授权弹窗。

4. 清除历史数据后磁盘空间释放异常 ​

  • 问题描述：点击了“删除所有数据”后，系统磁盘空间并未立刻增加。
  • 原因分析：数据库文件存在空间预留保护，数据被擦除后需进行空间整理收归。

排障与修复步骤 ​

  1. 执行空间收归： 前往 高级设置，点击 删除所有数据。
  2. 耐心等待整理： 确认清理后，客户端会在后台发起数据碎片整理。此过程通常需要数秒，请耐心等待其完成，避免在此期间强制退出客户端。

5. 终端命令行工具未找到 ​

  • 问题描述：在终端执行命令提示找不到 clashmac 或没有权限。
  • 原因分析：
    1. 系统路径未加入环境变量：macOS 终端路径未包含 /usr/local/bin。
    2. 软链接文件建立失败：首次创建软链接时未成功获得系统权限。

排障与修复步骤 ​

  1. 核对软链接指向： 在终端执行以下命令，确认软链接是否正确指向客户端内部的可执行程序：
    bash
    ls -la /usr/local/bin/clashmac
  2. 手动建立软链接： 如果自动安装失败，可在终端中执行以下命令进行手动装配：
    bash
    sudo mkdir -p /usr/local/bin
sudo ln -sf "/Applications/ClashMac.app/Contents/MacOS/ClashMacCLI" /usr/local/bin/clashmac
sudo chmod +x /usr/local/bin/clashmac
  3. 更新 Shell 配置文件： 若提示命令未找到，打开 ~/.zshrc 配置文件，确保包含以下环境变量设置，保存后执行 source ~/.zshrc 生效：
    bash
    export PATH="/usr/local/bin:$PATH"

6. 高并发流量下载时系统网络挂起 ​

  • 问题描述：进行高并发、大流量下载时，Mac 突然断网且网络设置无响应，必须重启设备。
  • 原因分析：在特定网卡环境下开启了实验性“数据包发送优化”选项，引发硬件冲突。

排障与修复步骤 ​

  1. 关闭发送包优化： 前往 控制台 -> 引擎配置 -> 增强模式(TUN)。
  2. 调整性能优化开关：
    • 确保 数据包发送优化 处于关闭状态（默认已关闭）。
    • 保持 数据包接收优化 处于开启状态（此选项稳定，可有效降低 CPU 占用率）。
  3. 重载代理服务： 保存设置并重启代理核心以应用新配置。

7. 如何彻底卸载客户端 ​

若需在系统上彻底清除 ClashMac 所有残留，请按以下步骤操作：

卸载清理步骤 ​

  1. 卸载后台特权服务： 在彻底关闭客户端前，前往客户端 状态栏下拉菜单中的 设置 -> 系统权限，点击 卸载辅助服务。这会自动向系统注销并停止安装在系统中的后台网络辅助守护进程（app.clashmac.helper）。
  2. 删除终端命令行工具： 打开终端，执行以下命令清理命令行软链接：
    bash
    sudo rm -f /usr/local/bin/clashmac
  3. 清理系统级特权守护进程残留： 如果需要手动彻底清空 XPC 守护进程相关的物理残留文件，可以在终端执行以下命令：
    bash
    sudo rm -f /Library/PrivilegedHelperTools/app.clashmac.helper
sudo rm -f /Library/LaunchDaemons/app.clashmac.helper.plist
  4. 清理本地用户配置、缓存与偏好设置： 在终端中执行以下命令，彻底清理存储在本地的用户主配置目录、沙盒缓存、偏好设置 plist 配置文件及窗口关闭状态：
    bash
    # 清理用户配置与缓存
rm -rf ~/Library/Application\ Support/ClashMac
rm -rf ~/Library/Caches/app.clashmac
# 清理应用偏好设置与窗口状态
rm -f ~/Library/Preferences/app.clashmac.plist
rm -rf ~/Library/Saved\ Application\ State/app.clashmac.savedState
  5. 移除应用程序： 进入系统的“应用程序”文件夹，将 ClashMac 拖入废纸篓并清空（或在终端直接运行 sudo rm -rf /Applications/ClashMac.app），即可完成彻底卸载。