마이그레이션 예상 읽기 시간 21분

OpenAI Codex CLI 국내 사용법과 Clash Verge 연결 설정 가이드

OpenAI Codex CLI를 사용하면서 로그인 오류, 응답 지연, 터미널 연결 끊김을 겪고 있나요? 이 글에서는 Clash Verge에 구독을 추가하고 TUN 모드와 규칙 기반 라우팅을 설정하는 방법을 단계별로 설명해 안정적인 AI 코딩 환경을 구성하도록 돕습니다.

Codex CLI와 Clash Verge의 역할부터 구분하기

OpenAI Codex CLI는 터미널에서 코드 설명, 파일 수정, 테스트 실행과 프로젝트 탐색을 수행하는 AI 코딩 도구입니다. 반면 Clash Verge는 터미널 명령을 실행하는 프로그램이 아니라, 애플리케이션의 네트워크 요청을 로컬 프록시로 전달하고 규칙에 따라 직접 연결 또는 프록시 연결을 선택하는 클라이언트입니다. 따라서 Codex CLI가 연결되지 않을 때는 Codex 자체의 인증 문제와 Clash Verge의 네트워크 경로 문제를 분리해서 확인해야 합니다.

국내 네트워크에서 Codex CLI를 사용할 때는 세 가지 경로가 자주 혼동됩니다. 첫째는 Codex CLI 프로세스가 OpenAI 인증 및 API 서버에 직접 접속하는 경로입니다. 둘째는 HTTP_PROXY, HTTPS_PROXY, ALL_PROXY 같은 환경 변수를 통해 로컬 Clash 포트로 요청을 보내는 경로입니다. 셋째는 Clash Verge의 TUN 모드가 운영체제 수준에서 트래픽을 가로채는 경로입니다. 처음 설정할 때는 변수가 적은 시스템 프록시 또는 명시적 환경 변수부터 시작하고, 필요할 때만 TUN을 추가하는 편이 문제를 좁히기 쉽습니다.

구성 요소 담당 기능 확인할 항목
Codex CLI 터미널에서 AI 코딩 작업 실행 설치 상태, 로그인, 프로젝트 권한, 요청 오류
Clash Verge 로컬 포트 수신과 프록시 정책 적용 실행 중인 코어, 포트, 모드, 현재 선택된 정책
mihomo 코어 DNS, 규칙 매칭, 노드 연결과 트래픽 전달 로그, 규칙 순서, 노드 지연 시간, 연결 성공 여부
운영체제 셸 Codex CLI에 환경 변수와 작업 디렉터리 제공 HTTP_PROXY, HTTPS_PROXY, NO_PROXY

Clash Verge에서 프로필과 기본 포트 준비하기

Clash Verge를 실행한 뒤 먼저 유효한 프로필을 가져옵니다. 구독을 추가할 때는 제공업체가 명시한 Clash 또는 mihomo 형식을 선택하고, 업데이트가 성공했는지 확인해야 합니다. 프로필 목록에 이름이 보이는 것만으로는 충분하지 않습니다. 실제로 해당 프로필을 적용했는지, mihomo 코어가 실행 중인지, 프록시 그룹에 사용할 수 있는 노드가 표시되는지 순서대로 확인하세요.

Clash Verge의 메뉴 이름은 버전에 따라 조금 다를 수 있지만 일반적으로 Profiles에서 프로필을 선택하고, Proxies 또는 연결 화면에서 정책 그룹을 선택합니다. 처음에는 Global 모드보다 Rule 모드를 권장합니다. Global 모드는 모든 요청을 같은 프록시 정책으로 보내므로 진단에는 편리하지만, 패키지 저장소나 사내 주소까지 불필요하게 우회할 수 있습니다. Rule 모드는 도메인과 IP 규칙에 따라 연결 경로를 나누므로 일상적인 개발 환경에 더 적합합니다.

로컬 수신 포트는 Clash Verge의 설정 화면에서 실제 값을 확인해야 합니다. 많이 사용되는 예시는 7890이지만 설치 버전이나 사용자가 변경한 프로필에 따라 다를 수 있습니다. 다음과 같은 설정이라면 HTTP와 SOCKS5를 하나의 혼합 포트에서 받을 수 있습니다.

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
external-controller: 127.0.0.1:9090

