6つの一般的なインストール失敗の概要
macOS に ClashX をインストールする際、ポップアップ警告が表示されたり、アプリが開かなかったり、インストールが途中で失敗したりすることがあります。以下に、最も一般的な 6 つの原因とその解決策をまとめました。
| # | 原因 | 典型的なエラー / 症状 | 解決策 |
|---|---|---|---|
| 1 | Gatekeeper によるブロック | 「開発元が未確認のため開けません」 | セキュリティ設定 + xattr |
| 2 | コード署名の問題 | 「破損しているため開けません」 / 署名が無効 | spctl / codesign 確認 |
| 3 | macOS の互換性なし | 起動時にクラッシュ、または起動しない | 最小バージョンの確認 |
| 4 | ディスク容量不足 | エラーでインストールが中断される | df -h 確認 + クリーンアップ |
| 5 | 旧バージョンとの競合 | 更新後の異常な動作や設定の消失 | 旧バージョンを完全に削除 |
| 6 | ダウンロードファイルの破損 | ファイルが壊れている、ファイルサイズが異常 | shasum 検証 |
原因 1 — macOS Gatekeeper によるインストールのブロック
macOS Gatekeeper は Apple 内蔵のセキュリティメカニズムで、デフォルトでは App Store または確認済みの開発元からのアプリのみを許可します。ClashX は Apple の公証を受けていないオープンソースのコミュニティリリースであるため、Gatekeeper によってブロックされます。
方法 1: システム環境設定で許可する
- ClashX を開こうとします。ブロックダイアログが表示されたら、OK をクリックします。
- システム環境設定 → セキュリティとプライバシー → 全般 に移動します。
- 下部にある 「ClashX はブロックされました」 というメッセージを探し、このまま開く をクリックします。
- 確認ダイアログで 開く をクリックします。
方法 2: ターミナルで検疫属性を削除する
方法 1 で解決しない場合は、xattr コマンドを使用して、macOS がダウンロードされたファイルに付与する検疫フラグを削除します。
sudo xattr -cr /Applications/ClashX.appパスワードを求められたら管理者パスワードを入力し、その後 ClashX を再度開きます。
方法 3: 一時的にすべての場所からのアプリを許可する（長期使用は非推奨）
sudo spctl --master-disableこれにより、セキュリティとプライバシーに 「すべての場所」 というオプションが追加されます。問題が解決したら、保護を再度有効にしてください：
sudo spctl --master-enable原因 2 — コード署名の問題
「ClashX は破損しているため開けません」 や 「開発元を検証できません」 と表示される場合、アプリのコード署名が欠落しているか、無効である可能性があります。
アプリの署名ステータスを確認する
# Gatekeeper の評価を確認
spctl --assess --verbose /Applications/ClashX.app
# 詳細なコード署名情報を表示
codesign -dv --verbose=4 /Applications/ClashX.app
# 署名の整合性を検証
codesign --verify --deep --strict /Applications/ClashX.app解決策
- アプリを再署名する（推奨）: アドホック署名を適用します。
sudo codesign --force --deep --sign - /Applications/ClashX.app - 検疫削除 + 再署名:
sudo xattr -cr /Applications/ClashX.app sudo codesign --force --deep --sign - /Applications/ClashX.app - すべて失敗した場合は、公式ダウンロードページから最新バージョンを再ダウンロードしてください。
原因 3 — macOS のバージョン互換性なし
ClashX には macOS 10.15 (Catalina) 以降が必要です。それより古い macOS バージョンでは、インストールの失敗や起動時のクラッシュが発生する可能性があります。
現在の macOS バージョンを確認する
# macOS バージョンを確認
sw_vers
# 出力例:
# ProductName: macOS
# ProductVersion: 14.3.1
# BuildVersion: 23D60バージョンの互換性
| ClashX バージョン | 最小 macOS | サポートされているチップ |
|---|---|---|
| ClashX 1.118+ | macOS 11.0 (Big Sur) | Intel + Apple Silicon |
| ClashX 1.95 – 1.117 | macOS 10.15 (Catalina) | Intel + Apple Silicon |
| ClashX < 1.95 | macOS 10.14 (Mojave) | Intel のみ |
解決策
- macOS が古すぎる場合は、macOS をアップグレードするか、互換性のある古い ClashX バージョンを使用してください。
- Apple Silicon (M1/M2/M3) ユーザーは、必ず Universal または ARM64 ビルドをダウンロードしてください。
原因 4 — ディスク容量不足
ClashX インストーラーは約 20 MB ですが、実行時には設定ファイルやログ用に追加のスペースが必要です。ディスク容量が不足していると、インストールが中断されたり、アプリが正常に動作しなかったりします。
利用可能なディスク容量を確認する
# ディスク使用量を確認
df -h /
# 出力例:
# Filesystem Size Used Avail Capacity Mounted on
# /dev/disk1s1 460Gi 380Gi 75Gi 84% /クイッククリーンアップ方法
# システムキャッシュをクリア
sudo rm -rf ~/Library/Caches/*
# Xcode の Derived Data をクリア（該当する場合）
rm -rf ~/Library/Developer/Xcode/DerivedData
# システムログをクリア
sudo rm -rf /var/log/*.gz
# 大きいファイルを探す
du -sh ~/Downloads/* | sort -rh | head -20ClashX をスムーズに動作させるために、少なくとも 5 GB の空き容量を確保してください。
原因 5 — 旧バージョンとの競合
既存の ClashX または ClashX Pro の上に新しいバージョンをインストールすると、残った設定、キャッシュ、またはヘルパーツールの競合により失敗することがあります。
旧バージョンの ClashX を完全にアンインストールする
# 1. ClashX を終了
osascript -e 'quit app "ClashX"'
# 2. アプリ本体を削除
sudo rm -rf /Applications/ClashX.app
# 3. 設定とデータを削除
rm -rf ~/Library/Application\ Support/com.west2online.ClashX
rm -rf ~/Library/Application\ Support/ClashX
# 4. プリファレンスを削除
rm -f ~/Library/Preferences/com.west2online.ClashX.plist
rm -f ~/Library/Preferences/com.west2online.ClashXPro.plist
# 5. キャッシュをクリア
rm -rf ~/Library/Caches/com.west2online.ClashX
# 6. ヘルパーツールを削除
sudo rm -f /Library/PrivilegedHelperTools/com.west2online.ClashX.ProxyConfigHelper
sudo rm -f /Library/LaunchDaemons/com.west2online.ClashX.ProxyConfigHelper.plistクリーンアップが完了したか確認する
# 残っているプロセスがないか確認
ps aux | grep -i clash
# ヘルパーが削除されたか確認
ls -la /Library/PrivilegedHelperTools/ | grep -i clashクリーンアップ後、ダウンロードページから最新バージョンを再ダウンロードしてインストールしてください。
原因 6 — ダウンロードファイルの破損
ダウンロード中にネットワークが不安定な場合（特にプロキシや CDN を使用している場合）、インストーラーファイルが不完全になったり、破損したりすることがあります。
ダウンロードファイルの整合性を検証する
# SHA-256 で検証
shasum -a 256 ~/Downloads/ClashX.dmg
# 出力されたハッシュ値を公式リリースページの値と比較します
# 一致しない場合はファイルが破損しているため、再ダウンロードが必要です解決策
- ネットワークを切り替える: プロキシを無効にして直接接続でダウンロードしてみてください。
- ブラウザを使用する: ファイルを変更する可能性のあるダウンロードマネージャーの使用を避けてください。
- curl でダウンロードする:
# curl で GitHub Release からダウンロード curl -L -o ~/Downloads/ClashX.dmg \ https://github.com/ClashX-Pro/ClashX/releases/latest/download/ClashX.dmg # ダウンロード後に検証 shasum -a 256 ~/Downloads/ClashX.dmg - GitHub ミラーを使用する: GitHub への直接アクセスが遅い場合は、CDN 加速リンクを試してください。
よくある質問 (FAQ)
Q: ClashX と ClashX Pro で修正方法は同じですか？
A: はい、基本的に同じです。どちらも同じヘルパーツールとシステム権限メカニズムを使用しています。このガイドのすべての方法は、ClashX と ClashX Pro の両方に適用されます。
Q: M1/M2/M3 Mac で ClashX を動かすのに Rosetta は必要ですか？
A: 最新の ClashX は Apple Silicon をネイティブサポートしているため、Rosetta は不要です。古いバージョンを使用している場合は、互換性のために Rosetta をインストールしてください：
softwareupdate --install-rosetta --agree-to-licenseQ: sudo を実行したときに 「Operation not permitted」 と表示されたら？
A: これは通常、macOS の SIP (System Integrity Protection) に関連しています。xattr や codesign コマンドは通常 SIP を無効にする必要はありません。それでも問題が発生する場合は、ターミナルに 「フルディスクアクセス」 があるか確認してください（システム環境設定 → セキュリティとプライバシー → プライバシー → フルディスクアクセス）。
Q: ClashX のインストールには成功しましたが、起動しません。
A: 起動の失敗や接続の問題については、ClashX 接続タイムアウト トラブルシューティングガイドで詳細な手順を確認してください。
Q: すべて試しましたが、まだインストールできません。他にできることはありますか？
A: 以下の手順を順に試してください：
- Mac を再起動してもう一度試す
- 新しい管理者アカウントを作成して、そこでインストールをテストする
- macOS セーフモードでインストールを試す
- GitHub Issues で検索、または問題を報告する