OpenClash 코어 다운로드 실패 해결 방법

OpenClash에 ‘코어가 없음’ 또는 ‘코어 업데이트 실패’가 표시되더라도 먼저 플러그인을 다시 설치하지 마세요. 현재 공식 스크립트는 원격 버전 읽기, 선택한 CPU 아키텍처용 압축 파일 다운로드, gzip 검사, 임시 파일로 압축 해제, 실행 권한 부여, -v 실행을 차례로 수행하며 모두 통과한 뒤에만 정식 코어를 교체합니다. 처음 나타난 명확한 오류가 다음 확인 지점을 결정합니다.

Core Version Check Error는 원격 버전 정보를 읽지 못했다는 뜻이고, Core Download Failed는 압축 파일 요청 실패, Core Verification Failed는 다운로드한 내용이 gzip 검사를 통과하지 못했다는 뜻입니다.

Core Update Failed는 압축 해제, 권한 또는 -v 자체 검사 실패를 뜻합니다. 검증된 임시 파일을 대상 경로에 두지 못했을 때만 Core Move Failed가 표시됩니다. 서로 다른 문제입니다.

2026년 9월 13일 기준 OpenClash 최신 안정 버전은 v0.47.156입니다. 이 글은 현재 master 업데이트 스크립트와 해당 안정 버전에서 사용할 수 있는 안전한 점검 경로를 설명합니다. 단일 issue에 나온 라우터 환경을 모든 기기에서 발생하는 장애로 확대하지 않습니다.

OpenClash가 현재도 시작되고 트래픽을 전달할 수 있다면 /etc/openclash/core를 삭제하거나 업데이트를 연속으로 누르지 마세요. 공식 스크립트는 새 파일을 .new와 프로세스 번호가 포함된 임시 경로에 쓰고 gzip 검사, 압축 해제, chmod 4755, -v 자체 검사를 마친 뒤에만 정식 파일을 덮어씁니다. 자동 업데이트가 실패했을 때 기존 코어가 보통 가장 확실한 복구 지점입니다.

먼저 OpenClash 상태 페이지에서 실행 중인 코어와 버전을 기록한 뒤 사이트의 업그레이드 가이드에 따라 UCI 설정, 구성 파일, 오버라이드를 백업하세요. 코어 파일은 같은 기기와 아키텍처에서 잠시 복구할 사본일 뿐 설정 백업을 대신할 수 없습니다. 구독이나 키가 든 전체 디렉터리를 공개 업로드하지 마세요.

현재 다운로드 스크립트는 UCI의 core_version을 직접 읽어 clash-${core_version}.tar.gz 파일명을 만듭니다. 여기에는 라우터 상품명으로 추측한 비슷한 값이 아니라 OpenClash 버전 업데이트 페이지가 제공하는 빌드 아키텍처가 필요합니다. 잘못 선택하면 다운로드가 완료돼도 -v 실행에 실패할 수 있습니다.

Issue #4758 로그에는 다운로드 시간 초과와 ‘v3 마이크로아키텍처를 지원하는 AMD64 프로세서에서만 실행 가능’ 오류가 함께 나타납니다. 해당 기기에 적어도 네트워크와 아키텍처라는 두 문제가 있었다는 점만 보여 줄 뿐, 모든 수동 업로드 실패가 amd64-v3 때문이라고 증명하지는 않습니다.

현재 공식 빌드 절차에서 amd64와 amd64-v3는 모두 GOAMD64 v3를 요구합니다. x86_64라고 해서 CPU가 v3를 지원하는 것은 아닙니다. v3 unsupported가 표시되면 업데이트 페이지에서 amd64-compatible 또는 amd64-v1을 선택하고 plain amd64를 호환 버전으로 간주하지 마세요.

일반 모드의 정식 대상은 /etc/openclash/core/clash_meta입니다. 소용량 플래시 모드에서는 자동 업데이트 대상이 /tmp/etc/openclash/core/clash_meta로 바뀝니다. 화면을 우회해 추측한 디렉터리에 파일을 강제로 복사하지 마세요. 먼저 설정을 확인한 뒤 해당 마운트 지점과 /tmp의 여유 공간을 점검합니다.

공식 v0.47.156 설치 안내는 curl과 ca-bundle을 의존 패키지로 명시합니다. Issue #5114의 한 기기에서는 openclash_last_version과 clash_last_version을 다운로드할 때 각각 curl 35 TLS connect error와 curl 60 certificate has expired가 기록됐습니다.

이 issue는 유지관리자가 근본 원인을 결론 내리지 않은 단일 기기 보고입니다. 버전 파일도 TLS 계열 오류를 겪을 수 있다는 점만 보여 주며, 코어 압축 파일이 없거나 ca-bundle 재설치가 반드시 효과가 있다고 증명하지 않습니다.

먼저 라우터 시간이 올바른지 확인하고 패키지 페이지에서 curl과 ca-bundle이 설치돼 있으며 손상되지 않았는지 점검하세요. curl에 -k를 추가하거나 TLS 검증을 끄거나 버전 주소를 HTTP로 바꾸지 마세요. 이런 조치는 코어 업데이트의 출처 검증 경계를 없앱니다.

GitHub 직접 연결이 불안정하면 OpenClash의 ‘오버라이드 설정 > 일반 설정’에 있는 GitHub 주소 프록시 옵션을 사용할 수 있습니다. 현재 스크립트는 이 설정에 따라 공식 OpenClash core 브랜치 또는 지원되는 CDN 주소를 구성합니다. 화면이 제공하는 신뢰 가능한 옵션만 선택하고 포럼의 출처 불명 미러를 붙여 넣지 마세요.