mixed-port는 일반적인 HTTP 및 SOCKS 요청을 받는 포트이고, external-controller는 상태 조회와 정책 제어용 API입니다. Codex CLI의 프록시 주소로 127.0.0.1:9090을 입력하면 안 됩니다. 해당 포트는 웹 프록시가 아니라 제어 인터페이스이기 때문입니다. Codex CLI에는 실제 프록시 수신 포트인 7890 또는 Clash Verge 화면에 표시된 현재 포트를 사용해야 합니다.

로컬 포트 동작 확인

Windows PowerShell에서는 다음 명령으로 로컬 포트의 수신 여부를 확인할 수 있습니다. 포트 번호는 실제 Clash Verge 설정에 맞게 바꾸세요.

Test-NetConnection 127.0.0.1 -Port 7890

macOS 또는 Linux에서는 다음처럼 확인할 수 있습니다.

curl -I --proxy http://127.0.0.1:7890 https://example.com

이 테스트에서 “connection refused”가 표시되면 아직 Codex CLI를 점검할 단계가 아닙니다. Clash Verge가 종료되어 있거나, 코어가 시작되지 않았거나, 다른 포트를 사용 중일 가능성이 큽니다. 반대로 응답 헤더가 반환되면 로컬 포트와 기본 HTTPS 프록시 경로는 일단 작동한다고 볼 수 있습니다.

Codex CLI에 프록시 환경 변수 적용하기

Codex CLI를 터미널에서 실행할 때는 현재 셸 세션에 프록시 환경 변수를 설정하는 방식이 가장 재현하기 쉽습니다. HTTP와 HTTPS 요청을 모두 로컬 Clash 포트로 보내려면 다음과 같이 설정합니다. 주소의 포트는 Clash Verge에서 확인한 값으로 교체하세요.

# macOS 또는 Linux
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
export ALL_PROXY=http://127.0.0.1:7890

# 로컬 주소와 사내 개발 주소는 프록시에서 제외
export NO_PROXY=localhost,127.0.0.1,::1

Windows PowerShell에서는 환경 변수 문법이 다릅니다.

$env:HTTP_PROXY="http://127.0.0.1:7890"
$env:HTTPS_PROXY="http://127.0.0.1:7890"
$env:ALL_PROXY="http://127.0.0.1:7890"
$env:NO_PROXY="localhost,127.0.0.1,::1"

일부 프로그램은 대문자 변수만 읽고, 일부 네트워크 라이브러리는 소문자 변수도 확인합니다. 요청이 계속 직접 연결되는 것처럼 보이면 다음처럼 소문자 변수도 같은 값으로 맞춰 볼 수 있습니다.

export http_proxy="$HTTP_PROXY"
export https_proxy="$HTTPS_PROXY"
export all_proxy="$ALL_PROXY"
export no_proxy="$NO_PROXY"

환경 변수를 셸 시작 파일에 영구적으로 넣기 전에 현재 터미널에서 먼저 테스트하는 것이 좋습니다. 영구 등록을 하면 Git, 패키지 관리자, 다른 개발 도구까지 모두 프록시를 사용하게 됩니다. 특히 사내 Git 서버나 국내 미러 주소는 프록시를 거치지 않아야 더 안정적일 수 있으므로, 동작을 확인한 뒤 필요한 범위만 NO_PROXY에 추가하세요.

Codex CLI가 사용하는 실제 네트워크 라이브러리와 버전에 따라 모든 프록시 변수의 동작이 동일하지 않을 수 있습니다. 따라서 변수를 지정했다고 해서 반드시 프록시가 사용된다고 가정하면 안 됩니다. Clash Verge의 연결 기록 또는 로그에서 요청이 나타나는지 확인하고, 요청이 보이지 않으면 CLI의 공식 옵션과 현재 버전 문서를 함께 점검해야 합니다.

