Source: https://aiprimetech.io/ko/learn/use-claude-api-with-claude-code/

[홈](/ko/) / [학습](/ko/learn/) / Claude Code 무제한 이용 

# Claude Code 무제한 이용 

Claude Code는 소프트웨어 개발을 위한 Anthropic의 공식 명령줄 에이전트입니다. 200k 컨텍스트 창으로 작동하고, 독립적인 컨텍스트를 가진 하위 에이전트를 생성하며, 파일 전체를 대화 기록으로 읽어 들이고, 매 턴마다 전체 컨텍스트를 다시 전송합니다. 이로 인해 세션이 길어질수록 토큰 사용량이 제곱에 비례해 증가합니다. 따라서 Claude Code는 현재 사용 가능한 개발자 도구 중에서도 토큰 사용량이 가장 많은 도구 중 하나입니다. Claude Code를 정액제 무제한 게이트웨이에 연결하면 사용량을 신중하게 배분해야 하는 도구에서 언제나 함께하는 진정한 개발 파트너로 바뀝니다. 

## Claude Code의 토큰 사용량이 제곱에 비례해 증가하는 이유 

API 관점에서 Claude Code는 턴 사이에 상태를 유지하지 않습니다. 보내는 모든 메시지에는 이전 메시지 전체, 읽어 들인 모든 파일 내용, 모든 도구 결과, 모든 어시스턴트 응답을 포함한 전체 대화 기록이 들어갑니다. 첫 번째 메시지는 5,000 토큰일 수 있습니다. 열 번째 대화에서는 50,000 토큰의 기록에 새로 추가된 내용을 더해 전송하게 됩니다. 스무 번째 대화에서는 요청당 컨텍스트가 150,000 토큰을 초과할 수 있습니다. 

하위 에이전트는 이 현상을 더욱 심화합니다. Claude Code가 하위 에이전트에 작업을 위임하면 해당 에이전트는 자체 컨텍스트 창을 갖고 독립적으로 기록을 쌓기 시작합니다. 상위 에이전트의 컨텍스트는 하위 에이전트의 요약을 포함하면서 커지고, 하위 에이전트 자체도 별도의 토큰 비용을 발생시킵니다. 여러 하위 에이전트가 협업하는 에이전트 팀은 이를 더욱 증폭합니다. 복잡한 작업에서는 상위 에이전트와 하위 에이전트 세 개가 각각 100k 이상의 토큰으로 구성된 컨텍스트를 가지고 모두 같은 API 키로 실행될 수 있습니다. 

/compact 명령은 기록을 요약하고 오래된 컨텍스트를 잘라 내어 도움이 되지만, 공간을 확보하는 대신 세부 정보를 포기하는 수동 개입입니다. 토큰당 과금 방식에서는 사용자가 비용을 관리하기 위해 강박적으로 컨텍스트를 압축하게 됩니다. 무제한 요금제에서는 대화가 자연스럽게 늘어나도록 두고, 컨텍스트의 품질이 떨어질 때만 압축하며, 비용을 머릿속으로 계산하지 않고 하위 에이전트를 자유롭게 사용할 수 있습니다. 

## 환경 변수 설정 

Claude Code는 환경 변수에서 API 설정을 읽습니다. 필수 변수는 ANTHROPIC_BASE_URL과 ANTHROPIC_API_KEY 또는 ANTHROPIC_AUTH_TOKEN입니다. ANTHROPIC_BASE_URL을 https://unlimited.aiprimetech.io로 설정하세요. Anthropic SDK가 API 경로를 자동으로 덧붙이므로 /v1이 없는 루트 호스트를 사용해야 합니다. 키의 경우, 게이트웨이가 표준 Anthropic 형식인 x-api-key 헤더 인증을 요구한다면 ANTHROPIC_API_KEY를 사용하세요. 

설정을 유지하려면 셸 프로필(.bashrc, .zshrc 또는 PowerShell의 $PROFILE)에 이 변수들을 설정하세요. Windows에서는 고급 시스템 설정 대화 상자를 통해 시스템 환경 변수로 설정할 수도 있습니다. Claude Code는 시작할 때 이 변수들을 읽으므로, 값을 변경했다면 새 값이 적용되도록 Claude Code 세션을 다시 시작하세요. 

