설정 실전 2026-08-19 약 19분 소요

OpenAI Codex CLI Clash 설정법과 터미널 연결 문제 해결

Codex CLI는 터미널에서 AI 코딩을 지원하지만 네트워크가 불안정하면 인증과 명령 실행이 중단될 수 있습니다. Clash를 활용해 연결을 안정화하는 기본 방법을 알아보세요.

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

OpenAI Codex CLI는 그래픽 화면이 아니라 터미널에서 로그인, 코드 분석, 파일 수정, 명령 실행을 수행하는 개발 도구입니다. 따라서 브라우저만 프록시로 열리는 상태와 Codex CLI가 정상적으로 인증되는 상태는 서로 다를 수 있습니다. 브라우저에서 웹페이지가 열려도 터미널 프로세스가 시스템 프록시를 읽지 않거나, 별도의 환경 변수만 참조한다면 인증 요청은 계속 직접 연결로 나갑니다.

Clash는 일반적으로 세 가지 방식으로 터미널 트래픽을 받을 수 있습니다. 시스템 프록시는 HTTP와 HTTPS 프록시를 인식하는 프로그램에 적합하고, SOCKS5 포트는 애플리케이션이 SOCKS5를 명시적으로 지원할 때 사용할 수 있습니다. TUN 모드는 가상 네트워크 인터페이스를 통해 프로세스가 프록시 설정을 무시하는 경우까지 넓게 가로채는 방식입니다. Codex CLI만 연결하면 되는 상황에서는 먼저 명시적 환경 변수와 시스템 프록시를 확인하고, 다른 프로그램까지 함께 처리해야 할 때 TUN을 고려하는 순서가 안전합니다.

시스템 프록시: Windows, macOS의 네트워크 프록시 설정을 따르는 CLI와 앱에 적합합니다.
HTTP_PROXY와 HTTPS_PROXY: 터미널 세션에서 실행되는 Codex CLI에 가장 직접적으로 적용할 수 있습니다.
SOCKS5: ALL_PROXY를 지원하는 프로그램에서 유용하지만 모든 HTTPS 라이브러리가 동일하게 처리하는 것은 아닙니다.
TUN 모드: 환경 변수를 무시하거나 별도 네트워크 라이브러리를 사용하는 프로세스까지 처리할 수 있지만 관리자 권한과 DNS 설정이 필요할 수 있습니다.

먼저 프록시 포트를 확인하세요

예시에서는 Clash의 혼합 포트를 7890으로 사용하지만 실제 포트는 클라이언트의 설정에 따라 다릅니다. Clash Verge 또는 mihomo 기반 클라이언트의 설정 화면에서 HTTP, mixed, SOCKS 포트를 확인한 뒤 같은 값을 터미널 명령에 입력해야 합니다.

Clash 프로필과 프록시 그룹 준비

Codex CLI를 설정하기 전에 Clash 프로필이 먼저 정상적으로 동작해야 합니다. 노드가 표시되더라도 실제 연결에 사용하는 프록시 그룹이 비어 있거나, 규칙의 마지막 출구가 DIRECT라면 터미널 요청은 프록시를 사용하지 않습니다. 프로필을 적용한 뒤 프록시 그룹에서 응답이 안정적인 노드를 선택하고, 연결 모드는 규칙 기반으로 시작하는 것이 좋습니다.

인증과 API 요청은 여러 호스트 또는 여러 포트로 나뉠 수 있으므로 특정 주소 하나만 프록시로 지정하는 방식은 유지보수가 어렵습니다. 처음 진단할 때는 전역 모드로 바꾸어 Codex CLI의 모든 외부 요청이 선택한 노드로 전달되는지 확인한 다음, 문제가 해결되면 규칙 모드로 돌아가 필요한 트래픽만 분리하세요. 국내 저장소, 패키지 미러, 사내 주소까지 모두 프록시로 보내면 속도가 떨어지거나 사내 서비스가 차단될 수 있습니다.

mixed-port: 7890
mode: rule
rules:
  - DOMAIN-SUFFIX,internal.example,DIRECT
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - MATCH,PROXY

위 설정의 internal.example은 실제 서비스 주소가 아닌 설명용 예시입니다. 실제 프로필에서는 회사 내부 도메인이나 로컬 네트워크 대역만 자신의 환경에 맞게 바꾸세요. 마지막의 MATCH,PROXY는 앞선 규칙에 해당하지 않는 요청을 프록시 그룹으로 보내는 기본 규칙입니다. 그룹 이름이 실제 프로필에서 PROXY가 아니라면 해당 이름으로 맞춰야 합니다.

