Cursor와 Claude Code의 HTTPS_PROXY 설정 방법 (기업 네트워크에서)

귀하의 회사가 기업 프록시를 통해 아웃바운드 트래픽을 차단하는 경우, Cursor 및 Claude Code와 같은 AI 어시스턴트는 응답을 멈추게 됩니다: 자동 완성이 멈추고, CLI는 ETIMEDOUT 또는 SSL certificate problem을 출력합니다. 환경 변수 HTTPS_PROXY를 올바르게 설정하고, 인증을 구성하며, 개발자가 코드 대신 네트워크 설정 디버깅에 몇 시간을 낭비하게 만드는 일반적인 오류를 피하는 방법을 알아보겠습니다.

기업 네트워크에서 AI 어시스턴트에 프록시가 필요한 이유

Cursor와 Claude Code는 로컬 모델이 아닙니다. 이들은 외부 API에 지속적으로 접근합니다: Cursor는 코드 인덱싱 서버와 모델 API(OpenAI, Anthropic, Google 등 선택한 공급자에 따라)에 요청을 보내고, Claude Code는 HTTPS를 통해 Anthropic API에 직접 접근합니다. 기업 네트워크에서는 인터넷에 대한 직접 접근이 방화벽에 의해 차단되는 경우가 많으며, 모든 아웃바운드 트래픽은 프록시 서버(Squid, Zscaler, Blue Coat, Fortinet FortiProxy 또는 내부 기업 게이트웨이)를 통해 이루어져야 합니다. 올바르게 설정된 환경 변수가 없으면 애플리케이션은 트래픽을 프록시를 통해 전송해야 한다는 것을 알지 못하고 직접 인터넷에 접근하려고 시도하여 타임아웃이 발생합니다.

추가적인 복잡성은 Cursor가 Electron(기본적으로 Chromium + Node.js) 기반으로 구축되었고, Claude Code는 Node.js CLI 애플리케이션이라는 점입니다. 각 애플리케이션은 프록시 설정을 읽는 방식이 다릅니다: Electron은 부분적으로 운영 체제의 시스템 설정을 상속받고, Node.js 프로세스는 HTTP_PROXY/HTTPS_PROXY 변수를 직접 읽거나 undici 및 node-fetch와 같은 라이브러리를 통해 읽습니다. 이로 인해 혼란이 발생할 수 있습니다: 설정이 되어 있지만 도구가 이를 "인식하지 못하는" 경우가 발생합니다.

HTTP_PROXY, HTTPS_PROXY 및 NO_PROXY 변수: 작동 방식

Node.js, Python 및 Go 애플리케이션의 콘솔 프록시를 지정하는 전통적인 방법은 환경 변수를 사용하는 것입니다. HTTP_PROXY와 HTTPS_PROXY의 차이는 본질적입니다: 첫 번째는 HTTP 프로토콜 요청에 사용되고, 두 번째는 HTTPS 요청에 사용됩니다(대부분의 AI 어시스턴트 트래픽은 HTTPS를 통해 이루어집니다). 실제 트래픽이 HTTPS만 있더라도 두 변수를 모두 지정하는 것이 좋습니다 — 일부 라이브러리는 시작 시 HTTP 요청을 수행합니다.

export HTTP_PROXY="http://proxy.company.local:8080"
export HTTPS_PROXY="http://proxy.company.local:8080"
export NO_PROXY="localhost,127.0.0.1,.company.local"

주의: HTTPS 트래픽의 경우에도 프록시 주소의 스킴은 http://로 지정해야 하며, https://가 아닙니다 — 이는 프록시 서버의 주소이지 대상 리소스의 주소가 아닙니다. HTTP를 통한 프록시 연결은 정상이며, 최종 서버까지의 암호화는 여전히 CONNECT 터널링 메커니즘을 통해 작동합니다.

NO_PROXY

export http_proxy="$HTTP_PROXY"
export https_proxy="$HTTPS_PROXY"
export no_proxy="$NO_PROXY"

Cursor용 프록시 설정