프로젝트별로 설정을 재정의하려면 프로젝트 루트에 .env 파일을 만드세요. Claude Code는 작업 디렉터리에서 .env 파일을 불러옵니다. 이를 통해 프로젝트마다 서로 다른 API 설정을 사용할 수 있습니다. 일부 프로젝트는 무제한 요금제로, 다른 프로젝트는 Anthropic 직접 과금으로 사용하는 경우 유용합니다. .env 파일은 시스템 환경 변수보다 우선합니다. 

## Sonnet, Opus, Haiku, Fable 모델 매핑 

Claude Code는 환경 변수로 재정의할 수 있는 내부 모델 별칭을 사용합니다. ANTHROPIC_DEFAULT_SONNET_MODEL은 기본 'sonnet' 선택에 사용되는 모델을 제어합니다. ANTHROPIC_DEFAULT_OPUS_MODEL은 'opus' 선택을 재정의합니다. ANTHROPIC_DEFAULT_HAIKU_MODEL와 ANTHROPIC_DEFAULT_FABLE_MODEL은 나머지 등급을 제어합니다. 이 변수들을 게이트웨이가 지원하는 정확한 모델 ID로 설정하세요. 

예를 들어 ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4-5 및 ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4-6.으로 설정하세요. Claude Code에서 /model 또는 시작 플래그로 모델 등급을 선택하면 매핑한 모델로 연결됩니다. 게이트웨이가 사용자 지정 모델 식별자를 제공하거나 특정 모델 버전을 고정하려는 경우 특히 유용합니다. 

무제한 요금제에서 모델 선택은 오직 품질과 속도 사이의 선택입니다. 등급별 비용 차이는 없습니다. 최고의 품질을 위해 Opus를 기본값으로 사용하고, 빠르게 반복 작업을 진행하면서 더 빠른 응답이 필요할 때만 Sonnet이나 Haiku로 전환하세요. /effort 명령은 Claude Code가 각 작업을 얼마나 철저하게 수행할지 추가로 조정합니다. 가장 뛰어난 성능의 구성을 원한다면 높은 노력 수준과 Opus를 함께 사용하세요. 

## 하위 에이전트, 에이전트 팀, 백그라운드 에이전트 

Claude Code는 자체 컨텍스트 창을 가지고 위임된 하위 작업을 처리하는 독립적인 Claude 인스턴스인 하위 에이전트를 생성할 수 있습니다. 메인 에이전트가 복잡한 작업을 만나면 조사, 구현 또는 검증을 독립적으로 작업한 뒤 결과를 보고하는 하위 에이전트에 위임할 수 있습니다. 각 하위 에이전트는 새로운 컨텍스트로 시작하며 자체 대화 기록을 쌓습니다. 

에이전트 팀은 여러 하위 에이전트가 관련 작업을 동시에 협업할 수 있도록 이 개념을 확장합니다. 메인 에이전트는 작업을 배분하고 결과를 종합하는 조정자 역할을 합니다. 이는 대규모 변경에 매우 강력합니다. 한 하위 에이전트가 모듈 A를 리팩터링하는 동안 다른 에이전트가 모듈 B를 처리할 수 있습니다. 다만 API 사용량은 활성 에이전트 수에 비례해 증가합니다. 

백그라운드 에이전트는 메인 세션에서 작업을 계속하는 동안 비동기적으로 실행됩니다. 별도의 작업을 수행하고 완료되면 결과를 보고합니다. 토큰당 과금 방식에서는 여러 백그라운드 에이전트를 동시에 실행하면 비용이 빠르게 늘어납니다. 무제한 요금제에서는 여러 백그라운드 에이전트를 실행해 프로젝트의 서로 다른 부분을 작업하게 하고, 결과가 준비되면 검토할 수 있습니다. 이 모든 사용량은 정액 요금에 포함됩니다. 