구독 링크와 토큰을 설정 파일에 남기지 마세요

인증 토큰, 구독 URL, API 키는 명령 기록이나 공개된 설정 파일에 저장하지 마세요. 특히 환경 변수를 한 줄 명령으로 입력하면 셸 히스토리에 남을 수 있으므로, 인증 정보는 Codex CLI의 공식 로그인 흐름이나 운영체제의 안전한 자격 증명 저장소를 우선 사용해야 합니다.

터미널에 프록시 환경 변수 적용하기

Codex CLI를 실행하는 터미널 프로세스가 Clash의 로컬 포트를 사용하도록 환경 변수를 설정합니다. HTTP 기반 혼합 포트를 사용할 때는 HTTP_PROXY, HTTPS_PROXY를 함께 지정하고, 일부 네트워크 라이브러리가 소문자 이름만 읽는 경우를 대비해 소문자 변수도 함께 지정하는 편이 좋습니다. 프록시 주소는 로컬 컴퓨터에서만 접근하므로 127.0.0.1을 사용합니다.

Windows PowerShell

$env:HTTP_PROXY="http://127.0.0.1:7890"
$env:HTTPS_PROXY="http://127.0.0.1:7890"
$env:http_proxy="http://127.0.0.1:7890"
$env:https_proxy="http://127.0.0.1:7890"
$env:NO_PROXY="localhost,127.0.0.1,.local"

이 설정은 현재 PowerShell 창과 그 창에서 실행되는 자식 프로세스에만 적용됩니다. 새 터미널을 열면 다시 지정해야 하므로, 자주 사용할 때는 PowerShell 프로필에 넣거나 Codex CLI 전용 실행 스크립트를 만드는 방법이 편리합니다. 단, 여러 프로젝트에서 같은 셸을 공유한다면 모든 명령이 프록시를 사용하게 되므로 사내 주소와 로컬 장비가 포함된 NO_PROXY 목록을 점검하세요.

macOS와 Linux 셸

export HTTP_PROXY="http://127.0.0.1:7890"
export HTTPS_PROXY="http://127.0.0.1:7890"
export http_proxy="http://127.0.0.1:7890"
export https_proxy="http://127.0.0.1:7890"
export NO_PROXY="localhost,127.0.0.1,.local"

현재 셸에서만 임시로 적용하려면 위 명령을 실행한 뒤 Codex CLI를 시작하면 됩니다. 지속 적용이 필요하면 사용하는 셸의 프로필 파일에 추가할 수 있지만, 프록시가 꺼진 상태에서 터미널을 열면 일반 명령까지 실패할 수 있습니다. 회사 네트워크와 개인 네트워크를 오가며 사용하는 노트북이라면 전역 등록보다 필요할 때 실행하는 별도 스크립트가 문제를 줄입니다.

SOCKS5 포트를 사용할 경우 클라이언트와 라이브러리가 해당 형식을 지원하는지 먼저 확인하세요. 지원 여부가 불분명하면 HTTP 형식을 제공하는 mixed 포트를 우선 사용합니다. ALL_PROXY=socks5://127.0.0.1:7891을 무조건 추가하면 이미 설정한 HTTPS 프록시와 충돌하거나 DNS 처리가 예상과 달라질 수 있습니다.

설정 변경은 한 번에 하나씩 진행해야 어느 단계에서 문제가 생겼는지 확인할 수 있습니다. Clash를 실행하고 노드를 선택한 뒤 터미널에 환경 변수를 적용합니다. 이후 인증을 시작하고, 브라우저 인증 방식인지 터미널 입력 방식인지 화면에 표시되는 안내를 그대로 따릅니다. 브라우저가 열리더라도 실제 인증을 기다리는 CLI 프로세스는 계속 실행 중일 수 있으므로, 인증이 완료될 때까지 터미널을 닫지 마세요.

Clash에서 선택한 프록시 그룹의 현재 노드가 실제로 연결 가능한지 확인하고, 로그 레벨을 일시적으로 info 또는 debug로 설정합니다.
새 터미널을 열어 HTTP_PROXY와 HTTPS_PROXY를 지정하고, 환경 변수 값에 오타나 불필요한 공백이 없는지 확인합니다.
Codex CLI의 로그인 명령을 실행합니다. 일반적으로 codex login처럼 제공되지만 설치된 버전에 따라 도움말에서 정확한 하위 명령을 확인하세요.
브라우저 인증이 완료되면 원래 터미널로 돌아와 로그인 성공 메시지를 확인합니다. 콜백 단계에서 멈추면 브라우저와 CLI가 서로 다른 프록시 경로를 사용하는지 점검합니다.
인증 후 간단한 읽기 전용 요청으로 연결을 시험합니다. 처음부터 파일 수정이나 셸 명령 실행을 요청하지 말고, 현재 작업 디렉터리와 권한 상태를 먼저 확인하세요.
Clash 로그에서 인증 요청이 선택한 프록시 그룹으로 나갔는지, 반복적인 TLS 오류나 연결 시간 초과가 없는지 확인합니다.

