Claude Code와 OpenRouter를 어떻게 붙이나. 개인 개발자의 모델 비용

한 줄로: Claude Code를 OpenRouter에 붙일 수 있는지는 많이 묻는다. 붙은 뒤 청구가 어느 등급의 모델로 가는지는 먼저 계산하는 사람이 드물다. 아래에서는 요청이 기기를 떠난 뒤의 경로와 공식 문서가 요구하는 환경 변수부터 쓰고, 네 등급과 같은 가정 사용량, 구독과 종량을 한자리에 둔 다음, 개인 개발자가 실제로 돌릴 수 있는 손잡이를 마지막에 둔다.

요청이 기기를 떠난 뒤 어디로 가나

Claude Code가 상류에 말하는 프로토콜은 Anthropic Messages API다. OpenRouter는 이 인터페이스와 맞는 입구를 두고, 공식 문서에서는 그것을 Anthropic skin이라고 부른다. 생각 블록과 도구 호출은 그대로 넘어가고, 비용은 OpenRouter 크레딧에 찍힌다. 로컬에 전달 프로세스를 하나 더 띄울 필요는 없다.

기준 주소는 https://openrouter.ai/api이고 끝에 /v1을 붙이지 않는다. 나머지 경로는 Claude Code가 잇는다. /v1이 붙은 주소는, 변수는 다 썼는데 요청이 다른 호스트로 가는 가장 흔한 이유 중 하나다.

호환 범위는 좁다. 공식 문서는 Claude Code를 OpenRouter로 쓸 때 Anthropic 자사 공급자만 보장한다고 적는다. 모델 선택기에는 다른 id가 나올 수 있고, 같은 페이지는 Claude Code가 Anthropic 모델에 맞춰져 있어 다른 공급자에서는 제대로 동작하지 않을 수 있다고 함께 적는다. OpenRouter에 연결하는 일과, 카탈로그에서 가장 싼 id를 기본값으로 조용히 바꾸는 일은 다르다. 싼 단가와, 도구 호출이 끝까지 끝나는 일은 따로 확인한다.

크레딧 구매와 토큰 단가도 다른 장부다. OpenRouter 자신의 Claude Code 설명은 추론에 가산이 없고, 내는 돈은 카탈로그 단가라고 적는다. 크레딧을 살 때 5.5% 수수료가 붙고 최저 $0.80이다. 등급 차이에 비하면 수수료는 작은 쪽이다. 뒤의 표가 그 비율을 보여 준다.

환경 변수는 네 줄, 비워 둔 한 줄은 빼면 안 된다

공식 빠른 시작은 키를 ANTHROPIC_AUTH_TOKEN에 두고, ANTHROPIC_API_KEY를 명시적인 빈 문자열로 두라고 한다. 전자는 Authorization: Bearer로 들어가 게이트웨이가 기대하는 자격이다. 후자는 x-api-key로 들어가고, Claude Code는 그것을 Anthropic 직접 연결 자격으로 본다. 빈 문자열은 그 직접 연결로 되돌아가지 않게 한다. 옛 키만 지우고 =""를 쓰지 않으면, 대화형 세션은 기기에 저장된 로그인을 그대로 쓸 수 있다.

export OPENROUTER_API_KEY="<your-openrouter-api-key>"
export ANTHROPIC_BASE_URL="https://openrouter.ai/api"
export ANTHROPIC_AUTH_TOKEN="$OPENROUTER_API_KEY"
export ANTHROPIC_API_KEY=""

순서가 비기 쉽다. ANTHROPIC_AUTH_TOKEN="$OPENROUTER_API_KEY"는 셸이 그 줄을 읽는 순간 펼쳐진다. 키가 뒤에 있거나, 프로필이 끝난 뒤에 비밀 관리자가 넣으면 토큰은 빈 문자열이 되고 모든 요청이 인증에 실패한다. ~/.zshrc에서는 OPENROUTER_API_KEY를 먼저 정의한다.

