Codex CLI와 Clash Verge로 안정적인 접속 설정하는 법

Codex CLI와 Clash Verge의 연결 구조 이해하기

Codex CLI는 터미널에서 코딩 작업을 요청하고, 프로젝트 파일을 읽고, 명령을 실행하며, 원격 AI 서비스와 통신하는 명령줄 도구입니다. 브라우저에서 웹페이지가 정상적으로 열리더라도 터미널의 Codex CLI가 반드시 같은 네트워크 경로를 사용하는 것은 아닙니다. 브라우저는 운영체제 프록시나 확장 프로그램의 설정을 읽을 수 있지만, 명령줄 프로그램은 별도의 프록시 환경 변수나 자체 네트워크 라이브러리를 사용할 수 있습니다.

Clash Verge의 역할은 Codex CLI 자체를 대신 실행하는 것이 아니라, 로컬 HTTP 또는 SOCKS 프록시 포트를 열고 해당 포트로 전달된 연결을 규칙과 정책 그룹에 따라 처리하는 것입니다. 따라서 문제를 점검할 때는 다음 세 구간을 나누어 확인해야 합니다.

이 세 구간을 구분하면 “로그인은 실패하지만 일반 웹 접속은 된다”, “curl은 성공하지만 Codex CLI만 실패한다”, “프록시를 지정했는데도 연결 기록이 없다”와 같은 현상을 더 빠르게 분류할 수 있습니다. 특히 인증 토큰이나 계정 설정을 반복해서 삭제하기 전에 먼저 네트워크 경로와 로컬 포트부터 확인하는 것이 안전합니다.

Clash Verge에 프로필을 등록하고 기본 상태 확인

먼저 Clash Verge를 실행하고 사용할 구독 또는 로컬 YAML 프로필을 등록합니다. 화면 구성은 Clash Verge와 Clash Verge Rev의 버전, 운영체제, 선택한 테마에 따라 다를 수 있지만 일반적으로 Profiles 또는 프로필 화면에서 구독 URL을 추가한 뒤 업데이트합니다. 구독 주소를 입력할 때는 주소 전체가 정확한지 확인하고, 웹 브라우저에서 임의로 열어 내용을 공개하거나 다른 사람에게 전달하지 마세요. 구독 URL에 사용자 식별 정보가 포함되는 경우가 있기 때문입니다.

프로필을 가져온 뒤에는 해당 프로필을 선택해 실제 실행 설정으로 적용합니다. 목록에 프로필이 존재하는 것과 현재 코어가 그 프로필을 사용 중인 것은 다릅니다. 선택 표시, 활성화 상태 또는 현재 설정 표시를 확인한 다음 Clash Verge의 연결 화면에서 노드와 정책 그룹이 나타나는지 살펴보세요. 노드 목록이 비어 있거나 설정 파싱 오류가 표시되면 Codex CLI 설정을 변경하기 전에 YAML과 코어 호환성부터 해결해야 합니다.

코어, 포트와 시스템 프록시 점검

Clash Verge는 그래픽 인터페이스와 프록시 코어를 함께 제공하지만, 실제 연결 처리는 현재 실행 중인 코어가 담당합니다. 정보 화면이나 로그에서 사용 중인 코어가 Mihomo인지, 그리고 정상적으로 시작되었는지 확인하세요. 프로필 안에 mixed-port, port, socks-port가 지정되어 있다면 그 값을 기준으로 해야 하며, 로컬 포트가 항상 7890이라고 가정하면 안 됩니다.

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info

mixed-port는 HTTP와 SOCKS 요청을 하나의 포트에서 받을 수 있어 터미널 도구를 테스트하기 편리합니다. 반면 external-controller 포트는 Clash 상태를 제어하거나 조회하는 API 포트이므로 Codex CLI의 프록시 주소로 사용하면 안 됩니다. 예를 들어 127.0.0.1:9090이 제어 인터페이스라면 이 주소를 프록시로 설정하는 것이 아니라 실제 HTTP, SOCKS 또는 mixed 포트를 사용해야 합니다.

