클로드 코드 사용법·설치 오류·요금제 2026, 버그 수정 1건 8원

클로드 코드(Claude Code)는 말로 시키면 AI 가 내 컴퓨터의 파일을 직접 읽고 고치고 테스트까지 돌리는 Anthropic 의 코딩 도구예요. 무료 플랜에는 없고 Pro(월 $20)부터 써요. 요금표가 바뀌어(11월 3일 확인) 지금은 Pro·Max($100)·Ultra($200) 세 단계예요. 설치는 명령 한 줄이고, 윈도우는 PowerShell 에서 해요. 같은 버그 3개를 고치게 해 보니 API 로는 새 모델 Haiku 5.5 가 한 건에 8원, Sonnet 5.5 가 60원이었어요(2026-11-03 실측). 설치 오류와 사용 중 오류를 푸는 법도 함께 정리했어요.

글 서순명(웹 에이전시·SI 프로젝트 PM 10년, 솔리드그루 이사) · 운영 솔리드그루(사업자 875-44-00335 · 02-6933-6229 · support@futureinfra.ai) · 처음 작성 2026-10-01 · 가격 확인·실측·최종 수정 2026-11-03 서울 · 요금·한도는 Anthropic 공식 페이지 기준 · 이용약관 · 개인정보처리방침

클로드 코드가 뭐예요?

Anthropic 이 만든 AI 코딩 도구예요. 채팅창의 Claude 는 코드를 보여 주고, 사람이 복사해 붙여 넣어요. 클로드 코드는 프로젝트 폴더 안에서 직접 움직여요.

1. 파일을 찾아서 읽어요.
2. 고칠 곳을 고치고, 새 파일도 만들어요.
3. 테스트·빌드 같은 명령을 실행해 결과를 확인해요.
4. 안 되면 다시 고쳐요. 끝나면 무엇을 바꿨는지 알려 줘요.

터미널에서 쓰는 게 기본이에요. 데스크톱 앱, VS Code·JetBrains 같은 편집기, 웹에서도 쓸 수 있어요. 터미널이 낯설면 데스크톱 앱을 받아 화면에서 바로 써도 돼요. 같은 계정·같은 한도를 써요.

쉽게 말하면 옆자리 개발자에게 "이거 고쳐 줘" 하면 직접 키보드를 잡고 고쳐 주는 것과 같아요. 사람은 무엇을 원하는지 말하고, 결과를 확인하면 돼요.

클로드 코드 무료로 쓸 수 있어요?

무료 플랜으로는 못 써요. 공식 요금표의 플랜 비교에서 Free 칸만 클로드 코드가 빠져 있어요. 공식 설치 문서도 무료 claude.ai 플랜에는 포함되지 않는다고 적어 두었어요.

쓰는 길은 두 가지예요. 하나는 Pro 이상 구독이에요. 다른 하나는 Claude 콘솔에 선불로 충전하고 쓴 만큼 내는 API 방식이에요. 아주 가끔 쓸 거라면 API 쪽이 더 쌀 수 있어요. 얼마인지는 아래에서 직접 재 봤어요.

클로드 코드 설치는 어떻게 해요?

아래 순서는 공식 빠른 시작 문서와 설치 문서(2026-11-03 다시 확인)를 따랐어요. 준비물은 두 가지예요. 터미널, 그리고 Pro 이상 구독이나 Claude 콘솔(API) 계정이에요(요금은 아래 "요금제는 얼마예요?"에). 컴퓨터는 macOS 13, Windows 10(1809)·Windows Server 2019, Ubuntu 20.04, Debian 10, Alpine 3.19 이상에 메모리 4GB 이상이면 돼요. 한국은 지원 국가라 그대로 쓸 수 있어요.

1. 설치 명령 붙여 넣기

맥·리눅스는 터미널에, 윈도우는 PowerShell 에 붙여 넣고 엔터를 쳐요.

# 맥 · 리눅스 · WSL
curl -fsSL https://claude.ai/install.sh | bash

# 윈도우 PowerShell
irm https://claude.ai/install.ps1 | iex

