omniroute claude code free 무료 모델 연결 확인 방법

무료 모델을 연결했는데 요청이 실제로 무료로 처리됐는지 판단하기 어렵다면, 모델 별칭과 공급자 사용량 기록을 따로 봐야 합니다. 이름에 free가 붙었다고 무료는 아닙니다.

앞선 포스트에서 설치한 OmniRoute가 준비되어 있어야 합니다. 범위는 실행 중인 OmniRoute에서 Claude Code 요청의 목적지와 사용량 분류를 확인하는 데까지입니다. 설치와 공급자 계정 생성은 다루지 않습니다.

개요

OmniRoute는 클라이언트가 보낸 모델 이름을 공급자 모델로 연결하는 라우터입니다. Claude Code에 별칭을 넣으면 라우터가 설정에 맞는 공급자와 모델 ID를 고릅니다. 그래서 클라이언트에 보이는 이름과 실제 요청을 받은 모델 이름이 다를 수 있습니다.

무료 여부도 이름만으로는 정해지지 않습니다. 판단 기준은 공급자가 현재 계정에 적용한 요금 조건과 사용량 기록입니다.

체험 크레딧, 기간 한정 무료, 한도 내 무료 구간은 서로 다른 조건입니다. 응답 성공, 목적지 일치, 무료 사용량 분류는 각각 따로 확인해야 합니다. 저라면 라우터 기록에서 최종 모델부터 찾고, 그 요청을 공급자 기록과 대조합니다.

적용 대상

아래 명령은 OmniRoute가 Anthropic Messages 형식 API를 제공하고 Bearer 인증을 받는 경우를 다룹니다. OpenAI 호환 API만 제공하는 배포라면 /v1/messages 요청은 맞지 않습니다.

공급자 API에 직접 붙여 이미 목적을 이뤘다면, 무료 여부 확인만을 위해 라우터를 새로 둘 필요는 없습니다. 이 절차는 OmniRoute를 이미 운영하면서 Claude Code 요청 경로를 구분해야 할 때 맞습니다.

공급자 사용량 페이지를 볼 권한도 있어야 합니다. 권한이 없으면 최종 분류는 미확정으로 남겨 두시면 됩니다.

1. 무료 조건과 모델 목적지 확인

공급자 계정에서 모델의 무료 제공 조건과 한도를 먼저 봅니다. 목록의 free 표시는 무제한 사용이나 모든 계정의 무료 처리를 뜻하지 않습니다. 요청 수, 토큰 양, 동시 요청 제한, 체험 크레딧 적용 여부를 각각 확인합니다.

조건이 확인되지 않으면 테스트 요청은 보류합니다. 출력 길이를 줄여도 요청 자체는 사용량 기록을 남길 수 있습니다.

1.1. 별칭과 공급자 모델 ID 대조

OmniRoute 설정에서 클라이언트 별칭, 선택 공급자, 공급자 모델 ID를 각각 봅니다. 별칭이 free-chat이어도 실제 모델 ID는 공급자가 정한 다른 이름일 수 있습니다. 메뉴 이름은 배포마다 다르니 아래 항목은 설정에 붙여 넣는 값이 아니라 대조 목록입니다. fallback 목적지도 함께 적어 둡니다.

Client model alias: <MODEL_ALIAS>
Selected provider: <PROVIDER_NAME>
Provider model ID: <PROVIDER_MODEL_ID>
Fallback destinations: <REVIEW_EACH_DESTINATION>

Fallback은 첫 목적지 대신 다른 모델로 요청을 보내는 설정입니다. 무료 목적지만 점검하려면 별도 테스트 경로를 쓰거나 대체 목적지를 전부 확인하셔야 합니다. 운영 경로의 fallback을 바꾸면 다른 요청에도 영향이 가므로 임의로 수정하지 않습니다.

2. 라우터 주소와 인증 변수 준비

