설치 및 마이그레이션 · Clash 기술 블로그

구성을 잃지 않고 OpenClash를 업그레이드하는 방법: 플러그인, 코어, 구독 및 백업 복원 가이드

OpenClash의 플러그인, 코어, 구성 및 덮어쓰기는 같은 업데이트 항목이 아닙니다. 별도로 백업하고 단계별로 업그레이드해 문제가 생긴 단계에서 중지해야 한 번의 업데이트로 집 전체의 인터넷이 끊기는 일을 피할 수 있습니다.

본문 읽기블로그로 돌아가기
  • OpenClash
  • OpenWrt
  • 업그레이드
  • 백업 복구
이 글의 목차
게시일
업데이트 날짜
예상 읽기 시간
약 9분

구성을 잃지 않고 업그레이드하려면 플러그인, 코어, 구독과 백업부터 분리

OpenClash 업그레이드에서 가장 쉽게 문제가 생기는 부분은 LuCI 플러그인, Mihomo 코어, 구독 구성과 덮어쓰기를 한꺼번에 바꾸는 것입니다. 먼저 백업하고 계층 하나만 변경하세요. 각 계층이 통과한 뒤 다음으로 진행하면 페이지가 열리지 않거나 코어가 시작되지 않거나 구독 업데이트가 실패할 때 해당 롤백 파일을 사용할 수 있습니다.

2026-07-16 기준 OpenClash 공식 Latest는 v0.47.116이며 luci-app-openclash_0.47.116_all.ipk와 luci-app-openclash-0.47.116.apk를 함께 제공합니다.

기존 opkg 시스템은 IPK를 사용하고 apk 패키지 관리를 채택한 새 OpenWrt 브랜치는 APK를 사용합니다. 확장자가 비슷하다는 이유로 두 형식을 섞어 설치하면 안 됩니다.

유선 또는 로컬 네트워크를 통해 OpenClash가 중지되어도 라우터 관리 페이지를 열 수 있는지 확인한 뒤 /overlay와 /tmp를 검사합니다. 원격지에서 유지보수하면서 예비 진입점이 없다면 집 전체 네트워크의 플러그인이나 코어를 바로 업그레이드하면 안 됩니다.

공간과 현재 버전, opkg와 apk 시스템 모두 지원
df -h /overlay /tmp
if command -v opkg >/dev/null 2>&1; then
  opkg list-installed | grep -i openclash
else
  apk list --installed | grep -i openclash
fi
uci show openclash.config.config_path

앱 내 백업과 수동 아카이브를 함께 보존

공식 Release 안내에는 플러그인 설정을 백업하고 '구성 파일 관리'에서 압축 파일을 업로드해 복원할 수 있다고 적혀 있습니다. 화면에서 백업 하나를 생성해 컴퓨터로 내려받은 뒤 수동 아카이브도 만드세요. 수동 아카이브를 사용하면 어떤 파일이 실제로 저장되었는지 확인하기 쉽습니다.

일반적인 주요 위치는 /etc/config/openclash, /etc/openclash/config, custom, overwrite와 core입니다. 구성과 구독에는 실제 인증 정보가 있으므로 아카이브를 공개 클라우드 저장소에 두지 마세요.

SSH로 수동 백업 생성, 현재 기기에 실제로 있는 디렉터리만 수집
BACKUP=/tmp/openclash-backup-$(date +%F-%H%M).tgz
set --
for ITEM in etc/config/openclash etc/openclash/config etc/openclash/custom etc/openclash/overwrite etc/openclash/core; do
  [ -e "/$ITEM" ] && set -- "$@" "$ITEM"
done
[ "$#" -gt 0 ] || { echo 'No OpenClash files found'; exit 1; }
tar -C / -czf "$BACKUP" "$@"
ls -lh "$BACKUP"
tar -tzf "$BACKUP" | sed -n '1,40p'

LuCI 플러그인만 먼저 업그레이드하고 코어와 구독은 그대로 유지

백업에 파일이 나열되는지 확인한 뒤 웹 플러그인만 먼저 업데이트합니다. 이때 기존 코어와 구성을 계속 사용하면 페이지에 오류가 날 때 원인을 LuCI 패키지와 의존성으로 제한할 수 있습니다.

패키지 이름을 실제 다운로드한 파일로 교체
# opkg 系统
opkg install /tmp/luci-app-openclash_0.47.116_all.ipk

# apk 系统只使用对应 APK，不执行上面的 opkg 命令
apk add --force-overwrite --clean-protected --allow-untrusted /tmp/luci-app-openclash-0.47.116.apk

설치가 끝나면 LuCI를 새로 고치고 OpenClash 페이지, 구성 파일 목록과 버전 업데이트 페이지를 확인합니다. 페이지가 비어 있거나 의존성 오류가 나거나 메뉴가 사라진다면 플러그인과 시스템 패키지 문제입니다. 이때 Mihomo 코어를 바꾸거나 구독을 업데이트하지 마세요.

페이지가 정상인 뒤 clash_meta 코어 업데이트

OpenClash 공식 안내에서는 버전 업데이트 페이지에서 코어 빌드 버전을 먼저 확인하도록 요구합니다. 수동 설치에서는 코어를 /etc/openclash/core/에 압축 해제해 clash_meta로 이름을 바꾸고 라우터 CPU 아키텍처와 일치시키며 실행 권한도 부여해야 합니다.

기존 코어 사본을 보존하고 업데이트 후 같은 기존 구성을 먼저 로드합니다. 로그에 Exec format error가 나타나면 대개 아키텍처 오류이고 Permission denied는 실행 권한을 확인해야 합니다. YAML 파싱 실패일 때만 구성 필드로 돌아가세요.

