이 문서는 NVIDIA에서 무료로 제공하는 AI 모델 API를 이용해서, 터미널에서 쓰는 AI 코딩 도구인 Claude Code를 비용 없이 사용하는 방법을 설명합니다. 컴퓨터에 익숙하지 않은 분도 순서대로 따라 할 수 있도록 작성했습니다.
- 모델 추천 (먼저 읽고 자신에게 맞는 모델을 골라두세요)
NVIDIA NIM에는 수십 가지 모델이 있는데, 일반 사무 업무 기준으로 추천하는 모델은 다음과 같습니다.
한국어 업무가 많은 경우 (문서 요약, 이메일, 번역 등) 기본 모델: nvidia_nim/z-ai/glm-5.1 이유: 한국어와 중국어 등 다국어에 특히 강하고, 한국어 문서 작성이 자연스럽습니다.
영어 업무가 많은 경우 기본 모델: nvidia_nim/minimax/minimax-m2.7 이유: 230B 파라미터 대형 모델로, 문서 작성, 요약, 번역 전반에 걸쳐 균형 잡힌 성능을 냅니다.
중요한 문서나 복잡한 작업용 (느려도 괜찮으니 품질이 중요할 때) nvidia_nim/mistralai/mistral-large-3-675b 이유: 675B 초대형 모델로 품질이 높지만 응답이 다소 느릴 수 있습니다.
한국어 업무 위주라면 glm-5.1을 Default로, 영어 업무 위주라면 minimax-m2.7을 Default로 설정하는 것을 권장합니다.
- 사전 준비
이 설정을 진행하기 전에 아래 두 가지가 설치되어 있어야 합니다.
Claude Code (터미널에서 claude 명령어가 작동하는 상태)
uv (Python 패키지 실행 도구)
uv가 설치되어 있지 않다면 터미널에서 아래 명령어를 실행합니다.
Mac / Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh
설치 후 터미널을 새로 열거나 아래 명령어로 적용합니다.
source ~/.zshrc
- NVIDIA API 키 발급
NVIDIA NIM은 무료 개발자 계정을 만들면 API 키를 발급해줍니다. 신용카드 없이 가입할 수 있습니다.
1. build.nvidia.com 에 접속합니다.
2. 우측 상단에서 무료로 회원가입합니다.
3. 로그인 후 우측 상단 프로필 아이콘 클릭 후 API Keys 메뉴로 이동합니다.
4. Create API Key 버튼을 클릭합니다.
5. 이름을 입력하고 (예: my-key), 만료일을 Never로 설정합니다.
6. 생성된 키를 바로 복사해 둡니다. 이 키는 한 번만 표시되므로 반드시 복사해서 저장해두세요.
키 형식은 nvapi-로 시작하며 총 56자 정도입니다. 앞뒤를 잘리지 않게 전체를 복사해야 합니다.
- 프록시 설치 및 설정
Claude Code는 Anthropic API 형식으로 통신하고, NVIDIA NIM은 OpenAI 호환 형식을 씁니다. 이 둘을 이어주는 중간 서버(프록시)를 로컬에 설치합니다.
4-1. 저장소 다운로드
터미널에서 아래 명령어를 실행합니다.
git clone https://github.com/Alishahryar1/free-claude-code.git
cd free-claude-code
4-2. 설정 파일 생성
cp .env.example .env
4-3. 설정 파일 열기
nano .env
4-4. 설정 파일 내용 입력
파일을 열면 여러 항목이 있습니다. 아래 세 가지 항목을 찾아서 본인 값으로 채웁니다.
NVIDIA_NIM_API_KEY="nvapi-여기에_본인_키_전체_붙여넣기"
MODEL="nvidia_nim/z-ai/glm-5.1"
ANTHROPIC_AUTH_TOKEN="freecc"
MODEL 값은 1번 항목에서 본인에게 맞는 모델로 바꿔서 넣으세요. ANTHROPIC_AUTH_TOKEN은 로컬 인증용 임의 값이라 아무 문자열이나 넣어도 됩니다.
저장하고 닫기: Ctrl+O 누르고 Enter, 그 다음 Ctrl+X
- 프록시 서버 실행
아래 명령어로 서버를 시작합니다.
uv run server.py
아래와 같은 메시지가 뜨면 정상입니다.
INFO: Uvicorn running on http://0.0.0.0:8082 (Press CTRL+C to quit)
이 터미널 창은 Claude Code를 쓰는 동안 계속 켜두어야 합니다. 닫으면 프록시가 꺼집니다.
- Claude Code 연결
프록시가 실행 중인 상태에서 터미널 탭을 하나 더 열고, 아래 명령어를 순서대로 입력합니다.
export ANTHROPIC_AUTH_TOKEN="freecc"
export ANTHROPIC_BASE_URL="http://localhost:8082"
claude
ANTHROPIC_AUTH_TOKEN 값은 .env 파일에서 설정한 값과 동일하게 맞춰야 합니다.
Claude Code가 열리면, 안에서 /status 명령어를 입력해 아래 항목을 확인합니다.
Anthropic base URL: http://localhost:8082
이렇게 표시되면 연결 성공입니다. 프록시 터미널에도 아래와 같은 로그가 찍혀야 합니다.
POST /v1/messages HTTP/1.1 200 OK
- 모델 변경 방법 (Admin UI)
브라우저에서 아래 주소로 접속합니다.
http://127.0.0.1:8082/admin
왼쪽 메뉴에서 Model Config를 클릭하면 모델 라우팅 설정 화면이 나옵니다.
Default Model: 모든 요청의 기본 모델
Opus Override: 복잡하고 중요한 작업 요청
Sonnet Override: 일반 작업 요청
Haiku Override: 빠른 단순 작업 요청
각 칸에 nvidia_nim/모델이름 형식으로 넣으면 됩니다.
예시 설정 (한국어 업무 위주): Default Model: nvidia_nim/z-ai/glm-5.1 Opus Override: nvidia_nim/mistralai/mistral-large-3-675b Haiku Override: nvidia_nim/minimax/minimax-m2.7
- 매번 사용할 때 순서
Claude Code를 쓸 때마다 아래 순서로 진행합니다.
1. 터미널 1에서 free-claude-code 폴더로 이동 후 프록시 실행
cd free-claude-code
uv run server.py
2. 터미널 2(새 탭)에서 환경변수 설정 후 Claude Code 실행
export ANTHROPIC_AUTH_TOKEN="freecc"
export ANTHROPIC_BASE_URL="http://localhost:8082"
claude
매번 export를 입력하는 게 번거로우면 ~/.zshrc 파일에 아래 두 줄을 추가해두면 터미널을 새로 열 때마다 자동으로 적용됩니다.
export ANTHROPIC_AUTH_TOKEN="freecc"
export ANTHROPIC_BASE_URL="http://localhost:8082"
- 알아두어야 할 것들
무료 제한: NVIDIA NIM 무료 티어는 분당 40 요청까지 가능합니다. 너무 빠르게 연속으로 요청하면 429 오류가 납니다. 잠시 기다리면 해결됩니다.
모델 변경 가능 여부: build.nvidia.com/models 에서 현재 사용 가능한 전체 모델 목록을 확인할 수 있습니다. 모델 클릭 후 View Code를 누르면 정확한 모델 ID를 알 수 있습니다.
Claude Code가 자기소개를 Claude Opus라고 하는 이유: Claude Code가 NIM 모델에게 "당신은 Claude입니다"라는 시스템 프롬프트를 보내기 때문에, 실제로 어떤 모델이 응답하든 Claude라고 대답합니다. 이는 정상 동작이며 실제 응답은 NIM 모델이 하고 있습니다.
보안 주의: 코드나 대화 내용이 NVIDIA NIM 서버로 전달되므로, 민감한 개인정보나 회사 기밀이 포함된 내용은 주의해서 사용하세요.
- 오류 해결
오류: Required uv version >= 0.11.0 does not match the running version
원인: uv 버전이 낮습니다.
해결:
uv self update
위 명령어가 안 되면 아래로 재설치합니다.
curl -LsSf https://astral.sh/uv/install.sh | sh
오류: 429 Too Many Requests
원인: NVIDIA NIM 무료 티어의 분당 40 요청 한도를 초과했습니다.
해결: 1~2분 기다린 후 다시 시도합니다.
오류: Claude Code가 프록시가 아닌 Anthropic 계정으로 연결됨 (화면에 실제 이메일 계정이 표시됨)
원인: 환경변수가 제대로 적용되지 않았습니다.
확인:
echo $ANTHROPIC_BASE_URL
위 명령어 결과가 비어있으면 export가 안 된 것입니다.
해결: 아래 세 줄을 다시 입력합니다.
export ANTHROPIC_AUTH_TOKEN="freecc"
export ANTHROPIC_BASE_URL="http://localhost:8082"
claude
오류: /status에서 Anthropic base URL이 localhost가 아닌 다른 주소로 표시됨
원인: 환경변수 문제이거나 기존 로그인 세션이 남아있는 경우입니다.
해결: Claude Code를 종료 후 아래를 실행합니다.
claude /logout
이후 export를 다시 입력하고 claude를 실행합니다.
오류: 프록시 서버가 실행되지 않거나 포트 충돌이 발생함
원인: 8082 포트를 다른 프로그램이 이미 사용 중입니다.
확인 (Mac / Linux):
lsof -i :8082
해결: 해당 프로세스를 종료하거나, .env 파일에서 PORT 항목을 다른 번호(예: 8083)로 바꾼 후 ANTHROPIC_BASE_URL도 같은 번호로 맞춰줍니다.