예전에 Anthropic 계정으로 Claude Code에 로그인한 적이 있으면 세션에서 /logout을 한 번 실행하고, 종료한 뒤 다시 연다. 공식 설명은 캐시된 로그인과 게이트웨이 자격이 함께 있으면 시작 때 인증 충돌이 난다고 한다. 겉으로 보이는 증상은 모델을 찾지 못하는 경우가 많고, openrouter/auto처럼 OpenRouter에만 있는 id도 포함된다. macOS에서 이 캐시는 키체인 항목 Claude Code-credentials에 있다. 기본 설치가 ~/.claude/.credentials.json을 쓴다는 보장은 없다.

확인은 세션 안의 /status다. 인증 줄은 ANTHROPIC_AUTH_TOKEN, 기준 주소 줄은 https://openrouter.ai/api여야 한다. 인증 줄이 아직 ANTHROPIC_API_KEY이거나 로그인 방식이 Claude 계정이면, 변수는 이 프로세스에 들어오지 않은 것이다. 같은 요청이 OpenRouter Activity에 보여야 한다.

프로젝트 단위로는 저장소의 .claude/settings.local.json에 쓸 수 있다. Claude Code가 읽지 않는 .env에 넣지 말고, 키를 git에 커밋하지도 않는다. 그 파일이 저장소에 들어가면 클론하는 모든 사람에게 크레딧 키를 주는 것과 같다. 한 기기에서만 오래 쓸 때는 셸 설정이 낫고, sk-or-로 시작하는 문자열을 점 파일에 붙이기보다 운영체제 키체인에서 읽는 편이 공식 권장에 가깝다.

연결이 안 되거나, 프로세스가 뜨지 않거나, 메모리가 가득 찬 문제는 이 청구 경로와 다른 고장이다. 설치와 오류는 Claude Code 배포 오류 가이드를 본다.

단가를 가르는 것은 네 등급이다

Claude Code는 작업을 Fable, Opus, Sonnet, Haiku 네 등급으로 나누고 각각 환경 변수를 본다. 서브에이전트는 CLAUDE_CODE_SUBAGENT_MODEL이다. OpenRouter 예시는 이 등급들을 ~anthropic/claude-…-latest로 가리키고, 서브에이전트 예시는 Opus를 가리킨다. 그것은 최신 별칭을 고르는 쓰기이지 개인 예산의 쓰기가 아니다. 별칭은 카탈로그를 따라간다. 오늘의 ~anthropic/claude-opus-latest 가격은 anthropic/claude-opus-5.5와 같다. 내일도 그 id일 필요는 없다.

아래 표는 2026-10-20에 OpenRouter 공개 모델 카탈로그에서 읽은 단가다. 단위는 토큰 100만 개당 미국 달러다. 캐시 읽기는 카탈로그의 cache read 가격이다. 공급자가 실제로 접두 캐시에 맞았을 때만 이 가격이 적용되고, 모든 입력이 할인되는 것은 아니다.

같은 날 카탈로그에서 anthropic/claude-fable-5의 입력과 출력은 5.1과 같은 $10 / $50였지만, 캐시 읽기는 $0.25가 아니라 $1이었다. anthropic/claude-opus-5는 다른 줄이다. 입력 $5, 출력 $25. anthropic/claude-sonnet-5의 입력과 출력은 5.5와 같고, 캐시 읽기는 $0.20으로 5.5의 $0.10보다 두 배다. 이름에 Opus나 Sonnet이 있어도 청구는 같은 수가 아니다. 이 글의 장부로 예산을 지키려면 id를 고정하고 latest만 쓰지 않는다.

export ANTHROPIC_DEFAULT_FABLE_MODEL="anthropic/claude-fable-5.1"
export ANTHROPIC_DEFAULT_OPUS_MODEL="anthropic/claude-opus-5.5"
export ANTHROPIC_DEFAULT_SONNET_MODEL="anthropic/claude-sonnet-5.5"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="anthropic/claude-haiku-5.5"
export CLAUDE_CODE_SUBAGENT_MODEL="anthropic/claude-haiku-5.5"

