네트워크 설정

프록시 서버, 커스텀 CA(Certificate Authority), mTLS(Mutual Transport Layer Security) 인증을 사용하는 엔터프라이즈 환경에서 Claude Code를 설정하는 방법을 안내합니다.

Claude Code는 환경 변수를 통해 다양한 엔터프라이즈 네트워크 및 보안 설정을 지원합니다. 여기에는 기업 프록시 서버를 통한 트래픽 라우팅, 커스텀 CA 신뢰 설정, 강화된 보안을 위한 mTLS 인증서 인증이 포함됩니다.

참고: 이 페이지에 나오는 모든 환경 변수는 settings.json에서도 설정할 수 있습니다.

프록시 설정

환경 변수

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="*"

참고: Claude Code는 SOCKS 프록시를 지원하지 않습니다.

기본 인증(Basic Authentication)

프록시에 기본 인증이 필요한 경우, 프록시 URL에 자격 증명을 포함시킵니다.

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

주의: 스크립트에 비밀번호를 하드코딩하지 마십시오. 대신 환경 변수나 안전한 자격 증명 저장소를 사용하십시오.

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

프록시 설정 영구화

환경 변수를 매번 수동으로 설정하는 대신, 셸 프로파일 파일(.bashrc, .zshrc)에 추가하거나 settings.json을 통해 영구적으로 설정할 수 있습니다.

{
  "env": {
    "HTTPS_PROXY": "https://proxy.example.com:8080",
    "NO_PROXY": "localhost,192.168.1.1"
  }
}

커스텀 CA 인증서

엔터프라이즈 환경에서는 종종 내부 HTTPS 연결을 위해 자체 서명된 CA를 사용합니다. 프록시를 통한 연결이든 직접 API 접근이든 관계없이, Claude Code가 이러한 CA를 신뢰하도록 설정할 수 있습니다.

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

여러 CA 인증서 설정

여러 CA 인증서를 신뢰해야 하는 경우, 인증서를 하나의 PEM 파일로 합칩니다.

# 여러 인증서를 하나의 파일로 합치기
cat corp-root-ca.pem intermediate-ca.pem > combined-ca.pem
export NODE_EXTRA_CA_CERTS=/path/to/combined-ca.pem

인증서 형식 확인

CA 인증서는 PEM(Base64로 인코딩된 DER) 형식이어야 합니다. DER 바이너리 형식의 인증서는 먼저 변환이 필요합니다.

# DER에서 PEM으로 변환
openssl x509 -inform der -in cert.cer -out cert.pem

mTLS 인증

클라이언트 인증서 인증이 필요한 엔터프라이즈 환경의 경우, 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"

mTLS 설정 확인

설정이 올바른지 확인하려면 OpenSSL을 사용하여 연결을 테스트할 수 있습니다.

# mTLS 연결 테스트
openssl s_client \
  -connect api.anthropic.com:443 \
  -cert /path/to/client-cert.pem \
  -key /path/to/client-key.pem \
  -CAfile /path/to/ca-cert.pem

settings.json을 통한 mTLS 설정

{
  "env": {
    "CLAUDE_CODE_CLIENT_CERT": "/path/to/client-cert.pem",
    "CLAUDE_CODE_CLIENT_KEY": "/path/to/client-key.pem"
  }
}

네트워크 접근 요구 사항

Claude Code가 정상적으로 작동하려면 다음 URL에 대한 접근이 필요합니다.

URL	용도
`api.anthropic.com`	Claude API 엔드포인트
`claude.ai`	claude.ai 계정 인증
`platform.claude.com`	Anthropic 콘솔 계정 인증

프록시 설정 및 방화벽 규칙에서 이 URL들이 허용 목록에 포함되어 있는지 확인하십시오. 이는 컨테이너화된 환경이나 네트워크가 제한된 환경에서 Claude Code를 사용할 때 특히 중요합니다.

방화벽 규칙 예시

다음은 필요한 URL에 대한 방화벽 허용 규칙 예시입니다.

# iptables를 사용하는 경우 (Linux)
iptables -A OUTPUT -d api.anthropic.com -p tcp --dport 443 -j ACCEPT
iptables -A OUTPUT -d claude.ai -p tcp --dport 443 -j ACCEPT
iptables -A OUTPUT -d platform.claude.com -p tcp --dport 443 -j ACCEPT

문제 해결

프록시 연결 문제

프록시를 통한 연결에 문제가 있을 경우 다음을 확인하십시오.

환경 변수 확인: 환경 변수가 올바르게 설정되어 있는지 확인합니다.
```
echo $HTTPS_PROXY
echo $NO_PROXY
```
프록시 URL 형식 확인: 프록시 URL이 올바른 형식인지 확인합니다.
```
https://[username:password@]hostname:port
```
프록시 서버 직접 테스트: curl을 사용하여 프록시 서버 자체를 테스트합니다.
```
curl -x https://proxy.example.com:8080 https://api.anthropic.com
```

CA 인증서 문제

UNABLE_TO_GET_ISSUER_CERT_LOCALLY 또는 유사한 인증서 오류가 발생하는 경우:

CA 인증서 파일 경로가 올바른지 확인합니다.
파일이 PEM 형식인지 확인합니다.
인증서가 만료되지 않았는지 확인합니다.
```
openssl x509 -in /path/to/ca-cert.pem -noout -dates
```

다음 단계

LLM 게이트웨이 설정 - 중앙화된 API 관리
Claude Code 설정 - 전체 설정 옵션
보안 가이드 - 보안 모범 사례
문제 해결 가이드 - 일반적인 문제 해결 방법