아키텍처, 공간, 시간, CA 인증서가 모두 정상이면 OpenClash 버전 업데이트 페이지로 돌아가 코어를 다시 확인하세요. 현재 스크립트는 작업당 최대 세 번 재시도하며 매 시도 전에 이번 다운로드 파일과 새 임시 코어를 정리합니다. 실행 중에 두 번째 작업을 시작하지 마세요.

다운로드 성공이 업데이트 완료를 뜻하지는 않습니다. 로그에 다운로드 성공, 업데이트 시작, Core Update Successful이 차례로 나타나야 합니다. Verification, Update 또는 Move에서 멈추면 해당 단계를 계속 처리하고 진행률이 한때 100%였다는 이유만으로 코어가 교체됐다고 판단하지 마세요.

스크립트는 업데이트에 성공한 뒤에만 재시작을 예약합니다. 두 번째 변수가 생기지 않도록 재시작 전에 구독, DNS, 방화벽을 바꾸지 마세요. 플러그인이 계속 기존 버전을 사용한다면 먼저 상태 페이지를 완전히 새로 고치고 실제 -v 출력을 확인하며 반복해서 덮어쓰지 마세요.

수동 업로드는 라우터가 공식 파일을 안정적으로 다운로드하지 못하는 문제만 해결합니다. 잘못된 아키텍처 선택, 공간 부족, 신뢰할 수 없는 TLS 출처는 고치지 못합니다. 먼저 다른 신뢰할 수 있는 기기에서 vernesong/OpenClash의 core 브랜치로부터 현재 release branch, Meta 유형, core_version과 정확히 일치하는 공식 파일을 받으세요.

파일명은 자동 스크립트가 만드는 clash-${core_version}.tar.gz와 일치해야 합니다. 업로드 컨트롤에는 [Meta] Core File (.tar.gz)이라고 명확히 표시됩니다. ZIP이나 직접 만든 다중 파일 패키지로 이름을 바꿔 업로드하거나 이 절차를 Smart 또는 Oix에 적용하지 마세요.

OpenClash 설정 관리의 업로드 영역으로 들어가 [Meta] Core File (.tar.gz)을 선택하세요. 현재 config.lua는 임시 하위 디렉터리에서 압축을 풀고 첫 번째 일반 파일을 /etc/openclash/core/clash_meta로 이동한 뒤 권한을 4755로 설정하고 업로드 임시 디렉터리를 정리합니다.

이 수동 경로는 -v를 실행하지 않고 해시나 서명도 검증하지 않은 채 기존 파일을 직접 교체합니다. 업로드 전에 작동 중인 기존 코어를 별도로 보관해야 합니다. 업로드 후 File saved는 파일 처리가 끝났다는 뜻일 뿐 아키텍처 호환성이나 실행 가능성을 보장하지 않습니다.

소용량 플래시 모드, 맞춤 펌웨어 또는 이후 버전은 링크나 실행 디렉터리를 통해 코어를 처리할 수 있습니다. 따라서 최종 판단은 현재 화면의 저장 안내, 상태 페이지, -v 출력을 기준으로 해야 합니다. 업로드 후에도 코어가 없다고 표시되면 다른 아키텍처를 반복 업로드하지 말고 앞 절로 돌아가 core_version과 공간을 다시 확인하세요.

업로드 성공 안내는 파일 처리가 끝났다는 뜻일 뿐입니다. 상태 페이지에서 Meta 코어 파일이 존재하고 실행 권한이 정상이며 버전을 표시할 수 있는지 확인한 뒤 OpenClash를 시작하세요. 페이지에 기존 결과가 캐시돼 있으면 새로 고쳐 다시 읽고 운을 시험하듯 재업로드하지 마세요.

이어서 시작 로그에서 설정 테스트, 코어 시작, DNS, 방화벽 단계를 확인합니다. 마지막으로 작동한다고 확인된 노드를 하나 고정하고 도메인 조회와 실제 HTTPS 요청을 각각 완료하세요. 코어는 시작되지만 통신이 실패하면 바이너리를 계속 바꾸지 말고 설정, DNS, 규칙, 노드를 점검해야 합니다.

새 코어를 실행할 수 없거나 시작 직후 종료되거나 기존에 작동하던 설정이 실패하면 먼저 OpenClash를 중지하세요. 수정 전에 저장한 같은 기기·아키텍처의 기존 코어를 복구하고 플러그인이 버전을 읽게 한 뒤 시작합니다. 호환되지 않는 새 파일을 정식 경로에 둔 채 반복 재시작하거나 플러그인, 코어, 설정을 동시에 다운그레이드하지 마세요.

자동 업데이트는 새 파일이 자체 검사를 통과할 때까지 별도의 임시 경로를 사용합니다. 따라서 다운로드, 검증 또는 압축 해제가 실패하면 업데이트를 중지하고 기존 코어를 계속 사용하는 것이 보통 가장 안전합니다. 기존 코어를 수동으로 덮어썼고 백업도 없다면 공식 core 브랜치에서 작동이 확인된 같은 아키텍처 버전을 다시 받으세요. 단체 채팅이나 웹 드라이브에서 같은 이름의 clash_meta를 찾지 마세요.

복구 후 버전 출력, 시작 로그, DNS, HTTPS 네 항목을 다시 검증하세요. 기존 코어가 정상으로 돌아오고 새 버전 문제를 안정적으로 재현할 수 있을 때만 OpenClash issue에 플러그인 버전, core_version, 첫 실패 로그, 남은 공간, 민감 정보를 제거한 환경 정보를 제출합니다.