윈도우에서 "'irm'은(는) 내부 또는 외부 명령…이 아닙니다"가 뜨면 CMD 창에 있는 거예요. PowerShell 을 열거나 문서의 CMD 용 명령을 쓰세요. Git for Windows 를 깔아 두면 좋아요. 없으면 클로드 코드가 PowerShell 로 명령을 실행해요.

패키지 관리자로도 깔 수 있어요. 맥은 brew install --cask claude-code, 윈도우는 winget install Anthropic.ClaudeCode 예요. 이 둘은 저절로 업데이트되지 않아서 가끔 brew upgrade·winget upgrade 를 쳐야 해요. npm 으로 깔 때는 Node.js 22 이상이 필요하고, sudo 는 쓰지 말라고 공식 문서가 권해요.

npm install -g @anthropic-ai/claude-code

2. 설치 확인

터미널을 새로 열고 아래를 쳐요. 2.1.317 (Claude Code) 처럼 버전 숫자가 나오면 끝이에요. 11월 3일 기준 최신 버전은 2.1.317(11월 2일), 한 주쯤 늦게 따라가는 안정판(stable)은 2.1.311 이에요(npm 기록). 문제가 있으면 claude doctor 가 세션을 열지 않고 설치 상태와 설정 오류를 알려 줘요.

claude --version

3. 프로젝트 폴더에서 실행하고 로그인

cd 내-프로젝트-폴더
claude

처음 실행하면 브라우저가 열려요. Claude 계정(Pro·Max)이나 콘솔 계정으로 로그인하면 돼요. 나중에 계정을 바꾸려면 /login 을 쳐요.

4. 첫 질문 던지기

"이 프로젝트가 뭐 하는 건지 설명해 줘"처럼 시작해 보세요. 클로드 코드가 필요한 파일을 알아서 읽어요. 고쳐 달라고 하면 바꿀 내용을 보여 주고 고쳐요. 기본 설치는 백그라운드에서 스스로 업데이트돼요. 바로 올리려면 claude update 를 쳐요.

윈도우에서는 어떻게 설치해요?

윈도우는 그냥 윈도우에 깔거나, WSL(윈도우 안의 리눅스)에 깔 수 있어요. 대부분은 그냥 윈도우로 충분해요. 관리자 권한은 필요 없어요.

1. PowerShell 열기 시작 메뉴에서 "PowerShell" 을 찾아 열어요. 줄 앞이 PS C:\Users\이름> 이면 PowerShell, PS 없이 C:\ 로 시작하면 CMD 예요. "Windows PowerShell (x86)" 은 32비트라 안 돼요.
2. 명령 붙여 넣기 PowerShell 이면 irm https://claude.ai/install.ps1 | iex, CMD 면 아래 CMD 줄을 써요. 받는 동안 진행 표시가 없으니 끝날 때까지 기다려요.
3. 새 창에서 확인 PowerShell 을 닫고 새로 열어 claude --version 을 쳐요. 설치 위치가 PATH(명령을 찾는 경로)에 들어가는 건 새 창부터예요.
4. Git for Windows(선택)를 깔아 두면 클로드 코드가 Git Bash 로 명령을 돌려요. 없으면 PowerShell 로 돌려요.

# 윈도우 PowerShell
irm https://claude.ai/install.ps1 | iex

# 윈도우 CMD
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

# 또는 WinGet
winget install Anthropic.ClaudeCode

VS Code 를 쓴다면 확장으로도 돼요. VS Code 1.94 이상에서 Ctrl+Shift+X 로 확장 화면을 열고 "Claude Code" 를 찾아 설치하면, 오른쪽 패널에서 대화하며 바뀐 코드를 바로 봐요. 커서(Cursor)에도 같은 확장이 깔려요. 확장 안에 CLI 가 들어 있지만, VS Code 터미널에서 claude 를 치려면 위 설치를 따로 해야 해요(VS Code 안내).

설치 오류는 어떻게 해결해요?

오류 문장을 그대로 아래 표에서 찾으세요. 공식 설치 문제 해결 문서(2026-11-03 확인)에서 자주 만나는 것만 골랐어요.

로그인에서 막히면 이렇게 봐요. API Error: 403 Request not allowed 는 구독이 꺼져 있거나(claude.ai 설정에서 확인) 콘솔 계정에 Claude Code 역할이 없는 경우예요. 원격 서버·WSL 에서 브라우저 로그인이 안 되면 공식 문서의 OAuth 항목을 따라요.

