Claude Code 공식문서 리뷰-Deployment[5] : 기업 네트워크 구성(Enterprise network configuration)

안녕하세요! 갓대희입니다. 

Claude Code Docs 공식 문서 >> Deployment 섹션의 내용 중 [기업 네트워크 구성]을 살펴 보려고 합니다.

https://code.claude.com/docs/en/network-config

Enterprise network configuration - Claude Code Docs

 

이 카테고리의 글은 편하게 공식 문서 위주의 내용을 눈으로 쭉 살펴 보고 넘어가는 목적을 갖고 시작 하게 되었습니다.

저도 초심으로 돌아가 기초적읜 글을 살펴보다보니, 지금와서 클로드에서 강조 하고자 하는 원칙이 어떤건지 되돌아볼 수 있는 계기가 되기도 하는 것 같아, 다른 분들도 꼭 한번 눈으로라도 이해 하고 넘어가는것이 좋다고 생각하여 공식 문서의 내용을 억지로 리뷰해보게 되었습니다.

 

 

엔터프라이즈 네트워크 구성

• 프록시: HTTPS/HTTP 프록시 서버 지원
• 인증서: 커스텀 CA 인증서 구성
• mTLS: 상호 TLS 인증 지원
• 구성: 환경 변수 또는 settings.json

용어 설명: mTLS (Mutual TLS)
서버와 클라이언트가 서로의 인증서를 확인하는 양방향 TLS 인증이다. 일반 TLS는 서버만 인증하지만, mTLS는 클라이언트도 인증서를 제시해야 하므로 더 높은 보안을 제공한다.

엔터프라이즈 네트워크 구성이 왜 필요한가?

실제 상황을 생각해보자

대부분의 기업은 보안상의 이유로 모든 외부 API 호출을 프록시를 통해서만 허용한다.
또한 회사 내부 CA(Certificate Authority)를 사용하거나, 클라이언트 인증서로 신원을 확인하는 mTLS를 요구한다.

상황: 개발자 노트북에서 Claude Code를 실행했는데 "연결 실패" 에러가 뜬다.
원인: 회사 프록시 설정이 없어서 api.anthropic.com에 접근할 수 없다.
해결: 이 문서에서 설명하는 프록시와 인증서 설정을 적용하면 된다.

이 문서가 필요한 경우

• 회사 프록시가 필수인 환경 - 모든 외부 트래픽이 프록시를 거쳐야 한다
• 자체 CA 인증서 사용 - 회사 내부에서 발급한 SSL 인증서를 쓴다
• mTLS 인증 요구 - 클라이언트 인증서로 신원 확인이 필요하다
• 엄격한 방화벽 정책 - 특정 URL만 화이트리스트에 있다

 

프록시 구성

좋은 소식
Claude Code는 업계 표준 프록시 환경 변수를 그대로 쓴다. 다른 CLI 도구(npm, curl 등)를 위해 이미 설정해놨다면, 그대로 동작한다!

환경 변수

Claude Code는 표준 프록시 환경 변수를 지원한다:

# HTTPS 프록시 (권장)
export HTTPS_PROXY=https://proxy.example.com:8080

# HTTP 프록시 (HTTPS를 사용할 수 없는 경우)
export HTTP_PROXY=http://proxy.example.com:8080

# 특정 요청에서 프록시 우회 - 공백 구분 형식
export NO_PROXY="localhost 192.168.1.1 example.com .example.com"

# 특정 요청에서 프록시 우회 - 쉼표 구분 형식
export NO_PROXY="localhost,192.168.1.1,example.com,.example.com"

# 모든 요청에서 프록시 우회
export NO_PROXY="*"

NO_PROXY 실전 팁

• localhost 테스트: 로컬 개발 서버는 프록시 없이 접근하려면 localhost 추가
• 내부 도메인: 회사 내부 서비스는 .company.com (앞에 점 찍으면 모든 서브도메인 포함)
• 형식: 공백 또는 쉼표 구분 둘 다 가능 - 회사 정책에 맞춰 선택하자

참고
Claude Code는 SOCKS 프록시를 지원하지 않는다. HTTP/HTTPS 프록시만 가능하다.

기본 인증

프록시가 기본 인증을 요구하는 경우, 프록시 URL에 자격 증명을 포함한다:

export HTTPS_PROXY=http://username:password@proxy.example.com:8080

보안 경고
스크립트에 비밀번호를 하드코딩하지 않는다. 대신 환경 변수나 안전한 자격 증명 저장소를 사용한다.

팁
고급 인증(NTLM, Kerberos 등)이 필요한 프록시의 경우, 해당 인증 방법을 지원하는 LLM 게이트웨이 서비스 사용을 고려한다.

 

커스텀 CA 인증서

언제 필요한가?