Clash Verge에서 System Proxy 또는 시스템 프록시를 켜면 운영체제의 프록시를 읽는 애플리케이션에 영향을 줄 수 있습니다. 그러나 이 스위치만으로 모든 터미널 프로그램이 자동으로 프록시를 사용하는 것은 아닙니다. TUN 모드는 더 넓은 범위의 트래픽을 처리할 수 있지만 운영체제 권한, DNS 모드, 가상 네트워크 인터페이스와 충돌할 수 있으므로 처음부터 TUN에 의존하기보다 명시적인 프록시 환경 변수로 CLI 연결을 검증하는 편이 원인 파악에 유리합니다.

터미널에 프록시 환경 변수 설정하기

Codex CLI를 실행하는 셸에 프록시 환경 변수를 설정하면 시스템 프록시를 무시하는 명령줄 프로그램도 로컬 Clash 포트를 사용하도록 유도할 수 있습니다. 가장 먼저 HTTP 프록시와 HTTPS 프록시를 같은 로컬 mixed 포트로 지정해 보세요. HTTPS 연결이라고 해서 반드시 https://127.0.0.1 형식의 프록시를 사용해야 하는 것은 아닙니다. 일반적인 HTTP 프록시는 HTTPS 목적지로의 CONNECT 요청을 전달할 수 있으므로 로컬 프록시 주소는 실제 리스너의 프로토콜에 맞춰 작성해야 합니다.

Windows PowerShell 설정

PowerShell에서 아래 명령을 실행하면 현재 창에서만 환경 변수가 적용됩니다. 포트가 7890이 아니라면 Clash Verge에 표시된 실제 포트로 바꾸세요.

$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"

codex

현재 셸에 저장된 값을 확인하려면 다음과 같이 실행합니다.

Get-ChildItem Env:HTTP_PROXY,Env:HTTPS_PROXY,Env:ALL_PROXY

새 터미널을 열 때마다 다시 입력하기 싫다면 PowerShell 프로필이나 운영체제 환경 변수에 저장할 수 있지만, 회사 네트워크나 학교 네트워크처럼 프록시를 사용하지 않는 장소에서는 잘못된 설정이 남아 연결을 방해할 수 있습니다. 먼저 일시적인 세션 변수로 작동 여부를 확인한 뒤 영구 설정을 결정하세요.

macOS와 Linux 설정

zsh, bash 등 대부분의 Unix 계열 셸에서는 export 명령을 사용합니다.

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"

codex

SOCKS 포트를 사용해야 한다면 Clash Verge에 실제 SOCKS 리스너가 열려 있는지 확인한 후 다음처럼 지정할 수 있습니다.

export ALL_PROXY="socks5h://127.0.0.1:7891"

socks5h의 h는 대상 도메인 해석을 프록시 측에서 처리하도록 요청하는 표기입니다. 로컬 DNS가 대상 주소를 해석하지 못하는 환경에서는 도움이 될 수 있지만, 모든 CLI 내부 라이브러리가 모든 프록시 표기를 동일하게 지원하는 것은 아닙니다. HTTP 프록시 환경 변수로 먼저 테스트한 다음 SOCKS 방식으로 비교하는 순서가 좋습니다.

실제 연결을 단계별로 테스트하기

이제 Codex CLI를 바로 반복 실행하지 말고 로컬 포트, HTTPS 요청, Clash 기록 순서로 확인합니다. 아래 절차는 Windows, macOS, Linux에서 공통으로 적용할 수 있으며 명령어 문법만 운영체제에 맞게 바꾸면 됩니다.

  1. Clash Verge를 실행합니다. 프로필이 활성화되어 있고 노드 목록과 정책 그룹이 정상적으로 표시되는지 확인합니다.
  2. 현재 프록시 포트를 기록합니다. 설정 화면에서 mixed 포트 또는 HTTP 포트를 확인합니다. 예시에서는 7890을 사용합니다.
  3. 프록시를 명시한 curl을 실행합니다. 셸의 환경 변수보다 먼저 로컬 포트 자체가 작동하는지 검사합니다.
  4. Clash 연결 기록을 확인합니다. 테스트 대상 도메인과 적용 규칙, 선택된策略 그룹이 표시되는지 살펴봅니다.
  5. 같은 셸에서 Codex CLI를 실행합니다. 별도의 터미널에서 실행하면 환경 변수가 전달되지 않을 수 있으므로 테스트에 사용한 동일한 창을 유지합니다.
