기업 네트워크 내부에 AI 에이전트를 처음 배포했는데, 그냥... 그대로 멈춰 있는 상황을 마주할 때가 있습니다. 연결 거부(connection refused) 메시지도 없고, 타임아웃(timeout) 로그도 남지 않습니다. 그저 침묵뿐입니다. 에이전트는 피어(peers)에게 도달할 수 없고, 스토어에서 도구를 가져올 수 없으며, 홈(phone home)으로 연락할 수도 없습니다. 기업 방화벽 문제에 직면한 것입니다.

이것은 코드 버그가 아닙니다. 네트워크 아키텍처의 불일치입니다. 당신의 에이전트는 평평한(flat) 인터넷을 가정하지만, 기업은 명시적인 허가 없이는 아무것도 나가지 않는다고 가정합니다. IT 부서에 방화벽 규칙 변경을 요청하지 않고도 이를 단계별로 디버깅하는 방법을 소개합니다.

기업 네트워크가 에이전트를 망가뜨리는 이유

엔터프라이즈 네트워크는 NAT 뒤에 위치하며 송신 필터링(egress filtering)을 강제합니다. 외부로 나가는 트래픽은 다음을 거칩니다:

1. NAT 게이트웨이 (NAT gateway) (종종 캐리어급 또는 기업용 프록시)
2. 특정 포트와 프로토콜을 제외한 모든 것을 차단하는 방화벽 규칙 (Firewall rules)
3. 비 TLS(non-TLS) 트래픽을 가로채는 투명 HTTP/HTTPS 프록시 (transparent HTTP/HTTPS proxy)
4. 443 포트가 아니거나 유효한 TLS가 아닌 모든 것을 드롭(drop)하는 심층 패킷 검사 (Deep packet inspection)

대부분의 AI 에이전트 통신 프레임워크는 양방향 연결성(bidirectional connectivity)을 가정합니다. 즉, 리스너(listener)를 열고 피어가 연결되기를 기다립니다. 하지만 기업용 NAT 뒤에는 리스너가 없습니다. 라우팅 가능한 주소도 없습니다. 에이전트는 인터넷에 대해 송신 전용(outbound-only) 액세스 권한만 가집니다.

다음은 순서대로 정리한 체크리스트입니다.

1단계: 외부 UDP가 실제로 허용되는지 확인하기

많은 기업 방화벽은 모든 외부 UDP를 차단합니다. 허용되는 유일한 프로토콜은 80, 443 포트의 TCP와 때때로 22 포트뿐입니다. 이는 NAT 홀 펀칭(hole-punching)을 위해 UDP에 의존하는 대부분의 피어 투 피어(peer-to-peer) 프로토콜을 무력화합니다.

# 빠른 UDP 도달 가능성 테스트
timeout 5 bash -c 'echo test > /dev/udp/8.8.8.8/53' && echo "UDP egress OK"

만약 이 명령이 멈추거나 실패한다면, 방화벽이 UDP를 완전히 드롭하고 있는 것입니다. 주의하세요. 이는 직접적인 STUN 기반 홀 펀칭과 일반 UDP 터널을 사용할 수 없음을 의미합니다. TCP 폴백(fallback)이나 릴레이(relay)가 필요할 것입니다.

2단계: 에이전트 환경 내부에서 DNS 테스트하기

기업용 DNS는 종종 내부 전용 레코드만 해석하거나, 외부 쿼리를 차단하거나, 캡티브 포털 (captive portal)을 반환합니다. 피어 주소 (peer addresses)를 해석할 수 없는 에이전트는 연결할 수 없는 에이전트입니다.

# 외부 DNS 해석 테스트
dig +short pilotprotocol.network @8.8.8.8
# 시스템 리졸버 (system resolver)와 비교
...

공용 리졸버 (public resolver)는 작동하지만 시스템 리졸버가 작동하지 않는다면, DNS 인터셉트 (DNS intercept) 또는 스플릿 호라이즌 DNS (split-horizon DNS) 상황입니다. 에이전트는 내부 DNS를 우회하기 위해 공용 리졸버 또는 DoH (DNS over HTTPS)를 사용해야 합니다.

3단계: 투명 프록시 (transparent proxies) 탐지하기

많은 기업 네트워크는 TCP/80 및 TCP/443 트래픽을 가로채는 투명 프록시를 운영합니다. 에이전트의 TLS 연결은 대상 서버가 아닌 프록시에서 종료됩니다. 이는 인증서 피닝 (certificate pinning), WebSocket 업그레이드 헤더 (WebSocket upgrade headers), 그리고 가공되지 않은 TCP (raw TCP)를 기대하는 모든 프로토콜을 깨뜨립니다.

# 실제 서버 대신 프록시 응답을 받는지 테스트
curl -v https://api.github.com 2>&1 | grep -i "proxy\|x-forwarded-for\|via"