Claude Code가 텔레메트리와 필수적이지 않은 요청을 보내지 않도록 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1로 설정하세요. 이는 모든 사용자 지정 게이트웨이에서 불필요한 트래픽을 줄이는 좋은 방법입니다. 또한 CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1은 Claude Code가 하드코딩된 목록을 사용하는 대신 게이트웨이에 사용 가능한 모델을 조회하도록 합니다. 

## 헤드리스 모드 및 CI/CD 통합 

Claude Code의 헤드리스 모드(--headless 플래그)는 대화형 프롬프트 없이 실행되므로 CI/CD 파이프라인, 자동 코드 검토, 일괄 처리에 적합합니다. 헤드리스 모드에서 Claude Code는 stdin 또는 명령줄 인수에서 입력을 읽고 stdout으로 결과를 출력합니다. 추가 입력을 기다리는 대신 작업이 완료되면 종료됩니다. 

CI 통합을 위해 파이프라인 설정(GitHub Actions 시크릿, GitLab CI 변수, Jenkins 자격 증명)에 환경 변수를 설정하고 작업 설명을 인수로 전달하여 Claude Code를 실행하세요. 일반적인 CI 활용 사례에는 자동 PR 검토, 문서 생성, 테스트 작성, 마이그레이션 스크립트가 있습니다. 

무제한 요금제에서는 헤드리스 모드로 대량 처리 워크플로를 구현할 수 있습니다. 저장소의 모든 PR에 Claude Code를 실행하거나, 테스트가 없는 모듈의 테스트 모음을 일괄 생성하거나, 릴리스마다 문서 업데이트를 자동화할 수 있습니다. 모두 실행당 비용을 걱정할 필요가 없습니다. 공정 사용 정책의 요청 속도 제한을 준수하는 한 전체 사용량이 정액 요금에 포함됩니다. 

## CLAUDE.md 프로젝트 메모리 및 훅 

CLAUDE.md 파일은 Claude Code가 자동으로 불러오는 지속적인 프로젝트 컨텍스트를 제공합니다. 프로젝트 루트에 CLAUDE.md를 배치하고 코딩 표준, 아키텍처 결정 사항, 일반적인 패턴, 프로젝트별 지침을 작성하세요. 이 내용은 모든 요청의 시스템 프롬프트에 포함되어 호출마다 토큰이 추가되지만, 응답의 품질과 일관성을 크게 높여 줍니다. 

토큰당 과금 방식에서는 사용자가 비용을 관리하기 위해 CLAUDE.md를 최소한으로 유지합니다. 세션이 유지되는 동안 모든 단어가 매 요청에 토큰을 추가하기 때문입니다. 무제한 요금제에서는 상세한 아키텍처 문서, 전체 스타일 가이드, 의존성 설명, 팀 규칙 등 실제로 도움이 되는 컨텍스트를 충분히 작성하세요. 요청마다 추가되는 토큰에 별도의 비용이 들지 않으며, 매 상호작용을 거치면서 품질 향상 효과가 누적됩니다. 

훅을 사용하면 도구 호출 전후, 세션 시작 시, 컨텍스트 압축 시 등 Claude Code 실행의 특정 시점에 사용자 지정 스크립트를 실행할 수 있습니다. 훅으로 동적 컨텍스트를 주입하거나, CI를 통해 변경 사항을 검증하거나, 코드 형식을 자동으로 정리하거나, 알림을 트리거하세요. 훅은 API 수준이 아닌 CLI 수준에서 작동하므로 무제한 게이트웨이와 원활하게 통합됩니다. 

## Claude Code 게이트웨이 문제 해결 

Claude Code가 연결되지 않으면 ANTHROPIC_BASE_URL이 /v1 없는 루트 호스트로 설정되어 있는지 확인하세요. echo $ANTHROPIC_BASE_URL(PowerShell에서는 $env:ANTHROPIC_BASE_URL)을 실행해 값을 확인하세요. SDK가 /v1/messages를 자동으로 덧붙이므로 기본 URL에 /v1을 포함하면 요청이 /v1/v1/messages로 전송되어 404을 반환합니다. 

