Mac の CLI・AI ツールにおける SWG TLS/SSL 証明書エラーを解決する方法
macOS の SWG 環境下で git、npm、Python、Claude Code、Cursor に発生する CERTIFICATE_VERIFY_FAILED やローカル発行者証明書エラーの原因と対処法を解説します。
SWG bar · 更新日
会社の Mac が **HTTPS/SSL 検査(Break-and-Inspect)**を行うセキュア Web ゲートウェイ(SWG)配下にあると、Safari や Chrome では警告なしにウェブサイトが開くのに、ターミナルの CLI ツールや AI コーディングエージェントでは SSL: CERTIFICATE_VERIFY_FAILED、UNABLE_TO_GET_ISSUER_CERT_LOCALLY、SSL certificate problem: unable to get local issuer certificate といった TLS ハンドシェイクエラーが発生することがよくあります。
この不一致が起きる理由は、ブラウザーが macOS キーチェーン(MDM によって組織の検査用ルート CA が登録される場所)を参照するのに対し、多くのコマンドラインランタイム(git、curl、Node.js/npm、Python/pip)や AI ツール(Claude Code、Cursor、MCP サーバー)は、独自に同梱された公開 CA ストアを使って証明書を検証するためです。
1. どのホスト名が HTTPS 検査を受けているか確認する
環境変数やネットワーク設定を変更する前に、失敗しているエンドポイントの証明書チェーンが Mac 上で実際に置き換えられているかを確認します。
- macOS 14 以降(Apple シリコン)に SWG bar をインストールして開きます。
- エラーになるコマンドを一度実行してから SWG bar → ドメインを確認するか、同梱の CLI を使ってターミナルから対象エンドポイントを直接プローブします。
/Applications/SWGBar.app/Contents/MacOS/swgbar probe registry.npmjs.org
/Applications/SWGBar.app/Contents/MacOS/swgbar domains detail registry.npmjs.org
- 分類ステータスとルート CA を確認します。Web フロントエンド、認証サーバー、パッケージレジストリ、LLM API エンドポイントはそれぞれ異なるホスト名を使っていることが多く、あるサブドメインは素通りしていても別のサブドメインが復号されている場合があります。
MCP 対応のアシスタントを利用している場合は、SWG bar 内蔵の MCP サーバーを接続することで、AI クライアントから観測済みドメインや証明書チェーンを直接照会することも可能です。
2. 環境に適した解決策を選ぶ
対象ホスト名の証明書が検査用ルート CA によって署名されていることを確認したら、ネットワークポリシーと権限に応じて次の 3 つのアプローチから選択します。
| アプローチ | 仕組み | 適しているケース |
|---|---|---|
| ツールに CA 信頼を設定する | ランタイムの環境変数(NODE_EXTRA_CA_CERTS、SSL_CERT_FILE、REQUESTS_CA_BUNDLE など)に、社内ルート CA を含むエクスポート済み PEM バンドルを指定します。 |
社内ポリシーで検査付き SWG 経由が必須であり、そのツールに対して該当 CA を信頼できる場合。 |
| 管理者に TLS 検査の除外を依頼する | IT 部門がゲートウェイ上で対象 API やレジストリのホスト名を HTTPS 復号から除外し、ゲートウェイ経路自体は維持します。 | 証明書ピンニングを行うツールやチーム共通の開発エンドポイントが Break-and-Inspect で動作しない場合。 |
| SWG bar でドメイン単位の SWG 回避を有効にする | メニューバー、CLI、または MCP から、選択したホスト名をゲートウェイの HTTPS 復号なしでルーティングします。 | 自身が管理するネットワーク、または Mac 上で特定ドメインの非検査経路をテストする権限がある場合。 |
ゲートウェイでの除外設定と経路変更のアーキテクチャ上の詳しい比較は、SWG 回避と TLS 検査の除外設定の違いをご覧ください。
3. 許可された環境で検査対象ドメインを回避する
ドメイン単位の回避がネットワーク運用上適切な場合は、メニューバー(SWG bar → ドメイン → SWG を回避 → オン)またはターミナルから、該当する API やレジストリの正確なホスト名に対して有効化できます。
/Applications/SWGBar.app/Contents/MacOS/swgbar bypass enable registry.npmjs.org
/Applications/SWGBar.app/Contents/MacOS/swgbar bypass status
ステータスが回避中(CLI では bypassing)になったら、既存の接続を閉じて新しいルールで再接続するよう、CLI コマンド、バックグラウンドデーモン、または IDE の拡張機能ホストを再起動してください。初回利用時の macOS ネットワーク拡張の承認、再起動時の動作、作業完了後に回避をオフにする手順については、Mac で SWG を回避する方法を参照してください。
プラットフォームとネットワークの制約に注意する
- ホスト名単位の適用範囲:
example.comを回避しても、api.example.comやauth.example.comは自動的に含まれません。ツールが通信する各ホスト名を確認してください。 - ネットワーク要件:SWG bar 2.4.12 は Apple シリコン搭載の macOS 14 以降と、物理ネットワークインターフェイス経由の利用可能な IPv4 経路を必要とします。ファイアウォールが直接の外向き接続をブロックしている場合や、ツール自体が明示的プロキシを強制している場合は、回避ルールを無効にし、管理者の TLS 除外設定または CA バンドル設定を使用してください。
- 最新の証拠で検証する:変更を行った後はキャッシュされた結果に頼らず、HTTPS・SSL 検査ガイドの手順で新しく確認を実行してください。