OpenAI Codex CLI와 Clash Verge 국내 사용 설정 가이드

OpenAI Codex CLI가 Clash Verge와 함께 필요한 이유

OpenAI Codex CLI는 브라우저에서 질문을 입력하는 도구가 아니라, 터미널에서 현재 프로젝트의 파일·명령·테스트 결과를 읽고 코딩 작업을 이어 가는 AI 개발 에이전트에 가깝습니다. 따라서 단순히 웹 페이지가 열리는지만으로 네트워크 상태를 판단하기 어렵습니다. 로그인 과정에서는 인증 페이지와 리다이렉트가 필요하고, 실제 작업에서는 OpenAI API와 스트리밍 연결을 오래 유지하며, 프로젝트에 따라 패키지 레지스트리와 Git 저장소에도 접속합니다.

브라우저용 ChatGPT가 정상인데 Codex CLI만 멈추는 경우도 이런 차이에서 발생합니다. 브라우저는 운영체제의 시스템 프록시를 자동으로 상속하지만, 터미널은 셸 환경 변수, 애플리케이션 자체 설정, Clash의 시스템 프록시 적용 여부에 따라 경로가 달라질 수 있습니다. 특히 로그인 브라우저는 프록시를 사용하고 CLI 프로세스는 DIRECT로 나가면 인증은 완료된 것처럼 보여도 터미널 세션이 토큰을 받지 못하거나 첫 요청에서 타임아웃이 발생합니다.

Clash Verge를 사용하면 프록시 노드 선택, 시스템 프록시 전환, 연결 로그 확인을 한 화면에서 처리할 수 있습니다. 다만 모든 트래픽을 무조건 프록시로 보내는 것보다 Codex에 필요한 인증·API·패키지 경로를 먼저 확인하고, 그 범위에 맞춰 규칙을 설계하는 편이 안정적입니다. 회사나 학교 네트워크에서 프록시 사용이 제한되어 있다면 해당 정책을 먼저 확인하고 허용된 환경에서만 테스트하세요.

설치 전 준비: Clash Verge와 Codex CLI의 역할 구분

먼저 최신 버전의 Clash Verge 또는 사용 중인 배포판의 공식 릴리스를 준비합니다. Clash 계열 클라이언트는 화면은 비슷해도 내장 코어와 지원하는 설정 필드가 다를 수 있으므로, 오래된 버전에서 새 프로필을 억지로 열기보다는 현재 클라이언트가 사용하는 Mihomo 코어와 설정 형식을 확인하는 것이 좋습니다. 프로필을 추가했는데 정책 그룹이 비어 있거나 코어 오류가 표시되면 Codex 설정을 시작하기 전에 이 문제부터 해결해야 합니다.

Codex CLI 쪽에서는 Node.js 기반 설치 여부와 로그인 방식을 확인합니다. 패키지 관리자에서 설치한 경우 npm이 레지스트리와 패키지 저장소에 접속할 수 있으므로, 실행 파일만 통과시키는 방식으로는 설치 단계가 해결되지 않을 수 있습니다. 이미 설치되어 있다면 버전 확인 명령을 실행하고, 오류 메시지에 표시되는 호스트명과 Clash 연결 로그의 호스트명을 비교하세요.

운영체제의 프록시 화면과 Clash Verge의 시스템 프록시 버튼도 함께 점검해야 합니다. Windows에서는 WinHTTP 프록시와 브라우저 프록시가 서로 다를 수 있고, macOS에서는 시스템 설정의 프록시 상태와 터미널 셸의 환경 변수가 별도로 남아 있을 수 있습니다. 하나의 테스트 세션에서는 다른 VPN, 회사용 보안 터널, 로컬 포워더를 잠시 끄는 편이 좋습니다. 여러 프록시가 동시에 포트를 점유하면 Codex가 어느 경로를 사용하는지 판단하기 어려워집니다.

• Clash Verge 상태: 코어 실행, 활성 프로필, 정책 그룹, 시스템 프록시를 확인합니다.
• 터미널 상태: Codex 명령이 인식되는지, 셸이 오래된 프록시 변수를 상속하지 않는지 확인합니다.
• 인증 상태: 브라우저 로그인과 CLI의 토큰 교환이 같은 테스트 시간대에 성공하는지 확인합니다.
• 보안 정책: 회사·학교 장비의 프록시 및 개발 도구 사용 규정을 먼저 확인합니다.

Clash Verge에 프로필을 가져오고 기본 모드 설정하기