마지막 줄은 예산 선택이지 공식 예시가 아니다. 공식 예시는 서브에이전트를 Opus에 둔다. 서브에이전트가 주로 파일을 찾고 테스트를 돌리고 요약을 쓰면, 세션과 같은 Opus에 두는 것은 가지마다 $4 / $20로 계산하는 것과 같다. Haiku로 내리기 전에 /model에서 네 등급이 모두 보이는지 확인하고, Activity의 모델 열이 고정한 id인지 본다.

$60을 $0.60으로 나누면 100배다. 카탈로그 비율이지 어떤 세션의 실측이 아니다. 글자가 청구 토큰이 되는 과정은 토큰과 단가 대조에 있다. 이번 주 다른 계열의 사용량과 표시 가격은 OpenRouter 주간 순위에 있다.

같은 가정 사용량에서 등급은 얼마나 벌어지나

아래는 로그에서 꺼낸 「평균적인 하루」가 아니다. 토큰을 고정하고 등급만 바꾸면 카탈로그 가격이 얼마나 달라지는지만 답한다. 어떤 근무일에 입력 800만 토큰, 출력 80만 토큰, 대략 10 대 1이라고 둔다. 에이전트가 문맥을 반복해서 보내고, 실제로 쓰는 글은 그보다 적다는 뜻이다. 이 절에서는 캐시 읽기를 0으로 둔다.

계산은 다시 볼 수 있다. Opus 5.5의 하루는 8 × $4 + 0.8 × $20 = $48이다. 혼합 행은 같은 800만 / 80만을 나눈다. 토큰의 절반이 Haiku면 $0.60, 40%가 Sonnet이면 $9.60, 10%가 Opus면 $4.80, 합은 $15다. 22는 한 달 정도의 근무일이고 할인도 요금제도 아니다.

캐시도 같은 방식으로 가정이라고 적는다. 그 Opus의 하루에 입력의 절반이 캐시 읽기라면 400만 × $4 + 400만 × $0.20 + 출력 $16 = $32.80이고, $48이 아니다. 도구 출력이 바뀌면 접두가 끊기고 다음 턴은 원래 입력 단가로 돌아간다. $32.80은 약속이 아니다.

크레딧 구매 5.5%는 이 표 밖에 있다. $48이면 약 $2.64, $330이면 약 $18이다. 하루 종일 Fable과 혼합 사이의 $2,310 차이를 바꾸지는 못한다. 등급을 먼저 바꾸고, 수수료는 그다음이다.

구독, 직접 연결, OpenRouter는 세 개의 계량기다

2026-10-20 Claude 가격 페이지는 세금 별도이고 요금제는 바뀔 수 있다고 적은 뒤 이렇게 표시하고 있었다. Pro는 월 $20, 연간은 월 $17에 해당한다(한 번에 $200). Max 5x는 월 $100, Max 20x는 월 $200이다. Pro와 Max 모두 Claude Code를 포함하고, 웹·데스크톱·휴대폰의 Claude와 사용량을 공유한다. 도움말 센터의 제한은 5시간 세션 한도에 주간 한도가 더해지는 형태다. Max에는 Fable 주간 한도가 따로 있다. Pro 대비 5배와 20배는 5시간 세션마다의 배수로 적혀 있다.

OpenRouter는 다른 계량기다. 도움말 센터는 ANTHROPIC_API_KEY가 설정되어 있으면 Claude Code가 API로 청구하고, 구독에 포함된 사용량에서는 빼지 않는다고 적는다. OpenRouter로 붙일 때는 /logout도 필요하고, API 키는 비운 채 ANTHROPIC_AUTH_TOKEN을 쓴다. 연결된 뒤의 요청은 첫 건부터 OpenRouter 크레딧을 쓰고, Pro에 남은 사용량을 소모하지 않는다.

고르는 기준은 자신이 어느 벽에 닿아 있는지이지, 게이트웨이가 더 새로운지 여부가 아니다.

