왜 Codex CLI에서는 Clash Verge와 터미널 프록시를 함께 말하는가

2026년 들어 터미널에서 돌아가는 코딩 에이전트와 OpenAI Codex CLI 같은 도구는 검색·업무·개인 프로젝트 전반으로 퍼졌습니다. 브라우저의 ChatGPT와 달리, CLI는 대부분 표준 HTTPS 스택으로 api.openai.com과 같은 엔드포인트에 붙고, 동시에 짧은 시간에 여러 TLS 세션을 엽니다. 그런데 운영체제에서 시스템 프록시만 켜 두면 Safari나 Chrome은 잘 나가는데, 터미널의 Codex만 간헐적으로 타임아웃·TLS 오류를 내는 경우가 많습니다. 이는 「노드 품질」만의 문제가 아니라, 터미널 프로세스가 시스템 프록시 설정을 읽지 않고, 혹은 읽더라도 Clash 규칙이 API 호스트를 다른 출구로 보내기 때문인 경우가 큽니다.

Clash Verge(Mihomo 코어를 쓰는 GUI 클라이언트)에서는 로컬 mixed 포트나 HTTP 포트를 통해 터미널 트래픽을 코어로 넣은 뒤, 도메인 분류 규칙으로 OpenAI 관련 호스트를 한 그룹에 묶을 수 있습니다. 즉 Codex CLI proxy 검색으로 이 글을 연 분들이 찾는 것은 대개 둘 중 하나입니다. 첫째, 셸에 HTTP_PROXY·HTTPS_PROXY(및 대문자 변형)를 걸어 CLI가 반드시 로컬 Clash를 거치게 만드는 일. 둘째, 코어 안에서 OpenAI API routing이 의도한 노드로 고정되는지, 규칙 순서와 DNS를 점검하는 일입니다. 두 축이 동시에 맞아야 terminal proxy 장애를 줄일 수 있습니다.

도메인 목록 자체는 이미 ChatGPT·OpenAI API용 Clash 분기에서 다룬 바와 같이 openai.com, chatgpt.com, api.openai.com 축을 중심으로 움직입니다. 본문은 그 위에 Codex CLI라는 제품명과 터미널 세션에 초점을 맞추어, 같은 원리를 실행 환경 변수·Clash Verge UI·검증 관점에서 다시 정리합니다. macOS 셸 예시는 macOS 터미널·Homebrew 프록시와도 연결됩니다.

⚠️
준수: 프록시·AI 서비스 이용은 거주 국가 법령과 OpenAI 이용약관을 따라야 합니다. 본문은 네트워크·클라이언트 설정 기술만 설명하며, 규제 회피나 약관 위반을 조장하지 않습니다.

Clash Verge에서 먼저 볼 것: 로컬 포트·시스템 프록시·TUN

작업 순서의 시작은 항상 숫자 몇 개를 화면에서 확인하는 것입니다. Clash Verge 설정에서 Mixed Port 또는 HTTP Port, 필요하면 SOCKS Port를 메모합니다. Codex CLI와 curl 검증에는 보통 http://127.0.0.1:<포트> 형태의 HTTP 프록시를 쓰기 쉽습니다. 클라이언트에 따라 기본값이 7890 근처인 경우가 많지만, 사용자가 바꿨다면 그 값이 곧 정답입니다.

다음으로 「시스템 프록시(System Proxy)」를 켤지, TUN 모드를 켤지 결정합니다. 시스템 프록시는 macOS·Windows에서 GUI 앱과 Chromium 계열이 잘 따르는 경로이고, 터미널은 별도입니다. 반면 TUN은 OS 아래로 트래픽을 가로채어 규칙 모드를 CLI에도 강하게 적용할 수 있어, 환경 변수를 매번 손으로 넣기 싫을 때 유리합니다. 다만 다른 VPN·회사 에이전트와 충돌할 수 있으니 TUN 모드 가이드를 읽고 권한·라우팅을 이해한 뒤 켜는 편이 안전합니다. 「규칙은 맞는데 터미널만 코어를 안 탄다」면 우선 TUN 여부와 병행해서 생각하세요.