Clash Verge를 실행한 뒤 Profiles 또는 프로필 관리 화면에서 제공자가 안내한 구독 URL을 추가합니다. 릴리스에 따라 메뉴 이름이 “프로필”, “구성”, “원격”처럼 다르게 표시될 수 있지만, URL을 저장하고 원격 구성을 내려받은 뒤 활성화하는 흐름은 대체로 같습니다. 구독 URL에는 계정 정보가 포함될 수 있으므로 공개 저장소나 채팅방에 그대로 붙여 넣지 말고, 유출이 의심되면 제공자에게 즉시 갱신을 요청하세요.

프로필을 활성화한 다음 Proxies 화면에서 실제 노드가 표시되는지 확인합니다. 노드가 많을 때는 처음부터 자동 선택 그룹을 신뢰하기보다, 응답이 안정적인 노드를 하나 골라 짧은 테스트를 진행하는 편이 원인 분리에 유리합니다. Codex처럼 스트리밍 요청이 길어질 수 있는 도구에서는 순간적인 핑이 낮은 노드보다 연결이 자주 끊기지 않고 장시간 세션을 유지하는 노드가 더 적합할 수 있습니다.

모드는 일반적으로 Rule, Global, Direct로 나뉩니다. 기본 점검에서는 Rule 모드를 먼저 사용하세요. Global 모드는 모든 애플리케이션을 같은 프록시로 보내므로 문제 확인은 쉽지만, 국내 서비스나 사내 도메인까지 불필요하게 우회할 수 있습니다. Direct 모드에서 Codex가 작동하지 않는다고 해서 곧바로 Global 모드로 고정하기보다, 규칙 모드에서 어떤 호스트가 어떤 정책으로 처리되는지 로그로 확인하는 것이 장기적으로 안전합니다.

Codex 트래픽을 단계별로 이해하기

Codex CLI의 네트워크 요청을 하나의 주소로 생각하면 문제를 찾기 어렵습니다. 실제로는 설치, 인증, 모델 요청, 프로젝트 보조 작업이 서로 다른 호스트를 사용할 수 있습니다. 아래 표는 특정 버전의 고정 목록이 아니라, Clash 로그를 읽을 때 사용할 분류 기준입니다. 릴리스나 계정 환경에 따라 실제 호스트는 달라질 수 있으므로, 표에 없는 주소가 나타났다고 해서 무조건 차단된 주소라고 단정하지 마세요.

예를 들어 로그인 브라우저 요청은 프록시 그룹으로 들어갔지만 API 스트림은 DIRECT로 처리되면, 사용자는 인증 성공 후 첫 명령에서만 멈추는 현상을 보게 됩니다. 반대로 API는 정상인데 npm 레지스트리만 직접 연결이 되지 않으면 Codex 자체 문제가 아니라 의존성 설치 문제일 수 있습니다. 따라서 오류 메시지의 한 줄만 보고 노드를 바꾸기보다, 같은 시각의 연결 로그에서 관련 요청이 같은 정책 의도를 따르는지 비교해야 합니다.

직접 설정하기: 시스템 프록시와 Codex 연결 검증

이제 실제로 최소 설정을 적용해 보겠습니다. 첫 단계는 Clash Verge에서 안정적인 노드를 선택하고 Rule 모드를 켜는 것입니다. 그다음 시스템 프록시를 활성화하고, 브라우저에서 일반적인 HTTPS 페이지가 열리는지 확인합니다. 이 과정은 Codex를 실행하기 위한 최종 테스트가 아니라, 로컬 프록시 포트와 운영체제 연결이 살아 있는지 확인하는 준비 단계입니다.

1. 프로필 활성화: 프로필 화면에서 최신 구성을 선택하고 코어 오류가 없는지 확인합니다. 정책 그룹에 실제 노드가 표시되는지도 함께 봅니다.
2. 노드 선택: 자동 그룹을 그대로 두지 말고 테스트용 노드를 하나 선택합니다. 응답 속도뿐 아니라 장시간 연결 안정성도 고려합니다.
3. 시스템 프록시 켜기: Clash Verge의 시스템 프록시 토글을 활성화한 뒤 브라우저와 터미널을 새로 열어 오래된 프로세스가 남지 않게 합니다.
4. Codex 로그인: CLI에서 제공되는 로그인 명령을 실행하고, 브라우저가 열리면 인증을 완료합니다. 터미널으로 돌아왔을 때 성공 메시지가 나오는지 확인합니다.
5. 작은 프로젝트로 테스트: 큰 저장소 전체를 열기 전에 몇 개의 파일만 가진 테스트 디렉터리에서 상태 확인과 짧은 코드 설명을 요청합니다.
6. 로그 대조: 요청 직후 Clash Verge의 로그에서 인증 호스트와 API 호스트를 검색하고, 모두 예상한 프록시 정책으로 처리되었는지 확인합니다.

