서론: Codex CLI와 Clash를 함께 사용하는 이유
터미널에서 AI 코딩 도구를 사용하려는 개발자에게 OpenAI Codex CLI는 편리한 선택지입니다. 편집기 화면을 오가지 않고 현재 프로젝트의 파일을 읽고, 명령어를 실행하며, 코드 수정안을 검토할 수 있기 때문입니다. 그러나 중국 내 네트워크 환경에서는 로그인 페이지가 열리지 않거나, 인증은 완료되었는데 터미널에서 응답이 멈추는 문제가 발생할 수 있습니다.
이러한 현상은 Codex CLI 자체의 오류라기보다 인증 서버, API 엔드포인트, 패키지 저장소, 원격 모델 서버로 향하는 트래픽이 서로 다른 경로를 사용하기 때문에 나타나는 경우가 많습니다. 브라우저에만 시스템 프록시를 적용하면 터미널 프로세스는 프록시를 사용하지 않을 수 있으며, 반대로 모든 트래픽을 무조건 우회하면 국내 서비스와 패키지 미러의 속도가 떨어질 수 있습니다.
Clash를 함께 사용하면 도메인과 프로세스의 목적에 따라 연결 경로를 나눌 수 있습니다. Codex 관련 트래픽은 안정적인 프록시 그룹으로 보내고, 국내 Git 저장소나 사내 서버는 DIRECT로 유지하는 방식입니다. 이 글에서는 2026년 기준으로 Windows, macOS, Linux 터미널에서 공통으로 적용할 수 있는 기본 원칙과 점검 순서를 설명합니다.
먼저 확인할 사항
Clash는 네트워크 경로를 제어하는 도구이며, OpenAI 계정이나 유료 API 사용 권한을 대신 제공하지 않습니다. 사용 중인 지역의 법률, 서비스 약관, 조직의 보안 정책을 먼저 확인하세요.
1설치 전 준비와 터미널 환경 점검
설정에 들어가기 전에 Codex CLI가 실행될 컴퓨터의 기본 환경을 확인해야 합니다. CLI는 터미널에서 동작하므로 GUI 브라우저의 프록시 상태와는 별개로 네트워크를 점검해야 합니다. 먼저 Clash 클라이언트가 실행 중이고, 실제로 사용할 프록시 그룹에 정상적인 노드가 선택되어 있는지 확인하세요.
- Clash 코어 확인: Clash Verge Rev 또는 Mihomo 기반 클라이언트를 사용하고, 시스템 프록시와 TUN 모드 중 자신의 환경에 맞는 방식을 선택합니다.
- 터미널 권한 확인: macOS와 Linux에서는 셸 설정 파일을 수정할 권한이 있는지, Windows에서는 PowerShell 또는 Windows Terminal이 정상 실행되는지 확인합니다.
- 시간과 인증서 확인: 시스템 날짜가 크게 어긋나거나 오래된 루트 인증서를 사용하면 HTTPS 인증과 로그인 콜백이 실패할 수 있습니다.
- 기존 프록시 정리: 과거에 설정한
HTTP_PROXY,HTTPS_PROXY,ALL_PROXY값이 Clash의 포트와 다른지 확인합니다.
Clash 포트와 연결 상태 확인
Clash의 설정 화면에서 HTTP 포트 또는 Mixed 포트를 확인하세요. 일반적으로 로컬 주소는 127.0.0.1이며, 포트 번호는 사용자가 변경할 수 있습니다. 아래 명령으로 해당 포트가 열려 있는지 확인할 수 있습니다. 예시의 7890은 실제 Clash 포트로 바꾸어야 합니다.
응답이 전혀 없으면 Codex 설정부터 수정하기보다 Clash의 포트, 노드, 모드가 정상인지 먼저 확인해야 합니다. 또한 회사 보안 프로그램이나 다른 VPN이 같은 포트를 점유하고 있지 않은지도 살펴보세요.
2Clash에서 Codex 트래픽 분기하기
핵심은 OpenAI 관련 요청을 하나의 안정적인 프록시 그룹으로 보내는 것입니다. 그룹 이름은 사용 중인 설정 파일에 따라 다르므로 아래 예시의 AI-Proxy를 실제 그룹 이름으로 바꾸세요. 모든 도메인을 무조건 우회하기보다는 인증, 모델 요청, 업데이트에 필요한 도메인을 관찰하면서 필요한 범위만 추가하는 편이 관리하기 쉽습니다.
설정 파일의 rules 항목에서 구체적인 도메인 규칙을 일반적인 규칙보다 위에 배치하세요.
※ 실제 요청 도메인은 버전과 로그인 방식에 따라 달라질 수 있으므로 Clash의 연결 로그에서 확인하세요.
규칙 순서가 잘못되면 앞에 있는 GEOIP,CN,DIRECT 또는 MATCH,DIRECT가 OpenAI 요청을 먼저 처리할 수 있습니다. 따라서 OpenAI 관련 규칙을 상단에 배치하고, 마지막에는 전체 트래픽을 처리할 기본 규칙을 둡니다. GUI 클라이언트에서 규칙 제공자와 기본 설정을 사용하는 경우에도 현재 적용된 규칙 순서를 반드시 확인하세요.
주의사항
공유 노드나 데이터센터 IP는 로그인 보안 확인, CAPTCHA, 응답 제한을 유발할 수 있습니다. 반복 로그인이나 빠른 노드 변경을 계속하면 계정 보호 절차가 강화될 수 있으므로, 안정적인 단일 노드를 먼저 테스트하세요.
3터미널에 프록시를 적용하는 방법
Clash 시스템 프록시를 켰다고 해서 모든 CLI가 자동으로 이를 따르는 것은 아닙니다. 사용하는 프로그램이 환경 변수나 운영체제 프록시 설정을 읽는지에 따라 결과가 달라집니다. 가장 먼저 현재 셸에만 프록시를 적용해 테스트하면 영구 설정으로 인한 혼란을 줄일 수 있습니다.
임시 환경 변수 설정
ALL_PROXY는 프로그램에 따라 SOCKS5 주소를 해석하는 방식이 다를 수 있습니다. HTTP 프록시만 지원하는 도구라면 HTTP_PROXY와 HTTPS_PROXY만 사용하세요. 사용하지 않을 때는 다음 명령으로 값을 제거할 수 있습니다.
Windows, macOS, Linux별 적용 팁
PowerShell에서는 다음처럼 현재 세션의 환경 변수를 지정합니다. 영구 적용이 필요하면 PowerShell 프로필에 추가하되, 공용 컴퓨터에서는 비밀 정보와 함께 저장하지 마세요.
Zsh나 Bash를 사용하는 경우 ~/.zshrc 또는 ~/.bashrc에 필요한 변수만 추가한 뒤 새 터미널을 열어 적용합니다. SSH로 접속한 원격 서버에서 Codex를 실행한다면 로컬 컴퓨터의 Clash가 아니라 원격 서버의 네트워크 경로가 사용된다는 점을 기억하세요.
프록시 변수를 설정한 뒤에도 로그인 명령이 실패한다면 환경 변수가 실제 Codex 프로세스까지 전달되는지 확인하세요. 셸에서 실행한 env 결과와 IDE 내장 터미널의 환경은 다를 수 있습니다. VS Code나 JetBrains 계열 IDE를 사용한다면 IDE를 완전히 다시 시작한 뒤 재시험하는 것이 좋습니다.
4로그인과 API 응답 오류 진단
Codex CLI의 문제를 해결할 때는 “로그인 실패”, “인증 완료 후 멈춤”, “모델 응답 지연”을 서로 다른 문제로 분리해야 합니다. 각 단계에서 요청이 어디까지 도달했는지를 확인하면 무작정 노드를 교체하는 일을 줄일 수 있습니다.
- 브라우저 로그인 단계: 인증 페이지가 열리지 않으면 Clash의 브라우저 트래픽이 AI 전용 그룹을 사용하는지 확인합니다. 로그인 후 터미널로 돌아오지 않는다면 로컬 콜백 포트가 다른 프로그램에 의해 차단되었는지 확인하세요.
- 토큰 저장 단계: 인증이 완료되었지만 매번 다시 로그인하라는 메시지가 나오면 사용자 계정의 설정 디렉터리 권한과 보안 프로그램의 파일 차단 여부를 확인합니다.
- API 요청 단계: 로그에 401 또는 403이 표시되면 계정 권한, 토큰 만료, 지역 및 서비스 정책을 먼저 점검합니다. 네트워크 문제로 단정하고 반복 요청하지 마세요.
- 시간 초과 단계: 408, 429 또는 연결 시간 초과가 반복되면 노드의 혼잡도, DNS 응답, 프록시 연결 유지 상태를 확인합니다.
권장 점검 순서
Clash 연결 로그 확인 → API 도메인에 적용된 규칙 확인 → 터미널 환경 변수 확인 → 계정과 권한 확인 → Codex CLI 업데이트 순서로 점검하면 원인을 빠르게 좁힐 수 있습니다.
DNS와 TUN 모드 점검
도메인은 열리지만 특정 API 요청만 멈춘다면 DNS 해석 결과가 서로 다른 경로를 가리키는지 확인하세요. Clash의 DNS 모드와 운영체제 DNS가 충돌하면 로그인 페이지와 API 요청이 서로 다른 IP로 연결될 수 있습니다. TUN 모드를 사용할 때는 가상 네트워크 인터페이스와 DNS 가로채기 옵션을 함께 확인하고, 이미 다른 VPN이 실행 중이라면 하나씩 끈 상태에서 테스트하세요.
다만 TUN 모드가 항상 정답은 아닙니다. 단순히 환경 변수를 읽는 CLI라면 시스템 프록시 또는 HTTP 프록시만으로 충분할 수 있습니다. TUN 모드를 켠 뒤 문제가 생겼다면 먼저 모드를 끄고 동일한 노드와 명령으로 비교하여 어느 계층에서 오류가 발생하는지 확인하세요.
5안정적인 개발 워크플로와 보안 수칙
Codex CLI는 프로젝트 파일을 읽거나 명령어를 실행할 수 있으므로 네트워크 설정만큼 권한 관리도 중요합니다. 처음 사용하는 저장소에서는 작업 디렉터리를 별도로 만들고, 변경 전 Git 커밋이나 백업을 남겨 두세요. AI가 제안한 명령어를 그대로 실행하기보다 파일 변경 내역과 터미널 명령을 한 줄씩 검토하는 습관이 필요합니다.
- 비밀 정보 보호: API 키, 쿠키, 개인 인증서,
.env파일을 프롬프트에 복사하지 말고 Git 저장소에도 커밋하지 않습니다. - 규칙 최소화: Codex 관련 도메인만 AI 전용 그룹으로 보내고, 사내 Git이나 중국 내 업무 시스템은 조직 정책에 맞춰 직접 연결합니다.
- 노드 고정: 테스트 중에는 자동 선택보다 안정적인 노드를 고정해 응답 시간과 오류율을 비교합니다.
- 로그 관리: Clash 연결 로그에 토큰이나 전체 요청 내용이 기록되지 않는지 확인하고, 문제 해결 후 상세 로그를 끄거나 보관 기간을 줄입니다.
- 업데이트 확인: Codex CLI, Clash 클라이언트, Mihomo 코어를 신뢰할 수 있는 공식 배포 경로에서 업데이트합니다.
일상적인 작업에서는 터미널을 열 때마다 프록시가 자동으로 적용되도록 설정하기보다, AI 작업용 셸 함수나 별도 프로필을 사용하는 방법도 유용합니다. 이렇게 하면 일반 개발 작업과 AI 작업의 네트워크 경로를 분리할 수 있고, 패키지 설치나 사내 서비스 접속에 불필요한 지연을 줄일 수 있습니다.
자주 묻는 질문
시스템 프록시를 켰는데도 Codex CLI가 연결되지 않습니다. 왜 그런가요?
CLI가 운영체제의 시스템 프록시를 읽지 않고 별도의 환경 변수만 읽는 경우가 많습니다. Clash의 HTTP 또는 Mixed 포트를 확인한 뒤 현재 셸에 HTTP_PROXY와 HTTPS_PROXY를 임시로 설정해 비교해 보세요. 그래도 실패한다면 연결 로그에서 요청이 실제로 Clash를 통과하는지 확인해야 합니다.
HTTP 프록시와 SOCKS5 중 무엇을 사용해야 하나요?
프로그램이 공식적으로 지원하는 방식을 우선 사용하세요. 많은 Node.js 기반 CLI는 HTTP 및 HTTPS 환경 변수를 비교적 잘 처리하지만, SOCKS5 지원은 실행 방식이나 의존성에 따라 달라질 수 있습니다. 먼저 HTTP 포트로 테스트하고, 필요한 경우에만 SOCKS5 포트를 사용하면 문제 범위를 좁히기 쉽습니다.
Codex CLI에는 TUN 모드가 반드시 필요한가요?
반드시 필요한 것은 아닙니다. CLI가 프록시 환경 변수를 정상적으로 읽고 DNS도 올바르게 해석한다면 일반 시스템 프록시로 충분할 수 있습니다. 반면 프록시 변수를 무시하는 프로세스, 컨테이너, 일부 GUI 통합 기능까지 같은 규칙으로 처리해야 한다면 TUN 모드가 도움이 됩니다.
로그인 후 401, 403, 429 오류가 계속 발생합니다. 노드를 바꾸면 해결되나요?
항상 그렇지는 않습니다. 401은 인증 정보나 권한 문제, 403은 접근 정책이나 보안 차단, 429는 요청 빈도 또는 사용량 제한일 가능성이 있습니다. 먼저 계정 상태와 서비스 정책을 확인하고, 요청을 반복하지 않은 상태에서 Clash 로그와 CLI 버전을 점검하세요. 노드 변경은 네트워크 품질 문제가 확인된 경우에만 신중하게 시도하는 것이 좋습니다.
마무리
안정적인 Codex CLI 환경은 빠른 노드 하나보다 정확한 규칙, 올바른 터미널 프록시 변수, 일관된 DNS와 권한 관리에서 시작됩니다. 먼저 작은 테스트 프로젝트에서 연결을 검증한 뒤 실제 업무에 적용하세요.