Source: https://aiprimetech.io/ko/claude-code/

[홈](/ko/) › [Claude Code](/ko/claude-code/)

[개요](/ko/claude-code/)[설치](/ko/claude-code/install/)[CLI 참조](/ko/claude-code/cli/)[요금 및 한도](/ko/claude-code/pricing/)[Agent SDK](/ko/claude-code/sdk/)[스킬 및 플러그인](/ko/claude-code/skills/)[GitHub](/ko/claude-code/github/)[웹, 데스크톱 및 IDE](/ko/claude-code/web-and-desktop/)[모델](/ko/claude-code/models/)[오류](/ko/claude-code/errors/)[오픈 소스인가요?](/ko/claude-code/open-source/)[튜토리얼](/ko/claude-code/tutorial/)[학생용 안내](/ko/claude-code/for-students/)[QA 자동화](/ko/claude-code/qa-automation/)[Cursor와 비교](/ko/claude-code/vs-cursor/)[Codex 및 OpenCode와 비교](/ko/claude-code/vs-codex/)[하위 에이전트](/ko/claude-code/subagents/)[훅](/ko/claude-code/hooks/)[MCP](/ko/claude-code/mcp/)[생태계](/ko/claude-code/ecosystem/)[VS Code](/ko/claude-code/vscode/)[OpenRouter](/ko/claude-code/openrouter/)[요청 속도 제한](/ko/claude-code/rate-limits/)[중국어 가이드](/claude-code/zh/)

최종 업데이트: 2026년 10월 11일

# Claude Code: 완벽 가이드

Claude Code는 Anthropic의 에이전트형 코딩 도구입니다. 저장소를 읽고, 계획을 세우고, 파일을 수정하고, 명령을 실행하고, 풀 리퀘스트를 생성하는 터미널 프로그램이며, 2025년 말부터는 웹 앱, 데스크톱 앱, IDE 확장도 제공됩니다. 이 가이드에서는 설치 방법, 효과적인 사용법, 비용, 그리고 비용 걱정에서 벗어날 수 있도록 게이트웨이에 연결하는 방법을 다룹니다.

## TLDR
- npm, 네이티브 설치 프로그램 또는 데스크톱 앱으로 설치하세요. macOS, Linux, Windows 또는 WSL에서 5분이면 됩니다.
- API를 통해 토큰당 요금이 청구되며, 긴 세션에서는 매 턴마다 전체 대화를 다시 전송합니다. 비용이 많이 드는 이유가 바로 이것입니다.
- 환경 변수 두 개(ANTHROPIC_BASE_URL + ANTHROPIC_API_KEY)로 이 게이트웨이에 연결할 수 있습니다. 동일한 모델을 사용하면서 액면가의 7.69231배에 해당하는 크레딧을 받거나, $1부터 시작하는 정액 무제한 요금제를 이용할 수 있습니다.
- 스킬, 플러그인, 하위 에이전트, MCP 서버 및 GitHub Action은 모두 계속 작동합니다. 게이트웨이는 도구 내부가 아니라 도구의 기반 계층에 위치합니다.

## Claude Code의 실제 작동 방식 

Claude Code는 코드 버튼이 달린 채팅창이 아닙니다. 에이전트 루프로 작동합니다. 원하는 결과를 설명하면 저장소를 살펴보고, 계획을 제안하고, 파일을 수정하고, 테스트를 실행하고, 실패 내용을 읽고, 반복해서 개선합니다. 파괴적인 작업을 하기 전에는 권한을 요청합니다. npm 패키지(@anthropic-ai/claude-code, 현재 2.1.296), 네이티브 설치 프로그램, VS Code / JetBrains 확장, 데스크톱 앱, 그리고 Anthropic이 호스팅하는 샌드박스에서 실행되는 웹 버전으로 제공됩니다. 

내부적으로 매 턴은 그때까지의 전체 대화를 담은 Messages API 호출입니다. 이 사실 하나로 사람들이 이 도구에 관해 검색하는 대부분의 질문을 설명할 수 있습니다. 왜 강력한지, 왜 토큰을 많이 소모하는지, 왜 요청 한도가 문제가 되는지, 그리고 더 저렴하거나 정액제인 API 백엔드가 사용 경험을 왜 크게 바꾸는지 말입니다. 