수동 교체 전 기존 파일 보존
cp -a /etc/openclash/core/clash_meta /etc/openclash/core/clash_meta.before-upgrade
chmod 0755 /etc/openclash/core/clash_meta
/etc/openclash/core/clash_meta -v

플러그인과 코어가 모두 안정된 뒤 구독을 한 번 수동 업데이트

업그레이드 검증 단계에서는 기존 구성과 노드를 계속 사용해 장애 원인이 플러그인 또는 코어가 아닌지 확인합니다. 페이지, 코어 버전, DNS와 규칙이 모두 정상인 뒤 '구성 파일 구독'에서 자주 쓰는 구독 하나만 업데이트하고 업데이트 시각, 노드 수와 첫 오류를 기록하세요. 업그레이드 당일에 구독 주소, 변환 템플릿과 덮어쓰기를 함께 바꾸지 마세요.

구독 URL 또는 token은 일반적으로 OpenClash 구성과 UCI 설정에 저장되므로 백업 파일은 민감한 자료입니다. 복구 후 목록에 이름은 있지만 업데이트할 수 없다면 URL이 완전한지, 시스템 시간과 401/403 상태를 먼저 확인하고 플러그인 패키지를 다시 덮어쓰지 마세요.

업데이트에서 401 / 403 반환

구독 인증 정보 또는 서비스 권한에 문제가 있습니다. 기존 구성을 계속 실행하고 합법적인 URL을 다시 받으세요.

다운로드는 성공했지만 YAML 파싱 실패

업데이트 전후 구성과 현재 Mihomo 지원 필드를 비교하고 LuCI 플러그인은 롤백하지 않습니다.

노드는 업데이트되었지만 사용자 규칙이 사라짐

custom/overwrite를 복원하고 덮어쓰기 로드 순서를 확인하세요. 캐시를 백업으로 간주하지 않습니다.

복구할 때는 화면 가져오기 또는 전체 아카이브 중 한 방법만 선택

일반적인 경우 OpenClash에서 직접 내보낸 백업을 우선 사용합니다. 페이지를 사용할 수 없고 수동 아카이브 내용이 올바르다고 확인한 경우에만 SSH에서 원래 경로로 복원하세요. 같은 복구 작업에서 두 방식을 섞지 않습니다.

복구 순서

  1. OpenClash 중지

    압축을 푸는 동안 프로세스가 구성과 캐시를 계속 쓰지 않도록 합니다.

  2. 구성 파일 관리에서 공식 백업 가져오기를 우선 사용

    일반 사용자에게 가장 안전한 진입점이며 가져온 뒤 구성 경로를 먼저 확인합니다.

  3. 수동 아카이브가 있을 때만 SSH 사용

    현재 디렉터리를 먼저 따로 저장한 뒤 아카이브를 원래 경로에 압축 해제합니다.

  4. 권한을 복원하고 시작

    clash_meta에 실행 권한이 있는지 확인하고 UCI를 커밋한 뒤 OpenClash를 시작합니다.

  5. 기기 한 대부터 연결

    직접 연결, 프록시, DNS와 라우터 관리가 모두 정상인 뒤 집 전체를 복구합니다.

수동 아카이브 복구 예시, BACKUP 경로를 먼저 실제 파일로 교체
BACKUP='/tmp/openclash-backup-YYYY-MM-DD-HHMM.tgz'
tar -tzf "$BACKUP" | sed -n '1,80p'
/etc/init.d/openclash stop
cp -a /etc/openclash /etc/openclash.failed-$(date +%F-%H%M)
tar -C / -xzf "$BACKUP"
chmod 0755 /etc/openclash/core/clash_meta
uci commit openclash
/etc/init.d/openclash restart

먼저 실패한 계층에서 중단

업그레이드 완료 여부는 새 버전 번호가 아니라 라우터 페이지, 코어, 구성과 단말의 정상 복구로 판단합니다. 어느 계층에서든 먼저 오류가 나면 방금 진행한 단계로 돌아가고 다음 계층을 계속 업데이트하지 마세요.

LuCI 페이지가 비어 있거나 404 반환

플러그인 패키지를 롤백하고 의존성을 수정하거나 브라우저 캐시를 지우며 코어와 구독은 건드리지 않습니다.

clash_meta를 실행할 수 없음

before-upgrade 파일을 복원하고 CPU 아키텍처와 권한을 확인합니다.

코어는 시작했지만 모든 단말에서 DNS 실패

기존 코어 또는 구성으로 돌아가 DNS 하이재킹과 방화벽 변경을 확인합니다.

사용자 규칙 또는 덮어쓰기가 사라짐

custom/overwrite 또는 공식 백업에서 복원하고 OpenWrt 전체를 덮어쓰지 않습니다.

TV 또는 게임기만 비정상

해당 기기부터 다시 연결하고 이전 DNS 임대를 정리하며 다른 구성 요소 업그레이드는 계속하지 않습니다.

집 전체 복구 전 확인

  • LuCI 페이지가 열리고 플러그인 버전이 설치 패키지와 일치함
  • clash_meta -v를 실행할 수 있고 시작 로그에 아키텍처, 권한 또는 파싱 오류가 없음
  • 자주 쓰는 구독을 업데이트할 수 있고 사용자 규칙과 덮어쓰기가 계속 있음
  • 컴퓨터 한 대에서 직접 연결, 프록시, DNS와 라우터 관리 페이지를 각각 먼저 테스트
  • 마지막으로 휴대전화, TV와 게임기가 DHCP와 DNS를 다시 받게 함

참고 자료