ℹ️
참고: Windows 10·11에서 Clash Verge를 쓰는 초기 설치·구독 가져오기 흐름은 Windows 11 Verge Rev 설치 등 기존 글과 맞춰 두면, 이후 포트 확인이 반복하기 쉽습니다.

터미널 프록시: HTTP_PROXY·HTTPS_PROXY를 Clash 로컬 포트에 맞추기

Codex CLI를 포함한 많은 Node·Python·Go 기반 CLI는 HTTPS_PROXY 환경 변수를 읽습니다. 운영체제마다 영구 설정 방법은 다르지만, 진단용으로는 현재 셸 세션에만 아래와 같이 넣고 테스트하는 것이 빠릅니다. 포트 숫자는 앞서 확인한 Clash Verge의 HTTP 또는 mixed 포트로 바꿉니다.

# Example — replace 7890 with your Clash Verge HTTP/mixed port
export http_proxy="http://127.0.0.1:7890"
export https_proxy="http://127.0.0.1:7890"
export HTTP_PROXY="$http_proxy"
export HTTPS_PROXY="$https_proxy"

일부 도구는 SOCKS만 안정적으로 지원하므로, HTTP로 재현이 안 되면 all_proxy에 socks5://127.0.0.1:<SOCKS포트>를 추가해 보세요. 대문자·소문자 변수를 함께 맞추는 이유는 런타임·라이브러리마다 읽는 이름이 달라서입니다. 같은 환경에서 curl -I https://api.openai.com와 Codex 작업을 번갈아 실행해, Clash의 최근 연결에 기대한 호스트가 뜨는지 확인합니다.

Windows에서 PowerShell을 쓴다면 세션 한정으로 $env:HTTPS_PROXY="http://127.0.0.1:7890" 형태로 넣을 수 있고, 지속 적용은 시스템 환경 변수 편집이나 사용자 프로필 스크립트에 두는 식이 일반적입니다. 조직 정책으로 HTTP_PROXY가 비어 있지 않은 채로 공급되는 경우도 있으니, echo $HTTPS_PROXY로 실제 값을 먼저 확인하는 습관이 OpenAI API routing 문제를 가릴 때 도움이 됩니다.

도메인 규칙으로 OpenAI API 출구 고정하기

환경 변수는 트래픽을 Clash에 던질 뿐, 어느 국가·어느 업링크로 나갈지는 여전히 프로필의 rules와 proxy-groups가 결정합니다. Clash Verge에서 편집기를 열어, DOMAIN-SUFFIX,openai.com,<그룹명>, DOMAIN-SUFFIX,chatgpt.com,<그룹명> 같은 줄이 GEOIP나 넓은 RULE-SET보다 위에 있는지 확인하세요. 가장 흔한 실수는 OpenAI 전용 규칙을 아래에 두어 다른 규칙에 먼저 잡히는 경우입니다. 이 논리는 OpenAI API 분기 글의 「규칙 순서」 절과 동일합니다.

전용 그룹 이름(예: AI-OPENAI)은 YAML 전파에서 한 글자라도 다르면 로드 실패로 이어질 수 있으니, Verge UI의 프록시 그룹 탭에 표시되는 문자열과 일치하는지 다시 봅니다. 자동 선택(url-test)을 API에 쓸 때는 간격을 지나치게 짧게 잡아 세션이 흔들리지 않게 조정하세요. 스니퍼·SNI 기반 분기가 필요하면 스니퍼·SNI 라우팅 문맥도 참고할 수 있으나, OpenAI API는 우선 도메인 규칙과 DNS를 맞추는 편이 운영 비용 대비 효과가 큽니다.

# Sketch — group name and ports must match your profile / Verge UI
proxy-groups:
  - name: AI-OPENAI
    type: select
    proxies:
      - Proxy
      - AUTO

rules:
  - DOMAIN-SUFFIX,openai.com,AI-OPENAI
  - DOMAIN-SUFFIX,chatgpt.com,AI-OPENAI
  - DOMAIN-SUFFIX,oaistatic.com,AI-OPENAI
  - GEOIP,CN,DIRECT
  - MATCH,Proxy