## 두 줄로 게이트웨이에 연결하기 

Claude Code는 표준 Anthropic 환경 변수를 읽습니다. 기본 URL을 이 게이트웨이로 설정하고 대시보드에서 발급받은 키를 사용하세요. 그 외에는 바뀌는 것이 없습니다. 

```
export ANTHROPIC_BASE_URL=https://aiprimetech.io
export ANTHROPIC_API_KEY=your_gateway_key
claude
```

다음 명령을 실행하세요: /status 명령을 Claude Code 안에서 실행해 연결 중인 기본 URL을 확인하고, /model 명령으로 모델을 선택하세요. 게이트웨이에서 제공하는 모든 모델을 사용할 수 있습니다. 현재 목록은 모델 가이드를 참고하세요. 

## 가이드 
- 설치 — npm, 네이티브 설치 프로그램, Windows/WSL 및 설치 문제 해결.
- CLI 참조 — 플래그, 슬래시 명령어, 헤드리스 모드, 출력 형식.
- 요금 및 한도 — API, Pro/Max 및 이 게이트웨이에서의 이용 비용.
- Agent SDK — Python 또는 TypeScript에서 프로그래밍 방식으로 Claude Code 제어하기.
- 스킬 및 플러그인 — 스킬의 개념, 마켓플레이스 및 나만의 스킬 작성하기.
- GitHub — GitHub App, Action 및 풀 리퀘스트의 @claude.
- 웹, 데스크톱 및 IDE — 터미널 외에 Claude Code를 실행할 수 있는 환경.
- 모델 — 기본 모델, 모델 전환 및 등급별 설정 재정의.
- 오류 — 500, 400, 429, 529, 인증 실패 및 각 오류의 의미.
- 오픈 소스인가요? — 오픈 소스인 부분과 아닌 부분, 그리고 오픈 소스 대안.
- 튜토리얼 — 첫 실전 세션: CLAUDE.md, 계획 모드, 권한, 대화 압축.
- 학생용 안내 — 학습하면서 가장 저렴하게 합법적으로 사용하는 방법.
- QA 자동화 — 테스트 생성, 실행과 수정의 반복, CI에서의 헤드리스 실행, Playwright.
- 하위 에이전트, 훅, MCP — 세 가지 확장 지점과 각각의 작동 예제.
- Cursor와 비교 및 Codex 및 OpenCode와 비교 — 솔직한 비교 및 함께 사용하는 방법.
- 생태계 — claude-code-router, SuperClaude, caveman, 상태 표시줄, awesome 목록.
- VS Code, OpenRouter, 요청 속도 제한 — 확장과 관련 오류, 다른 백엔드 사용 및 "요청 한도에 도달함"의 의미.

## 먼저 무료로 사용해 보세요

신규 계정에는 $5의 무료 API 크레딧이 제공됩니다 사용할 코드: CLAUDECODE — Sonnet으로 저녁 한나절 Claude Code를 사용하기에 충분합니다. 이후에는 액면가의 7.69231배에 해당하는 크레딧이 제공됩니다.

```
export ANTHROPIC_BASE_URL=https://aiprimetech.io
export ANTHROPIC_API_KEY=your_key
```

[코드 CLAUDECODE로 계정 만들기](/register?promo=CLAUDECODE)

## 자주 묻는 질문

Claude Code는 무료인가요?

도구 자체는 무료로 설치할 수 있습니다. 사용 요금은 Claude Pro/Max 구독을 통해 청구되거나 API를 통해 토큰당 청구됩니다. 이 게이트웨이에서는 종량제 크레딧이나 정액 무제한 요금제로 사용할 수 있습니다.Claude Code는 다른 API 엔드포인트에서도 작동하나요?