연결 확인용으로는 운영체제에 설치된 기본 도구를 사용할 수 있습니다. 아래 명령은 실제 API 응답을 보장하는 테스트가 아니라, 로컬 프록시 포트가 열려 있고 HTTPS 연결을 프록시를 통해 만들 수 있는지 확인하는 용도입니다.

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

example.invalid은 의도적으로 존재하지 않는 문서용 도메인입니다. 이 명령에서 “프록시 연결 거부”가 나타나면 포트나 Clash 실행 상태를 먼저 고치고, TLS 핸드셰이크 시간 초과가 나타나면 노드와 규칙을 점검하세요. 실제 서비스 주소를 무작정 반복 요청하는 방식은 계정이나 사용량에 영향을 줄 수 있으므로 진단 단계에서는 피하는 것이 좋습니다.

자주 나타나는 오류와 원인별 해결법

증상	가능한 원인	확인할 항목
로그인 명령이 즉시 연결 거부	Clash가 꺼져 있거나 포트가 다름	mixed-port, HTTP 포트, 로컬 리스닝 상태
브라우저 인증은 끝났지만 CLI가 대기	콜백 주소가 프록시나 보안 프로그램에 의해 차단됨	localhost를 `NO_PROXY`에 포함했는지 확인
TLS handshake timeout	노드 품질 저하, 잘못된 규칙, MTU 문제	Clash 로그, 다른 노드, TUN 사용 여부
인증 성공 후 요청만 실패	API 요청이 다른 호스트로 이동하거나 규칙에서 DIRECT 처리됨	요청 도메인의规则匹配 결과와 프록시 그룹
명령을 찾을 수 없음	CLI 설치 경로가 PATH에 없음	`codex --help`, 운영체제 PATH, 설치 방식
인증 정보가 반복해서 사라짐	권한 문제, 임시 컨테이너, 자격 증명 저장 실패	설정 디렉터리 쓰기 권한과 실행 환경

로그인 콜백이 멈추는 경우에는 NO_PROXY가 지나치게 넓게 설정되지 않았는지 확인하세요. localhost와 127.0.0.1은 로컬 콜백을 위해 직접 연결하는 것이 일반적이지만, 외부 인증 서버 도메인을 무심코 NO_PROXY에 넣으면 브라우저 인증 페이지와 CLI의 인증 요청이 서로 다른 경로로 나갈 수 있습니다.

반대로 TUN 모드에서 localhost까지 가상 인터페이스로 보내면 콜백 서버가 정상적으로 응답하지 않을 수 있습니다. 이런 환경에서는 DNS 하이재킹과 자동 라우팅을 켜더라도 로컬 주소 예외를 유지하세요. TUN을 켠 뒤 문제가 시작됐다면 TUN을 끄고 환경 변수 방식으로 재시험하면 원인을 빠르게 분리할 수 있습니다.

프록시 오류와 인증 오류를 구분하세요

“connection refused”, “timeout”, “TLS handshake”는 대체로 네트워크 경로 문제이고, 인증 만료·권한 부족·잘못된 계정은 서버가 반환하는 인증 단계의 오류입니다. 전자는 Clash 로그와 포트를 먼저 보고, 후자는 Codex CLI의 로그아웃 후 재로그인과 계정 권한을 확인해야 합니다.

TUN과 DNS를 사용할 때의 추가 점검

Codex CLI가 실행하는 셸 명령이나 패키지 도구까지 같은 네트워크 정책으로 처리해야 한다면 TUN 모드가 편리할 수 있습니다. 다만 TUN은 단순히 브라우저를 프록시로 바꾸는 기능이 아니라 시스템 라우팅과 DNS 흐름을 변경하는 기능입니다. Windows에서는 서비스 모드와 관리자 권한이 필요할 수 있고, macOS에서는 네트워크 확장 또는 VPN 구성 허용이 요구될 수 있습니다.