DNS·fake-ip: API만 간헐 실패할 때

규칙과 노드가 맞아 보이는데도 API만 끊긴다면 DNS 쪽을 의심합니다. fake-ip 모드에서는 해석 결과와 규칙 매칭이 어긋나 간헐적으로 실패하는 사례가 있고, OpenAI 측 엔드포인트는 TLS·SNI 조합에 민감합니다. 반복되는 호스트는 fake-ip-filter 후보나 nameserver 체인을 재검토하세요. 자세한 절차는 Fake-IP·DNS 가이드에 정리되어 있습니다. 터미널에서만 문제가 난다면, 앱이 자체 DNS 해석기를 쓰는지도 함께 보세요.

검증 체크리스트: curl, 연결 로그, Codex CLI

  • HTTPS_PROXY를 설정한 같은 터미널에서 curl -v https://api.openai.com로 TLS 핸드셰이크가 끝까지 가는지 본다.
  • Clash Verge의 연결·최근 연결에서 해당 흐름이 기대한 규칙 이름·프록시 그룹으로 찍히는지 확인한다.
  • 브라우저 ChatGPT와 동시에 부하를 걸어, 서로 다른 노드로 나가 충돌이 없는지 비교한다.
  • 회사 VPN·보안 에이전트가 TUN·라우트와 겹치지 않는지 확인한다.
  • API 키·구독 문자열은 로그에 남지 않게 관리하고, 팀 룰셋 변경 시에는 버전을 남긴다.

자주 겹치는 질문

Q. 브라우저는 되는데 Codex CLI만 실패합니다. A. 먼저 터미널에 HTTP_PROXY·HTTPS_PROXY가 비어 있지 않은지 확인하고, 비어 있다면 Clash Verge의 로컬 포트로 채웁니다. 그다음 코어 규칙에서 api.openai.com이 어떤 그룹으로 매칭되는지 봅니다.

Q. 프록시를 넣었는데도 규칙이 안 먹는 것 같습니다. A. 환경 변수는 「Clash까지 가는 길」만 열어 줄 뿐입니다. 여전히 rule 순서·DNS·TUN 미적용 중 하나가 흔한 원인입니다. OpenAI 도메인 분기 글의 체크리스트를 그대로 따라가며 로그와 대조하세요.

정리

OpenAI Codex CLI와 같은 터미널 도구는 브라우저보다 프록시 적용 경로가 잘게 갈라지기 쉽습니다. Clash Verge로 로컬 포트를 확인하고 HTTPS_PROXY로 terminal proxy를 확실히 연 뒤, OpenAI API routing을 도메인 규칙으로 고정하면 반복되는 타임아웃과 규칙 혼선을 줄일 수 있습니다. 설정은 한 번에 완벽할 필요가 없고, 연결 로그에 새 호스트가 보이면 룰셋을 조금씩 업데이트하는 방식이 장기적으로 가장 덜 깨집니다. 기본 개념은 문서 섹션과 함께 보면 속도가 납니다.

다만 일반 프록시 앱 가운데는 GUI만 강조하고 터미널·코어 로그·도메인 편집을 한 화면에서 다루기 어렵거나, 문서가 플랫폼마다 흩어져 처음부터 끝까지 같은 흐름으로 따라가기 힘든 경우가 있습니다. ClashSky는 Clash 계열 작동 방식을 한데 모아, 설치·구독·규칙·로그 검증까지 같은 맥락에서 읽히도록 정리해 두었습니다. 터미널과 브라우저를 오가며 출구를 맞추느라 시간을 쓰기보다, 한 번 구성해 두고 재현성을 얻고 싶다면 Clash 클라이언트를 무료로 내려받아 프로필과 Codex CLI 세션을 같은 기준으로 다시 시험해 보시길 권합니다.

→ Clash를 무료로 내려받아 터미널 프록시와 OpenAI API 규칙을 맞춘 뒤, Codex CLI 작업을 다시 실행해 보세요.