이 글이 맞는 증상

2026년 기준으로 OpenAI Codex나 GPT-5.3-Codex 계열 CLI·IDE 플러그인, 또는 직접 호출하는 ChatGPT API 스크립트를 로컬 터미널에서 돌릴 때, 브라우저로는 chat.openai.com이나 대시보드가 열리는데 API 요청만 timeout·connection reset·지루하게 이어지다 실패하는 패턴을 자주 봅니다. 같은 회선에서 npm·git은 되는데 특정 엔드포인트만 끊기거나, 회선·구독 규칙·DNS가 바뀐 직후부터 터미널만 불안정해지기도 합니다.

이 문서는 Clash Verge Rev(이하 CVR)를 전제로, 규칙 기반 API 분기와 HTTPS_PROXY 같은 환경 변수, 그리고 시스템 프록시 연동과 TUN 중 어떤 조합이 터미널 출구를 브라우저와 맞추기 쉬운지 실무 순서로 정리했습니다. 특정 공항 구독 YAML이나 노드 이름에 묶이지 않고, 패턴만 가져가서 재사용할 수 있게 썼습니다.

왜 브라우저는 되는데 Codex·API 터미널만 더 자주 깨질까

브라우저는 OS 시스템 프록시를 잘 따르고, 프로필·PAC·확장으로 경로가 갈라지기도 합니다. 반면 터미널에서 도는 Node·Python·Go 런타임과 Codex CLI는 기본적으로 직접 DNS 조회 후 소켓을 연다는 전제에 가깝고, HTTPS_PROXY를 읽지 않으면 프록시 입구를 통과하지 않습니다. Electron IDE의 창은 시스템 설정을 일부 물려받지만, 통합 터미널 안의 셸은 부모가 export한 환경 변수와 규칙 스택에 더 민감합니다.

또 하나의 흔한 원인은 규칙 분기 오판입니다. 구독의 GEOSITE·커스텀 규칙 때문에 api.openai.com이 DIRECT로 떨어져 차단 구간을 그대로 박거나, 반대로 불안정한 업스트림으로만 묶이는 경우가 있습니다. 같은 PC에서도 패킷이 거치는 레이어(시스템 프록시 vs TUN vs 순수 직접 연결)가 프로세스마다 달라 보이는 오류 문자열만 달라질 수 있습니다.

규칙 API 분기 vs 글로벌 TUN: 무엇부터 맞출까

글로벌 TUN은 OS 트래픽을 넓게 덮어 한 번에 우회 경로를 통일하기 좋지만, 다른 VPN·MDM·네트워크 필터와 충돌하기 쉽고, 회사 노트북에서는 권한 때문에 비활성화되는 경우도 있습니다. TUN을 켠 뒤에도 일부 런타임이 가상 인터페이스 변경을 즉시 따르지 않는 보고가 있습니다.

반면 규칙 분기 + 로컬 mixed-port를 축으로 두면, 어떤 호스트가 어느 정책 그룹을 타는지 CVR 로그로 추적하기 쉽습니다. 브라우저는 시스템 프록시로 같은 포트를 향하게 하고, CLI는 HTTPS_PROXY=http://127.0.0.1:<mixed-port>처럼 같은 로컬 입구를 쓰게 맞추면 브라우저만 됨 증상이 줄어듭니다.

실무에서는 (1) CVR 코어가 의도한 포트에 바인드했는지, (2) OpenAI API 호스트가 원하는 노드·체인을 타는지 규칙 패널에서 확인하고, (3) 그다음 TUN이 정말 필요한지 판단하는 순서가 디버깅 비용 대비 효율이 좋습니다.

팁: GPT-5.3-Codex·Codex CLI가 내부적으로 어떤 HTTP 스택을 쓰는지에 따라 HTTP_PROXY와 HTTPS_PROXY를 둘 다 맞춰야 하는 경우가 있습니다. 한쪽만 비어 있으면 즉시 거절되기보다 묵시적 타임아웃으로 보일 때가 많습니다.

1단계: Clash Verge Rev 기본 상태 점검

