Atasi error sertifikat TLS & SSL SWG di CLI dan alat AI di Mac

Atasi error CERTIFICATE_VERIFY_FAILED dan local issuer certificate pada git, npm, Python, Claude Code, serta Cursor di balik SWG pada macOS.

SWG bar · Diperbarui

Saat Mac kantor berada di balik Secure Web Gateway (SWG) yang menjalankan inspeksi HTTPS/SSL (break-and-inspect), Safari dan Chrome sering kali memuat situs web tanpa peringatan sementara alat Terminal dan agen pengodean AI gagal dengan error jabat tangan (handshake) TLS seperti SSL: CERTIFICATE_VERIFY_FAILED, UNABLE_TO_GET_ISSUER_CERT_LOCALLY, atau SSL certificate problem: unable to get local issuer certificate.

Ketidakcocokan ini terjadi karena browser memeriksa Rantai Kunci macOS (Keychain)—tempat MDM dapat memasang CA akar inspeksi organisasi Anda—sedangkan banyak runtime baris perintah (git, curl, Node.js/npm, Python/pip) dan alat AI (Claude Code, Cursor, server MCP) memvalidasi sertifikat terhadap penyimpanan CA publik bawaan mereka sendiri.

1. Pastikan nama host mana yang mengalami inspeksi HTTPS

Sebelum mengubah variabel lingkungan (environment variables) atau pengaturan jaringan, pastikan terlebih dahulu apakah rantai sertifikat endpoint yang gagal memang diganti di Mac Anda:

  1. Pasang dan buka SWG bar pada macOS 14 atau lebih baru (Apple silicon).
  2. Jalankan perintah yang gagal satu kali, lalu periksa SWG bar → Domain—atau uji langsung endpoint tersebut dari Terminal menggunakan CLI bawaan:
/Applications/SWGBar.app/Contents/MacOS/swgbar probe registry.npmjs.org
/Applications/SWGBar.app/Contents/MacOS/swgbar domains detail registry.npmjs.org
  1. Periksa klasifikasi dan CA akarnya. Ingat bahwa antarmuka web, server autentikasi, registri paket, dan endpoint API LLM sering kali menggunakan nama host berbeda—satu subdomain bisa lewat tanpa disentuh sementara subdomain lain didekripsi.

Jika Anda menggunakan asisten yang kompatibel dengan MCP, Anda juga dapat menghubungkan server MCP bawaan SWG bar agar klien AI Anda dapat memeriksa domain yang diamati dan rantai sertifikat secara langsung.

2. Pilih solusi yang tepat untuk lingkungan Anda

Setelah memastikan bahwa CA akar inspeksi menandatangani sertifikat nama host target, pilih salah satu dari tiga pendekatan berikut sesuai kebijakan jaringan dan kewenangan Anda:

Pendekatan Cara kerjanya Paling tepat ketika
Konfigurasi kepercayaan CA untuk alat terkait Arahkan runtime (misalnya NODE_EXTRA_CA_CERTS, SSL_CERT_FILE, atau REQUESTS_CA_BUNDLE) ke bundel PEM hasil ekspor yang menyertakan CA akar perusahaan. Kebijakan perusahaan mewajibkan perutean SWG terinspeksi dan Anda memercayai CA tersebut untuk alat spesifik itu.
Ajukan pengecualian inspeksi TLS ke admin Tim TI mengecualikan nama host API atau registri dari dekripsi HTTPS pada gateway sambil tetap mempertahankan perutean melalui gateway. Alat dengan penyematan sertifikat (certificate pinning) atau endpoint pengembang bersama tim gagal akibat break-and-inspect.
Aktifkan bypass SWG per domain di SWG bar Merutekan nama host terpilih di macOS tanpa dekripsi HTTPS gateway melalui bar menu, CLI, atau MCP. Anda mengelola jaringan atau berwenang menguji rute tanpa inspeksi untuk domain tertentu di Mac Anda.

Baca Bypass SWG vs. pengecualian inspeksi TLS untuk perbandingan arsitektur mendalam antara pengecualian di gateway dan perubahan rute.

3. Lewati domain yang diinspeksi di macOS bila berwenang

Jika bypass per domain sesuai untuk jaringan Anda, aktifkan untuk nama host API atau registri yang tepat melalui bar menu (SWG bar → Domain → Lewati SWG → Aktifkan bypass untuk domain ini) atau dari Terminal:

/Applications/SWGBar.app/Contents/MacOS/swgbar bypass enable registry.npmjs.org
/Applications/SWGBar.app/Contents/MacOS/swgbar bypass status

Setelah status menampilkan Bypass aktif, mulai ulang perintah CLI, daemon latar belakang, atau host ekstensi IDE agar koneksi lama ditutup dan tersambung kembali melalui aturan baru. Ikuti Cara melewati SWG di Mac untuk persetujuan ekstensi jaringan macOS pertama kali, perilaku mulai ulang, dan cara menonaktifkan bypass setelah selesai.

Perhatikan batas platform dan jaringan

  • Cakupan per nama host: Melewati example.com tidak otomatis mencakup api.example.com atau auth.example.com. Periksa setiap nama host yang dihubungi alat Anda.
  • Persyaratan jaringan: SWG bar 2.4.12 memerlukan macOS 14+ pada Apple silicon serta jalur IPv4 yang tersedia melalui antarmuka jaringan fisik. Jika firewall memblokir koneksi keluar langsung atau alat menerapkan proxy eksplisitnya sendiri, nonaktifkan aturan bypass dan gunakan pengecualian TLS administrator atau konfigurasi bundel CA.
  • Verifikasi dengan bukti terbaru: Jalankan pemeriksaan baru menggunakan panduan inspeksi HTTPS & SSL setelah melakukan perubahan apa pun, alih-alih mengandalkan hasil dalam cache.