Cursor는 시스템의 프록시 설정을 일부 사용하지만(특히 macOS 및 Windows에서), 기업 네트워크에서 안정적으로 작동하려면 환경 변수를 명시적으로 설정하고 필요에 따라 애플리케이션의 구성 파일을 통해 설정하는 것이 좋습니다.

macOS 및 Linux에서는 가장 간단하게 쉘 프로파일 파일에 변수를 추가하여 Cursor를 시작하는 각 터미널에서 이를 읽도록 설정할 수 있습니다:

# ~/.zshrc 또는 ~/.bash_profile
export HTTP_PROXY="http://user:[email protected]:8080"
export HTTPS_PROXY="http://user:[email protected]:8080"
export NO_PROXY="localhost,127.0.0.1,*.company.local"

프로파일 파일을 변경한 후 source ~/.zshrc 명령을 실행하고 Cursor를 완전히 재시작하세요(단순히 창을 최소화하지 말고 — Activity Monitor 또는 작업 관리자를 통해 프로세스를 종료하세요, Electron 애플리케이션은 시작 시 환경을 캐시합니다).

Windows에서는 시스템 환경 설정(제어판 → 시스템 → 고급 시스템 설정 → 환경 변수) 또는 PowerShell을 통해 변수를 설정하는 것이 더 편리합니다:

[System.Environment]::SetEnvironmentVariable('HTTPS_PROXY','http://user:[email protected]:8080','User')
[System.Environment]::SetEnvironmentVariable('HTTP_PROXY','http://user:[email protected]:8080','User')
[System.Environment]::SetEnvironmentVariable('NO_PROXY','localhost,127.0.0.1','User')

이 후에도 Cursor가 여전히 모델 API에 연결되지 않는 경우, 애플리케이션 내에서 프록시 설정을 확인하세요: Settings → Network (또는 General) — 그곳에 시스템 변수를 덮어쓰는 별도의 Proxy URL 필드가 있을 수 있습니다. 일부 Cursor 빌드에서는 "Use system proxy settings" 옵션을 명시적으로 활성화해야 합니다.

Claude Code용 프록시 설정

Claude Code는 Node.js 기반의 CLI 도구로, npm/npx를 통해 실행되므로 호출된 터미널 세션에서 직접 환경 변수를 읽습니다. 이는 설정을 간소화합니다: 실행 전에 변수를 내보내기만 하면 됩니다.

export HTTPS_PROXY="http://user:[email protected]:8080"
export HTTP_PROXY="http://user:[email protected]:8080"
claude

CI 파이프라인의 일부로 또는 스크립트에서 Claude Code를 실행하는 경우, 전역 쉘 환경에 대한 의존성을 피하기 위해 실행 명령에 변수를 명시적으로 전달하세요:

HTTPS_PROXY="http://proxy.company.local:8080" \
HTTP_PROXY="http://proxy.company.local:8080" \
claude --print "프로젝트에서 테스트를 확인하세요"

지속적인 구성을 위해서는 .env 파일에 변수를 고정하고 direnv 또는 내장된 dotenv 지원을 통해 이를 읽어오는 것이 편리합니다, 쉘이 이를 지원하는 경우. 이는 서로 다른 프로젝트가 서로 다른 프록시 설정을 요구할 때 특히 유용합니다(예: 하나의 프로젝트는 내부 API와 작업하고, 다른 하나는 외부 서비스와 작업합니다).

기업 프록시에서의 인증

대부분의 기업 프록시는 인증을 요구합니다 — Basic Auth, Digest 또는 NTLM. Basic Auth의 경우 로그인과 비밀번호를 프록시 URL에 직접 포함시킬 수 있습니다, 위에서 보여준 것처럼: http://user:[email protected]:8080. 중요한 점은 비밀번호에 특수 문자가 포함되어 있는 경우(@, #, %), 이를 URL 인코딩해야 하며, 그렇지 않으면 프록시 문자열 파서가 로그인과 호스트 경계에서 실패합니다.

# 비밀번호가 P@ssw0rd#2024인 경우, 특수 문자를 인코딩합니다:
# @ -> %40, # -> %23
export HTTPS_PROXY="http://user:P%40ssw0rd%[email protected]:8080"