Codex 인증과 프로젝트 권한 확인하기

프록시가 정상이어도 인증이 완료되지 않으면 Codex CLI를 사용할 수 없습니다. Codex CLI의 로그인 방식과 명령은 설치 버전에 따라 달라질 수 있으므로, 설치 직후 표시되는 도움말과 공식 안내를 기준으로 진행하세요. 일반적으로 터미널에서 codex를 실행한 뒤 로그인 또는 인증 메뉴를 선택하거나, 제공되는 codex login 흐름을 사용하게 됩니다. API 키를 환경 변수로 사용하는 배포 방식이라면 키 이름과 적용 범위를 현재 버전 문서에서 확인해야 합니다.

인증 정보는 Clash 설정 파일이나 셸 명령 기록에 직접 넣지 않는 것이 안전합니다. API 키를 명령줄 인자로 입력하면 터미널 히스토리, 프로세스 목록 또는 CI 로그에 남을 수 있습니다. 환경 변수나 운영체제의 자격 증명 저장 기능을 사용하고, 키가 노출되었다고 의심되면 즉시 폐기하고 새 키를 발급하세요. 구독 URL에 포함된 토큰과 Codex 인증 키는 모두 외부에 공개하면 안 되는 정보입니다.

Rule 모드에서 Codex 트래픽 분기하기

Clash Verge의 Rule 모드에서 Codex 요청을 안정적으로 처리하려면 관련 서비스 도메인이 프록시 정책으로 연결되어야 합니다. 다만 서비스의 실제 도메인 목록은 제품 버전과 인증 방식에 따라 바뀔 수 있으므로, 인터넷에서 복사한 오래된 규칙을 무조건 추가하지 마세요. Codex CLI 실행 시 Clash Verge의 Logs 화면을 열고 실제로 요청된 호스트를 확인한 다음, 필요한 도메인만 규칙에 반영하는 방식이 안전합니다.

규칙은 위에서부터 순서대로 매칭됩니다. 특정 도메인을 프록시로 보낼 규칙보다 앞에 DOMAIN-SUFFIX 또는 GEOIP,DIRECT 같은 넓은 직접 연결 규칙이 있으면 원하는 정책에 도달하지 못할 수 있습니다. 규칙을 수정한 뒤에는 프로필을 다시 적용하거나 코어를 재시작하고, 기존 연결을 정리한 다음 재테스트하세요.

rules:
  - DOMAIN-SUFFIX,example-openai-domain.invalid,PROXY
  - DOMAIN,localhost,DIRECT
  - IP-CIDR,127.0.0.0/8,DIRECT,no-resolve
  - MATCH,DIRECT

위 예시의 도메인은 설명을 위한 가상 값이며 실제 설정에 그대로 넣으면 안 됩니다. 실제 서비스 호스트는 Codex CLI 버전의 로그와 공식 문서를 기준으로 확인해야 합니다. 또한 프록시 그룹 이름이 PROXY가 아니라 “자동 선택”, “노드 선택” 등으로 되어 있다면 현재 프로필의 실제 그룹 이름으로 바꾸세요.

정책 그룹과 DNS 확인

노드가 보이지만 Codex 요청이 실패한다면 정책 그룹에서 실제 노드가 선택되었는지 확인합니다. URL 테스트 결과가 낮은 노드가 항상 좋은 것은 아닙니다. 측정 대상의 응답 시간만 짧고 장시간 TLS 연결이나 큰 응답 전송에서 불안정할 수 있기 때문입니다. 국내에서 사용할 때는 지연 시간뿐 아니라 패킷 손실, 연결 재설정, HTTPS 인증서 협상 실패가 반복되는지도 함께 봐야 합니다.

DNS 오류가 반복되면 먼저 Clash Verge의 DNS 설정과 시스템 DNS를 구분하세요. 도메인이 해석되지 않는다고 해서 곧바로 노드가 불량인 것은 아닙니다. Rule 모드에서 DNS 요청은 직접 연결되고 실제 HTTPS 요청만 프록시로 전달되는 구성도 있으므로, DNS 경로와 애플리케이션 트래픽 경로가 다를 수 있습니다. TUN을 켠 상태라면 DNS 하이재킹, fake-ip 또는 redir-host 설정이 추가되어 결과가 달라질 수 있습니다.