터미널 환경 변수를 함께 사용해야 하는 경우에는 Clash Verge가 표시하는 혼합 포트 또는 HTTP 포트의 값을 확인한 뒤 현재 셸 세션에만 임시로 적용하는 방식부터 시도하세요. 운영체제마다 환경 변수 이름과 지원 범위가 다르고, Codex 버전에 따라 자체 프록시 처리가 달라질 수 있으므로 무작정 여러 변수를 영구 등록하지 않는 편이 좋습니다. 임시 설정으로 성공한 뒤에만 셸 프로필에 기록하고, 더 이상 필요하지 않은 변수는 제거하세요.

# 예시는 포트와 주소를 실제 Clash Verge 화면의 값으로 교체합니다
export HTTPS_PROXY=http://127.0.0.1:7890
export HTTP_PROXY=http://127.0.0.1:7890
export NO_PROXY=127.0.0.1,localhost

로그인 콜백은 보통 로컬 주소를 사용하므로 127.0.0.1과 localhost를 프록시에서 제외하는 편이 안전합니다. 로컬 콜백까지 외부 노드로 보내면 브라우저 인증은 완료됐는데 CLI가 대기하거나 포트 연결이 거부되는 문제가 생길 수 있습니다. 다만 NO_PROXY 처리 방식은 프로그램과 운영체제에 따라 다르므로, 설정 후에는 반드시 실제 로그와 터미널 결과를 함께 확인하세요.

Codex 전용 분리 규칙을 설계하는 방법

기본 설정이 확인되면 Codex 트래픽을 별도 정책 그룹으로 묶을지 결정합니다. 개인 PC에서 간단히 사용할 때는 OpenAI 관련 요청을 기존 프록시 그룹으로 보내는 것만으로 충분할 수 있습니다. 반면 회사 네트워크, 여러 AI 도구, 국내 업무 사이트를 함께 사용하는 환경에서는 CODEX_CLI 같은 별도 그룹을 만들면 로그와 장애 범위를 구분하기 쉬워집니다.

규칙은 가능한 한 좁게 시작해야 합니다. 넓은 와일드카드로 모든 AI·개발 도메인을 한꺼번에 프록시로 보내면 GitHub, 사내 Git, 패키지 미러까지 같은 노드로 몰릴 수 있습니다. 먼저 실제 로그에서 OpenAI API와 인증에 사용된 호스트를 확인하고, 필요한 경우에만 패키지 레지스트리나 Git 호스트를 추가하세요. DOMAIN-SUFFIX를 사용하더라도 전체 상위 도메인을 무리하게 포함하지 말고, 규칙 순서상 더 구체적인 예외가 위에 놓였는지 점검해야 합니다.

국내 서비스와 로컬 개발 도구는 DIRECT로 남겨 두는 구성이 보통 관리하기 쉽습니다. 단, “국내 도메인은 모두 직접 연결” 같은 광범위한 규칙은 예외를 놓칠 수 있으므로 회사 내부 도메인, 사설 IP, 로컬 주소를 별도로 확인하세요. Codex가 프로젝트 파일은 로컬에서 읽더라도 패키지 설치와 원격 저장소 요청은 외부로 나갈 수 있으므로, 로컬 작업과 네트워크 작업을 구분해서 로그를 보는 것이 중요합니다.

규칙을 수정한 뒤에는 프로필을 다시 적용하거나 코어를 재로드해야 변경 사항이 실제 런타임에 반영됩니다. YAML의 들여쓰기 오류, 그룹 이름 오타, 존재하지 않는 노드 이름은 저장 단계에서 바로 드러나지 않을 수도 있습니다. 변경 전 원본을 복사하고 한 번에 한 종류의 규칙만 추가하면, 문제가 발생했을 때 어느 줄이 원인인지 되돌리기 쉽습니다.

로그인·타임아웃·스트리밍 오류 해결 순서

브라우저 로그인 후 터미널이 계속 대기하는 경우

먼저 브라우저가 열린 사실과 CLI가 인증 토큰을 받은 사실을 분리해서 확인합니다. Clash 로그에서 인증 페이지 요청은 보이지만 로컬 콜백 또는 토큰 교환 요청이 없다면 브라우저가 잘못된 리디렉션으로 돌아갔거나 셸 프로세스가 다른 환경을 사용하고 있을 수 있습니다. 브라우저와 터미널을 모두 종료한 뒤 Clash 시스템 프록시 상태를 확인하고, 새 터미널에서 다시 로그인하는 것이 첫 번째 조치입니다.

