네트워크 설정

프록시 서버, 커스텀 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 설정 - 전체 설정 옵션
보안 가이드 - 보안 모범 사례
문제 해결 가이드 - 일반적인 문제 해결 방법

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

참고: 이 페이지에 나오는 모든 환경 변수는 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 인증서

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에 대한 방화벽 허용 규칙 예시입니다.

# 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 설정 - 전체 설정 옵션
보안 가이드 - 보안 모범 사례
문제 해결 가이드 - 일반적인 문제 해결 방법

프록시 설정

환경 변수

기본 인증(Basic Authentication)

프록시 설정 영구화

커스텀 CA 인증서

여러 CA 인증서 설정

인증서 형식 확인

mTLS 인증

mTLS 설정 확인

settings.json을 통한 mTLS 설정

네트워크 접근 요구 사항

방화벽 규칙 예시

문제 해결

프록시 연결 문제

CA 인증서 문제

다음 단계

관련 가이드

프록시 설정

환경 변수

기본 인증(Basic Authentication)

프록시 설정 영구화

커스텀 CA 인증서

여러 CA 인증서 설정

인증서 형식 확인

mTLS 인증

mTLS 설정 확인

settings.json을 통한 mTLS 설정

네트워크 접근 요구 사항

방화벽 규칙 예시

문제 해결

프록시 연결 문제

CA 인증서 문제

다음 단계

관련 가이드