NTLM 인증은 더 복잡합니다(종종 Microsoft ISA Server, Forefront TMG 또는 Fortinet과 함께 사용됨) — Node.js 및 대부분의 HTTP 클라이언트는 NTLM 핸드셰이크를 기본적으로 지원하지 않습니다. 이 경우 표준 해결책은 NTLM 핸드셰이크를 처리하고 이후 애플리케이션에 "깨끗한" HTTP 프록시를 제공하는 로컬 프록시 미들웨어를 설정하는 것입니다. 이를 위해 cntlm 또는 px (Python으로 작성된 로컬 NTLM 프록시)를 자주 사용합니다. 구조는 간단합니다: Cursor/Claude Code → localhost:3128 (cntlm) → 기업 NTLM 프록시 → 인터넷.

# cntlm의 예시 구성 (/etc/cntlm.conf)
Username    your_login
Domain      COMPANY
Password    귀하의_비밀번호_또는_해시
Proxy       proxy.company.local:8080
Listen      3128

# cntlm을 실행한 후, 로컬 주소를 지정합니다:
export HTTPS_PROXY="http://127.0.0.1:3128"
export HTTP_PROXY="http://127.0.0.1:3128"

인증서 및 MITM: 기업 네트워크의 SSL 문제

회사에 Zscaler, Netskope 또는 기타 SSL 검사 웹 필터가 배포된 경우, 트래픽은 프록시에서 해독되고 기업 Root CA 인증서로 서명됩니다. Node.js(즉, Claude Code 및 Cursor의 대부분의 내부 모듈)는 기본적으로 내장된 루트 인증서 집합만 신뢰하며 UNABLE_TO_VERIFY_LEAF_SIGNATURE 또는 self signed certificate in certificate chain 오류를 발생시킵니다.

해결책은 기업 CA 인증서를 내보내는 것입니다(보통 IT 부서에서 받을 수 있거나 브라우저의 인증서 저장소에서 내보낼 수 있습니다) 그리고 Node.js에 NODE_EXTRA_CA_CERTS 변수를 통해 경로를 지정하는 것입니다:

export NODE_EXTRA_CA_CERTS="/etc/ssl/certs/company-root-ca.pem"

NODE_TLS_REJECT_UNAUTHORIZED=0를 통해 인증서 검증을 전역적으로 비활성화하는 것은 강력히 권장되지 않습니다 — 이는 전체 프로세스에서 MITM 공격에 대한 보호를 제거하며, 합법적인 연결도 포함됩니다. 이 플래그는 단지 진단을 위해서만 사용하고 반드시 보호를 다시 활성화해야 합니다.

일반적인 오류 및 해결 방법

오류	원인	해결 방법
ETIMEDOUT / ECONNREFUSED	애플리케이션이 실행되는 세션에 프록시 변수가 내보내지지 않음	같은 터미널에서 echo $HTTPS_PROXY를 확인하고 애플리케이션을 완전히 재시작하세요
407 Proxy Authentication Required	로그인/비밀번호가 지정되지 않았거나 만료됨	프록시 문자열에서 자격 증명을 업데이트하고 비밀번호의 특수 문자를 URL 인코딩하세요
self signed certificate in certificate chain	기업 MITM 프록시가 인증서를 대체함	기업 Root CA와 함께 NODE_EXTRA_CA_CERTS를 지정하세요
프록시는 터미널에서 작동하지만 Cursor에서는 작동하지 않음	Cursor가 잘못된 터미널에서 실행되었거나 환경이 없는 바로 가기를 통해 실행됨	내보낸 변수가 있는 터미널에서 명령으로 Cursor를 실행하거나 시스템에서 전역적으로 변수를 설정하세요
NTLM authentication failed	클라이언트가 NTLM 핸드셰이크를 지원하지 않음	애플리케이션과 기업 프록시 사이에 중간 프록시 cntlm 또는 px를 설정하세요

curl을 통한 연결 확인