curl -I -x http://127.0.0.1:7890 https://example.com

curl -v -x http://127.0.0.1:7890 https://example.com

첫 번째 명령에서 HTTP 응답 헤더가 반환되고 Clash 연결 기록에도 요청이 표시되면 로컬 포트와 기본 노드 경로는 대체로 정상입니다. connection refused가 나오면 해당 포트에서 프로세스가 수신 중이지 않거나 포트 번호가 잘못된 것입니다. 오랫동안 응답이 없으면 선택한 노드, 원격 연결, DNS와 방화벽을 확인해야 합니다. curl은 성공하지만 Codex CLI만 실패한다면 CLI가 환경 변수를 읽지 않거나, 별도의 인증·네트워크 라이브러리를 사용하거나, 다른 셸에서 실행하고 있을 가능성이 있습니다.

Windows에서는 다음 명령으로 포트가 실제로 열려 있는지 확인할 수 있습니다.

Test-NetConnection 127.0.0.1 -Port 7890

macOS와 Linux에서는 다음 중 하나를 사용할 수 있습니다.

lsof -nP -iTCP:7890 -sTCP:LISTEN
ss -lntp | grep 7890

포트 테스트가 성공해도 요청이 DIRECT로 처리되면 프록시가 사용되지 않았다는 뜻이 아니라, 해당 규칙이 직접 연결을 선택했다는 뜻일 수 있습니다. Codex CLI가 접속하는 도메인이 필요한 정책 그룹으로 전달되는지, 규칙 목록의 위쪽에 이를 덮어쓰는 DOMAIN, DOMAIN-SUFFIX, GEOSITE 또는 사용자 지정 규칙이 있는지 확인하세요. 마지막의 MATCH 규칙은 앞선 규칙에 일치하지 않은 연결을 처리하므로, 테스트할 때는 최종 매칭 결과도 함께 봐야 합니다.

로그인과 API 호출이 실패할 때 점검할 항목

Codex CLI의 로그인 과정과 실제 작업 요청은 서로 다른 단계일 수 있습니다. 로그인 페이지를 브라우저에서 열어 인증을 완료했더라도 CLI가 실행되는 터미널 환경에 인증 결과가 전달되지 않거나, 콜백 주소가 로컬 보안 프로그램에 의해 차단될 수 있습니다. 브라우저 인증이 끝난 뒤 CLI가 계속 기다린다면 Clash의 연결 기록에서 인증 도메인 요청이 발생했는지 확인하고, 터미널에 표시된 콜백 주소와 포트를 다른 프로그램이 점유하고 있지 않은지 살펴보세요.

로그인 이후 API 호출만 실패한다면 인증 정보가 무효라고 단정하지 마세요. API 요청 대상 도메인이 로그인 과정과 다를 수 있고, 정책 규칙이 한쪽은 프록시로 다른 쪽은 직접 연결로 처리할 수 있습니다. DNS 실패, TLS 인증서 오류, 프록시 서버의 연결 제한, 로컬 시간 오류도 API 요청 실패를 일으킬 수 있습니다. 시스템 날짜와 시간대가 크게 어긋나면 인증 토큰 검증에 영향을 줄 수 있으므로 자동 시간 동기화 상태도 확인하는 것이 좋습니다.