• 사용량이 Pro 또는 Max 한도 안에 머물면 구독은 상한 가격이다. $20 또는 $100을 낸 뒤, 그 기간의 추가 세션은 Opus 단가로 계속 쌓이지 않고 한도에 닿는다. 한도로 충분하면 OpenRouter 때문에 종량으로 가를 필요가 없다.
• 매주 한도에 닿고, 닿은 뒤에는 어차피 API 크레딧을 살 것이라면 벽이 Fable인지 Opus인지 먼저 본다. 서브에이전트와 일상적인 수정을 Haiku와 Sonnet으로 옮기는 편이 Max를 한 단계 올리는 것보다 직접적인 경우가 많다. 상위 요금제가 사는 것은 더 많은 구독 사용량이지, 더 낮은 토큰 단가가 아니다.
• 키 하나에 단단한 상한이 필요하고 요청마다 모델 열을 보고 싶다면, OpenRouter 키 한도와 Activity가 구독 사용량 막대가 주지 않는 화면이다. 그 화면의 대가는 카탈로그 단가이고, 크레딧을 살 때 5.5%가 붙는다. Anthropic Console 직접 연결의 토큰 단가가 카탈로그와 같을 때, 이 5.5%가 게이트웨이 자체의 차이고, 대신 받는 것은 장애 전환과 모든 요청을 키 하나로 보는 일이다. 「추론 가산 없음」은 그 층에 대한 말이고, Pro보다 싸다는 뜻은 아니다.

Claude Code와 편집기 안의 도우미가 같은 제품인지는 Claude Code와 Cursor가 비교한다. 그 글은 제품 형태이고, 이 글은 연결한 뒤의 계량기다.

개인 개발자가 먼저 돌리는 다섯 손잡이

첫째, 세션을 하루 종일 Fable이나 Opus에 두지 않는다. 네 개의 변수가 그 손잡이다. 긴 추론은 Fable, 어려운 수정은 Opus, 보통 변경은 Sonnet, 검색과 짧은 완성은 Haiku에 둔다. id를 고정하면 별칭 가격이 바뀌어도 이미 계산한 등급이 조용히 바뀌지 않는다.

둘째, 서브에이전트만 내린다. 공식 예시를 복사하면 서브에이전트는 Opus를 따른다. 부모 세션이 셋을 만들면, 가지마다 Opus로 계산될 때 본문에서 보는 답보다 가지의 토큰이 더 비쌀 수 있다. 개인 예산에서는 CLAUDE_CODE_SUBAGENT_MODEL을 Haiku로 두고, 그 하위 작업 자체가 어려운 추론일 때만 잠깐 올린다.

셋째, /fast는 가산이지 절약이 아니다. 공식 설명은 출력이 최대 약 2.5배 빨라지고, 해당 Opus 일반 단가보다 비싸다고 한다. 대상은 Opus 4.6, 4.7, 4.8, Opus 5뿐이고 Fable은 포함하지 않는다. OpenRouter에서 Claude Code의 /fast가 정말로 speed: "fast"를 붙이려면 Claude Code 2.1.96 이상, CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK=1, 그리고 Opus 변수를 anthropic/claude-opus-5 같은 구체 id에 고정해야 한다. ~anthropic/claude-opus-latest에 고정하면 /fast가 켜졌다고 보여도 요청에 speed가 빠질 수 있다. 표시보다 더 기억할 동작이 있다. 세션이 Fable에 있을 때 /fast를 켜도 Fable이 빨라지지 않는다. Claude Code는 세션을 설정한 Opus로 바꾸고, 이후 요청은 Opus로 청구된다. 속도에 프리미엄을 낼 생각이 없으면 이 스위치를 켜지 않는다.

넷째, 그 키에 한도를 둔다. OpenRouter 키는 따로 상한을 둘 수 있다. 개인이라면 적어도 Claude Code용 키와 실험용 키를 나누고, 월 상한은 태워도 되는 금액으로 쓴다. Activity의 모델 열은 「오늘 다시 Fable로 갔는가」를 잡는 자리다. 공식 예제 저장소의 statusline 스크립트는 이번 세션의 비용과 캐시 할인을 더해 간다. 새로고침마다 생성 기록을 다시 요청하고, 긴 세션은 서서히 따라잡는다. 청구서가 아니다.