클로드 코드 요금제는 얼마예요?

요금표가 바뀌었어요(11월 3일 확인). 예전 Max 5x($100)·Max 20x($200) 두 칸이 Max($100) 와 Ultra($200) 로 바뀌었어요. 11월 3일 Claude 공식 요금제에서 확인한 값이에요.

원화는 2026년 11월 3일 환율(1달러 1,344.13원)로 계산했어요. 위 달러 값은 세금 전 기준이에요. 한국에서 공식 요금표를 열면 부가세 10%를 더한 값(Pro $22·Max $110·Ultra $220)으로 보여요(2026-11-03 확인). 아이폰 앱으로 결제하면 값이 달라지니, 원화 결제 차이는 클로드 요금제 글을 보세요.

Max 는 Pro 의 기능을 다 쓰면서 5시간마다·매주 Pro 의 5배를 써요. Ultra 는 매주 Pro 의 10배이고, 인증한 계정은 5시간 한도가 없어요. 두 요금제 모두 가장 큰 모델인 Fable 을 주간 한도의 절반까지 쓰고, 클로드 플랫폼(API)에 쓸 크레딧을 매달 줘요(Max $100, Ultra $200). Pro 에서 Fable 은 사용량 크레딧을 따로 내야 써요.

예전 Max 20x 를 쓰던 사람이 어떻게 옮겨지는지는 공식 안내에서 확인하지 못했어요. 결제 화면(설정 > 결제)에서 지금 요금제를 확인하세요.

사용량 한도는 어떻게 돌아가요?

한도는 두 겹이에요. 5시간 단위로 다시 차는 세션 한도가 있어요. 유료 플랜은 그 위에 주간 한도가 하나 더 있어요. 주간 한도가 다시 차는 날은 계정마다 달라요. Ultra 는 인증한 계정이면 5시간 한도 없이 주간 한도만 있어요.

주의할 점이 하나 있어요. 웹·데스크톱·모바일 채팅과 클로드 코드가 같은 통에서 꺼내 써요. 낮에 채팅을 많이 하면 저녁에 코딩할 몫이 줄어요.

"메시지 몇 개"처럼 정해진 숫자는 없어요. 대화 길이, 읽는 파일 크기, 고른 모델, 쓰는 기능에 따라 한 번에 쓰는 양이 달라져요. 한도 규칙은 공식 요금제 페이지의 자주 묻는 질문과 클로드 코드 비용 관리 문서에 나와 있어요.

클로드 코드 사용량 확인은 어떻게 해요?

클로드 코드 안에서 /usage 를 치면 돼요. /cost 도 같은 화면이에요. 구독 중이면 남은 양 막대와 최근 사용 내역이 나와요. 스킬이나 MCP 가 몇 %를 썼는지도 보여 줘요. d·w 키로 최근 24시간과 7일을 바꿔 봐요. claude.ai 의 설정 > 사용량 화면에서도 볼 수 있어요.

/usage

한도에 걸리면 어떻게 해요?

"You've hit your session limit · resets 3:45pm"(세션 한도), "You've hit your weekly limit · resets Mon 12:00am"(주간 한도) 같은 메시지가 떠요. 메시지 끝에 다시 열리는 시각이 나와요. 다 쓰기 전에 "You've used 85% of your session limit" 같은 미리 알림도 떠요. 할 수 있는 일은 세 가지예요.

1. 다시 찰 때까지 기다려요.
2. 더 높은 요금제로 올려요.
3. 사용량 크레딧을 켜요. 한도를 넘긴 만큼 API 표준 요금으로 내고 계속 써요. /usage-credits 로 열어요.

"You've hit your Opus limit"처럼 모델 이름이 붙은 메시지라면 사정이 달라요. /model 로 다른 모델 계열로 바꾸면 이어서 쓸 수 있어요. 세션·주간 한도는 모델을 바꿔도 풀리지 않아요(공식 오류 안내).

쓰다가 뜨는 오류(500·529·429·401)는요?

설치는 됐는데 쓰는 중에 "API Error" 가 뜨는 경우예요. 대부분 내 잘못이 아니에요. 공식 오류 안내 기준으로 정리했어요.