Via 또는 X-Forwarded-For 헤더가 보인다면, 투명 프록시 뒤에 있는 것입니다. 에이전트는 프록시의 CA 인증서를 신뢰하거나, 프록시가 가로채는 프로토콜을 피해야 합니다.

4단계: 실제 외부 송출 (egress) 포트 규칙 매핑하기

추측은 비용이 많이 듭니다. 어떤 포트와 프로토콜이 외부 세계에 도달할 수 있는지 정확히 파악하십시오:

# 일반적인 외부 송출 포트 테스트
for port in 80 443 8080 8443 53 123 3478 4433 51820; do
  timeout 3 bash -c "echo >/dev/tcp/pilotprotocol.network/$port" 2>/dev/null &&
...

대부분의 기업 네트워크는 TCP/443 (HTTPS) 아웃바운드(outbound)만 허용합니다. 일부는 HTTP를 위한 TCP/80과 SSH를 위한 TCP/22를 추가합니다. UDP는 일반적으로 완전히 차단됩니다. 만약 TCP/443만 열려 있다면, 에이전트가 사용하는 모든 프로토콜은 반드시 TLS를 통해 터널링되어야 합니다.

5단계: NAT 동작을 결정하기 위한 STUN 테스트

UDP가 열려 있다면, NAT 유형을 이해하기 위해 STUN 테스트를 실행하십시오. 이를 통해 홀 펀칭 (hole-punching)이 가능한지 여부를 알 수 있습니다.

# STUN 클라이언트 설치 및 실행
apt-get install -y stun-client
stun-client stun.l.google.com 19302

확인할 수 있는 결과값들:

• Open internet (개방형 인터넷) — NAT 없음, 방화벽 없음. 기업 네트워크 문제가 아닙니다.
• Full-cone NAT — 홀 펀칭 (hole-punching)이 작동합니다. 에이전트가 하나의 아웃바운드 (outbound) 패킷을 보낸 후, 피어 (peers)가 에이전트에 도달할 수 있습니다.
• Symmetric NAT — 홀 펀칭 (hole-punching)이 실패합니다. 각 목적지마다 서로 다른 소스 포트 (source port)가 할당됩니다. 릴레이 (relay) 또는 TCP 기반 터널 (tunnel)이 필요합니다.
• Blocked (차단됨) — UDP가 어디로도 전달되지 않았습니다. 홀 펀칭 (hole-punching)이 불가능합니다.

가장 흔한 결과: TCP/443 포트만 열려 있음

이것이 대부분의 기업 환경이 처한 현실입니다. UDP는 드롭 (dropped)됩니다. Symmetric NAT가 일반적입니다. 직접적인 피어 투 피어 (peer-to-peer) 연결은 불가능합니다.

세 가지 옵션이 있습니다:

옵션 A: TCP/443 폴백 (fallback)을 사용하는 릴레이 (relay)

공인 IP가 있는 VPS에 릴레이 (relay) 서버를 설정합니다. 에이전트는 릴레이 (relay)로 장기 유지되는 TCP 연결을 엽니다 (아웃바운드 — 방화벽 변경 불필요). 릴레이 (relay)는 피어 (peers)로부터 오는 트래픽을 에이전트로 전달합니다.

# 공인 릴레이 (relay)로 SSH를 통한 간단한 SOCKS 터널 (tunnel)
ssh -R 8080:localhost:3000 user@your-relay-server -N

이 방식은 작동하지만 단점이 있습니다. 모든 바이트가 릴레이 (relay)를 통과하므로, 릴레이 (relay)가 병목 현상 (bottleneck)이자 단일 장애점 (single point of failure)이 됩니다.

옵션 B: 자동 릴레이 (relay) 폴백 (fallback)을 지원하는 오버레이 네트워크 (overlay network)

오버레이 네트워크 (overlay networks)는 에이전트 환경 내부에서 경량 클라이언트를 실행합니다. 이들은 STUN, NAT 트래픽 관통 (traversal), 그리고 릴레이 (relay) 폴백 (fallback)을 투명하게 처리합니다. 에이전트는 하부 네트워크와 관계없이 작동하는 가상 주소를 할당받습니다.

이 지점이 Pilot Protocol과 같은 오버레이 (overlay) 접근 방식이 적합한 곳입니다 — 에이전트는 네트워크로의 아웃바운드 (outbound) 연결을 설정하고, 암호화를 협상하며, 터널 (tunnel)을 유지하는 작은 데몬 (daemon)을 실행합니다. 피어 (peers)는 가상 주소를 통해 에이전트에 도달하며, 직접적인 홀 펀칭 (hole-punching)이 실패할 경우 오버레이 (overlay)가 자동으로 릴레이 (relay) 폴백 (fallback)을 처리합니다. 에이전트는 인바운드 (inbound) 포트를 절대 열지 않습니다.

