Source: https://swgbar.com/ko/guides/swg-tls-certificate-errors-macos/
Language: ko

# Mac의 CLI 및 AI 도구에서 발생하는 SWG TLS/SSL 인증서 오류 해결

macOS의 SWG 환경에서 git, npm, Python, Claude Code, Cursor에 발생하는 CERTIFICATE\_VERIFY\_FAILED 및 로컬 발급자 인증서 오류를 진단하고 해결하세요.

SWG bar · 업데이트 2026년 11월 18일

회사 Mac이 \*\*HTTPS/SSL 검사(Break-and-Inspect)\*\*를 수행하는 보안 웹 게이트웨이(SWG) 뒤에 있으면 Safari와 Chrome에서는 경고 없이 웹사이트가 열리지만, 터미널 도구와 AI 코딩 에이전트에서는 `SSL: CERTIFICATE_VERIFY_FAILED`, `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, `SSL certificate problem: unable to get local issuer certificate` 같은 TLS 핸드셰이크 오류가 발생하는 경우가 많습니다.

이러한 불일치가 생기는 이유는 브라우저는 MDM이 조직의 검사 루트 CA를 설치해 둔 \*\*macOS 키체인(Keychain)\*\*을 참조하는 반면, 많은 명령줄 런타임(`git`, `curl`, `Node.js`/`npm`, `Python`/`pip`)과 AI 도구(`Claude Code`, `Cursor`, MCP 서버)는 자체적으로 번들링된 공개 CA 저장소를 기준으로 인증서를 검증하기 때문입니다.

## 1\. 어떤 호스트 이름이 HTTPS 검사를 받고 있는지 확인하기

환경 변수나 네트워크 설정을 바꾸기 전에, 실패하는 엔드포인트의 인증서 체인이 Mac에서 실제로 교체되고 있는지 먼저 확인하세요.

1.  macOS 14 이상(Apple Silicon)에 [SWG bar를 설치하고 엽니다](<https://swgbar.com/ko/install/>).
2.  실패하는 명령을 한 번 실행한 뒤 **SWG bar → 도메인**을 확인하거나, 내장된 [CLI](<https://swgbar.com/ko/cli/>)를 사용해 터미널에서 해당 엔드포인트를 직접 프로브합니다.

```
/Applications/SWGBar.app/Contents/MacOS/swgbar probe registry.npmjs.org
/Applications/SWGBar.app/Contents/MacOS/swgbar domains detail registry.npmjs.org
```

3.  분류 상태와 루트 CA를 확인합니다. 웹 프론트엔드, 인증 서버, 패키지 레지스트리, LLM API 엔드포인트는 서로 다른 호스트 이름을 사용하는 경우가 많아서, 한 하위 도메인은 그대로 통과하더라도 다른 하위 도메인은 복호화되고 있을 수 있습니다.

MCP 호환 어시스턴트를 사용 중이라면 [SWG bar의 내장 MCP 서버](<https://swgbar.com/ko/mcp/>)를 연결해 AI 클라이언트가 관측된 도메인과 인증서 체인을 직접 조회하도록 할 수도 있습니다.

## 2\. 환경에 맞는 해결 방법 선택하기

검사 루트 CA가 대상 호스트 이름의 인증서에 서명하고 있음을 확인했다면, 네트워크 정책과 권한에 따라 다음 세 가지 접근 방식 중 하나를 선택하세요.

| 접근 방식 | 작동 원리 | 적합한 상황 |
| --- | --- | --- |
| **도구에 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를 통해 macOS에서 선택한 호스트 이름을 게이트웨이 HTTPS 복호화 없이 라우팅합니다. | 네트워크를 직접 관리하거나 Mac에서 특정 도메인에 대해 비검사 경로를 테스트하도록 승인받았을 때. |

게이트웨이 예외와 경로 변경의 아키텍처 차이에 대한 자세한 비교는 [SWG 우회와 TLS 검사 예외 비교](<https://swgbar.com/ko/guides/swg-bypass-vs-tls-exception/>)를 읽어보세요.

## 3\. 승인된 환경에서 macOS의 검사 대상 도메인 우회하기

도메인별 우회가 네트워크 정책에 부합한다면 메뉴 막대(**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를 우회하는 방법](<https://swgbar.com/ko/guides/how-to-bypass-swg/>)을 참고하세요.

## 플랫폼 및 네트워크 경계 유의하기

*   **호스트 이름 단위의 적용 범위**: `example.com`을 우회해도 `api.example.com`이나 `auth.example.com`이 자동으로 포함되지는 않습니다. 도구가 접속하는 각 호스트 이름을 개별적으로 확인하세요.
*   **네트워크 요구 사항**: SWG bar 2.4.12는 Apple Silicon 기반 macOS 14 이상과 물리적 네트워크 인터페이스를 통한 사용 가능한 IPv4 경로가 필요합니다. 방화벽이 직접 아웃바운드 연결을 차단하거나 도구가 자체 명시적 프록시를 강제하는 경우 우회 규칙을 비활성화하고 관리자 TLS 예외 또는 CA 번들 구성을 대신 사용하세요.
*   **최신 근거로 검증하기**: 설정을 변경한 뒤에는 캐시된 결과에 의존하지 말고 [HTTPS 및 SSL 검사 가이드](<https://swgbar.com/ko/guides/detect-https-inspection/>)를 사용해 새로 확인하세요.

## 관련 가이드

*   [Mac에서 SWG 우회하는 방법 (원클릭 도메인 우회 및 CLI)](<https://swgbar.com/ko/guides/how-to-bypass-swg/>)
*   [Mac에서 SSL 검사 우회하는 방법(기업 SWG 도메인별 해결책)](<https://swgbar.com/ko/guides/bypass-ssl-inspection-mac/>)
*   [macOS에서 HTTPS 및 TLS 검사 우회하는 방법(Break-and-Inspect 가이드)](<https://swgbar.com/ko/guides/bypass-https-tls-inspection-mac/>)
*   [Mac에서 기업 프록시 및 SWG SSL 검사 우회하는 방법](<https://swgbar.com/ko/guides/bypass-corporate-proxy-ssl-inspection-mac/>)
*   [내 Mac이 SWG에 의해 가로채기되고 있는지 확인하는 방법(HTTPS 및 SSL 검사)](<https://swgbar.com/ko/guides/detect-https-inspection/>)
*   [회사나 업무용 Mac이 HTTPS를 가로채고 있는지 확인하는 방법(SSL 검사)](<https://swgbar.com/ko/guides/check-if-work-mac-intercepting-https/>)
*   [Mac용 SSL 검사 체커: HTTPS 가로채기를 감지하는 메뉴 막대 도구](<https://swgbar.com/ko/guides/ssl-inspection-checker-mac/>)
*   [Mac의 Zscaler SSL 검사: 도메인별 확인 및 우회 방법](<https://swgbar.com/ko/guides/zscaler-ssl-inspection-bypass-mac/>)
*   [Mac의 Netskope SSL 검사: 복호화 확인 및 도메인별 우회](<https://swgbar.com/ko/guides/netskope-ssl-inspection-bypass-mac/>)
*   [Mac의 Cloudflare WARP 및 Zero Trust TLS 검사: 감지 및 우회](<https://swgbar.com/ko/guides/cloudflare-warp-tls-inspection-mac/>)
*   [SWG bar에서 HTTPS 검사의 ‘확인됨’과 ‘의심됨’ 분류 이해하기](<https://swgbar.com/ko/guides/confirmed-vs-suspected-https-inspection/>)
*   [SWG bar에서 중간자(MITM) 루트 인증서 및 발급자 확인하기](<https://swgbar.com/ko/guides/inspect-mitm-root-certificates-macos/>)
*   [Mac의 기업용 SWG 및 MDM HTTPS 검사 원리](<https://swgbar.com/ko/guides/enterprise-swg-https-inspection-macos/>)
*   [SWG 우회와 TLS 검사 예외(Break-and-Inspect) 비교](<https://swgbar.com/ko/guides/swg-bypass-vs-tls-exception/>)
*   [Mac에서 멀티 도메인 웹 앱, SSO, CDN, API용 SWG 우회하기](<https://swgbar.com/ko/guides/multi-domain-sso-api-cdn-swg-bypass/>)
*   [Mac에서 SWG 우회 ‘복구 중’, ‘일시 중지’ 및 연결 오류 해결하기](<https://swgbar.com/ko/guides/troubleshoot-swg-bypass-recovering-paused-macos/>)
*   [macOS VPN 가상 인터페이스와 SWG HTTPS 검사 비교](<https://swgbar.com/ko/guides/macos-vpn-virtual-interface-vs-swg-inspection/>)
*   [인증서 피닝 및 mTLS 앱이 SWG 검사 환경에서 실패하는 이유](<https://swgbar.com/ko/guides/certificate-pinning-mtls-swg-inspection-macos/>)
*   [Mac의 SWG 환경에서 Homebrew, Docker, Python, Node.js CA 신뢰 구성](<https://swgbar.com/ko/guides/homebrew-docker-python-node-ca-trust-swg-macos/>)
*   [Mac에서 Claude Code 및 Cursor의 'unable to get local issuer certificate' 오류 해결(SWG 및 MCP)](<https://swgbar.com/ko/guides/ai-coding-agents-claude-code-cursor-swg-macos/>)
*   [Mac에서 openssl과 security verify-cert로 TLS 인증서 검증하기](<https://swgbar.com/ko/guides/verify-tls-certificates-openssl-security-verify-cert-macos/>)
*   [SWG bar 권한, 로컬 개인정보 보호 및 TLS 프로브 제한](<https://swgbar.com/ko/guides/macos-network-extension-privacy-probe-limits/>)
*   [SWG bar의 HTTPS 검사 원리](<https://swgbar.com/ko/how-it-works/>)
*   [Mac용 SWG bar 다운로드 및 설치(macOS 14+)](<https://swgbar.com/ko/install/>)
*   [SSL 및 HTTPS 검사를 감지하는 Chrome 확장 프로그램(SWG bar 연동)](<https://swgbar.com/ko/chrome-extension/>)
*   [SWG bar CLI 가이드](<https://swgbar.com/ko/cli/>)
*   [SWG bar MCP 가이드](<https://swgbar.com/ko/mcp/>)
*   [SWG bar 릴리스 정보](<https://swgbar.com/ko/releases/>)
*   [SWG bar 소개](<https://swgbar.com/ko/about/>)