API 로 쓰면 작업 하나에 얼마예요?

직접 재 봤어요. 작은 쇼핑몰 장바구니 코드(파이썬 파일 3개)에 버그 3개를 심었어요. 합계에서 마지막 상품이 빠지고, 5만 원 무료배송 경계가 틀리고, 10% 쿠폰이 100%로 계산되는 버그예요. 테스트 6개는 처음에 모두 실패해요.

AI 에게는 도구 4개만 줬어요. 파일 목록 보기, 읽기, 쓰기, 테스트 실행이에요. 그리고 "테스트가 실패해요. 고쳐 주세요"라고만 했어요. AI 가 스스로 파일을 읽고 고치고 테스트를 돌리게 했어요. 클로드 코드가 일하는 방식을 그대로 따라 했어요.

퓨쳐인프라 AI 라우터로 모델 4개를 3번씩 돌렸어요. 비용은 매번 응답에 찍힌 실제 청구액(원)을 더했어요. 이 청구액은 제공사가 매긴 실제 원가에 정해진 마진과 환율을 적용한 값이에요(퓨쳐인프라 요금). 구독 값의 원화는 11월 3일 환율(1달러 1,344.13원) 하나로 계산했어요. 실측 비용은 응답에 찍힌 원화 청구액 그대로예요. 환율로 바꾼 값을 쓰지 않았어요.

모델 id   anthropic/claude-haiku-4.5 · claude-sonnet-5.5 · claude-opus-5.5 · claude-fable-5.1
설정      max_tokens 8000 · 캐시 안 씀 · 최대 20번 왕복 · 생각 강도 기본값
도구      list_files · read_file · write_file(테스트 파일은 못 고침) · run_tests(python -m unittest)
시스템    "You are a coding agent working in a small Python project. Use the tools to inspect
           files, fix the code, and run the tests. Do not edit the test file. When all tests
           pass, reply with a one-paragraph summary in Korean of what you changed."
사용자    "테스트가 실패해요. 원인을 찾아서 고쳐 주세요. 테스트 파일은 바꾸지 마세요."

심은 버그 3개
cart.py      for i in range(len(items) - 1):        # 마지막 상품이 합계에서 빠져요
cart.py      if amount > FREE_SHIPPING_FROM:          # 딱 5만 원이면 배송비가 붙어요
coupons.py   return amount - amount * c["value"] // 10   # 10% 쿠폰이 100% 할인이 돼요
판정      작업이 끝난 뒤 테스트 6개를 다시 돌려 모두 통과하고, 테스트 파일이 그대로면 성공

AI 가 고친 결과(Sonnet 5.5, 기록한 회차)
cart.py      for i in range(len(items)):
cart.py      if amount >= FREE_SHIPPING_FROM:
coupons.py   return amount - amount * c["value"] // 100

버그 3개를 빠짐없이 찾았다는 뜻이에요. 눈에 띈 점은 세 가지예요.

• Haiku 4.5 는 토큰 값이 Sonnet 5.5 의 절반이에요. 그런데 7번 오가며 파일을 더 읽어서, 읽은 양이 22,047토큰으로 두 배를 넘었어요. 결국 58원으로 비슷하게 끝났어요.
• Opus 5.5 는 117원으로 Sonnet 5.5 의 약 2배였어요. 이 정도 쉬운 일에서는 결과 차이가 없었어요.
• Fable 5.1 은 296원, 34.0초로 가장 비싸고 느렸어요. 큰 일을 오래 맡기는 모델이라 작은 버그에는 과해요.

새로 나온 Haiku 5.5 는요?

10월에 Haiku 5.5 가 나왔어요. 100만 토큰당 읽는 값 $0.10, 쓰는 값 $0.50 으로 Haiku 4.5 의 10분의 1이에요. 11월 3일 같은 과제·같은 지시로 Haiku 5.5 와 Sonnet 5.5 를 3번씩 다시 돌렸어요.

Haiku 5.5 는 Sonnet 5.5 보다 파일을 더 읽고(약 1.5배) 더 길게 썼지만, 토큰 값이 워낙 싸서 한 건 8원에 끝났어요. 시간은 Sonnet 5.5 가 조금 빨랐어요. Pro 한 달 값(26,883원)이면 이 작은 과제를 API 의 Haiku 5.5 로 3,000번 넘게 돌릴 수 있는 셈이에요. 클로드 코드에서는 /model haiku 로 고르고, Haiku 5.5 는 v2.1.293 이상에서 써요(모델 설정 문서).