네. ANTHROPIC_BASE_URL 설정을 따르므로 Anthropic과 호환되는 모든 엔드포인트에서 작동합니다. 이 게이트웨이에도 바로 이 방식으로 연결되며, 패치나 래퍼가 필요하지 않습니다.Claude Code는 어떤 모델을 사용하나요?

기본적으로 현재 Sonnet 등급 모델을 사용합니다. /model 또는 --model 플래그로 전환할 수 있으며, 환경 변수로 각 등급의 모델 설정을 재정의할 수 있습니다. 모델 가이드에는 이 게이트웨이에서 현재 제공하는 모델이 나와 있습니다.

## 게이트웨이에서 Claude Code 실행하기

동일한 모델, 환경 변수 두 개, 액면가의 7.69231배에 해당하는 크레딧 또는 정액 무제한 요금제를 이용하세요. 신규 계정: 코드 CLAUDECODE로 $5의 무료 API 크레딧을 받으세요.[API 키 발급받기](/register?promo=CLAUDECODE) [무제한 요금제 보기](/ko/plans/)

AI Prime Tech는 독립 API 게이트웨이이며 Anthropic과 제휴 관계가 없고, Anthropic의 보증이나 후원을 받지 않습니다. “Claude”와 “Claude Code”는 Anthropic의 상표입니다. 여기에 설명된 Claude Code 기능은 작성 당시 Anthropic의 공개 문서를 기준으로 하며 자주 변경됩니다. 이 페이지의 가격과 모델 목록은 이 게이트웨이의 실시간 설정에서 가져옵니다.

## 더 많은 Claude Code 가이드

[Claude Code 설치 방법](/ko/claude-code/install/)[Claude Code CLI 문서: 명령어와 플래그](/ko/claude-code/cli/)[Claude Code 요금 및 한도 설명](/ko/claude-code/pricing/)[Claude Code SDK, 이제 Claude Agent SDK로](/ko/claude-code/sdk/)[Claude Code 스킬과 플러그인](/ko/claude-code/skills/)[GitHub에서 Claude Code 사용하기: App, Action 및 @claude](/ko/claude-code/github/)[Claude Code에 웹 인터페이스가 있나요? 웹, 데스크톱 및 IDE 설명](/ko/claude-code/web-and-desktop/)[Claude Code가 사용하는 모델과 변경 방법](/ko/claude-code/models/)[Claude Code 오류와 해결 방법](/ko/claude-code/errors/)[Claude Code는 오픈 소스인가요?](/ko/claude-code/open-source/)[Claude Code 튜토리얼: 첫 실전 세션](/ko/claude-code/tutorial/)[학생을 위한 Claude: Claude Code, API 및 교육 분야에서 실제로 제공되는 혜택](/ko/claude-code/for-students/)[QA 자동화에 Claude Code를 사용하는 방법](/ko/claude-code/qa-automation/)[Claude Code와 Cursor 비교: 어떤 도구를 언제 선택하고, 둘 다 어떻게 사용할까](/ko/claude-code/vs-cursor/)[Claude Code vs Codex vs OpenCode: 터미널 에이전트 비교](/ko/claude-code/vs-codex/)[Claude Code 하위 에이전트: 작동 방식, 정의 방법, 에이전트 팀](/ko/claude-code/subagents/)[Claude Code 훅: 에이전트 동작에 대한 결정론적 제어](/ko/claude-code/hooks/)[Claude Code MCP: 서버 연결, 범위, 원격 MCP와 실제 예제](/ko/claude-code/mcp/)[Claude Code 생태계: 라우터, 프레임워크, 플러그인과 이를 모아 둔 목록](/ko/claude-code/ecosystem/)[VS Code에서 Claude Code 사용하기: 확장 프로그램, 터미널 사용 방식, 오류](/ko/claude-code/vscode/)[Claude Code에서 OpenRouter를 사용하는 방법과 사용하지 않는 편이 나은 경우](/ko/claude-code/openrouter/)[Claude 요청 한도 오류: "API 오류: 요청 한도 도달"의 의미와 해결 방법](/ko/claude-code/rate-limits/)[Claude Code 사용법: 설치부터 일상적인 사용까지](/claude-code/zh/)