Retiring a Claude Code Model Unattended with launchd: A Self-Destructing Job That Auto-Patches settings.json

개요

Claude Code 환경에서 모델 EOL(End of Life)로 인한 잠재적 문제를 해결하기 위해, 특정 날짜에 자동으로 설정을 변경하고 스스로를 비활성화하는 "일회용 마이그레이션 작업"을 launchd를 사용하여 구현하는 방법에 대한 내용을 다룹니다.

주요 내용

- 문제점: Claude Code의 settings.json 파일에 특정 모델(claude-fable-5) 설정이 EOL 이후에도 남아있을 경우, 명시적인 오류 없이 의도치 않은 동작이 발생하거나 사용자가 실제 사용 중인 모델을 알 수 없게 될 수 있습니다. 수동으로 설정 파일을 편집하는 것은 정확한 시점에 잊지 않고 한 번만 수행하기 어렵습니다.
- 해결 전략: launchd를 사용하여 이 작업을 자동화하고, 스크립트가 실행된 후에는 자체적으로 비활성화(self-unload)되도록 설계합니다.
- 구현 단계:
1. 날짜 가드 (Date Guard): 작업 스크립트 시작 시점에 현재 날짜를 확인하여, 지정된 날짜(2026년 7월 7일) 이전이면 즉시 종료합니다. 이는 launchd의 캐치업(catch-up) 기능으로 인한 조기 실행을 방지합니다.
2. settings.json 패치: jq를 사용하여 settings.json 파일의 model 필드를 안전하게 업데이트합니다. 이 과정은 원자적(atomic) 네 단계 작업으로 구성됩니다:
* 현재 모델 값 확인 및 fable 포함 여부 검사 (멱등성 확보).
* 설정 파일 백업 (settings.json.bak-model-transition).
* jq를 사용하여 model 값을 opus로 변경하는 임시 파일 생성 (settings.json.tmp).
* 임시 파일이 유효한 JSON인지 jq로 검증 후, 원본 파일로 덮어쓰기 (mv).
3. 알림 및 자기 비활성화 (Notify + Self-unload): 설정 변경이 성공하면 osascript를 통해 데스크톱 알림을 표시하고, launchctl unload 명령어를 사용하여 해당 launchd 작업을 자체적으로 비활성화하고 제거합니다. 이렇게 하면 작업이 완료된 후 더 이상 실행되지 않습니다.
- launchd 설정 (.plist 파일):
- Label, ProgramArguments (bash 스크립트 경로), StartCalendarInterval (하루 세 번 실행 시간 설정: 6:50, 12:50, 20:50), EnvironmentVariables (PATH 설정 포함, 특히 Homebrew jq 경로) 등을 정의합니다.
- StandardErrorPath를 설정하여 디버깅 시 에러 로그를 확인할 수 있도록 합니다.
- 잠재적 함정 및 해결책:
- jq가 PATH에 없어 발생하는 exit 127 오류: EnvironmentVariables.PATH에 Homebrew 설치 경로를 명시해야 합니다.
- 날짜 가드 없이 테스트 중 캐치업 실행으로 인한 조기 마이그레이션: 날짜 가드는 필수적으로 초기 설계에 포함해야 합니다.
- .model 키가 없는 settings.json 처리: jq -r '.model // empty'를 사용하여 null 값 처리를 명확히 합니다.
- 자기 비활성화 후 재실행 우려: launchctl unload는 스케줄을 제거하므로 재실행되지 않습니다. launchctl load를 다시 실행하지 않는 한 유지됩니다.
- stderr 경로 관리 부재: StandardErrorPath 설정은 필수입니다.
- 재사용 가능한 패턴: 이 "일회용 마이그레이션 작업" 패턴은 특정 날짜에 정확히 한 번만 실행되어 설정을 변경하고 사라져야 하는 다양한 시나리오(설정 플래그 토글, API 엔드포인트 변경, 스키마 마이그레이션 등)에 적용될 수 있습니다.

시사점

이 접근 방식은 cron이나 launchd와 같은 스케줄러가 기본적으로 제공하는 영구적인 실행 메커니즘의 한계를 극복하고, 특정 시점에 한 번만 수행되어야 하는 작업을 안정적이고 자동으로 처리하는 견고한 솔루션을 제공합니다.