옵션 C: TLS 기반의 WebSocket

사용 중인 에이전트 프레임워크가 WebSocket 전송 (transport)을 지원한다면, 표준 HTTPS 트래픽인 TCP/443을 통해 실행될 수 있으며, 이는 엄격한 방화벽도 통과할 수 있습니다. 양쪽 끝(endpoints)을 모두 제어할 수 있다면 이것이 가장 간단한 해결책입니다.

const ws = new WebSocket("wss://your-relay.example.com/agent");
ws.onmessage = (event) => handleMessage(JSON.parse(event.data));

단계 6: 릴레이 도달 가능성 테스트

어떤 릴레이(relay)나 오버레이(overlay)를 선택하든, 에이전트가 기업 네트워크 내부에서 해당 지점에 도달할 수 있는지 확인하십시오:

curl -sI https://your-relay.example.com/health | head -1
# 200 또는 204를 반환해야 함

이 작업은 노트북이 아닌 에이전트가 실제로 실행되는 환경에서 수행하십시오. 기업 네트워크는 종종 DNS는 화이트리스트(whitelist)에 포함시키지만, 임의의 IP는 허용하지 않는 경우가 많습니다.

단계 7: 프록시 인증 확인

일부 기업용 프록시(proxy)는 인증을 요구합니다. 에이전트의 HTTP 클라이언트가 프록시 자격 증명 (credentials)을 전송하지 않으면, 요청이 조용히 실패하거나 캡티브 포털 (captive portal) 페이지를 반환합니다.

export HTTP_PROXY="http://user:pass@proxy.corp.com:8080"
export HTTPS_PROXY="http://user:pass@proxy.corp.com:8080"

대부분의 HTTP 클라이언트 라이브러리는 이러한 환경 변수 (environment variables)를 지원합니다. 하지만 모든 UDP 기반 VPN이나 오버레이 네트워크가 이를 지원하는 것은 아닙니다.

mTLS 및 인증서 피닝 (certificate pinning)은 어떤가요?

에이전트가 상호 TLS (mTLS)를 사용하는 경우, 기업 프록시의 인증서 가로채기 (certificate interception)가 핸드셰이크 (handshake)를 중단시킵니다. 해결 방법:

• 에이전트의 신뢰 저장소 (trust store)에 기업 CA 인증서를 설치합니다.
• TLS 가로채기 없이 로우 TCP/443 (raw TCP/443) 위에서 실행되는 프로토콜을 사용합니다 (레이어 3/4 터널).
• 릴레이의 인증서를 피닝 (pin)하고, 폴백 (fallback)으로 프록시의 CA를 포함합니다.

빠른 참조 체크리스트

에이전트가 기업 방화벽 뒤에서 실행될 수 없다고 결론 내리기 전에, 다음 사항들을 각각 확인하십시오:

• 아웃바운드 (Outbound) UDP 허용 여부? echo test > /dev/udp/8.8.8.8/53
• DNS가 외부 도메인을 해석(resolve)하는가? dig pilotprotocol.network @8.8.8.8
• 투명 프록시 (Transparent proxy)가 감지되는가? curl -v https://api.github.com | grep -i proxy
• 이그레스 (Egress) 포트가 매핑되어 있는가? TCP/443만 허용되는가?
• STUN 테스트를 완료했는가? NAT 유형은 무엇인가?
• 릴레이 (Relay)에 도달 가능한가? curl -sI https://relay-host/health
• 프록시 인증 (Proxy auth)이 설정되었는가? HTTP_PROXY, HTTPS_PROXY가 설정되었는가?
• 프록시가 TLS를 가로채는 경우 CA 인증서 (CA cert)가 설치되었는가?

불가능한 경우는 드뭅니다

열에 아홉은 해결책이 다음 중 하나입니다: 에이전트의 트래픽을 TCP/443으로 실행하거나, 릴레이 (Relay)를 설정하거나, 기업용 CA 인증서 (CA certificate)를 설치하는 것입니다. NAT 트래버설 (NAT traversal)과 릴레이 폴백 (Relay fallback)을 자동으로 처리하는 오버레이 네트워크 (Overlay networks)는 이를 아키텍처 (Architecture) 문제가 아닌 설정 (Configuration) 문제로 만들어 줍니다. 에이전트는 영구적인 주소를 할당받고, 오버레이는 가능한 경우 직접적인 홀 펀칭 (Hole-punched) 터널을 통해, 불가능한 경우 릴레이를 통해 해당 주소에 도달하는 방법을 결정합니다.

기업 방화벽이 막다른 길은 아닙니다. 그것은 단지 당신의 에이전트가 당신이 바라는 네트워크가 아니라, 실제로 가지고 있는 네트워크를 위해 설계된 네트워크 계층 (Network layer)이 필요하다는 것을 의미할 뿐입니다.