Cursor 또는 Claude Code가 작동하지 않는 이유를 파악하기 전에, 프록시가 기본적으로 접근 가능하고 HTTPS 트래픽을 올바르게 프록시하는지 확인하세요. 이를 위해 curl을 사용하세요 — curl은 동일한 환경 변수를 읽고 무거운 애플리케이션을 실행하지 않고도 문제를 빠르게 찾을 수 있습니다.

# 프록시 접근 가능성 및 인증 확인
curl -v -x "http://user:[email protected]:8080" https://api.anthropic.com

# 기업 인증서를 고려한 확인
curl -v --cacert /etc/ssl/certs/company-root-ca.pem \
  -x "http://user:[email protected]:8080" \
  https://api.anthropic.com

curl이 성공적으로 응답을 받는 경우(401 또는 403도 정상입니다. 이는 TLS 핸드셰이크가 성공했음을 의미합니다), Claude Code가 여전히 연결되지 않는 경우 — 문제는 네트워크가 아니라 프로세스가 환경 변수를 인식하지 못하는 것입니다. 그러나 curl도 인증서 오류 또는 타임아웃으로 실패하는 경우 — 문제는 네트워크 또는 프록시 수준에서 발생하며, 도구와는 관련이 없습니다.

기업 대신 외부 프록시가 필요한 경우

때때로 작업은 기업 네트워크에서 외부로의 접근에 국한되지 않습니다. 지리적으로 의존적인 API와 통합을 테스트하는 개발자들은 다양한 국가에서 서비스의 동작을 확인하거나 공급자의 모델에 대한 속도 제한 정책을 디버깅하면서 기업 프록시가 모든 요청에 대해 동일한 기업 IP를 반환하는 문제에 직면합니다. 이러한 시나리오에서는 주요 작업 환경과 병행하여 테스트 트래픽을 외부 프록시를 통해 전송하는 것이 편리합니다.

안정적이고 장기적인 테스트 세션을 위해 IP 차단 위험이 최소화된 주거용 프록시가 적합합니다 — 이들은 실제 가정용 공급자의 IP 주소를 사용하며 일반 사용자 트래픽처럼 보이므로 API의 지리적 특정 응답을 확인할 때 중요합니다. 모바일 클라이언트의 동작을 재현하거나 네트워크 유형에 민감한 시나리오를 테스트해야 하는 경우, 모바일 프록시를 고려해야 합니다. 공개 API에 대한 대량 병렬 요청 테스트의 경우, 속도와 트래픽 비용이 중요하고 일반 사용자처럼 가장하는 것이 아닌 경우, 데이터 센터 프록시가 일반적으로 충분합니다.

중요: 이러한 외부 프록시는 HTTPS_PROXY/HTTP_PROXY 변수를 통해 동일하게 설정되지만, 테스트 환경 또는 별도의 터미널 프로필을 위해 설정하여 기업 게이트웨이를 통한 주요 작업 트래픽과 혼합되지 않도록 해야 합니다. 기업 정책이 모든 회사 트래픽이 내부 프록시를 통해서만 전송되도록 요구하는 경우, 외부 사용은 IT/Security와 협의해야 하며 — 많은 회사가 허가 없이 기업 게이트웨이를 우회하는 것을 명시적으로 금지합니다.

설정 체크리스트

결론

Cursor 및 Claude Code의 대부분의 문제는 세 가지로 요약됩니다: 환경 변수가 프로세스에 도달하지 않거나, 인증이 잘못 설정되었거나, 기업 MITM 인증서가 신뢰된 인증서에 추가되지 않았습니다. 이 세 가지 항목을 순서대로 확인하면 — curl을 통해, 애플리케이션을 통해 바로 확인하지 말고 — 디버깅에 몇 시간을 절약하고 문제의 원인을 빠르게 파악할 수 있습니다.

만약 작업이 기업 네트워크의 범위를 넘어 API의 동작을 다양한 지역에서 테스트해야 하거나 다양한 유형의 IP로 테스트해야 하는 경우, 주거용 프록시를 시도해보는 것을 추천합니다 — 이들은 일반 데이터 센터 주소에 비해 외부 서비스에 대해 안정적이고 덜 의심스러운 트래픽을 제공합니다.