API 기준 주소와 관리자 화면 주소가 같다고 단정하지 않습니다. 배포 설정에서 API 주소와 경로 접두어를 확인합니다. 아래 예시는 기준 주소 뒤에 /v1을 붙여 요청하는 구성이고, 주소는 문서용 예약 도메인입니다.

export ANTHROPIC_BASE_URL='https://router.example.com'
export ANTHROPIC_MODEL='<MODEL_ALIAS>'
read -rsp 'Router token: ' ANTHROPIC_AUTH_TOKEN
printf '\n'
export ANTHROPIC_AUTH_TOKEN

이 토큰은 라우터가 요구하는 자격 증명입니다. 공급자 비밀 키를 클라이언트에 넣는 절차가 아닙니다. 배포가 x-api-key 헤더를 요구하면 Bearer 예시 대신 라우터 인증 설정에 맞는 헤더로 바꿉니다.

공유 터미널이라면 환경 변수를 덤프하는 진단 자료에 토큰이 섞이지 않게 합니다. 기존 ANTHROPIC_API_KEY나 프로젝트별 설정이 있다면 출처부터 확인합니다. 다른 작업에서 쓰는 값인지 구분한 뒤에 덮어쓰십시오.

3. 로컬 변수와 API 경로 점검

다음 명령은 토큰을 출력하지 않습니다. 토큰은 출력 대상에서 뺐습니다.

printf 'Base URL: %s\nModel alias: %s\n' \
  "$ANTHROPIC_BASE_URL" "$ANTHROPIC_MODEL"

기준 주소와 별칭이 의도한 값이면 변수 지정은 맞습니다. ANTHROPIC_BASE_URL에 이미 /v1이 들어 있으면 아래 요청 경로가 중복됩니다. 프록시가 별도 접두 경로를 요구하면 그 경로도 주소에 포함합니다.

모델 목록 API가 있는 배포라면 목록부터 확인합니다. 없으면 이 단계는 건너뛰시면 됩니다.

curl --fail-with-body --silent --show-error \
  --connect-timeout 10 --max-time 60 \
  "${ANTHROPIC_BASE_URL%/}/v1/models" \
  -H "Authorization: Bearer ${ANTHROPIC_AUTH_TOKEN}" \
  -H 'Accept: application/json'

여기서 JSON 모델 목록이 출력되면 주소와 인증이 맞은 상태입니다. 목록에 별칭이 있어도 실제 요청이 그 모델에 도착했다는 뜻은 아닙니다. HTML이 나오면 관리 화면 주소를 호출했는지 확인합니다. 브라우저에서 관리 화면이 열린다는 사실도 API 인증의 근거가 아닙니다.

4. Claude 형식 요청의 경로 확인

아래 curl은 Claude Code와 별개인 API 요청입니다. 본문의 모델 값은 ANTHROPIC_MODEL과 같은 별칭으로 바꿉니다. max_tokens를 작게 둔 것은 응답 크기 제한일 뿐이고, 무료를 보장하지 않습니다.

curl --fail-with-body --silent --show-error \
  --connect-timeout 10 --max-time 60 \
  "${ANTHROPIC_BASE_URL%/}/v1/messages" \
  -H "Authorization: Bearer ${ANTHROPIC_AUTH_TOKEN}" \
  -H 'anthropic-version: 2023-06-01' \
  -H 'Content-Type: application/json' \
  --data '{"model":"<MODEL_ALIAS>","max_tokens":32,"messages":[{"role":"user","content":"Reply with OK only."}]}'

anthropic-version 값은 배포가 지원하는 형식과 맞아야 합니다. 응답에 텍스트가 있으면 Messages 형식 요청이 처리된 상태입니다. 응답의 model 필드는 별칭을 그대로 보여줄 수도 있으므로, 목적지 확정은 OmniRoute의 최종 전달 기록으로 합니다.