인증 페이지가 반복해서 열리면 시스템 시간이 크게 어긋나지 않았는지, 브라우저 확장이 리디렉션을 막지 않는지, 로컬 콜백 포트가 다른 프로세스에 점유되지 않았는지 확인하세요. 이 단계에서 무작정 API 도메인 목록을 늘리는 것은 도움이 되지 않을 수 있습니다. 인증 흐름의 각 요청이 어느 정책으로 처리되는지 로그에서 확인하는 편이 정확합니다.

첫 요청 또는 스트리밍 중 타임아웃이 나는 경우

첫 요청만 실패하면 API 호스트가 프록시를 타는지와 TLS 연결이 재사용되는지를 먼저 봅니다. 일정 시간 뒤에 끊기면 노드의 장시간 연결 품질, Clash 코어의 연결 유지 설정, 네트워크 사업자의 유휴 연결 제한을 의심할 수 있습니다. 같은 요청을 짧게 반복하기보다 작은 프롬프트와 짧은 작업으로 재현하고, 연결 로그의 시작·종료 시각을 기록하세요.

API 요청이 성공하지만 프로젝트 분석 도중 패키지 설치나 Git 작업에서 실패하면 Codex 모델 연결과 개발 도구 연결을 별도로 분리해야 합니다. npm, PyPI, GitHub, 사내 저장소가 각각 다른 정책을 사용하고 있을 수 있습니다. 이 경우 모델 API 그룹을 바꾸기 전에 실패한 보조 호스트를 찾아 필요한 규칙만 보강하는 것이 더 안전합니다.

Rule과 Global 모드 비교

Rule 모드에서만 실패하고 Global 모드에서 성공한다면 노드 자체보다 규칙 누락이나 우선순위 문제가 유력합니다. 반대로 두 모드에서 모두 실패한다면 인증 정보, 코어 연결, 노드 품질, 로컬 방화벽을 함께 확인해야 합니다. Global 모드에서 잠시 성공한 결과를 최종 설정으로 삼지 말고, 연결 로그에서 확인한 호스트를 기준으로 Rule 모드에 필요한 항목을 옮기세요.

업데이트와 개인정보를 고려한 운영 방법

Codex CLI와 Clash Verge는 모두 빠르게 업데이트될 수 있으므로, 오늘 동작한 호스트 목록이 다음 릴리스에서도 그대로 유지된다고 가정하지 않는 편이 좋습니다. CLI를 업데이트한 뒤에는 로그인, 짧은 모델 요청, 패키지 설치처럼 세 단계의 작은 회귀 테스트를 실행하세요. Clash 프로필도 자동 갱신 직후 정책 그룹 이름과 규칙 순서를 확인하고, 원격 설정이 로컬 예외를 덮어쓰지 않았는지 비교합니다.

API 키와 로그인 토큰은 셸 기록, 프로세스 목록, 디버그 로그에 노출될 수 있습니다. 명령줄 인자로 비밀 값을 직접 넣기보다 공식적으로 지원되는 인증 저장 방식을 사용하고, 로그를 공유할 때는 토큰·이메일·프로젝트 경로·사내 호스트를 가리세요. 구독 URL 역시 민감한 자격 정보처럼 취급해야 하며, 공개 이슈나 화면 녹화에 포함되지 않도록 주의합니다.

TUN 모드는 시스템 프록시를 인식하지 않는 애플리케이션까지 처리하는 데 도움이 될 수 있지만, 권한과 라우팅 범위가 커져 문제 원인이 더 복잡해질 수 있습니다. 먼저 일반 시스템 프록시와 명시적 규칙으로 Codex를 검증한 뒤, 필요한 프로세스가 계속 누락될 때만 TUN을 검토하세요. TUN을 켤 때는 기존 VPN과 충돌하지 않는지, DNS 모드와 로컬 네트워크 접근이 정상인지 함께 확인해야 합니다.

다른 프록시 클라이언트는 빠른 설치나 단순한 노드 선택에는 편리하지만, 터미널 프로세스별 로그가 부족하거나 시스템 프록시와 TUN의 동작 차이를 설명하기 어려운 경우가 있습니다. 반대로 Clash Verge는 프로필·정책 그룹·연결 로그를 한 흐름으로 확인하고 Codex의 인증과 API 트래픽을 분리해 검증하기 좋습니다. 특히 국내 서비스는 직접 연결로 남기고 OpenAI API만 명확히 관리해야 하는 환경이라면, 규칙 모드와 로그를 함께 제공하는 Clash V.CORE가 시행착오를 줄이는 선택이 될 수 있으니 다운로드 페이지에서 현재 시스템에 맞는 버전을 확인해 보세요.