AI 가 실제로 한 일은요?

Sonnet 5.5 로 한 번 더 돌리며 단계별로 기록했어요. 총 12.6초, 61원이었어요.

처음엔 테스트부터 돌려 6개가 실패하는 걸 확인했어요. 그다음 파일 3개를 한꺼번에 읽고, 두 파일을 고친 뒤 테스트를 다시 돌렸어요. 마지막엔 "반복문이 마지막 상품을 빠뜨렸다", "정확히 5만 원일 때 무료배송이 안 됐다", "10% 쿠폰이 100%로 계산됐다"고 원인 3개를 한국어로 정리해 답했어요. 뒤로 갈수록 읽는 양이 늘어요. 앞의 대화를 매번 다시 보내기 때문이에요.

Pro 한 달 값(26,883원, 11월 3일 환율)이면, 이 작업을 API 의 Sonnet 5.5 로 약 448번 할 수 있는 돈이에요. 다만 이번 과제는 파일 3개짜리라 아주 작아요. 실제 프로젝트는 읽는 파일이 많아요. 클로드 코드는 지침·도구 설명도 같이 보내요. 그래서 한 건에 몇 배에서 몇십 배가 들 수 있어요.

현실 기준은 공식 문서에 있어요. 기업에서 클로드 코드를 쓰는 개발자 1명은 일하는 날 하루 평균 약 $13(약 17,500원)어치를 써요. 한 달로는 $150~250어치예요. 90%는 하루 $30 아래였어요. 이 숫자로 보면 매일 쓰는 사람은 정액 구독이 대개 유리해요. 가끔 쓴다면 API 가 싸요.

모델별 API 값은요?

2026년 11월 3일 다시 확인한 Anthropic 공식 가격이에요(Haiku 5.5 추가, 나머지는 10월 1일과 같아요). "읽는 값"은 AI 에게 보내는 글, "쓰는 값"은 AI 가 돌려주는 글의 값이에요. 클로드 코드는 같은 내용을 반복해 보내서, 저장해 둔 내용을 다시 읽는 캐시 값(Opus 5.5 기준 100만 토큰당 $0.20)이 많이 쓰여요.

자주 쓰는 명령은 뭐예요?

그 밖에 Shift+Tab 으로 계획 모드에 들어가면, 고치기 전에 계획부터 보여 줘요. 엉뚱한 방향으로 가면 Esc 로 바로 멈춰요.

사용량 아끼는 법은요?

Pro·Max·Ultra·Team 의 기본 모델은 Opus 5.5 예요(모델 설정 문서, 11-03 확인). 공식 문서는 대부분의 코딩은 Sonnet 이 잘하고 더 싸다고 안내해요. 우리 실측에서도 Sonnet 5.5 가 Opus 5.5 의 절반 값에 더 빨랐고, 작은 수정은 Haiku 5.5 도 다 해냈어요.

커서·코덱스와 뭐가 달라요?

커서(Cursor)는 AI 가 들어간 코드 편집기예요. 코덱스(Codex)는 OpenAI 의 코딩 에이전트로, ChatGPT 요금제에 들어 있어요. 클로드 코드는 터미널에서 시작해 편집기·데스크톱·웹으로 넓힌 도구예요. 요금과 한도 방식은 서비스마다 달라요. 어떤 걸 고를지는 바이브코딩 시작법을 다룬 바이브코딩 글에서 이어서 다뤄요.

클로드 코드에 MCP 를 붙이면 뭐가 돼요?

MCP 로 다른 서비스를 연결하면 클로드 코드가 그 서비스의 기능까지 써요. 퓨쳐인프라 MCP 를 붙이면 서버·앱·도메인을 말로 만들 수 있어요. 터미널에 한 줄을 넣고, 클로드 코드에서 /mcp 로 로그인하면 돼요. 키는 복사하지 않아도 돼요.

claude mcp add --transport http futureinfra https://futureinfra.ai/v1/mcp
# 그다음 클로드 코드에서
/mcp