CVR을 켠 상태에서 활성 프로필·코어 기동 여부를 확인합니다. 구독 동기화 직후 규칙 세트가 바뀌면 예전에 통과하던 API용 서픽스가 다른 그룹으로 튀는 일이 있으니, 업데이트 시각을 메모해 두면 재발 분석에 도움이 됩니다.

mixed-port 숫자를 기록합니다. 브라우저의 시스템 프록시가 이 포트를 바라보도록 맞춰 두었다면, 터미널의 HTTPS_PROXY도 같은 번호여야 동일한 분기 정책을 공유합니다. 다른 앱이 포트를 선점해 코어가 예상과 다른 값으로 올라가면, 환경 변수만 고쳐도 증상이 그대로인 함정이 생깁니다.

2단계: 규칙으로 OpenAI·Codex 관련 트래픽 분기 확인

퍼블릭 문서에는 api.openai.com이 대표적으로 거론됩니다. 다만 Azure OpenAI·조직 프록시·리전 프리픽스·향후 엔드포인트 변경이 있을 수 있으므로, 목록을 맹신하지 말고 실패 직후의 접속 로그·SNI를 한 번 대조하세요. GPT-5.3-Codex·Codex CLI 버전을 올릴 때 호스트가 바뀌는 경우도 있으니, 장기 운영이라면 규칙만큼은 변경 이력을 남기는 편이 안전합니다.

CVR의 규칙 편집 화면 또는 YAML에서 해당 도메인을 안정적으로 쓰려는 프록시 그룹에 매핑합니다. 이미 포함된 GEOSITE 묶음이 DIRECT로 덮어쓰는지, 혹은 불안정한 업스트림 한 줄에만 묶이는지 확인하세요. 테스트가 끝난 규칙은 팀과 공유할 때 주석으로 이유를 적어 두면 온보딩 비용이 줄어듭니다.

3단계: 터미널 환경 변수는 어디에 둘까

많은 HTTP 클라이언트가 아래 변수를 읽습니다.

  • HTTPS_PROXY / HTTP_PROXY — TLS·일반 HTTP 요청의 프록시 URL
  • ALL_PROXY — 일부 스택에서 둘을 대신하는 통합 키
  • NO_PROXY — localhost·사내 레지스트리·내부 API 예외

어디에 적느냐는 OS와 셸 습관의 문제입니다. 계정 전체에 항상 켜 두기보다, ~/.zshrc 등에 CVR이 실제로 떠 있을 때만 적용하는 조건문을 두면 실수로 외부 네트워크에 프록시 주소를 들고 다니는 일을 줄일 수 있습니다.

레포마다 egress 정책이 다르면 direnv로 디렉터리 단 주입이 깔끔합니다. VS Code·Cursor·JetBrains는 터미널이 앱 환경을 상속하므로, 변수 export 후 IDE를 재시작했는지 확인하세요. 이미 띄운 셸은 부모가 바뀌기 전까지 옛 값을 유지합니다.

프록시 URL 형식과 SOCKS 선택

CVR의 mixed-port가 HTTP와 SOCKS를 함께 제공한다면, Codex CLI가 쓰는 스택에 맞춰 http://127.0.0.1:<port>를 먼저 시도하는 것이 일반적입니다. SOCKS가 필수인 도구는 socks5://127.0.0.1:<port>처럼 스키마를 분명히 적습니다. 스키마 오타는 곧바로 에러로 드러나지 않고 긴 대기로 보일 때가 많습니다.

4단계: 시스템 프록시·TUN과의 정렬

macOS·Windows에서 시스템 프록시를 CVR과 연동했다면, 브라우저가 가리키는 포트와 터미널 127.0.0.1 경로가 일치하는지 다시 확인합니다. TUN만 단독으로 쓴다면 터미널 트래픽이 실제로 가상 인터페이스를 통해 나가는지 라우팅·방화벽으로 교차 검증합니다.

이중 VPN(회사 Always-On + CVR TUN 등)은 핸드셰이크 실패를 난해하게 만듭니다. 한쪽만 끈 상태에서 API 지연이 사라지는지 비교하면 원인 후보를 빠르게 줄일 수 있습니다.