모델을 찾을 수 없다는 오류는 매핑 변수의 모델 ID가 게이트웨이에서 제공하는 모델과 일치하지 않는다는 뜻입니다. AI Prime Tech 대시보드에서 지원되는 정확한 식별자를 확인하고 그에 맞게 ANTHROPIC_DEFAULT_SONNET_MODEL을 업데이트하세요. 모델 ID는 대소문자를 구분하며 버전 접미사가 포함된다는 점을 기억하세요. 

세션은 작동하지만 하위 에이전트가 실패한다면, 하위 에이전트가 생성 방식에 따라 환경 변수를 다르게 상속하는 것이 원인일 수 있습니다. 환경 변수를 현재 셸 세션에만 설정하지 말고 시스템 수준에서 설정하세요. 특히 Windows에서는 자식 프로세스가 셸 로컬 변수를 상속하지 못할 수 있습니다. 

복사

```
# Shell environment (add to .bashrc / .zshrc / $PROFILE)
export ANTHROPIC_BASE_URL="https://aiprimetech.io"
export ANTHROPIC_API_KEY="<your AI Prime Tech Unlimited key>"
export ANTHROPIC_DEFAULT_SONNET_MODEL="claude-sonnet-4-5"
export ANTHROPIC_DEFAULT_OPUS_MODEL="claude-opus-4-6"
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1

# Or per-project .env file:
# ANTHROPIC_BASE_URL=https://aiprimetech.io
# ANTHROPIC_API_KEY=sk-...
# ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4-5

# Run Claude Code:
# claude            (interactive)
# claude --headless (CI/CD mode)
```

## 자주 묻는 질문 

 Claude Code는 왜 채팅보다 훨씬 더 많은 토큰을 사용하나요?

Claude Code는 매 턴마다 전체 대화 기록을 다시 전송합니다. API 측에서는 상태를 유지하지 않기 때문입니다. 세션이 길어질수록 각 요청에는 이전의 모든 메시지, 파일 내용, 도구 결과가 포함됩니다. 이로 인해 토큰 사용량이 이차적으로 증가하며, 세션의 스무 번째 메시지는 첫 번째 메시지보다 10-20x 더 커질 수 있습니다. 하위 에이전트의 사용량은 별도로 계산되나요?

각 하위 에이전트는 자체 컨텍스트 창을 갖춘 독립적인 대화를 실행합니다. 무제한 요금제에서는 상위 에이전트, 하위 에이전트, 백그라운드 에이전트의 모든 대화가 정액 요금에 포함됩니다. 에이전트별 또는 대화별 추가 요금은 없습니다. ANTHROPIC_BASE_URL에 /v1을 포함해야 하나요?

아니요. 루트 호스트인 https://unlimited.aiprimetech.io로 설정하세요. Anthropic SDK가 /v1/messages를 자동으로 추가합니다. 변수에 /v1을 포함하면 경로가 중복되어 404 오류가 발생합니다. 무제한 요금제로 CI/CD에서 Claude Code 헤드리스 모드를 사용할 수 있나요?

네. 파이프라인의 시크릿에 ANTHROPIC_BASE_URL 및 ANTHROPIC_API_KEY을 설정하고 작업 인수와 함께 claude --headless를 실행하세요. 무제한 요금제에서는 공정 사용 정책에 따른 요청 속도 제한 내에서 CI 사용에도 동일한 정액 요금이 적용됩니다. Claude Code에서 모델을 어떻게 전환하나요?

세션 중에 /model 명령을 사용하거나 ANTHROPIC_DEFAULT_SONNET_MODEL 및 ANTHROPIC_DEFAULT_OPUS_MODEL 환경 변수를 설정하여 각 등급에서 사용할 모델을 지정하세요. 무제한 요금제에서는 모델 간 비용 차이가 없습니다.  

몇 분 만에 Claude 사용 시작하기

API 키를 발급받으세요 — Anthropic 계정이나 대기자 명단 등록이 필요하지 않습니다.[API 키 발급받기](/register) 

