# Claude API와 Claude Code 차이: 내 작업엔 무엇을 쓸까

> Claude Code와 API는 같은 모델을 씁니다. 직접 코딩은 Pro·Max에 포함된 Claude Code로, 내 서비스나 남이 쓰는 제품은 API 키로 Claude API를 호출합니다.

- URL: https://blog.laozhang.ai/ko/posts/claude-api-vs-claude-code
- Published: 2026-09-26
- Updated: 2026-09-26
- Author: LaoZhang AI Team (https://blog.laozhang.ai/ko/about)
- Category: Claude Code
- Tags: Claude API, Claude Code, Agent SDK, Anthropic, Claude 요금제

---
Claude API와 Claude Code는 서로 다른 모델이 아닙니다. Claude API는 내 코드가 `api.anthropic.com`에 요청을 보내 모델을 호출하고, 입력·출력 토큰만큼 비용을 내는 개발자용 접점입니다. Claude Code는 Anthropic이 같은 모델 위에 만든 에이전트형 코딩 도구로, 코드베이스를 읽고 파일을 고치고 명령을 실행하며 터미널·IDE·데스크톱 앱·브라우저에서 동작합니다.

결제도 한쪽으로 묶여 있지 않습니다. 2026년 9월 26일 기준 Claude Code는 Pro와 Max 요금제에 포함되어 있어 API 키 없이 쓸 수 있고, 같은 Claude Code를 Console API 키나 클라우드 자격 증명으로 실행하면 토큰 단위 종량제로 청구됩니다. 그래서 고를 대상은 "API냐 Claude Code냐"보다 "지금 하려는 일이 어느 층에 속하느냐"입니다. 내 저장소에서 직접 코딩한다면 Claude Code, 내 서비스 안에서 Claude를 부른다면 Claude API, 그 사이에 있는 스크립트·CI·앱 내장 에이전트는 Claude Code를 프로그램으로 호출하는 `claude -p`와 Agent SDK가 맡습니다.

## 같은 모델을 쓰는 다섯 가지 접점

Anthropic의 Agent SDK 문서는 Claude로 무언가를 만들고 실행하는 방법을 Agent SDK, Claude Code CLI, Client SDK, Managed Agents 네 가지로 나눕니다. 여기에 가장 아래층인 Messages API를 더하면 아래와 같습니다. 위로 갈수록 완성된 도구이고, 아래로 갈수록 직접 만들어야 하는 부분이 늘어납니다.

| 접점 | 무엇인가 | 내가 직접 맡는 부분 |
| --- | --- | --- |
| Claude Code (CLI·IDE·데스크톱·웹) | 대화하면서 쓰는 완성형 코딩 에이전트 | 작업 지시와 변경 승인 |
| `claude -p`, Agent SDK | Claude Code의 에이전트 루프와 내장 도구를 스크립트나 Python·TypeScript 앱에서 호출 | 프롬프트, 허용할 도구, 권한 설정 |
| Managed Agents | Anthropic이 에이전트 실행 환경을 호스팅하고, Claude API로 구성 | 에이전트 구성과 내 서비스 연동 |
| Client SDK | 여러 언어에서 Claude API를 직접 부르는 라이브러리 | 도구 호출 루프 작성(베타 tool runner로 대신할 수 있음) |
| Messages API | `POST https://api.anthropic.com/v1/messages` HTTP 엔드포인트 | 요청, 응답 처리, 재시도 전부 |

이 구조를 알면 자주 헷갈리는 표현 세 가지가 정리됩니다.

- **Claude Code는 모델이 아닙니다.** Claude Code에서 고르는 Opus, Sonnet, Haiku는 API에서 호출하는 모델과 같은 계열이고, Claude Code 문서도 "Claude Code는 API 토큰 소비량 기준으로 비용이 발생한다"고 설명합니다. 같은 모델인데 결과가 달라 보인다면 그 차이는 도구, 컨텍스트, 권한 같은 실행 환경에서 나옵니다.
- **"Claude Code API"는 두 가지 뜻으로 쓰입니다.** 하나는 API 키로 과금되는 Claude Code이고, 다른 하나는 Claude Code를 프로그램에서 호출하는 `claude -p`나 Agent SDK입니다. 검색 결과나 대화에서 이 말을 만나면 어느 쪽인지 먼저 확인해야 합니다.
- **"크레딧"도 두 가지입니다.** Claude Console에 선불로 충전하는 API 크레딧이 있고, Pro·Max 한도를 넘었을 때 켜는 usage credits(사용 크레딧)가 있습니다. usage credits는 구독 계정에서 켜지만 초과분은 표준 API 요금으로 청구됩니다.

## 작업별 선택표: 접점, 자격 증명, 청구서, 주의할 경계

같은 Claude Code라도 어떤 자격 증명으로 실행하느냐에 따라 청구서가 바뀝니다. 그래서 하려는 일에서 출발해 접점, 자격 증명, 청구 위치, 넘으면 안 되는 선까지 한 줄로 이어 보면 판단이 쉬워집니다. 아래 표의 규칙은 2026년 9월 26일 기준 Anthropic의 인증·법률 문서에 적힌 내용입니다.

| 하려는 일 | 쓸 접점 | 쓸 수 있는 자격 증명 | 청구되는 곳 | 주의할 경계 |
| --- | --- | --- | --- | --- |
| 내 저장소에서 직접 코딩, 리팩터링, 디버깅 | Claude Code CLI·IDE | Pro·Max 로그인, Console 계정·API 키, 클라우드 자격 증명 | 구독 한도(초과분은 usage credits) 또는 Console·클라우드 종량 | 셸에 남은 `ANTHROPIC_API_KEY`는 로그인보다 우선 적용 |
| 내 스크립트나 CI에서 Claude Code 실행 | `claude -p` (Agent SDK의 CLI) | Console API 키, `CLAUDE_CODE_OAUTH_TOKEN`, 클라우드 자격 증명 | 키는 Console, 토큰은 구독 한도 | `-p`는 키가 있으면 항상 키를 쓰고, `--bare`는 구독 토큰을 읽지 않음 |
| 내 서비스에 요약·분류·챗봇 기능 추가 | Client SDK로 Messages API 호출 | Console API 키, 클라우드 자격 증명 | Console 또는 클라우드 청구서, 토큰 단위 | 구독 로그인으로는 대신할 수 없음 |
| 내 앱 안에 코딩 에이전트를 내장해 사용자에게 제공 | Agent SDK (Python·TypeScript) | Console API 키, 클라우드 자격 증명 | Console 또는 클라우드 청구서 | 사전 승인 없이 사용자에게 claude.ai 로그인을 제공하면 안 됨 |
| 에이전트 실행 환경까지 Anthropic에 맡김 | Managed Agents | Claude API 계정 | Claude API 사용량 | 구독 로그인 대상이 아님 |
| 호스팅 샌드박스 등 내 제품에 Claude Code를 넣어 제공 | 수정하지 않은 Claude Code 바이너리 | 최종 사용자 본인의 API 키, 구독, 클라우드 자격 증명 | 최종 사용자 본인 | 사용량을 대신 결제·재판매·중계하면 안 됨 |

표에서 판단이 갈리는 지점은 세 곳입니다. 직접 쓰느냐 남이 쓰느냐, 사람이 대화하느냐 스크립트가 도느냐, 그리고 Claude Code의 에이전트 기능이 필요하냐 모델 호출 한 번이면 되느냐입니다.

![직접 코딩, 스크립트·CI, 내 서비스 기능, 앱 내장 에이전트별로 쓸 접점과 자격 증명, 청구되는 곳을 잇고 다른 사람이 쓰는 제품에는 구독 로그인을 쓸 수 없다는 경계를 표시한 흐름도](https://blog.laozhang.ai/posts/ko/claude-api-vs-claude-code/img/task-to-billing-map.webp)

### 내 저장소에서 직접 코딩한다면

Pro나 Max를 이미 결제했다면 Claude Code를 쓰려고 API 키를 따로 만들 필요가 없습니다. `claude`를 실행해 claude.ai 계정으로 로그인하면 구독 한도 안에서 동작합니다. 요금제별 조건은 다음과 같습니다(2026년 9월 26일 기준, 세금 별도).

| 요금제 | 월 요금 | Claude Code |
| --- | --- | --- |
| Free | $0 | 포함되지 않음 |
| Pro | $20, 연간 결제 시 월 $17($200 일괄) | 포함 |
| Max 5x | $100 | 포함 |
| Max 20x | $200 | 포함 |

주의할 점은 한도가 채팅과 공유된다는 것입니다. 웹, 데스크톱, 모바일, Claude Code의 사용량이 모두 같은 풀에서 빠지고, 5시간 단위로 돌아가는 세션 한도와 주간 한도가 함께 적용됩니다. 한도에 닿으면 리셋을 기다리거나, 상위 요금제로 올리거나, usage credits를 켜서 표준 API 요금으로 계속 쓸 수 있습니다. 요금제 안내는 코딩량이 많은 경우 Console 계정의 종량제 API 크레딧으로 전환하는 방법도 제시합니다. 두 구독 사이의 선택은 [Claude Pro vs Max 2026: 가격, Claude Code 제한, Max 손익분기점](https://blog.laozhang.ai/ko/posts/claude-code-pro-vs-max), Team과 extra usage까지 포함한 전체 요금은 [Claude Code 가격 2026: Pro, Max, Team, API, extra usage 선택법](https://blog.laozhang.ai/ko/posts/claude-code-pricing-guide)에서 다룹니다. 아직 설치 전이라면 [Claude Code 설치 방법 2026: Mac, Windows, Linux 완전 가이드](https://blog.laozhang.ai/ko/posts/how-to-install-claude-code)부터 보면 됩니다.

### 스크립트와 CI에서 돌린다면

Claude Code를 비대화형으로 실행하는 방법이 `claude -p`입니다. Anthropic은 이것을 Agent SDK의 CLI 형태로 설명하고, 같은 에이전트 루프를 Python·TypeScript 패키지로도 제공합니다. 다른 언어에서는 CLI를 하위 프로세스로 띄우고 `--output-format json`으로 결과를 받으면 됩니다.

```bash
# 허용할 도구를 지정해 한 번 실행
claude -p "auth.py의 버그를 찾아 고쳐 줘" --allowedTools "Read,Edit,Bash"

# 스크립트용 권장 방식: 훅, MCP, CLAUDE.md 자동 로드를 건너뜀(ANTHROPIC_API_KEY 필요)
claude --bare -p "README.md를 요약해 줘" --allowedTools "Read" --output-format json
```

여기서 인증 규칙이 대화형과 달라집니다.

- `-p` 모드에서는 `ANTHROPIC_API_KEY`가 설정되어 있으면 승인 절차 없이 항상 그 키를 씁니다. 구독으로 돌린다고 생각했던 스크립트가 Console에 청구되는 흔한 이유입니다.
- `--bare`는 OAuth 자격 증명과 시스템 키체인을 읽지 않습니다. 그래서 `ANTHROPIC_API_KEY`나 `apiKeyHelper`가 필요하고, 클라우드 제공업체는 각자의 자격 증명을 읽습니다. Anthropic은 `--bare`를 스크립트·SDK 호출에 권장하며, 앞으로 `-p`의 기본값이 될 예정이라고 밝혔습니다.
- 구독으로 CI를 돌리려면 `claude setup-token`으로 1년짜리 토큰을 발급해 `CLAUDE_CODE_OAUTH_TOKEN`에 넣습니다. Pro, Max, Team, Enterprise 요금제가 필요하고, `--bare`에서는 이 토큰을 읽지 않습니다.
- `--bare` 없이 `-p`를 실행하면 저장소의 `.claude/settings.json` 훅과 `.mcp.json` 서버가 신뢰하지 않은 폴더에서도 확인 창 없이 실행됩니다. 외부 기여자의 PR을 받아 도는 CI라면 `--bare`로 이 경로를 막아 두는 편이 안전합니다.

구독 토큰 사용 자체가 금지된 것은 아닙니다. 다만 Pro·Max의 광고된 한도는 Claude Code와 Agent SDK의 "일반적인 개인 사용"을 전제로 합니다. 내 저장소의 개인 자동화 정도라면 이 범위에 들어가지만, 팀 전체가 공유하는 파이프라인을 개인 구독 토큰 하나로 돌리는 것은 그 전제에서 벗어납니다. 이런 경우에는 Console API 키, 클라우드 자격 증명, 또는 Team·Enterprise 쪽이 맞습니다.

### 내 서비스에 Claude 기능을 붙인다면

문서 요약, 문의 분류, 챗봇처럼 내 서비스가 Claude를 호출하는 경우에는 Claude Code가 아니라 Claude API가 맞습니다. 파일을 고치고 명령을 실행하는 에이전트가 필요 없는 작업에 Claude Code를 끼워 넣으면 구조만 무거워집니다. 키는 Claude Console(platform.claude.com)에서 발급하고, 요청은 다음 형태입니다.

```bash
curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-5-5",
    "max_tokens": 1000,
    "messages": [
      {"role": "user", "content": "이 고객 문의를 환불, 배송, 기타 중 하나로 분류해 줘: ..."}
    ]
  }'
```

반대로 API 위에서 파일 읽기·편집·명령 실행 도구와 반복 루프를 직접 짜고 있다면, 그 부분은 Agent SDK가 이미 제공합니다. 도구 호출 한두 번이면 Client SDK로 충분하고, 저장소를 탐색하며 여러 단계를 스스로 진행하는 에이전트가 필요하면 Agent SDK를 쓰는 식으로 나누면 됩니다. 에이전트 실행 환경까지 Anthropic에 맡기는 선택지가 Managed Agents이며, 언제 쓰고 언제 피할지는 [Claude Managed Agents란? 2026년에 언제 쓰고 언제 쓰지 말아야 하나](https://blog.laozhang.ai/ko/posts/claude-managed-agents)에 정리되어 있습니다. 키 발급과 결제 절차는 [Claude API 키 구매 가이드: 공식 결제·키 발급·무료 크레딧 확인법](https://blog.laozhang.ai/ko/posts/claude-api-key-free-tier)을 참고하세요.

### 다른 사람이 쓰는 제품이라면

여기가 구독과 API가 가장 분명하게 갈리는 곳입니다. Anthropic의 Claude Code 법률·규정 문서와 Agent SDK 문서는 다음을 명시합니다.

- 제품이나 서비스를 만드는 개발자는 Agent SDK를 쓰는 경우를 포함해 Claude Console 또는 지원 클라우드 제공업체의 API 키 인증을 써야 합니다.
- 제3자 개발자는 사전 승인 없이 자기 제품에 claude.ai 로그인을 제공하거나, 사용자 대신 Free·Pro·Max 요금제 자격 증명으로 요청을 중계할 수 없습니다. Claude.ai 자격 증명이나 세션 토큰을 수집·저장·중개하는 것도 금지됩니다.
- 내 제품에 Claude Code를 넣어 제공하려면 바이너리를 수정하지 않아야 하고, 최종 사용자마다 본인의 API 키, 구독, 클라우드 자격 증명으로 인증해야 합니다. 사용량을 대신 결제하거나 재판매·중계할 수 없습니다.

허용되는 쪽도 함께 알아 두면 경계가 선명해집니다. 회사가 자기 API 키를 개발 환경이나 시크릿 관리 도구에 넣어 자기 조직의 승인된 사용자에게 쓰게 하는 것은 괜찮습니다. 사용량이 키 소유자에게 청구되고 외부에 되팔지 않는다면 말입니다. 개인이 자기 구독으로 수정하지 않은 Claude Code에 로그인하는 것도 문제가 없습니다. Anthropic은 이 제한을 사전 통지 없이 집행할 수 있다고 밝히고 있으므로, 애매한 경우에는 영업팀에 허용 인증 방식을 문의하는 것이 공식 경로입니다.

## 구독 정액과 토큰 종량을 같은 잣대로 보기

Claude API 요금은 100만 토큰 단위로 매겨집니다(2026년 9월 26일 기준, 입력 / 출력).

| 모델 | 모델 ID | 입력 | 출력 |
| --- | --- | --- | --- |
| Fable 5.1 | `claude-fable-5-1` | $10 | $50 |
| Opus 5.5 | `claude-opus-5-5` | $4 | $20 |
| Sonnet 5 | `claude-sonnet-5` | $2 | $10 |
| Haiku 4.5 | `claude-haiku-4-5-20251001` | $1 | $5 |

Sonnet 5의 입력 $2 / 출력 $10은 출시 가격이 표준가로 확정된 것으로, 2026년 9월 1일로 예정됐던 인상은 시행되지 않습니다. 캐시 적중 입력은 기본가의 0.1배(Opus 5.5는 0.05배, Fable 5.1은 0.025배)이고, Batch API는 50% 할인입니다.

에이전트형 코딩 세션 한 번에 입력 200만 토큰, 출력 15만 토큰을 쓴다고 가정하고 캐시 없이 정가로 계산하면 다음과 같습니다. 토큰 수는 예시일 뿐이며, 실제 사용량은 저장소 크기와 작업 방식에 따라 크게 달라집니다.

- Sonnet 5: 2 × $2 + 0.15 × $10 = 세션당 $5.50
- Opus 5.5: 2 × $4 + 0.15 × $20 = 세션당 $11.00
- 한 달 20세션: Sonnet 5 $110, Opus 5.5 $220

같은 달 구독은 Pro $20, Max $100 또는 $200입니다. 다만 구독에는 5시간·주간 한도가 있으므로 "월 $20에 무제한"으로 비교하면 안 됩니다. 반복되는 컨텍스트가 많으면 프롬프트 캐싱으로 입력 비용이 크게 줄어드는 것도 API 쪽 계산에 넣어야 합니다.

조직 단위 참고치로는 Anthropic이 기업 배포에서 집계한 평균이 있습니다. 활성일 기준 개발자 1인당 약 $13, 월 $150~250이며, 90%의 사용자는 활성일당 $30 미만이었습니다. 이는 기업 배포 평균이지 개인 사용량 예측이 아닙니다. 헤비 유저가 구독을 유지할지, 낮출지, API로 옮길지는 [Claude Code 헤비 유저: 구독 유지, 다운그레이드, API 중 무엇을 선택할까](https://blog.laozhang.ai/ko/posts/claude-api-vs-subscription-cost)에서 시나리오별로 계산합니다.

## 돈이 새는 실수 세 가지

**요금제에 포함된 작업에 API 크레딧을 산다.** Pro나 Max를 결제했다면 대화형 Claude Code는 이미 포함되어 있습니다. Claude Code가 별도의 API 종량제 상품이라고 생각해 Console 크레딧을 충전하면, 이미 낸 구독 한도는 남겨 둔 채 토큰 비용을 따로 내게 됩니다. Console 크레딧은 내 서비스에서 API를 호출하거나, 의도적으로 종량제로 Claude Code를 돌릴 때 필요합니다.

**남아 있는 `ANTHROPIC_API_KEY` 때문에 종량제로 바뀐다.** Claude Code는 여러 자격 증명이 있을 때 정해진 순서로 하나를 고릅니다. 클라우드 제공업체 설정, `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_API_KEY`, `apiKeyHelper`, `CLAUDE_CODE_OAUTH_TOKEN` 순으로 앞서고, `/login`으로 만든 구독 로그인은 맨 뒤입니다. 예전에 다른 프로젝트 때문에 셸 프로필에 넣어 둔 키가 있으면, 대화형에서는 한 번 승인한 뒤부터, `-p`에서는 승인 없이 그 키로 청구됩니다. 키가 비활성화된 조직 소속이면 인증 오류로 나타나기도 합니다.

![Claude Code 자격 증명 적용 순서: 클라우드 제공업체 설정, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY, apiKeyHelper, CLAUDE_CODE_OAUTH_TOKEN, 마지막으로 /login 구독 로그인, 그리고 /status와 Console Usage로 청구 경로를 확인하는 순서](https://blog.laozhang.ai/posts/ko/claude-api-vs-claude-code/img/credential-priority.webp)

**구독 로그인으로 내 제품을 돌리려 한다.** 개인 구독 토큰을 서버에 넣고 사용자 요청을 처리하는 구조는 앞의 규정상 허용되지 않습니다. 사용자에게 제공하는 기능은 처음부터 Console API 키나 클라우드 자격 증명으로 설계해야, 나중에 인증 구조를 통째로 바꾸는 일을 피할 수 있습니다.

## 지금 어느 경로로 청구되는지 확인하는 순서

1. Claude Code 안에서 `/status`를 실행합니다. 지금 쓰는 인증 방식이 표시되고, 로그인과 API 키가 둘 다 있으면 쓰지 않는 쪽이 따로 표시됩니다.
2. 구독으로 돌려야 하는데 API 키가 잡혀 있다면 `unset ANTHROPIC_API_KEY`로 환경 변수를 지우고, 셸 프로필에서도 해당 줄을 삭제합니다. 대화형에서는 `/config`의 "Use custom API key" 토글로도 키 사용 여부를 바꿀 수 있습니다.
3. API로 청구되는 사용량은 Claude Console의 Usage 페이지에서 확인합니다. `/usage`의 Session 비용은 정가 기준으로 로컬에서 계산한 추정치이며, Pro·Max 구독자에게는 청구와 관계없는 숫자입니다.
4. 구독 한도를 넘긴 뒤의 사용량이 궁금하다면 claude.ai로 로그인한 상태에서 `/usage-credits`를 실행해 usage credits가 켜져 있는지, 이번 달 지출과 한도가 얼마인지 봅니다. API 키 인증 상태에서는 이 명령을 쓸 수 없습니다.

증상별로 더 깊이 진단하고 되돌리는 방법은 [Claude Code API 키와 구독 결제: 어떤 경로를 써야 할까](https://blog.laozhang.ai/ko/posts/claude-code-api-key-vs-subscription-billing)에, 키·`settings.json`·게이트웨이 설정 순서는 [Claude Code API 설정: 키, settings.json, 모델, 게이트웨이 확인 순서](https://blog.laozhang.ai/ko/posts/claude-code-api-configuration)에 있습니다.

## 자주 묻는 질문

### Claude Code를 쓰려면 Claude API를 따로 결제해야 하나요?

아닙니다. Claude Code는 Pro(월 $20)와 Max 요금제에 포함되어 있어 claude.ai 계정으로 로그인하면 API 결제 없이 씁니다. Free 요금제에는 포함되지 않습니다. API 결제가 필요한 경우는 Console 키로 종량제로 돌리고 싶을 때, 또는 `--bare` 모드처럼 구독 로그인을 읽지 않는 실행 방식을 쓸 때입니다.

### Pro 구독이 있는데 API 키를 Claude Code에 넣어도 되나요?

넣을 수 있고, 넣으면 API 키가 구독 로그인보다 우선합니다. 대화형에서는 처음 한 번 승인을 묻고 그 선택을 기억하며, `-p`에서는 키가 있으면 항상 키를 씁니다. 두 가지를 번갈아 쓰려면 `/config`의 "Use custom API key" 토글이나 `unset ANTHROPIC_API_KEY`로 전환하고 `/status`로 확인하세요.

### 한국에서 Claude API와 Claude Code를 쓸 수 있나요?

쓸 수 있습니다. Anthropic의 지원 지역 목록에 대한민국이 포함되어 있어, 한국에서 claude.ai 구독과 Console 계정을 공식 경로로 만들 수 있습니다. 공식 요금표는 달러 기준이며 세금은 별도입니다.

### 회사가 AWS나 Google Cloud를 쓰면 어떻게 되나요?

Claude Code는 Amazon Bedrock, Google Cloud's Agent Platform(구 Vertex AI), Microsoft Foundry를 통해서도 실행할 수 있습니다. `CLAUDE_CODE_USE_BEDROCK`, `CLAUDE_CODE_USE_VERTEX`, `CLAUDE_CODE_USE_FOUNDRY` 같은 환경 변수를 설정하면 브라우저 로그인 없이 클라우드 자격 증명을 쓰고, 이 설정은 다른 모든 자격 증명보다 우선합니다. 사용량은 해당 클라우드 제공업체를 통해 청구되고, 조직이 맺어 둔 기존 상용 계약이 Claude Code 사용에도 적용됩니다.