모델과 헤더를 동적으로 가져오기: 재배포 한 번이면 그 다음부터는 자동입니다

하드코딩된 설정의 문제

TokFresh 워커는 각자의 Cloudflare 계정에서 실행됩니다. 워커도 인증 정보도 각자의 몫이며, TokFresh 쪽엔 아무것도 저장하지 않습니다. 다만 지금까지는 워커 코드에 배포 시점 기준으로 두 가지가 고정되어 있었습니다. 요청을 보낼 모델 이름과, 매 요청마다 함께 보내는 API 헤더입니다.

3월 17일 OAuth 업데이트가 반영되자 예전 헤더 형식을 쓰던 워커들이 일제히 실패하기 시작했습니다. 해결 방법은 간단했습니다. 업데이트된 코드로 재배포하면 됩니다. 하지만 모든 사용자가 고장을 알아채고, 사이트에 다시 방문해, 설정을 처음부터 다시 실행해야 한다는 뜻이었습니다.

수천 개의 독립된 계정에서 각자 실행되는 코드에 설정값을 하드코딩하는 방식은 확장성이 없습니다. Anthropic은 자신들의 일정대로 API를 바꾸고, 이미 배포된 워커에는 TokFresh가 손쓸 방법이 없었습니다.

무엇이 바뀌었나

이제 워커는 고정된 모델 이름이나 헤더를 코드에 담고 배포되지 않습니다. 대신 실행될 때마다 Claude API에 요청을 보내기 직전, TokFresh 서버에 무엇을 써야 하는지 먼저 물어봅니다.

이 변화는 업데이트 방식 전체를 뒤집습니다. 이전에는 API가 바뀌면 TokFresh가 새 코드를 배포하고 사용자가 재배포하는 과정을 매번 반복했습니다. 이제는 설정 엔드포인트 하나만 업데이트하면 모든 워커가 다음 실행 주기에 자동으로 반영합니다. 재배포도, 해야 할 일도 없습니다.

작동 방식

워커는 실제 핑 요청 전에 가벼운 엔드포인트 두 개를 호출합니다.

• /api/config/model은 현재 사용할 모델 이름을 반환합니다
• /api/config/headers는 현재 사용할 API 헤더 세트를 반환합니다

두 응답 모두 워커 내부에서 5분간 캐싱되어, 매 실행마다 왕복이 추가되는 대신 주기적으로만 갱신됩니다. 설정 엔드포인트가 느리거나 잠깐 응답하지 않아도 워커는 하드코딩된 기본값(현재 claude-haiku-4-5-20251001)으로 폴백해 계속 실행됩니다.

이 폴백이 중요합니다. 핵심 기능을 외부 서비스에 온전히 의존하는 워커는 새로운 방식으로 고장 날 수 있습니다. 합리적인 기본값을 내장해두면 설정 서비스의 일시적 문제가 리셋 주기 누락으로 이어지지 않습니다.

현재 라이브 설정은 claude-haiku-4-5-20251001을 가리킵니다. Claude의 사용 주기를 트리거하는 것 외엔 역할이 없는 핑 요청에는 작고 빠른 이 모델로 충분합니다. 헤더 세트에는 현재 claude-code 베타 플래그, oauth-2025-04-20 버전, interleaved thinking, prompt-caching scope가 포함되며, Anthropic API가 OAuth 기반 클라이언트에 기대하는 값과 일치합니다.

달라지는 것

이 변경 이전에 배포하셨다면, 워커는 아직 예전 하드코딩된 로직으로 돌아가고 있습니다. tokfresh.com/setup에서 한 번만 더 재배포하시면 됩니다. 설정 과정과 설정값은 그대로입니다.

그 재배포 한 번이면 끝입니다. 다음에 Anthropic이 헤더를 바꾸거나 모델을 교체해도, 엔드포인트만 업데이트하면 워커는 다음 예약 실행 때 자동으로 맞춰집니다. 이메일도 수동 작업도 필요 없고, 지나간 공지를 놓쳐 리셋 주기가 조용히 실패할 위험도 없습니다.

기술적 세부사항

패턴은 의도적으로 단순합니다. 짧은 캐시로 가져오고, 오류가 나면 안전한 기본값으로 폴백합니다. 재시도도 큐잉도 없고, 설정값 문제가 리셋 실패로 이어질 의존성도 없습니다. 워커의 핵심 역할인 예약된 시간에 Claude를 핑하는 작업은 TokFresh 인프라가 다운돼도 계속 작동합니다.

이 덕분에 점진적 배포도 안전합니다. 재배포하지 않은 워커는 예전 값 그대로 작동하고, 재배포한 워커는 새 fetch-and-fallback 로직을 즉시 적용받습니다. 전환 과정에서 아무것도 깨지지 않고, 조율된 전환 작업도 필요 없습니다.

fetch와 fallback 로직이 어떻게 연결되어 있는지 궁금하시다면, 전체 구현이 TokFresh 저장소에 공개되어 있습니다.