mihomo 기반 클라이언트에서는 auto-route, auto-detect-interface, dns-hijack 설정이 서로 맞물립니다. 자동 라우팅이 꺼져 있으면 TUN 인터페이스가 만들어져도 일부 트래픽이 기존 네트워크 카드로 빠질 수 있습니다. DNS 하이재킹이 빠지면 도메인 조회는 운영체제 DNS로 남아 규칙 매칭이 불안정해질 수 있습니다. fake-ip을 사용하는 경우 198.18.0.1/16과 같은 가상 대역이 로컬 네트워크 규칙에 의해 차단되지 않는지도 확인하세요.

Clash 로그에서 DNS 요청이 기록되는지 확인합니다.
nslookup 또는 dig 결과가 매번 바뀌는지, 특정 잘못된 주소가 반복되는지 비교합니다.
사내 도메인과 로컬 프린터 주소는 NO_PROXY 또는 DIRECT 규칙으로 분리합니다.
패키지 설치 명령이 실패하면 Codex 자체가 아니라 패키지 저장소의 인증서, 별도 프록시 설정, 저장소 정책을 확인합니다.

터미널 명령 실행을 허용할 때는 네트워크가 안정적이라는 이유만으로 모든 명령을 자동 승인하지 마세요. Codex CLI가 파일을 수정하거나 외부 패키지를 설치하도록 설정되어 있다면 프로젝트 디렉터리, 셸 권한, 환경 변수에 저장된 비밀 정보까지 함께 고려해야 합니다. 먼저 읽기 작업으로 검증하고, 변경 작업은 명령별로 확인하는 것이 안전합니다.

FAQ: Codex CLI와 Clash 연결 문제

시스템 프록시를 켰는데도 Codex CLI가 직접 연결되는 이유는 무엇인가요?

터미널 프로그램이나 내부 HTTP 라이브러리가 운영체제의 시스템 프록시를 읽지 않을 수 있습니다. 현재 셸에 HTTP_PROXY와 HTTPS_PROXY를 직접 지정한 뒤 다시 실행하세요. 그래도 로그가 보이지 않으면 TUN 모드로 비교 테스트를 진행해 프로세스가 프록시 변수를 무시하는지 확인할 수 있습니다.

HTTP_PROXY와 HTTPS_PROXY에 서로 다른 포트를 넣어야 하나요?

Clash의 mixed 포트를 사용한다면 두 변수에 같은 HTTP 주소를 넣어도 됩니다. 다만 실제 클라이언트에서 HTTP와 SOCKS 포트가 분리되어 있다면 HTTPS 요청에 SOCKS 포트를 HTTP 주소로 입력하지 않도록 주의하세요. 포트 형식과 프로토콜이 맞지 않으면 연결 거부 또는 TLS 오류가 발생합니다.

Codex 로그인 후에는 환경 변수를 삭제해도 되나요?

로그인 정보가 안전하게 저장되고 이후 요청이 직접 연결로도 허용되는 환경이라면 가능하지만, 인증 후 API 요청도 프록시가 필요한 네트워크라면 환경 변수를 계속 유지해야 합니다. 테스트할 때는 변수를 삭제한 새 셸에서 간단한 요청을 실행해 인증 경로와 실제 작업 경로가 모두 정상인지 구분하세요.

노드를 바꾸면 Codex CLI 인증을 다시 해야 하나요?

일반적으로 노드 변경만으로 저장된 인증 정보가 사라지지는 않습니다. 그러나 출구 지역이나 IP가 바뀌면서 보안 확인이 추가되거나, 이전 연결이 만료되어 재인증이 요구될 수 있습니다. 짧은 시간에 여러 지역의 노드를 반복해서 바꾸기보다 안정적인 하나의 그룹을 선택하고 Clash 로그에서 연결 상태를 확인하세요.

다음 단계: Clash 설정과 Codex 실행 환경 정리

Codex CLI 연결 문제는 대부분 클라이언트 자체보다 로컬 포트, 셸 환경 변수, DNS 경로, 규칙 순서 중 하나에서 발생합니다. 먼저 mixed 포트와 전역 연결을 이용해 기본 경로를 검증한 뒤, 규칙 모드와 TUN 모드로 범위를 좁히면 불필요한 설정 변경을 줄일 수 있습니다. 설치 파일과 클라이언트 선택이 아직 정해지지 않았다면 다운로드 센터에서 플랫폼에 맞는 mihomo 기반 클라이언트를 확인하고, 적용 후에는 단계별 튜토리얼에 따라 프로필과 프록시 모드를 설정하세요.

전방위 다운로드 설정 튜토리얼