AI Prime Tech는 독립적인 API 게이트웨이입니다. Anthropic과 제휴 관계가 없으며, Anthropic의 보증을 받거나 Anthropic의 리셀러로 활동하지 않습니다. Claude 및 관련 모델 이름은 각 소유자의 상표입니다.    

## 더 많은 Claude API 가이드

[Claude API 키 발급 방법](/ko/learn/how-to-get-a-claude-api-key/)[Claude API 요금 해설](/ko/learn/claude-api-pricing-explained/)[Claude API를 가장 저렴하게 사용하는 방법](/ko/learn/cheapest-way-to-use-claude-api/)[Claude API로 Cursor 무제한 사용](/ko/learn/use-claude-api-with-cursor/)[Claude API 게이트웨이와 Anthropic 직접 이용 비교](/ko/learn/claude-api-vs-anthropic-direct/)[OpenAI 호환 API를 통해 Claude 사용하기](/ko/learn/openai-compatible-claude-api/)[Claude 모델 비교](/ko/learn/claude-api-models-compared/)[암호화폐로 Claude API 요금 결제하기](/ko/learn/claude-api-with-crypto-payment/)[대기 명단 없이 Claude API 이용하기](/ko/learn/claude-api-without-waitlist/)[Claude 토큰 사용량을 줄이는 방법](/ko/learn/how-to-reduce-claude-token-usage/)[Claude API로 Cline 무제한 사용](/ko/learn/use-claude-api-with-cline/)[Claude API로 Roo Code 무제한 사용](/ko/learn/use-claude-api-with-roo-code/)[JetBrains IDE에서 Claude 무제한 사용](/ko/learn/use-claude-api-with-jetbrains/)[Claude API로 Aider 무제한 사용하기](/ko/learn/use-claude-api-with-aider/)[VS Code에서 Claude 무제한 사용](/ko/learn/use-claude-api-with-vscode/)[Claude API로 OpenCode 무제한 사용하기](/ko/learn/use-claude-api-with-opencode/)[Claude에서 Hermes 에이전트 무제한 실행하기](/ko/learn/run-hermes-agent-with-claude-api/)[Claude에서 OpenClaw 무제한 실행하기](/ko/learn/run-openclaw-with-claude-api/)[Anthropic 호환 API의 의미](/ko/learn/anthropic-compatible-api/)[Claude Code API 키 — 발급 및 설정 방법](/ko/learn/claude-code-api-key-setup/)[Claude Code API 비용 — 요금과 절감 방법](/ko/learn/claude-code-api-costs/)[Claude API 오류 — 요청 한도, 400, 500, 529 해결 방법](/ko/learn/claude-api-errors-troubleshooting/)[Claude API 크레딧 구매 방법](/ko/learn/buy-claude-api-credits/)[Claude API 무료 체험: 실제로 무료인 것과 무료가 아닌 것](/ko/learn/claude-api-free-trial/)[Claude API와 Claude Pro/Max 구독 — 어떤 것을 선택할까요](/ko/learn/claude-api-vs-subscription/)[Claude에서 Codex CLI 실행하기](/ko/learn/use-claude-api-with-codex/)[Claude를 n8n에 연결하기](/ko/learn/use-claude-api-with-n8n/)[LiteLLM을 Claude로 라우팅하기](/ko/learn/use-claude-api-with-litellm/)[Kilo Code에서 Claude 사용하기](/ko/learn/use-claude-api-with-kilo-code/)[GitHub Copilot에 Claude 연결하기](/ko/learn/use-claude-api-with-github-copilot/)[게이트웨이를 통해 Zed를 Claude에 연결하기](/ko/learn/use-claude-api-with-zed/)[Cherry Studio를 Claude에 연결하기](/ko/learn/use-claude-api-with-cherry-studio/)[LangChain을 게이트웨이의 Claude에 연결하기](/ko/learn/use-claude-api-with-langchain/)[Claude로 Factory Droid 실행하기](/ko/learn/use-claude-api-with-factory-droid/)[Claude Code API 이해하기](/ko/learn/claude-code-api/)[애플리케이션에 Claude API 통합하기](/ko/learn/claude-api-integration/)