빌더 일지 11화 「스마트홈 자동화, 새벽 4 시에 우리 집이 스스로 토큰을 갈아 끼운다」에서 소개한 자가수리 장치를 누구나 쓸 수 있게 정리한 것입니다.

내려받기

aqara-token-renew.zip — 아래 파일 전부
낱개: scripts/aqara-token-renew.ps1 · config/selfrepair.local.example.ps1 · LICENSE (MIT)

처음에는 반드시 -DryRun 으로 돌려 보세요. 판단만 하고 아무것도 바꾸지 않습니다.

아카라 토큰 자동 갱신 키트 (Home Assistant + aqara_bridge)

블로그 「40대 비개발자 아저씨의 빌더 일지」 11화에서 소개한 자가수리 장치에서 우리 집 정보를 뺀 것이다. Aqara 클라우드 토큰은 30일마다 만료되고, 끊기면 Home Assistant(HA)를 거치는 아카라 기기가 한꺼번에 “사용 불가”가 된다. 이 스크립트는 매일 한 번 만료 시각을 보고, 5일 안으로 들어오면 새 토큰을 받아 HA에 넣고 다시 켠 뒤 연결이 살아났는지 확인해서 알린다.

무엇을 하나

매일 정해진 시각(우리 집은 새벽 4시)에 작업 스케줄러가 실행한다
HA 설정에서 aqara_bridge 토큰 만료 시각을 읽어 남은 날을 센다
5일보다 많이 남았으면 아무 말 없이 끝낸다
5일 이내면 Aqara 개방 API에 토큰 갱신을 요청한다
요청이 실패하면 HA는 건드리지 않고 텔레그램으로 “수동 개입 필요”만 보낸다
성공하면 설정을 백업하고, HA를 멈추고, 새 토큰을 넣고, HA를 다시 켠다
10초 간격으로 15번(약 2분 반) 통합이 다시 올라왔는지 확인하고 결과를 보낸다

우리 집에서 2026년 9월 25일 새벽 4시에 처음으로 사람 손 없이 갱신했고, 전체가 17초 걸렸다.

이런 환경에서 썼다

Windows 11, Windows PowerShell 5.1, Docker Desktop
Home Assistant 컨테이너(이름 homeassistant, 설정 볼륨 homeassistant_config)
aqara_bridge 사용자 통합(앱 ID, 키 ID, 앱 키, 갱신 토큰이 HA 설정에 들어 있는 형태)
텔레그램 봇(알림용, 없어도 된다)

다른 환경이면 config\selfrepair.local.ps1의 컨테이너, 볼륨, 이미지, 주소 값을 바꾼다.

설치

aqara-token-renew\
  scripts\aqara-token-renew.ps1
  config\selfrepair.local.ps1      ← 예시 파일을 복사해서 만든다
  logs\                            ← 실행하면 생긴다
  backups\                         ← 따로 정하지 않으면 여기에 백업

config\selfrepair.local.example.ps1을 config\selfrepair.local.ps1로 복사하고 값을 채운다
- $EntryId: HA의 aqara_bridge 통합 항목 ID. HA 설정의 기기 및 서비스에서 Aqara Bridge를 열면 주소창에 config_entry= 뒤로 보인다
- $ApiUrl: 계정 지역의 Aqara 개방 API 주소
- $HaToken: HA 장기 액세스 토큰. 다시 켠 뒤 통합 상태를 읽는 데만 쓴다
- $TelegramToken, $ChatId: 비워 두면 알림 없이 로그만 남긴다

처음엔 반드시 판단만 해 보는 모드로 돌린다

powershell -ExecutionPolicy Bypass -File scripts\aqara-token-renew.ps1 -DryRun

작업 스케줄러에 매일 한 번(예: 04:00), 가장 높은 권한으로 등록한다. 컴퓨터가 꺼져 있던 날을 위해 “예약된 시작 시간을 놓치면 가능한 대로 빨리 실행”도 켠다

안전 규칙

만료 5일 안에서만 갱신한다. 매일 한 번씩 다섯 번 다시 시도할 기회가 생긴다
갱신 요청이 실패하면 HA를 건드리지 않는다. 망가진 값으로 덮어쓰는 게 제일 무섭다
설정을 바꾸기 전에 core.config_entries를 백업한다. 백업에는 모든 통합의 비밀값이 평문으로 들어 있으니 다른 사람이 못 보는 폴더에 둔다
에러 메시지는 300자에서 자른다. 통째로 로그나 알림에 넣으면 비밀값이 샐 수 있다

꼭 알아둘 것

HA의 .storage 폴더를 직접 고치는 건 HA가 공식으로 권하는 방법이 아니다. 이 스크립트는 HA를 멈춘 뒤에만 고친다
만료 시각은 2026-08-31 23:48:49처럼 빈칸 형식이어야 한다. 가운데에 T가 들어가면 통합이 로그 한 줄 없이 멈춘다
PowerShell 5.1은 BOM 없는 UTF-8 스크립트를 지역 코드페이지로 읽는다. 그래서 스크립트는 영문만 쓰고, 한글 알림은 글자 번호로 조립한다
서버를 다시 설치하면 인코딩 환경이 바뀔 수 있다. 다시 설치한 뒤엔 -DryRun부터 다시 돌린다. 우리 집은 이걸 몰라서 6일 동안 갱신이 멈췄었다
알림이 오는지도 따로 감시한다. 알림이 죽으면 나머지도 죽은 것과 같다
갱신이 성공하면 새 토큰이 든 임시 파일 _selfrepair_patch.py를 스스로 지운다. 패치가 실패했을 때만 HA 설정 폴더에 남는다. 그때는 알림을 보고 새 토큰을 손으로 넣는다
패치가 실패하면(볼륨 이름이 틀린 경우 등) HA는 옛 토큰으로 다시 켜지고 “패치 실패” 알림을 보낸다. 아카라가 갱신하면서 옛 갱신 토큰을 무효로 만들 수 있어서, 이 알림을 받으면 며칠 안에 손으로 처리해야 한다

원본과 달라진 점

우리 집에서 2026년 8월부터 쓰는 스크립트와 동작은 같고, 다음만 바꿨다.

통합 항목 ID, API 주소, 백업 폴더, 컨테이너와 볼륨 이름, HA 주소를 설정 파일로 뺐다
로그에 새 토큰의 앞자리를 남기지 않는다
공개판에서 안전장치 두 가지를 더했다: 패치 결과를 확인해서 실패하면 “갱신 완료” 대신 실패 알림을 보내고(종료 코드 4), 성공하면 새 토큰이 든 임시 패치 파일을 지운다. 이 두 가지는 우리 집 원본에는 아직 없고, 공개판에서 처음 넣었다

출처와 라이선스

서명(Sign)을 만드는 규칙은 Aqara 개방 API 공식 문서(opendoc.aqara.cn)에 나온 방식이다. 헤더 값들을 이어 붙이고 앱 키를 붙인 뒤 소문자로 바꿔 MD5를 낸다
이 규칙을 처음 본 곳은 aqara_bridge 사용자 통합(github.com/niceboygithub/AqaraBridge)의 aiot_cloud.py다. 서명 함수는 그 규칙을 PowerShell로 다시 쓴 것이고, 그 저장소의 코드 자체는 들어 있지 않다(저장소에 라이선스 표기가 없다)
이 키트의 코드는 MIT 라이선스다(LICENSE)
코드는 비개발자인 내가 말로 설명하고 AI(Claude Code)가 짰다