연결한 뒤에는 이렇게 말하면 돼요. "퓨쳐인프라로 가게 소개 홈페이지를 만들어서 인터넷에 올려 줘. 다 되면 접속 주소와 한 달 예상 요금을 알려 줘." 앱 하나는 월 5,500원(부가세 포함)이에요. MCP 가 어떻게 움직이는지는 MCP 용어 글에 정리해 두었어요.

퓨쳐인프라 AI 라우터에서는 Claude 모델을 쓴 만큼 원화로 내요. 위 실측도 여기서 했어요. 같은 키로 300개 넘는 모델을 부를 수 있고, 충전한 지갑에서 빠져요. Opus 5.5 를 자세히 잰 결과는 Claude Opus 5.5 글에 있어요.

나한테 맞는 건 뭐예요?

자주 묻는 질문

클로드 코드는 무료인가요?

아니에요. 무료 플랜에는 없고 Pro(월 $20)부터 써요. 구독 없이 쓰려면 Claude 콘솔에 선불로 충전해 쓴 만큼 내는 API 방식이 있어요.

클로드 코드 가격은 원화로 얼마예요?

2026년 11월 3일 환율로 Pro 약 26,900원, Max 약 134,400원, Ultra 약 268,800원이에요. 이 값은 세금 전 기준이고, 한국에서는 부가세 10%가 더해진 Pro $22·Max $110·Ultra $220 으로 표시돼요.

클로드 코드 사용량은 언제 초기화돼요?

세션 한도는 5시간 단위로 다시 차요. 유료 플랜은 주간 한도가 따로 있고, 계정마다 정해진 날에 다시 차요. 한도 메시지 끝에 다시 열리는 시각이 적혀 있어요. Ultra 는 5시간 한도가 없어요.

클로드 코드 사용량은 어떻게 확인해요?

클로드 코드 안에서 /usage 를 치면 남은 양과 최근 사용 내역이 나와요. claude.ai 설정의 사용량 화면에서도 볼 수 있어요.

API 로 쓰면 비싸지 않나요?

작은 버그 3개를 고치는 작업이 Sonnet 5.5 로 60~61원, Haiku 5.5 로 8원이었어요. 실제 프로젝트는 몇 배에서 몇십 배 들 수 있어요. 매일 몇 시간 쓰면 구독이, 가끔이면 API 가 대개 싸요.

모델은 뭘 써야 해요?

평소엔 Sonnet 이 빠르고 싸요. 어려운 설계나 여러 단계 추론에 Opus 를 쓰세요. 우리 실측에서 Sonnet 5.5 는 Opus 5.5 의 절반 값이었어요. 작은 수정은 Haiku 5.5 가 더 싸요.

윈도우에 클로드 코드를 어떻게 설치해요?

PowerShell 을 열고 irm https://claude.ai/install.ps1 | iex 를 붙여 넣어요. CMD 라면 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd 예요. 끝나면 새 창에서 claude --version 으로 확인해요.

설치했는데 'claude' 를 인식하지 못해요.

터미널을 닫고 새로 열어요. 설치 위치가 PATH 에 들어가는 건 새 창부터예요. 그래도 안 되면 claude doctor 를 쓸 수 없으니 공식 설치 문제 해결 문서의 PATH 확인 단계를 따라요.

529 Overloaded 오류는 내 한도를 다 쓴 건가요?

아니에요. 모든 사용자가 몰려 Anthropic 서버 용량이 찬 거예요. 사용량이 깎이지 않아요. 몇 분 뒤 다시 하거나 /model 로 다른 모델로 바꿔요.

Max 와 Ultra 는 뭐가 달라요?

Max(월 $100)는 5시간마다·매주 Pro 의 5배를 써요. Ultra(월 $200)는 매주 Pro 의 10배이고, 인증한 계정은 5시간 한도가 없어요. 매달 주는 API 크레딧도 Max $100, Ultra $200 이에요.

이 글의 숫자는 어디서 왔나요?

부록 — 실측 원자료

10월 1일 모델 4개 × 3번, 11월 3일 모델 2개 × 3번, 모두 같은 과제·같은 지시예요. "오간 횟수"는 AI 에게 요청을 보낸 횟수예요.