다섯째, 길어지는 문맥은 입력 쪽 청구다. 모델 이름 끝의 [1m]은 Claude Code가 가정하는 창만 바꾸어 너무 이른 압축을 피하게 한다. OpenRouter는 라우팅 전에 이 표시를 떼어 낸다. 가정 창이 커지면 넣을 수 있는 접두도 커진다. 압축하고, 저장소 전체를 읽지 않고, 안정된 접두가 캐시에 맞을 자리를 남기는 것이 입력 절약이다. 표의 캐시 읽기는 이미 입력보다 한 자릿수 낮지만, 도구 출력이 접두를 끊지 않았을 때만 적용된다.

모델 요금 옆에는 기기 요금이 있다. 세션을 밤새 켜 두고 컴파일과 시뮬레이터가 같은 Mac의 메모리를 다투어도 그 청구는 OpenRouter에 나오지 않는다. 메모리 배분은 Claude Code 서버 메모리 구성을 본다. 두 장부를 나누어 봐야 토큰 초과를 「기기가 느리다」로 잘못 읽지 않는다.

Anthropic이 아닌 모델을 기본 절약 스위치로 두지 않는다

CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 뒤에 선택기가 나타난다. 공식 문서는 그것을 전체 카탈로그가 아니라 추린 목록이라고 하고, 일부 항목은 Anthropic이 아닌 공급자로 라우팅된다고 적는다. Anthropic 자사를 공급자 우선순위 맨 위에 두라고 하며, 빠른 모드는 그곳에서만 제공된다고 함께 적는다.

실패한 도구 호출은 문맥을 한 바퀴 더 보낸다. 단가가 Opus의 몇십 분의 일이어도 두 번 다시 시도하면 같은 크기로 돌아오고, 변경은 아직 끝나지 않을 수 있다. DeepSeek이나 다른 계열을 코딩에 넣으려면 별도 도구로 측정한다. Claude Code 네 등급 변수의 조용한 대체로 넣지 않는다. 능력 차이와 가격 차이를 함께 보려면 DeepSeek V4 Flash와 Claude Opus가 있다.

자주 묻는 질문

Claude Code를 OpenRouter에 연결할 때 공식이 보장하는 모델은 무엇인가. 공식 문서는 Anthropic 자사만 보장한다고 적는다. 선택기의 다른 모델은 나와도 그 문장 밖이다.

OpenRouter가 토큰 단가에 한 층을 더 얹나. Claude Code 설명은 추론 가산이 없고 단가는 카탈로그라고 한다. 가산은 크레딧을 살 때다. 5.5%, 최저 $0.80.

Pro 구독과 토큰 종량 중 어느 쪽이 싼가. 사용량을 뺀 답은 없다. Pro(월 $20, 또는 연간으로 월 $17)나 Max($100 / $200) 한도 안에 머물면 구독이 상한이다. OpenRouter에 연결한 뒤에는 크레딧으로 가고, 그 포함 사용량은 더 이상 깎이지 않는다. 위의 $48과 $15는 가정 토큰의 카탈로그 계산이지 당신의 청구서가 아니다.

/fast가 돈을 아끼나. 아니다. 더 높은 단가로 더 빠른 출력을 사는 것이고, 일부 Opus만 해당한다. Fable 세션에서 켜면 세션은 Opus 청구로 바뀐다.

키를 ~/.zshrc에 써도 되나. 동작은 하지만 평문이다. 점 파일이 저장소나 클립보드에 들어가면 키가 샌다. 운영체제 키체인에서 읽는 편이 더 단단하다. 새면 OpenRouter 키 페이지에서 폐기한다. 프로젝트 설정은 settings.local.json을 쓰고 커밋하지 않는다.

기준 주소를 바꿨는데 Activity에 요청이 없다. 왜인가. 먼저 /status를 본다. 인증 줄이 ANTHROPIC_AUTH_TOKEN인지, 기준 주소가 /v1 없는 https://openrouter.ai/api인지. 옛 계정 로그인은 /logout으로 지운다. 셸에 남은 ANTHROPIC_API_KEY는 빈 문자열로 써야 하고, 로그아웃만으로는 부족하다.