ClashX 사용법: 구독 추가부터 노드 변경까지 초보자 가이드
ClashX를 처음 실행한 뒤 필요한 기본 작업을 한 번에 정리했습니다. 구독 링크 등록, 프로필 새로고침, 노드 테스트와 선택, 프록시 켜기까지 순서대로 따라 하면 바로 사용할 수 있습니다.
ClashX를 시작하기 전에 확인할 것
ClashX는 macOS에서 프록시 프로필을 불러오고, 정책 그룹과 노드를 선택한 뒤 시스템 프록시를 전환하는 클라이언트입니다. 처음 실행했을 때 노드 목록이 바로 나타나지 않는 것은 정상입니다. 서비스 제공사가 발급한 구독 링크를 프로필로 등록하고, 해당 프로필을 활성화해야 실제 노드와 프록시 그룹이 표시됩니다.
이 가이드는 ClashX 계열 클라이언트의 기본 흐름을 기준으로 설명합니다. 메뉴 이름은 ClashX와 ClashX Pro, 설치된 버전에 따라 조금씩 다를 수 있지만, 프로필 추가 → 프로필 새로고침 → 노드 확인 → 정책 그룹 선택 → 시스템 프록시 활성화라는 순서는 거의 같습니다. 화면에 “Profiles”, “Proxy”, “Settings” 또는 “增强模式”와 비슷한 항목이 보이면 같은 기능을 찾으면 됩니다.
- macOS 권한: 처음 시스템 프록시를 켤 때 관리자 암호나 네트워크 확장 허용을 요구할 수 있습니다.
- 구독 링크: 보통
https://로 시작하는 긴 주소이며, 계정 토큰이 포함된 인증 정보입니다. - 프로필 형식: 일반적인 Clash YAML 프로필이어야 하며, 다른 클라이언트 전용 형식은 가져오기에 실패할 수 있습니다.
- 커널 확인: 구형 ClashX는 지원 프로토콜과 설정 키가 제한될 수 있으므로, Hysteria2·TUIC·VLESS Reality 같은 기능은 클라이언트의 커널 정보를 먼저 확인해야 합니다.
구독 링크를 공개하지 마세요
구독 주소를 가진 사람은 노드 목록을 내려받거나 서비스 사용량을 소진할 수 있습니다. 메신저 대화방, 게시판, 화면 녹화, 공개 문서에 전체 주소를 그대로 남기지 마세요. 유출이 의심되면 제공사 관리 화면에서 링크를 폐기하거나 재발급한 뒤 ClashX의 기존 프로필도 삭제하고 새 주소를 등록해야 합니다.
구독 링크를 프로필로 추가하기
ClashX에서 구독은 노드 하나를 직접 입력하는 기능이 아니라, 여러 노드와 정책 그룹이 들어 있는 설정 프로필을 내려받는 방식으로 관리합니다. 따라서 구독 링크를 등록한 뒤에도 목록에서 프로필을 한 번 더 선택해야 합니다. 프로필을 등록만 하고 활성화하지 않으면 Proxy 화면이 비어 있거나 이전 설정이 계속 사용될 수 있습니다.
- 서비스 제공사 계정 페이지에서 구독 링크를 복사합니다. 주소 앞뒤에 공백이나 줄바꿈이 들어가지 않도록 전체 URL을 선택하세요.
- macOS 상단 메뉴 막대의 ClashX 아이콘을 클릭하고 Config 또는 Profiles 메뉴를 엽니다.
- Remote Config, Manage, URL에서 가져오기와 같은 항목을 선택합니다. 버전에 따라 메뉴명이 다르지만 URL을 입력하는 창을 찾으면 됩니다.
- 주소 입력란에 구독 URL을 붙여넣고 프로필 이름을 지정한 뒤 확인합니다. 이름은 “개인 구독”, “업무용”처럼 알아보기 쉽게 정하면 됩니다.
- 다운로드가 끝나면 프로필 목록에서 방금 추가한 항목을 클릭해 활성 프로필로 지정합니다. 체크 표시나 활성화 표시가 생겼는지 확인하세요.
- 상단 메뉴 막대의 ClashX 아이콘에서 Proxy를 열어 정책 그룹과 노드 목록이 나타나는지 확인합니다.
구독을 추가했는데 “노드가 없음”, “YAML 파싱 실패”, “다운로드 실패”가 표시되면 URL 자체가 만료되었거나, 제공사가 Clash 형식이 아닌 다른 클라이언트용 링크를 발급했을 가능성이 있습니다. 브라우저 주소창에 링크를 직접 붙여넣어 파일이 내려오는지 확인하는 방법도 있지만, 주소에는 인증 토큰이 포함되어 있으므로 브라우저 기록과 다운로드 폴더를 다른 사람과 공유하지 않아야 합니다.
| 증상 | 가능한 원인 | 먼저 할 일 |
|---|---|---|
| 프로필이 목록에 추가되지 않음 | URL 공백, 만료 링크, 잘못된 메뉴 사용 | 주소를 다시 복사하고 Remote Config 메뉴에서 재등록 |
| 프로필은 있으나 노드가 보이지 않음 | 프로필을 활성화하지 않음, YAML 형식 오류 | 프로필을 클릭해 적용하고 오류 로그 확인 |
| 다운로드가 계속 실패함 | 현재 네트워크에서 구독 주소에 접근할 수 없음 | 브라우저 접근 여부와 시스템 날짜·시간 확인 |
| 노드 이름은 보이지만 연결되지 않음 | 노드 만료, 커널 미지원, 서버 장애 | 다른 노드를 선택하고 클라이언트 커널 지원 범위 확인 |
프로필 새로고침과 설정 적용
구독 서비스에서 서버를 추가하거나 삭제한 뒤에는 ClashX에 저장된 프로필도 갱신해야 합니다. 프로필 새로고침은 현재 활성 노드에 다시 연결하는 동작과 다릅니다. 새로고침은 원격 설정 파일을 다시 받아 노드와 규칙을 업데이트하고, 노드 변경은 이미 받아온 목록 안에서 사용할 출구를 바꾸는 작업입니다.
- 상단 메뉴 막대에서 ClashX 아이콘을 클릭합니다.
- Config 또는 Profiles에서 현재 사용 중인 원격 프로필을 찾습니다.
- 프로필 오른쪽의 새로고침 아이콘이나 Update, Reload 항목을 선택합니다.
- 다운로드 완료 알림이 나타날 때까지 기다립니다. 네트워크가 느리면 수 초에서 수십 초가 걸릴 수 있습니다.
- Proxy 화면을 다시 열어 새 노드가 추가되었는지, 기존 정책 그룹이 정상적으로 유지되는지 확인합니다.
새로고침 직후 현재 선택된 노드가 사라질 수 있습니다. 이는 제공사가 노드 이름을 바꾸거나 서버를 교체했기 때문이며, ClashX가 고장 난 것은 아닙니다. 이때 정책 그룹을 다시 열어 사용 가능한 노드를 선택하면 됩니다. 자동 갱신 주기를 지원하는 버전이라면 너무 짧은 간격으로 설정하지 않는 것이 좋습니다. 짧은 주기는 서비스 제공사의 요청 제한에 걸리거나, 사용 중인 프로필이 자주 교체되는 결과를 만들 수 있습니다.
새로고침 전후에 확인할 항목
프로필 이름, 마지막 업데이트 시각, 노드 개수, 정책 그룹 이름을 기록해두면 문제가 생겼을 때 원인을 좁히기 쉽습니다. 새로고침 전에는 30개 노드가 있었는데 이후 0개가 되었다면 노드 자체의 장애보다 구독 응답 형식이나 만료 상태를 먼저 점검하세요.
노드 테스트와 사용할 노드 선택
Proxy 화면에는 일반 노드뿐 아니라 정책 그룹도 함께 표시됩니다. 예를 들어 “자동 선택”, “Fallback”, “Streaming”, “모든 노드”와 같은 항목은 직접 연결되는 서버가 아니라 여러 노드를 선택하거나 시험하는 정책 그룹일 수 있습니다. 먼저 정책 그룹을 열고 그 안에서 실제 노드를 선택해야 합니다.
노드 선택에서 가장 중요한 수치는 지연 시간과 실제 서비스 접속 여부입니다. ClashX의 지연 시간 테스트는 지정된 테스트 URL에 대한 연결 응답 시간을 측정하는 값이므로, 숫자가 낮다고 모든 사이트와 동영상 서비스가 반드시 빠른 것은 아닙니다. 테스트 대상이 ICMP 핑이 아니라 HTTP 요청인 경우에도 측정 서버의 위치와 상태에 따라 결과가 달라집니다.
| 표시 항목 | 의미 | 선택 기준 |
|---|---|---|
| 지연 시간 50~120ms | 테스트 URL에 빠르게 응답함 | 웹 탐색과 일반 작업에 우선 고려 |
| 지연 시간 120~250ms | 사용 가능하지만 응답 지연이 느껴질 수 있음 | 안정성이 더 좋다면 충분히 사용 가능 |
| Timeout | 테스트 URL에 정해진 시간 안에 응답하지 않음 | 현재 사용 노드에서 제외하고 다른 노드 확인 |
| 자동 선택 그룹 | 그룹 규칙에 따라 노드를 고름 | 수동 선택을 줄이고 싶을 때 사용 |
| 스트리밍 전용 그룹 | 특정 서비스나 지역에 맞춘 노드 묶음 | 서비스의 국가 제한과 노드 지역을 함께 확인 |
노드를 고를 때는 한 번의 테스트 숫자보다 반복 결과를 보세요. 같은 노드를 세 번 테스트했을 때 70ms, 75ms, 80ms처럼 일정하면 안정적인 편입니다. 반대로 45ms와 400ms가 번갈아 나타나면 혼잡이나 경로 변동이 있을 수 있습니다. 동영상 재생이 목적이라면 지연 시간뿐 아니라 재생 시작 속도, 화질 전환, 버퍼링 여부를 실제로 확인해야 합니다.
프록시 모드 켜기와 정상 작동 확인
노드를 선택했다고 macOS의 모든 앱이 자동으로 프록시를 사용하는 것은 아닙니다. ClashX 메뉴에서 시스템 프록시를 활성화해야 Safari와 시스템 프록시 설정을 따르는 대부분의 앱이 ClashX를 사용합니다. 상단 메뉴 막대의 ClashX 아이콘을 클릭한 뒤 Set as System Proxy, 자동 프록시 또는 비슷한 이름의 항목을 켜세요.
- Proxy 화면에서 사용할 정책 그룹을 열고 실제 노드를 하나 선택합니다.
- ClashX 메뉴에서 Set as System Proxy를 활성화합니다. 메뉴 앞에 체크 표시가 생기는지 확인하세요.
- 브라우저에서 IP 확인 페이지나 평소 접속하던 테스트 사이트를 엽니다. 접속 주소와 표시되는 지역이 선택한 출구와 일치하는지 확인합니다.
- ClashX의 로그 화면을 열고 방금 접속한 도메인이
DIRECT인지 선택한 프록시 그룹인지 확인합니다. - 국내 사이트와 해외 사이트를 각각 열어 규칙 분기가 예상대로 동작하는지 확인합니다.
시스템 프록시를 켠 뒤에도 일부 프로그램이 직접 연결되는 것은 이상한 현상이 아닙니다. 게임 런처, 명령줄 도구, 별도 VPN 기능이 있는 앱은 macOS 시스템 프록시를 무시할 수 있습니다. 이런 프로그램까지 넘겨받아야 한다면 ClashX 버전이 TUN 또는 유사한 전체 트래픽 모드를 지원하는지 확인해야 하며, 해당 기능을 무리하게 켜기 전에 DNS, 라우팅, 다른 VPN 도구와의 충돌을 점검해야 합니다.
사용 후 시스템 프록시를 끄는 습관
ClashX를 종료하면서 시스템 프록시가 자동으로 해제되지 않는 버전도 있습니다. 클라이언트를 닫은 뒤 인터넷이 갑자기 작동하지 않으면 macOS 시스템 설정의 네트워크 프록시 항목을 확인하거나 ClashX 메뉴에서 Set as System Proxy를 직접 끄세요. 회사 네트워크나 학교 네트워크에서는 프록시 사용 정책도 함께 확인해야 합니다.
다운로드와 다음 설정
ClashX 또는 다른 mihomo 기반 클라이언트를 새로 설치해야 한다면 운영체제에 맞는 파일과 기본 설정 방법을 먼저 확인하세요. 클라이언트마다 TUN, DNS, 규칙 그룹의 지원 범위가 다르므로 설치 후에는 현재 커널과 시스템 프록시 상태를 함께 확인하는 것이 좋습니다.
자주 발생하는 문제 해결
구독은 추가됐지만 노드가 0개로 표시됩니다
먼저 해당 프로필이 실제로 활성화되어 있는지 확인하세요. 그다음 프로필을 새로고침하고 오류 로그를 확인합니다. 제공사가 구독 형식을 변경했거나 링크가 만료된 경우에는 ClashX에서 계속 재시도해도 해결되지 않습니다. 계정 페이지에서 Clash 또는 YAML 형식의 새 링크를 발급받는 것이 빠릅니다.
연결됨으로 표시되지만 사이트가 열리지 않습니다
선택한 노드가 만료되었거나, 정책 그룹이 실제 노드가 아닌 REJECT 또는 잘못된 그룹을 가리킬 수 있습니다. Proxy 화면에서 다른 노드를 직접 선택하고, 로그에서 요청이 DIRECT로 나가는지 확인하세요. 다른 VPN이나 macOS 네트워크 필터가 동시에 실행 중이면 먼저 하나를 종료해 경로 충돌도 배제해야 합니다.
지연 시간은 낮은데 속도가 느립니다
지연 시간은 짧은 테스트 요청의 응답 속도일 뿐이며, 대용량 전송 속도와 같지 않습니다. 저녁 시간대의 서버 혼잡, 노드의 대역폭 제한, 목적지 서비스의 지역 제한이 원인일 수 있습니다. 같은 지역의 다른 노드와 비교하고, 자동 선택 그룹이 지나치게 오래된 측정 결과를 사용하지 않는지도 확인하세요.
브라우저만 접속이 안 되거나 도메인이 이상하게 열립니다
ClashX의 DNS 설정과 브라우저의 보안 DNS가 서로 다른 경로를 사용할 수 있습니다. 브라우저에서 자체 DNS over HTTPS를 켜 두었다면 시스템 프록시와 별도로 조회가 진행될 수 있습니다. 우선 브라우저 보안 DNS를 임시로 끄고 다시 테스트한 뒤, ClashX의 DNS 모드와 macOS 네트워크 설정을 함께 점검하세요.
ClashX 사용 FAQ
구독을 한 번 등록하면 계속 최신 노드가 유지되나요?
자동 갱신을 지원하는 버전이라도 항상 즉시 최신 상태가 되는 것은 아닙니다. 제공사의 갱신 주기와 링크 만료 정책에 따라 다르며, 노드가 사라졌다면 Profiles 메뉴에서 수동 새로고침을 실행하세요.
노드는 어떤 기준으로 선택해야 하나요?
일반 웹 사용은 안정적인 지연 시간과 접속 성공률을 우선하고, 동영상 서비스는 서비스가 요구하는 지역과 실제 재생 품질을 함께 확인하세요. 가장 낮은 숫자 하나만 보고 고르기보다 여러 번 테스트한 결과가 일정한 노드를 선택하는 편이 좋습니다.
ClashX를 종료하면 프록시도 자동으로 꺼지나요?
버전과 설정에 따라 다릅니다. 종료 후 인터넷이 작동하지 않으면 macOS의 시스템 프록시 설정을 확인하고, ClashX 메뉴에서 시스템 프록시 체크를 직접 해제하세요.
ClashX와 ClashX Pro 중 무엇을 사용해야 하나요?
이름보다 실제 포함된 커널과 기능을 확인해야 합니다. 구독 프로필에 필요한 프로토콜, TUN 지원, DNS 기능, macOS 버전 호환성을 클라이언트 정보 화면에서 비교한 뒤 선택하세요. 최신 프로토콜을 사용하는 구독이라면 구형 Clash 커널에서 설정이 인식되지 않을 수 있습니다.
자주 나타나는 오류와 원인별 해결법
| 증상 | 가능한 원인 | 확인할 항목 |
|---|---|---|
| 로그인 명령이 즉시 연결 거부 | 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 기반 클라이언트를 확인하고, 적용 후에는 단계별 튜토리얼에 따라 프로필과 프록시 모드를 설정하세요.