--max-time은 대기 제한이지 응답 시간 측정값이 아닙니다. 제한에 걸렸다고 서버 처리가 취소됐다고 볼 수 없으니, 재요청 전에 라우터 기록을 먼저 봅니다.

5. Claude Code 요청과 기록 대조

curl이 성공했어도 Claude Code가 같은 요청을 보낸 것은 아닙니다. 두 실행은 서로 다른 요청으로 기록합니다. 환경 변수를 설정한 같은 셸에서 실행합니다.

claude --model "$ANTHROPIC_MODEL" -p 'Reply with OK only.'

OK가 담긴 응답이 나오면 클라이언트와 라우터 사이 요청은 처리된 것입니다. 무료 여부는 아직 미정입니다.

실행 뒤 OmniRoute에서 별칭, 최종 공급자, 최종 모델 ID, fallback 적용 여부를 확인합니다. 그다음 공급자 사용량 기록에서 같은 요청의 모델과 과금 분류를 찾습니다. 공통 요청 ID가 없으면 라우터가 남긴 상위 요청 ID와 공급자 요청 ID의 연결 정보를 봅니다.

Client request ID: <CLIENT_REQUEST_ID>
Provider request ID: <PROVIDER_REQUEST_ID>
Request time and timezone: <TEST_TIME_WITH_TIMEZONE>
Final provider model: <PROVIDER_MODEL_ID>
Provider usage classification: <PROVIDER_USAGE_LABEL>

식별 정보가 없으면 요청 시각과 모델을 보조 기준으로 씁니다. 같은 시간대에 요청이 겹쳤다면 어느 기록이 테스트인지 확정하기 어렵습니다. 요청 ID가 맞지 않는 기록을 억지로 짝짓지 않습니다.

5.1. 사용량 반영 지연 처리

공급자 기록은 반영까지 시간이 걸릴 수 있습니다. 계정 합계가 그대로라는 이유만으로 무료로 확정하지 않습니다. 기록이 안 보이면 집계 주기를 확인하고 판정을 미확정으로 둡니다. 집계 주기는 공급자 문서나 사용량 페이지 안내에서 확인합니다. 체험 크레딧 차감은 무료 구간과 구분합니다.

6. 결과 판정 범위

최종 모델이 설정한 목적지와 같고, 공급자 기록이 그 요청을 무료 사용량으로 분류했을 때만 해당 계정과 시점의 무료 경로가 확인된 것입니다. 다른 모델이나 계정에 같은 조건이 적용된다는 뜻은 아닙니다. 기록이 어긋나면 별칭 매핑과 fallback 목적지부터 다시 봅니다.

합계가 0으로 표시돼도 크레딧 사용이나 집계 지연이 없는지 분류 항목을 확인해야 합니다. 이 절차는 짧은 텍스트 요청까지만 다룹니다. 도구 호출, 긴 문맥, 스트리밍, 재시도는 별도 테스트와 기록 대조가 필요합니다.

6.1. 판정 상태 기록

판정 결과는 네 가지 상태 중 하나로 기록합니다.

• 확인됨: 라우터 최종 모델과 공급자 무료 분류가 같은 요청에서 일치한 상태.
• 미확정: 공급자 기록이 비었거나 아직 반영 전인 상태.
• 불일치: 최종 모델이 설정 목적지와 다르거나 fallback이 적용된 상태.
• 크레딧 차감: 합계는 0이어도 체험 크레딧에서 빠져나간 상태.

제 기준으로는 미확정을 확인됨으로 바꾸기 전에 공급자 기록 한 줄이 반드시 있어야 합니다.

확인

Claude Code 요청을 한 번 더 보냅니다.

claude --model "$ANTHROPIC_MODEL" -p 'Reply with OK only.'

텍스트 응답이 나오고, OmniRoute 기록의 최종 모델과 공급자 기록의 무료 분류가 같은 요청으로 대조되면 해당 요청의 무료 연결 확인이 끝난 것입니다.