주의: 터미널에 프록시 환경 변수를 넣으면 그 세션의 모든 아웃바운드에 영향을 줄 수 있습니다. 패키지 매니저·컨테이너 레지스트리·사내 REST까지 예기치 않게 우회 대상이 되지 않도록 NO_PROXY를 신중히 유지하세요.

5단계: 여전히 타임아웃일 때의 좁히기 순서

  1. 같은 시각에 브라우저로 동일 호스트에 HTTPS가 열리는지 비교합니다.
  2. CVR 로그에서 해당 도메인이 어느 규칙·어느 체인으로 분류됐는지 확인합니다.
  3. 터미널에서 env | grep -i proxy(또는 동등 명령)로 의도와 다른 잔여 변수가 없는지 봅니다.
  4. DNS가 시스템 resolver와 DoH 정책이 엇갈려 누설·필터링이 나는지 검사합니다.
  5. 구독·노드 상태가 아니라 MTU·패킷 로스인지 간단한 연속 측정으로 구분합니다.

팀 환경에서의 문서화 팁

여러 명이 같은 레포에서 Codex CLI를 쓰면 A는 되고 B는 안 된다는 질문이 반복됩니다. 루트에 선택적 예시 스크립트나 .env.example에 프록시 키 이름만 적고 실제 값은 각자 로컬에 두는 패턴이 안전합니다. CI 러너와 로컬 변수명이 겹치지 않게 접두사를 나누는 것도 좋습니다.

자주 묻는 질문

Q. API 키가 프록시 로그에 남지 않게 하려면?
A. 로그 레벨과 상세 트레이스를 제한하고, 공용 머신에서는 키 파일 권한과 셸 히스토리에 export 줄이 남지 않게 주의합니다. 가능하면 OpenAI가 권장하는 자격 증명 보관 방식을 따르세요.

Q. WSL2와 Windows CVR을 동시에 쓸 때는?
A. 루프백 전달과 DNS가 달라 WSL 안에서 127.0.0.1이 Windows mixed-port와 연결되지 않을 수 있습니다. 윈도우 측 LAN 주소를 향하게 하거나, WSL 네트워킹 정책에 맞춰 주소를 바꿔야 할 수 있습니다.

Q. 회사에서 터미널 프록시가 금지라면?
A. 정책을 우회하려 하지 말고 IT에 허용된 egress와 인증 프록시 형식을 요청하는 것이 안전합니다. 이 문서는 합법적인 개발자 환경 전제입니다.

정리: 상용 VPN 한 방보다 규칙·터미널을 맞추는 쪽이 나은 이유

단일 상용 VPN 앱만 켜 두는 방식은 처음에는 단순하지만, 스플릿 터널·세션 정책이 바뀔 때 어떤 프로세스가 어떤 인터페이스를 쓰는지 가시성이 떨어집니다. 반면 Clash·Mihomo·CVR처럼 규칙과 로그가 한 화면에 모이는 스택은 호스트 단위로 문제를 찍고, 필요하면 터미널에만 HTTPS_PROXY를 얹는 등 층을 나눠 제어하기 쉽습니다. 이미 Claude Code용으로 Anthropic 호스트를 규칙에 넣어 둔 경험이 있다면, 같은 방식으로 OpenAI Codex·GPT-5.3-Codex 루프에 맞춰 도메인 목록과 환경 변수만 추가하면 운영이 단순해집니다.

스트리밍·여행 중 빠른 우회에는 종합 VPN이 편하지만, npm·docker·퍼블릭 API를 한꺼번에 쓰는 개발자 프록시 시나리오에서는 예외 목록이 거칠거나 CLI를 놓치기 쉽습니다. CVR로 API 분기를 유지한 채 필요한 세션에만 환경 변수를 주면, 타임아웃 원인을 회선이 아닌 경로로 좁히는 데 시간이 덜 듭니다.

Clash 호환 클라이언트를 받아 터미널·브라우저 경로를 같은 규칙으로 맞추기 →