문제 재현 시에는 먼저 Clash Verge에서 시스템 프록시와 TUN 중 하나만 사용하고, 선택한 정책 그룹을 임시로 확인 가능한 노드로 고정하세요. 디버깅이 끝나면 전역 고정 설정을 그대로 두지 말고 원래의 자동 선택 또는 규칙 기반 설정으로 되돌립니다. 인증 토큰, 구독 URL, API 키와 컨트롤러 비밀 값은 로그나 화면 캡처에 포함되지 않도록 가리고 공유해야 합니다.

안정적인 일상 사용을 위한 운영 방법

Codex CLI를 자주 사용한다면 단순히 연결에 성공하는 것보다 재현 가능한 환경을 만드는 것이 중요합니다. 프로젝트별 셸 초기화 파일에 무조건 프록시를 고정하기보다는, 프록시가 필요한 작업에서만 적용되는 별도 명령이나 스크립트를 사용하는 편이 안전합니다. 프록시를 사용하지 않는 사내 Git 서버나 로컬 개발 서버까지 외부 노드로 보내면 속도 저하와 접근 오류가 발생할 수 있습니다.

Clash Verge의 로그 수준은 평상시 info 정도로 유지하고, 장애를 분석할 때만 일시적으로 높이세요. 로그에는 접속 도메인과 요청 정보가 나타날 수 있으므로 장기간 보관하거나 공개할 때 개인정보와 프로젝트 주소를 검토해야 합니다. 프로필을 업데이트한 뒤에는 포트, DNS, 정책 그룹과 사용자 지정 규칙이 원래대로 유지되었는지도 확인하세요. 구독 업데이트가 전체 YAML을 덮어쓰는 구조라면 지속적으로 필요한 변경은 클라이언트의 오버라이드나 병합 기능에서 관리해야 합니다.

또한 Codex CLI가 작업 중 장시간 연결을 유지하거나 스트리밍 응답을 받는다면 순간적인 지연보다 연결의 지속성이 중요할 수 있습니다. 여러 노드를 무작정 번갈아 선택하기보다 연결 기록, 오류 유형, 재시도 결과를 기준으로 안정적인 정책 그룹을 고르는 것이 좋습니다. 노드 선택 후에는 동일한 환경 변수와 동일한 테스트 명령으로 다시 확인해야 비교 결과가 의미를 가집니다.

자주 묻는 질문

Clash Verge에서 시스템 프록시를 켜면 Codex CLI도 자동으로 프록시를 사용하나요?

항상 그렇지는 않습니다. Codex CLI가 운영체제 프록시를 읽는지, 실행 환경의 프록시 변수를 읽는지에 따라 다릅니다. 가장 확실한 확인 방법은 HTTP_PROXY와 HTTPS_PROXY를 Clash의 실제 mixed 포트로 지정한 뒤 curl과 CLI를 같은 터미널에서 테스트하는 것입니다.

HTTP 프록시와 SOCKS5 프록시 중 어느 쪽을 사용해야 하나요?

먼저 CLI와 호환성이 좋은 HTTP 프록시를 시도하는 것이 일반적입니다. SOCKS5를 사용하려면 해당 라이브러리가 socks5 또는 socks5h 표기를 지원하는지 확인해야 합니다. 지원 여부가 불명확하면 mixed 포트와 HTTP 환경 변수로 연결을 검증하세요.

curl은 성공하지만 Codex CLI만 연결되지 않는 이유는 무엇인가요?

CLI가 다른 셸에서 실행되거나, 환경 변수를 읽지 않거나, 별도의 인증·네트워크 설정을 사용할 수 있습니다. 실행 중인 터미널에서 변수 값을 출력하고 Clash 연결 기록에 CLI의 실제 대상 도메인이 나타나는지 확인하세요.

TUN 모드를 켜면 환경 변수 설정이 필요 없나요?

TUN은 더 많은 트래픽을 가로챌 수 있지만 모든 애플리케이션의 동작을 동일하게 보장하지는 않습니다. DNS, 권한, 다른 VPN과의 충돌도 발생할 수 있으므로 환경 변수로 명시적인 프록시 경로를 먼저 검증한 뒤 필요할 때 TUN을 추가하는 편이 문제 해결에 유리합니다.

Clash 다운로드