이 글의 목차
로그가 멈춘 단계를 먼저 확인하고 두 가지 실패를 섞지 마세요
OpenClash의 APK 업데이트는 설치 패키지를 다운로드한 뒤 업데이트 전 테스트를 실행하고 실제 설치로 진행합니다. 로그의 '다운로드 성공'은 /tmp/openclash.apk가 라우터에 기록되었다는 뜻일 뿐 이후 두 단계까지 모두 성공한다는 의미는 아닙니다.
OpenClash 공식 issue #5256에는 2026년 7월 28일부터 두 가지 현상이 함께 기록되어 있습니다. 하나는 '업데이트 전 테스트' 단계에서 unrecognized option 'allow-downgrade'로 중단되는 경우이고, 다른 하나는 '업데이트 전 테스트 통과'가 명확히 표시된 뒤 '패키지 설치 실패'가 발생하는 경우입니다.
2026년 8월 6일 기준 이 issue는 여전히 Open 상태이며 프로젝트에서는 모든 기기에 적용되는 단일 원인을 아직 제시하지 않았습니다.
로그를 기준으로 다음 단계 결정
| 마지막 핵심 로그 묶음 | 현재 확인할 수 있는 내용 | 다음 단계 |
|---|---|---|
| 업데이트 전 테스트가 실패하고 unrecognized option 'allow-downgrade'가 나타남 | 현재 apk-tools가 해당 매개변수를 허용하지 않아 실제 설치 단계에는 아직 진입하지 않음 | APK 출처를 확인한 뒤 공식 Release에서 해당 매개변수가 없는 방식 사용 |
| 업데이트 전 테스트가 실패했지만 매개변수 오류는 없음 | 모의 트랜잭션에 다른 오류가 있음 | 전체 apk 출력을 보존하고 시스템 패키지 상태부터 확인 |
| 업데이트 전 테스트는 통과했지만 이후 패키지 설치 실패 | 사전 검사는 통과했으며 실제 트랜잭션에서 실패 발생 | 반복해서 누르지 말고 SSH에서 원본 설치 오류 확인 |
| 다운로드 실패 또는 /tmp/openclash.apk가 없음 | 완전한 설치 패키지가 아직 없음 | 다운로드, 출처 또는 저장 공간 문제부터 처리 |
- 설치 패키지 다운로드openclash.apk를 /tmp에 기록
- 업데이트 전 테스트apk-tools에서 매개변수와 트랜잭션을 모의 검사
- 실제 설치검사를 통과한 패키지를 시스템에 기록
- 서비스 검증플러그인을 재시작하고 구성, 코어와 네트워크 확인
'업데이트 전 테스트 실패'와 '테스트 통과 후 설치 실패'는 서로 다른 단계에서 발생합니다. 마지막 apk 오류를 먼저 읽고 수동 설치가 필요한지 판단하세요.
먼저 백업하고 해당 라우터가 실제로 APK를 사용하는지 확인
LuCI 플러그인을 업데이트하기 전에 OpenClash 구성 관리 페이지에서 현재 백업을 내보내고 OpenClash가 중지되어도 로컬 네트워크나 유선 SSH로 라우터에 접속할 수 있는지 확인하세요. 구독, 덮어쓰기와 사용자 규칙에는 민감한 링크가 포함될 수 있으므로 백업은 신뢰할 수 있는 위치에만 보관합니다.
OpenClash v0.47.133 공식 Release에서 APK 시스템은 apk와 openclash.apk를 사용하고 기존 OpenWrt 펌웨어는 opkg와 IPK를 사용합니다. 두 패키지 관리자와 설치 패키지 형식을 섞을 수 없습니다. 이 글은 로그에 apk가 명확히 나타나는 기기에만 적용됩니다.
command -v apk
apk --version
apk info luci-app-openclash 2>/dev/null
df -h /overlay /tmp
ls -lh /tmp/openclash.apk수동 처리 전 필수 조건
- OpenClash 구성을 내보냈거나 복원 가능한 백업이 있음을 확인함
- 로컬 네트워크 또는 유선 SSH로 라우터에 로그인할 수 있음
- 로그와 command -v 결과에서 IPK 또는 opkg가 아닌 APK를 사용함을 확인함
- /tmp/openclash.apk가 존재하며 파일 크기가 0이 아님
- 현재 OpenClash, 펌웨어와 apk-tools 버전을 기록함
업데이트 전 테스트 실패 시 매개변수와 패키지 상태부터 확인
전체 오류가 unrecognized option 'allow-downgrade'라면 의미는 좁습니다. 현재 apk-tools가 이 옵션을 파싱하지 못한다는 뜻입니다. 저장 공간 부족이나 설치 패키지 손상과는 다르며 OpenWrt를 반드시 다운그레이드해야 한다는 뜻도 아닙니다. 로컬 도움말에서 해당 매개변수가 있는지 먼저 확인하세요.
apk add --help 2>&1 | grep -- '--allow-downgrade' || echo '当前 apk-tools 不支持 allow-downgrade'테스트가 실패했지만 이 매개변수 오류가 없다면 공식 APK로 모의 수정 검사를 한 번 실행할 수 있습니다. Alpine 문서에 따르면 --simulate는 데이터베이스 변경을 커밋하지 않습니다. 출력에 의존성, world 제약 또는 다른 오류가 나타나면 결과부터 보존하고 fix에서 --simulate를 제거해 바로 실행하지 마세요.
apk fix --simulateallow-downgrade 미지원만 보고됨
다음 절로 이동해 해당 매개변수가 없는 공식 설치 방식을 사용합니다.
apk fix --simulate가 OK를 반환
이번 모의 검사에서 시스템 패키지 상태 오류가 드러나지 않았으므로 실제 설치 출력을 계속 확인합니다.
breaks: world, 의존성 충돌 또는 누락된 패키지가 나타남
수동 설치를 중단하고 타사 소프트웨어 저장소와 일치하지 않는 패키지를 확인하세요. force-broken-world를 사용하면 안 됩니다.
공간 또는 파일 검사 이상
펌웨어 자체의 저장 공간 관리 방식으로 먼저 처리하고 구성 백업을 보존하세요. /overlay 내용을 무작정 삭제하지 않습니다.
공식 Release와 일치하는 수동 설치를 한 번만 실행
로그에서 allow-downgrade 미지원 때문에 중단되었다고 명확히 표시된다면 OpenClash v0.47.133 공식 Release의 APK 설치 명령에는 이 옵션이 없습니다. 백업, 관리 경로와 /tmp/openclash.apk 출처를 확인한 뒤 같은 매개변수로 모의 설치를 먼저 실행합니다. 모의 설치가 통과하면 --simulate를 제거해 실제 설치를 한 번만 실행하세요.
두 번째 경우는 로그에 '업데이트 전 테스트 통과'가 표시되었지만 실제 설치 단계에서 실패한 상황입니다. 이때도 LuCI 업데이트를 계속 누르지 마세요. 아래 실제 명령을 SSH에서 실행하는 목적은 apk가 의존성, 서명, 공간, 잠금 또는 I/O 같은 원본 오류를 모두 출력하게 하는 것입니다. issue 댓글에 특정 원인이 언급되었다는 이유만으로 시스템을 미리 바꾸지 마세요.
apk add --simulate --force-overwrite --clean-protected --allow-untrusted /tmp/openclash.apkapk add --force-overwrite --clean-protected --allow-untrusted /tmp/openclash.apk명령이 완료되고 성공을 반환함
LuCI를 새로 고치고 플러그인 버전을 확인한 뒤 최종 목록에 따라 서비스를 검증합니다.
unrecognized option이 계속 표시됨
전체 명령과 출력을 저장하고 실제 실행한 apk 경로와 버전을 확인하세요. 매개변수를 계속 추측하지 않습니다.
UNTRUSTED signature가 나타나고 파일이 공식 출처가 아님
즉시 중단하고 강제 매개변수를 더 추가하지 마세요. 공식 Release에서 설치 패키지를 다시 받습니다.
의존성, world, 공간, 잠금 또는 읽기 전용 파일 시스템 오류가 나타남
원본 출력을 보존하고 해당 오류에 맞게 처리하세요. 더 많은 강제 변형 명령을 반복해서 실행하지 않습니다.
설치가 적용되지 않으면 마지막 정상 상태로 복귀
수동 설치는 성공했지만 LuCI를 열 수 없거나 OpenClash가 시작되지 않거나 기존 덮어쓰기가 사라졌다면 OpenClash를 먼저 중지해 라우터가 플러그인을 거치지 않는 로컬 관리 경로를 복구하도록 합니다. 그런 다음 업데이트 전에 내보낸 백업에서 구성을 복원하세요. 플러그인 패키지, Mihomo 코어, 구독과 덮어쓰기는 서로 다른 계층이므로 펌웨어 롤백 한 번으로 계층별 복원을 대신할 수 없습니다.
apk 명령 자체가 실패하면 /tmp/openclash.apk, 터미널 출력과 구성 백업을 보존하고 force 매개변수를 더한 변형 명령을 반복하지 마세요. 이전 버전으로 돌아가야 한다면 현재 펌웨어 저장소에서 시스템과 일치하는 패키지 또는 정상 작동을 확인한 공식 패키지를 우선 사용합니다. 검증 가능한 다운그레이드 경로가 없다면 현재 관리 가능한 상태를 유지하고 공식 issue에 민감 정보를 제거한 로그를 제출하세요.
실제 영향 범위에 따라 롤백
| 결과 | 보존할 항목 | 롤백 작업 |
|---|---|---|
| APK 명령은 실패했지만 기존 페이지는 계속 사용 가능 | 원본 apk 출력과 현재 구성 | 재시도를 중단하고 기존 서비스 상태 복구 |
| 설치는 성공했지만 페이지 또는 서비스가 비정상 | 업데이트 전 OpenClash 백업 | 서비스를 중지한 뒤 구성을 복원하고 코어 아키텍처 다시 확인 |
| 업데이트 후 집 안 모든 기기에서 접속 불가 | 라우터 로컬 관리 경로 | OpenClash를 임시로 비활성화하고 OpenWrt 직접 연결이 복구되는지 먼저 확인 |
| 로컬 네트워크에서도 라우터를 관리할 수 없음 | 기존 유선 또는 failsafe 복구 방안 | 관리 경로부터 복구하고 관찰할 수 없는 상태에서 업그레이드를 계속하지 않음 |
플러그인 설치 후 서비스와 전체 네트워크를 각각 검증
마지막으로 '플러그인 설치 성공'과 '프록시 서비스 복구'를 나누어 검증합니다. LuCI 또는 apk info에서 설치 버전을 먼저 확인한 뒤 OpenClash를 시작하고 코어 아키텍처, 구성, 구독과 덮어쓰기가 여전히 일치하는지 확인하세요. 서비스가 안정된 뒤에만 LAN 단말 한 대에서 새로운 DNS 및 웹 요청을 보냅니다.
플러그인 페이지는 정상인데 트래픽 분기만 계속 비정상이라면 코어, 구독, DNS와 라우팅 규칙을 확인하고 apk 설치를 반복하지 마세요. 반대로 네트워크는 되지만 LuCI 버전이 바뀌지 않았다면 패키지 설치 로그로 돌아가야 하며 페이지 캐시만 보고 업그레이드 완료를 판단하면 안 됩니다.
업데이트 완료 검증 목록
- apk info 또는 LuCI에 표시된 OpenClash 버전이 이번 목표와 일치함
- OpenClash 페이지가 열리고 구성, 덮어쓰기와 구독이 계속 표시됨
- Mihomo 코어 아키텍처가 라우터 플랫폼과 일치하고 시작 로그에 새 오류가 없음
- LAN 단말 한 대에서 새 도메인을 해석하고 일반 웹페이지를 열 수 있음
- 연결 기록에서 테스트 요청이 예상한 규칙과 정책에 일치함
- OpenClash를 비활성화해도 라우터에 명확한 직접 연결 및 관리 복구 경로가 있음