시스템 프록시와 TUN 모드 중 선택하기

Codex CLI가 환경 변수를 정상적으로 읽는다면 시스템 프록시 또는 명시적 프록시 변수만으로 충분할 수 있습니다. 이 방식은 특정 터미널 세션에만 적용하기 쉽고, 로컬 개발 서버나 Docker 컨테이너에 미치는 영향도 비교적 작습니다. 반면 CLI가 프록시 변수를 무시하거나 여러 하위 프로세스가 별도의 네트워크 라이브러리를 사용하는 경우에는 TUN 모드가 더 편리할 수 있습니다.

TUN을 활성화할 때는 기존 VPN, 다른 프록시 클라이언트, 가상 네트워크 어댑터와 충돌하지 않는지 확인하세요. TUN을 켠 뒤 인터넷 전체가 느려졌다면 Codex 문제가 아니라 전체 트래픽이 예상치 못한 정책 그룹을 통과하는 상황일 수 있습니다. 먼저 시스템 프록시와 환경 변수를 끄고 TUN만 테스트한 다음, 반대로 TUN을 끄고 환경 변수만 테스트하면 어느 계층에서 문제가 생기는지 확인할 수 있습니다.

실패 로그를 읽고 안정성을 높이는 방법

Codex CLI가 실패하면 먼저 터미널의 전체 오류를 저장하고, 동시에 Clash Verge의 Logs에서 같은 시간대의 요청을 찾습니다. Clash 로그에 요청 자체가 없다면 환경 변수 미적용, NO_PROXY 예외, CLI의 프록시 미지원 가능성을 살펴봅니다. 요청은 보이지만 연결이 끊기면 노드, DNS, TLS 협상과 규칙 정책을 점검합니다. Clash에서 연결 성공이 기록되는데 CLI만 인증 오류를 출력한다면 네트워크보다 계정 또는 프로젝트 권한 문제일 가능성이 높습니다.

관찰 결과 가능성이 높은 원인 다음 조치
Clash 로그에 요청이 없음 환경 변수 미적용 또는 직접 연결 현재 셸에서 변수 값을 출력하고 새 터미널에서 재실행
로컬 포트 connection refused 코어 중지, 포트 불일치 Clash Verge의 실제 mixed-port와 코어 상태 확인
DNS resolve 실패 DNS 정책 또는 TUN 충돌 DNS 로그와 규칙 모드를 분리해 테스트
401 또는 403 인증 정보와 계정 권한 문제 로그인 상태, 키 만료, 프로젝트 권한 확인
간헐적인 reset 또는 timeout 노드 품질, 패킷 손실, 규칙 분기 다른 노드와 비교하고 장시간 연결을 테스트

안정성을 높이려면 Codex CLI용 프록시와 일반 브라우저용 프록시를 무조건 같은 정책으로 묶지 않는 것도 방법입니다. 개발 도구는 장시간 연결과 반복 요청이 발생할 수 있으므로, 지연 시간만 낮은 노드보다 연결 유지가 안정적인 노드를 선택하세요. 자동 선택 그룹을 사용하는 경우에도 하루 동안 정책이 자주 바뀌면 인증 세션이나 다운로드가 중단될 수 있으므로, 문제를 해결하는 동안에는 검증된 노드를 임시로 고정하는 편이 좋습니다.

마지막으로 설정을 변경할 때는 한 번에 하나의 요소만 바꾸세요. 포트를 바꾼 뒤 모드를 Global로 변경하고 TUN까지 활성화하면 성공 여부를 확인해도 원인을 알 수 없습니다. 현재 포트, 모드, 선택된 정책, 적용된 환경 변수를 짧은 기록으로 남기면 다른 컴퓨터로 이전하거나 Clash Verge를 업데이트할 때도 같은 구성을 재현하기 쉽습니다.

FlClash 다운로드 플랫폼별 클라이언트 보기