OpenRouter란 무엇인가요? 왜 Claude Code의 모델을 교체할 수 있나요?
Claude Code는 Anthropic이 출시한 AI 프로그래밍 도우미로, 스스로 파일을 읽고 쓰며, 터미널 명령을 실행하고, 사용자를 대신해 코드를 작성하고 디버깅할 수 있습니다. 이 도구의 설계는 두 단계로 나뉩니다:
- 프레임워크 계층: 자율 의사결정 루프, 도구 호출, 파일 조작, 터미널 제어. 이 모든 것이 Claude Code 자체의 기능입니다.
- 모델 레이어: 배후에서 사고를 담당하는 언어 모델. Claude Code 공식 문서, Pro, Max 및 API 사용자는 현재 기본적으로 Claude Opus 5.5를 사용합니다.
두 계층은 표준 API를 통해 통신하며, API 주소를 호환되는 다른 서비스로 지정하기만 하면 프레임워크는 평소와 같이 작동하고, 그 배후의 모델은 교체할 수 있습니다.OpenRouter 바로 이런 서비스입니다. 하나의 API 키로 수백 개의 서로 다른 공급업체의 모델에 접속할 수 있으며, 여기에는 ‘free’로 표시된 무료 모델도 포함됩니다. OpenRouter에도공식 Claude Code 연동 가이드, 이 문서의 설정 단계는 이 문서를 기준으로 합니다.
비용 측면에서, Claude 공식의 Pro 요금제는 월 20달러, Max 요금제는 월 100달러부터 시작합니다(Claude 공식 가격 페이지), 반면 무료 버전에는 Claude Code가 포함되어 있지 않습니다. OpenRouter로 전환하면 실제 사용량에 따라 요금을 지불하면 되며, 무료 모델을 선택하면 비용 부담 없이 체험해 볼 수 있습니다.
홍콩 사용자가 먼저 알아야 할 지역 제한 사항
설정을 시작하기 전에, 홍콩 독자들은 다음 세 가지를 먼저 알아두어야 합니다:
- Anthropic 공식지원 지역 목록홍콩과 마카오는 포함되지 않습니다.
- OpenRouter 이용 약관일부 모델 공급업체는 특정 국가나 지역에 거주하는 사용자의 모델 사용을 허용하지 않으며, 공급업체는 언제든지 제한 대상 모델 목록을 조정할 수 있음을 명시하고 있습니다. 즉, OpenRouter를 통해 Claude 시리즈 모델을 호출하는 경우에도 Anthropic의 지역 정책이 적용되므로, 요청이 거부되거나 공급업체의 이용 약관을 위반할 가능성이 있습니다.
- Anthropic의 지역별 지원 페이지에서는 Claude Code 자체를 지역 정책의 적용을 받는 제품으로 분류하고 있으며,공식 법률 페이지또한 어떤 플랫폼을 통해 사용하든 Claude Code는 Anthropic의 표준 약관의 적용을 받는다고 명시되어 있습니다. 모델만 변경하고 Claude 모델을 사용하지 않더라도, 홍콩에서 Claude Code 소프트웨어를 실행하는 것은 약관상 공식적으로 지원되는 사용 방식에 해당하지 않습니다.
따라서 본문에서 시연하는 방법은 Claude Code 프레임워크를 OpenRouter의 Anthropic 모델이 아닌 모델(무료 또는 저비용)과 함께 사용하는 것입니다. 홍콩 사용자의 경우, 이 방법은 회색지대에 속하므로 위험은 사용자가 스스로 감수해야 하며, 본문에서는 지역 제한을 우회하는 방법을 가르치지 않습니다. 지역 정책에 대한 전체 내용과 홍콩 사용자를 위한 다른 선택지는 다음을 참조하시기 바랍니다. Claude Code 홍콩 사용 안내서. 각 플랫폼의 이용약관은 수시로 변경될 수 있으므로, 이용 전에 최신 버전을 직접 확인하시기 바라며, 공식 발표 내용을 기준으로 합니다.
OpenRouter에 Claude Code 연결 설정 방법
전체 설정에는 환경 변수 세 개만 필요하며, 별도의 프록시 프로그램을 설치할 필요가 없습니다. 다음 단계는 macOS 및 Linux에 적용되며, Windows 사용자는 WSL 또는 PowerShell 버전의 설치 명령어를 사용할 수 있습니다.
1~3단계: 가입, API 키 발급, Claude Code 설치
- OpenRouter 등록: 이동하기 openrouter.ai, 화면의 안내에 따라 계정을 생성하세요. 가입은 무료입니다.
- API 키 생성: 로그인 후 계정 설정의 ‘Keys’ 페이지(openrouter.ai/settings/keys)로 이동하여 ‘Create Key’를 클릭한 다음, sk-or-로 시작하는 키를 복사합니다. 이 키는 한 번만 전체가 표시되므로 안전하게 보관하고, GitHub에 업로드하거나 다른 사람에게 공유하지 마십시오.
- Claude Code 설치: 터미널을 열고 공식 기본 설치 명령어를 입력합니다(Windows PowerShell 명령어는 OpenRouter 공식 가이드를 참조하세요).
curl -fsSL https://claude.ai/install.sh | bash
아래 동영상은 MB가 이전에 촬영한 설정 시연 영상으로, 일부 인터페이스와 단계(예: Antigravity)가 본문의 최신 단계와 다릅니다. 실제 설정 시에는 본문을 기준으로 해 주시기 바랍니다.
4~6단계: 환경 변수 설정, 기존 계정 로그아웃, 연결 확인
- 환경 변수 설정: 다음 네 줄을 ~/.zshrc 파일(bash를 사용하는 경우 ~/.bashrc)에 추가하고, 따옴표 안의 내용을 본인의 OpenRouter API 키로 변경하십시오.
export OPENROUTER_API_KEY="사용자의 OpenRouter API 키"
export ANTHROPIC_BASE_URL="https://openrouter.ai/api"
export ANTHROPIC_AUTH_TOKEN="$OPENROUTER_API_KEY"
export ANTHROPIC_API_KEY=""
- 다시 로드하고 기존 계정에서 로그아웃하기: 저장 후 `source ~/.zshrc`를 입력하거나, 새 터미널을 직접 실행하세요. 이전에 Claude 계정으로 Claude Code에 로그인한 적이 있다면, 프로그램을 실행한 후 먼저 `/logout`을 입력한 다음 claude를 종료하고 다시 시작해야 합니다. 그렇지 않으면 프로그램이 계속해서 기존 로그인 정보를 사용하게 됩니다.
- 연결 확인: 프로젝트 폴더에서 claude를 입력하여 실행한 후, /status를 입력합니다. 화면에 Auth token이 ANTHROPIC_AUTH_TOKEN이고, Anthropic base URL이 https://openrouter.ai/api로 표시되면 OpenRouter에 성공적으로 연결된 것입니다.
설정 시 가장 흔히 발생하는 세 가지 실수:
- ANTHROPIC_API_KEY는 반드시 빈 값(따옴표 사이에 내용이 없는 상태)으로 명시적으로 설정해야 하며, 단순히 삭제해서는 안 됩니다. 그렇지 않으면 Claude Code가 Anthropic 계정으로 인증을 시도할 수 있습니다.
- OPENROUTER_API_KEY는 반드시 ANTHROPIC_AUTH_TOKEN 줄보다 앞에 작성해야 합니다. 공식 문서에 따르면, 순서를 바꾸면 토큰이 공백으로 변해 모든 요청에서 인증 오류가 발생한다고 합니다.
- 설정을 .env 파일에 작성하지 마세요. Claude Code는 이 파일을 읽지 않습니다. 단일 프로젝트에서만 사용하려는 경우, 프로젝트 루트 디렉터리에 .claude/settings.local.json 파일을 생성하고 env 블록에 동일한 값을 입력하면 됩니다.
설정이 완료되면, 먼저 무료 모델로 간단한 질문을 한 다음, OpenRouter의 Activity 페이지에서 요청이 기록되었는지 확인한 후에야 실제 프로젝트 처리를 시작하십시오.
VS Code에서 사용하고 싶으신가요?
Claude Code에는 공식 VS Code 확장 프로그램이 있으며, Cursor 등 VS Code를 기반으로 한 편집기에서도 확장 프로그램 마켓을 통해 설치할 수 있습니다. 클릭공식 VS Code 문서, OpenRouter와 같은 타사 서비스를 사용할 때는:
- 위의 환경 변수를 ~/.claude/settings.json 파일의 env 블록에 입력하여, 확장 프로그램과 터미널 버전이 동일한 설정을 공유하도록 합니다.
- VS Code 설정에서 ‘Disable Login Prompt’를 선택하면 Anthropic 계정 로그인 화면을 건너뛸 수 있습니다.
확장 프로그램을 설치할 수 없는 경우, 편집기의 내장 터미널에서 직접 'claude'를 입력해도 동일한 효과를 얻을 수 있습니다.
모델을 어떻게 전환하나요?
OpenRouter를 연결한 후에도 Claude Code 내부에서는 여전히 opus, sonnet, haiku라는 세 가지 ‘모델 위치’를 사용하여 작업을 할당합니다. 환경 변수를 통해 각 위치에 실제로 어떤 OpenRouter 모델을 사용할지 지정할 수 있습니다:
export ANTHROPIC_DEFAULT_OPUS_MODEL="nvidia/nemotron-3-super-120b-a12b:free"
export ANTHROPIC_DEFAULT_SONNET_MODEL="cohere/north-mini-code:free"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="openrouter/free"
- 모델 ID 복사: OpenRouter 모델 페이지에서 전체 ID를 복사하세요. 무료 모델의 ID는 :free로 끝납니다.
- 설정 입력: 위의 세 변수에 ID를 입력하고, 파일을 저장한 후 터미널을 다시 불러오세요.
- 언제든지 전환: Claude Code 내에서 /model을 입력하여 메뉴를 열거나, /model 뒤에 모델 이름을 입력하여 즉시 전환할 수 있습니다. 실행 시 claude –model을 사용하여 해당 세션에서 사용할 모델을 지정할 수도 있습니다.
- 모델 메뉴 열기: export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1을 추가하면, /model 메뉴에 OpenRouter에 있는 모델들이 표시됩니다.
주의: 구버전 튜토리얼에서 유포된 “/model openrouter, 모델명” 형식은 다른 타사 도구인 Claude Code Router의 형식이며, OpenRouter에 직접 적용할 경우 오류가 발생하므로 그대로 입력하면 안 됩니다.
Claude 공식 계정으로 다시 전환하려면, 앞서 설정한 환경 변수를 삭제하고 터미널을 다시 시작한 다음, /login 명령어를 사용하여 로그인하면 됩니다.
현재 이용 가능한 무료 모델 (2026년 10월 6일 업데이트)
OpenRouter의 무료 모델 목록은 빠르게 변동됩니다. 2026년 상반기까지만 해도 여전히 추천받던 DeepSeek 무료 버전은 현재 무료 목록에서 제외되었으며, DeepSeek 시리즈는 유료 버전만 남아 있습니다. 다음 목록은 2026년 10월 6일 OpenRouter 공식 모델 API에서 가져온 것으로, 도구 호출(Claude Code 필수)을 지원하는 모델만 나열했습니다:
| 모델 ID | 특징 | 적합한 용도 |
|---|---|---|
| openrouter/free | 공식 무료 라우터로, 요청된 기능(예: 도구 호출)에 따라 자동으로 무료 모델을 하나 선택합니다. | 초보자가 처음 테스트해 볼 때, 직접 모델을 선택할 필요가 없습니다. |
| cohere/north-mini-code:free | Cohere의 첫 번째 에이전트 프로그래밍 모델, 256K 컨텍스트 | 프로그래밍, 버그 수정 |
| nvidia/nemotron-3-super-120b-a12b:free | 1,200억 개의 파라미터, 공식적으로 다중 에이전트 애플리케이션으로 분류됨 | 다소 복잡한 다단계 작업 |
| google/gemma-4-31b-it:free | Google DeepMind의 오픈소스 모델로, 함수 호출 및 이미지 입력을 지원하며, 256K 컨텍스트를 갖습니다. | 일반 프로그래밍 및 워드 프로세싱 |
| poolside/laguna-s-2.1:free | 프로그래밍 모델이지만, OpenRouter는 2026년 10월 31일에 단종될 예정이라고 명시하고 있습니다. | 단기 체험용으로만 적합합니다 |
무료 모델 목록은 몇 주마다 변경되므로, 이용하기 전에 OpenRouter 무료 모델 페이지 모델이 여전히 목록에 있는지 확인하십시오. 특정 모델에서 갑자기 오류가 발생하면, 가장 간단한 방법은 openrouter/free로 변경하여 라우터가 대신 선택하도록 하는 것입니다.
OpenRouter의 이용 약관에도 명시되어 있듯이, 일부 공급업체는 특정 지역에서 서비스를 제공하지 않으므로, 모델 페이지에 표시된 목록이 위 표와 다를 수 있으며, 귀하의 계정에 실제로 표시되는 내용을 기준으로 합니다.
무료 한도는 얼마인가요? 일일 사용량 제한
按 OpenRouter 공식 제한 사항 문서, :free로 끝나는 모든 모델은 다음 상한에 제약을 받습니다:
| 계정 상태 | 분당 요청 제한 | 일일 요청 한도 |
|---|---|---|
| 누적 구매량이 10 크레딧 미만인 경우 | 20회 | 50회 |
| 크레딧을 총 10개 이상 구매한 경우 | 20회 | 1,000회 |
주의해야 할 몇 가지 사항:
- 일일 한도는 각 모델별로 계산되는 것이 아니라 전체 계정을 기준으로 계산되며, UTC 기준 자정(홍콩 시간 오전 8시)에 초기화됩니다.
- 누적 구매한 크레딧이 10개 이상이라면, 이후 잔액이 소진되더라도 일일 1,000회 이용 한도는 그대로 유지됩니다. 무료 모델을 사용할 때는 이 잔액이 차감되지 않습니다.
- Claude Code에서 한 가지 작업을 완료하려면 대개 여러 번의 요청을 연속으로 보내야 합니다(파일 읽기, 파일 수정, 명령어 실행이 각각 한 번씩 계산됨). 따라서 일일 50회 한도는 금방 소진됩니다. 자주 사용할 계획이라면, 미리 10달러를 충전해 두는 것이 훨씬 실용적입니다.
용도에 따라 어떤 모델을 선택해야 할까요?
- 학습 및 체험: openrouter/free 또는 위 표에 나와 있는 무료 모델을 활용하여, 비용 부담 없이 Claude Code의 작동 방식을 알아보세요.
- 개인 프로젝트: OpenRouter의 저가 유료 모델(예: deepseek/deepseek-v4-flash, z-ai/glm-5.3-flash, minimax/minimax-m3, qwen/qwen3-coder-next)을 고려해 보세요. 2026년 10월 6일 기준 공식 목록에 따르면, 주요 공급업체에서 제공하는 이 모델들의 입력 가격은 대부분 토큰 100만 개당 약 0.1~0.3달러이며, 모델 페이지에 실시간으로 표시되는 내용을 기준으로 합니다.
- 전문 개발: 코드 품질이 수익에 직접적인 영향을 미친다면, 오류 수정 데는 드는 시간이 도구 비용보다 더 비쌀 수 있으므로, 공식 Claude 솔루션이나 Claude 네이티브 모델이 여전히 더 안정적인 선택입니다. 참고로, OpenRouter에서 Claude Sonnet 5.5의 가격은 입력 토큰 100만 개당 2달러, 출력 10달러이지만, OpenRouter를 통해 Claude 모델을 호출하는 경우에도 Anthropic의 지원 지역 정책에 구속되며, 홍콩은 지원 지역에 포함되지 않습니다.
- 혼합 구성: 심도 있는 처리가 필요한 opus 및 sonnet 포지션을 성능이 더 뛰어난 모델로 설정하고, 간단한 작업을 처리하는 haiku 포지션을 openrouter/free로 설정하면 품질과 비용 간의 균형을 맞출 수 있습니다.
설정을 마친 후, AI 비서가 더 많은 일상 업무를 처리하도록 하고 싶다면 다음을 참고하세요. Openclaw 랍스터 AI 초보자 가이드。
무료 이용 시 고려해야 할 네 가지 장단점
무비용 방식은 확실히 가능하지만, 그 이면에 따르는 대가를 분명히 인식해야 합니다:
- 성능 차이: 무료 모델로 생성된 코드의 오류율은 일반적으로 높은 편입니다. OpenRouter 공식 문서에서도 Claude Code는 Anthropic 모델에 최적화되어 있어, 다른 모델과 함께 사용할 경우 비정상적인 현상이 발생할 수 있다고 경고하고 있습니다. 학생이나 아마추어 개발자에게는 큰 영향이 없겠지만, 시간당 요금을 받는 경우 수정하는 데 소요되는 추가 시간은 숨겨진 비용이 됩니다.
- 도구 호출의 불안정성: Claude Code는 모델이 고정된 형식으로 도구를 호출하는 방식에 의존합니다. 일부 대체 모델의 경우 가끔 형식 오류가 발생하여 작업이 실패하고 재시도해야 하는 경우가 있습니다. 단일 단계 작업에는 큰 영향이 없지만, 여러 단계로 이어지는 작업의 경우 중단될 가능성이 더 높습니다.
- 사용량 및 속도 제한: 무료 모델은 일일 사용 횟수에 제한이 있으며, 이용이 집중되는 시간대에는 대기열이 발생하거나 일시적으로 사용할 수 없을 수 있습니다. 또한 목록은 수시로 변경되므로, 지난주에 사용 가능했던 모델이 이번 주에는 서비스가 중단되었을 수도 있습니다.
- 데이터가 제3자를 거침: 사용자의 코드는 OpenRouter를 통해 모델 제공업체로 전송됩니다. OpenRouter에 따르면, 계정 설정에서 기록 기능을 직접 활성화하지 않는 한 사용자의 프롬프트 내용은 기록되지 않습니다. 다만 일부 무료 모델 제공업체는 입력 내용을 모델 훈련에 사용할 수 있으며, OpenRouter의 개인정보 보호 설정은 무료 모델과 유료 모델을 별도로 관리합니다. 개인 프로젝트의 경우 큰 문제가 되지 않지만, 회사의 독점 코드나 민감한 데이터는 무료 모델을 통해 처리하지 않는 것이 좋습니다.
또 다른 유용한 팁: 누르면 Claude Code 공식 데이터 문서, Claude Code의 웹 페이지 캡처 기능(WebFetch)은 URL을 캡처하기 전에 먼저 도메인 이름을 api.anthropic.com으로 전송하여 보안 검사를 수행하며, 이 단계는 어떤 모델 공급자를 사용하든 상관없이 실행됩니다. 네트워크에서 해당 도메인에 연결할 수 없는 경우, 웹 페이지 가져오기가 실패하게 됩니다. 공식에서 제공하는 해결 방법은 settings.json에 skipWebFetchPreflight: true를 추가하는 것이지만, 이렇게 하면 보안 블랙리스트 검사도 함께 비활성화됩니다.
AI 에이전트가 암호화폐 시장과 어떻게 결합되는지 더 자세히 알고 싶다면 다음을 읽어보시기 바랍니다. AI 에이전트 경제에 대한 종합 분석。
자주 묻는 질문
OpenRouter는 정말 무료로 사용할 수 있나요?
네. :free로 끝나는 모델은 무료이며, 계정 잔액이 없어도 사용할 수 있지만 일일 요청 횟수는 50회로 제한됩니다. 크레딧을 총 10개 구매하면 일일 요청 횟수 한도가 1,000회로 늘어납니다. 유료 모델의 경우 실제 토큰 사용량에 따라 요금이 부과됩니다.
홍콩에서도 OpenRouter를 통해 Claude Code에 접속할 수 있나요?
기술적으로 설정 단계는 다른 지역과 동일합니다. 하지만 Anthropic의 공식 지원 지역에는 홍콩이 포함되지 않으며, OpenRouter 이용 약관에도 일부 공급업체가 특정 지역의 사용자를 제한한다고 명시되어 있으므로, OpenRouter를 통해 Claude 시리즈 모델을 호출할 경우 거부되거나 약관을 위반할 가능성이 있습니다. Anthropic 모델이 아닌 다른 모델로 변경하더라도, Anthropic 지원 지역 페이지에는 Claude Code 소프트웨어 자체가 지역 정책 적용 범위에 포함되어 있으므로, 홍콩에서 이와 같이 사용하는 것은 회색지대에 속하며, 이에 따른 위험은 사용자가 스스로 부담해야 합니다. 사용 전 각 플랫폼의 최신 이용 약관을 직접 확인하시기 바랍니다.
왜 기본 설정대로 DeepSeek 무료 모델을 훈련시키면 실패할까요?
DeepSeek의 무료 버전이 더 이상 OpenRouter 무료 목록에 포함되어 있지 않기 때문에, 기존 튜토리얼에 사용된 모델 ID는 더 이상 유효하지 않습니다. 또한, “/model openrouter,모델명”은 Claude Code Router의 표기 방식이며, OpenRouter에 직접 연결할 때는 전체 모델 ID를 사용하거나 ANTHROPIC_DEFAULT_SONNET_MODEL 등의 환경 변수를 통해 지정해야 합니다.
모델을 전환하면 대화 기록이 사라지나요?
아닙니다. Claude Code는 대화 기록을 컴퓨터의 ~/.claude/projects/ 폴더에 일반 텍스트 형식으로 저장하며, 기본적으로 30일간 보관됩니다. 이는 어떤 모델을 사용하느냐와 무관합니다.
/status를 입력해도 여전히 Claude 계정이 표시되는데, 어떻게 해야 하나요?
환경 변수가 Claude Code로 전달되지 않았음을 의미합니다. 먼저 ANTHROPIC_API_KEY가 빈 값으로 설정되어 있는지 확인한 후, 터미널을 다시 로드하고 Claude Code 내에서 /logout을 입력한 뒤, 종료한 후 다시 시작하세요. macOS를 사용 중인데도 문제가 지속된다면, 이전 로그인 정보가 키 체인에 남아 있을 수 있습니다. 공식 문서에서 이를 삭제하는 방법을 안내하고 있습니다.
다음 단계
먼저 openrouter/free를 사용해 간단한 프로젝트를 진행해 보고, AI 프로그래밍 도우미가 실제로 여러분의 업무 효율을 높여주는지 확인한 후, 충전하거나 유료 모델로 업그레이드할지 결정하는 것이 좋습니다. 여러분에게 가장 적합한 도구는 반드시 가장 비싼 것도, 가장 저렴한 것도 아닌, 현재 직면한 문제를 가장 잘 해결해 주는 도구입니다.
무료 모델 목록은 몇 주마다 변경되며, MB는 이 글을 정기적으로 업데이트할 예정입니다. 현재 이용 가능한 최신 모델과 설정 팁을 알고 싶으시다면, 저희 커뮤니티에 참여하여 소통하시거나 다음 글을 읽어보시기 바랍니다. GPT Image 2.5 완전 해설, 또 다른 인기 있는 AI 도구의 사용법을 알아보세요.
웹사이트 면책 조항
이 기사의 내용은 참고 용일 뿐이며, 투자자는 독립적 인 판단을하고 자신의 책임하에 신중하게 투자해야하며,이 기사의 내용을 바탕으로 시청자에게 거래 또는 투자를 설득하거나 설득하려고 시도하지 않으며 공유 목적으로 만 제공되며 투자 조언으로 간주되어서는 안되며 몬스터 블록 크의 관점과 입장, 시간 제한 판단 특정 날짜의 모든 정보 및 견해를 나타내지 않습니다. 또한 본 웹사이트에 아직 홍콩에서 가상자산 거래 플랫폼 운영 라이선스를 취득하지 않은 가상자산 거래 플랫폼과 관련된 텍스트 소개, 사진, 프로모션, 이벤트 등의 콘텐츠가 포함되어 있는 경우 홍콩 특별행정구 외의 사용자에게만 제공됩니다.
홍콩의 자금 세탁 및 테러 자금 조달 방지(개정) 조례 2022에 따르면 2023년 6월 1일 이후 홍콩에서 운영되거나 홍콩 투자자에게 서비스를 적극적으로 홍보하는 모든 중앙집중식 가상자산 거래 플랫폼은 SFC의 허가를 받고 규제를 받게 되며, 관련 무허가 활동은 형사 범죄에 해당됩니다. 법률에 대한 자세한 정보와 세부 사항은 SFC 웹사이트를 참조하시기 바랍니다.