회사에서 자체적으로 발급한 SSL 인증서를 사용한다면 이 설정이 필수다.
예: 프록시 서버가 proxy.company.com인데, 이 도메인의 인증서가 공용 CA(Let's Encrypt 등)가 아닌 회사 내부 CA에서 발급되었다면, Claude Code가 "신뢰할 수 없는 인증서" 에러를 낸다.

기업 환경에서 HTTPS 연결에 커스텀 CA를 사용하는 경우(프록시를 통하든 직접 API 접근이든), Claude Code가 이를 신뢰하도록 구성한다:

export NODE_EXTRA_CA_CERTS=/path/to/ca-cert.pem

 

mTLS 인증

언제 필요한가?

초고보안 환경에서 사용한다. 서버가 "너 누구야?"라고 물어볼 때, 클라이언트가 인증서로 신분을 증명해야 하는 구조다.

예: 금융권, 정부기관, 의료 시스템처럼 높은 보안이 필요한 곳에서 "이 요청이 정말 우리 회사의 승인된 클라이언트에서 온 거 맞아?"를 확인할 때 쓴다.

클라이언트 인증서 인증이 필요한 엔터프라이즈 환경:

# 인증용 클라이언트 인증서
export CLAUDE_CODE_CLIENT_CERT=/path/to/client-cert.pem

# 클라이언트 개인 키
export CLAUDE_CODE_CLIENT_KEY=/path/to/client-key.pem

# 선택: 암호화된 개인 키의 암호문
export CLAUDE_CODE_CLIENT_KEY_PASSPHRASE="your-passphrase"

 

네트워크 접근 요구사항

방화벽 담당자에게 전달할 정보

네트워크 팀에 화이트리스트 요청할 때 아래 표를 복사해서 보내면 된다.
"Claude Code 도입을 위해 다음 URL들을 허용해달라고" 요청하자.

Claude Code는 다음 URL에 대한 접근이 필요하다:

URL	용도
api.anthropic.com	Claude API 엔드포인트
claude.ai	WebFetch 안전장치
statsig.anthropic.com	텔레메트리 및 메트릭
sentry.io	오류 보고

중요
프록시 구성 및 방화벽 규칙에서 이 URL들이 허용 목록에 있는지 확인한다. 컨테이너화된 환경이나 제한된 네트워크 환경에서 Claude Code를 사용할 때 특히 중요하다.

 

구성 방법

표시된 모든 환경 변수는 세션 간 지속적인 구성을 위해 settings.json에서도 구성할 수 있다:

{
  "env": {
    "HTTPS_PROXY": "https://proxy.example.com:8080",
    "NODE_EXTRA_CA_CERTS": "/path/to/ca-cert.pem"
  }
}

 

빠른 설정 체크리스트

내 환경에 맞는 단계만 진행하자

모든 설정이 다 필요한 건 아니다. 회사 보안 정책에 따라 필요한 것만 체크하면 된다.

단계 1: 기본 프록시 (대부분의 기업 환경)

1. ☐ IT 팀에서 프록시 주소 받기 (예: proxy.company.com:8080)
2. ☐ 환경 변수 설정:

   export HTTPS_PROXY=http://proxy.company.com:8080

3. ☐ 인증이 필요하면 URL에 자격 증명 포함
4. ☐ Claude Code 실행 테스트

단계 2: 커스텀 CA 인증서 (자체 SSL 인증서 사용 시)

1. ☐ IT 팀에서 CA 인증서 파일 받기 (보통 .pem 또는 .crt)
2. ☐ 인증서를 안전한 경로에 저장 (예: ~/.certs/company-ca.pem)
3. ☐ 환경 변수 설정:

   export NODE_EXTRA_CA_CERTS=~/.certs/company-ca.pem

4. ☐ 인증서 검증 에러가 사라졌는지 확인

단계 3: mTLS 인증 (최고 보안 환경)

1. ☐ IT 팀에서 클라이언트 인증서와 개인 키 받기
2. ☐ 인증서 파일을 안전한 경로에 저장
3. ☐ 환경 변수 설정:

   export CLAUDE_CODE_CLIENT_CERT=~/.certs/client.pem
   export CLAUDE_CODE_CLIENT_KEY=~/.certs/client-key.pem
   # 키가 암호화되어 있다면
   export CLAUDE_CODE_CLIENT_KEY_PASSPHRASE="your-passphrase"

4. ☐ mTLS 인증이 성공하는지 확인

단계 4: 방화벽 화이트리스트 요청

1. ☐ 네트워크 팀에 다음 URL 허용 요청:
   • api.anthropic.com (필수 - Claude API)
   • claude.ai (WebFetch용)
   • statsig.anthropic.com (텔레메트리)
   • sentry.io (오류 보고)
2. ☐ 승인 후 연결 테스트

설정을 영구적으로 만들기

환경 변수를 매번 설정하기 귀찮다면, ~/.claude/settings.json에 저장하자:

{
  "env": {
    "HTTPS_PROXY": "http://proxy.company.com:8080",
    "NODE_EXTRA_CA_CERTS": "/home/user/.certs/company-ca.pem"
  }
}

핵심 환경 변수 요약

HTTPS_PROXY	프록시 서버 주소
NO_PROXY	프록시 우회할 도메인
NODE_EXTRA_CA_CERTS	커스텀 CA 인증서 경로
CLAUDE_CODE_CLIENT_CERT	mTLS 클라이언트 인증서
CLAUDE_CODE_CLIENT_KEY	mTLS 개인 키

 

문제 해결

에러 1: "Connection failed" / "ECONNREFUSED"

원인과 해결

1. 프록시 URL 형식 확인
잘못된 경우: proxy.example.com:8080 (프로토콜 없음)
올바름: http://proxy.example.com:8080

2. 환경 변수 확인
터미널에서 echo $HTTPS_PROXY 실행해서 값이 제대로 설정되었는지 확인

3. 프록시 서버 접근 가능 여부
curl -x http://proxy.example.com:8080 https://api.anthropic.com로 테스트

에러 2: "Certificate verification failed" / "UNABLE_TO_VERIFY_LEAF_SIGNATURE"

원인과 해결

원인: 회사 내부 CA 인증서를 신뢰하지 못한다.

해결 1단계: CA 인증서 파일 경로 확인
ls -la /path/to/ca-cert.pem - 파일이 존재하고 읽기 가능한지 확인

해결 2단계: 인증서 내용 확인
openssl x509 -in /path/to/ca-cert.pem -text -noout - 인증서가 유효한지 확인

해결 3단계: NODE_EXTRA_CA_CERTS 적용
export NODE_EXTRA_CA_CERTS=/path/to/ca-cert.pem

에러 3: "Client certificate required" / mTLS 인증 실패

원인과 해결

체크리스트:

1. 인증서와 키 파일이 존재하는가? ls -la /path/to/client-*
2. 인증서와 키가 짝이 맞는가? (보통 같은 이름으로 .crt/.key 또는 .pem)
3. 개인 키가 암호화되어 있다면 PASSPHRASE를 설정했는가?
4. 인증서가 만료되지 않았는가? openssl x509 -in cert.pem -noout -dates

디버깅 팁

단계별 확인 순서

1. 프록시 없이 테스트: NO_PROXY="*" 설정 후 실행 - 프록시 문제인지 확인
2. curl로 먼저 테스트: curl로 api.anthropic.com에 접근 가능한지 확인
3. 환경 변수 출력: env | grep -i proxy, env | grep -i claude
4. 네트워크 팀에 문의: 위 단계로 해결 안 되면 방화벽 규칙 확인 요청

 

다음 단계 - 상황별 가이드

💡 네트워크 설정 완료! 이제 뭘 봐야 할까?

네트워크 구성은 끝났다. 이제 사용 환경에 맞는 추가 설정을 진행하자.

문서	언제 유용한가?
Third-party Integrations 공식 문서	AWS Bedrock, Google Vertex AI 같은 서드파티 클라우드를 통해 Claude를 쓰는 경우 • 회사에서 이미 AWS/GCP/Azure 계약이 있다 • 기존 클라우드 인프라와 통합하고 싶다 • IAM 정책으로 권한 관리를 하고 싶다
LLM Gateway 공식 문서	LLM 게이트웨이를 사용해서 Claude API 호출을 중앙 관리하는 경우 • 여러 LLM(Claude, GPT 등)을 하나의 엔드포인트로 통합 • 사용량, 비용, 로깅을 중앙에서 관리 • Portkey, Helicone 같은 게이트웨이 서비스를 쓴다
Sandboxing 공식 문서	Claude Code가 실행하는 명령어를 안전하게 격리하고 싶은 경우 • 프로덕션 서버에서 Claude Code를 실행한다 • 파일 시스템/네트워크 접근을 제한하고 싶다 • 보안 정책상 샌드박스 격리가 필요하다
Dev Container 공식 문서	Docker 컨테이너 안에서 Claude Code를 실행하는 경우 • 개발 환경을 컨테이너로 통일하고 싶다 • 팀원 모두가 동일한 환경에서 작업해야 한다 • VS Code Dev Containers를 이미 사용 중이다

권장 학습 경로

1. 직접 Claude API 쓴다면: 설정 완료! 바로 사용 시작
2. AWS/GCP 등 서드파티 통합: Third-party Integrations 문서 확인
3. LLM 게이트웨이 사용: LLM Gateway 문서로 이동
4. 보안이 중요하다면: Sandboxing 문서 검토
5. 컨테이너 환경: Dev Container 문서 참고