Claude Code 설치 및 Ollama, llama.cpp 구성, 가격 정책

에이전트 코딩, 이제 로컬 모델 백엔드로.

Page content

Claude Code 는 더 나은 마케팅을 가진 자동 완성 도구가 아닙니다. 이는 에이전트 기반 코딩 도구로, 코드베이스를 읽고 파일을 편집하며 명령을 실행하고 개발 도구와 통합됩니다.

이 차이는 업무의 단위가 “코드 한 줄"에서 “최종 상태가 있는 작업"으로 바뀌기 때문에 중요합니다.

Anthropic 은 이 구분을 명확히 설명합니다. 코드 완성 도구는 타이핑하는 동안 다음 줄을 제안하는 반면, Claude Code 는 프로젝트 수준에서 작동하며 여러 파일을 아우르는 계획을 세우고 변경 사항을 실행하며 테스트를 수행하고 실패 시 반복합니다. 실제로 이는 빠르게 잡무를 처리할 수 있지만 여전히 검토가 필요한 터미널 네이티브 주니어 엔지니어와 더 유사한 존재입니다.

그러한 속도와 감독 사이의 긴장감이 사람들이 “바이브 코딩 (Vibe Coding)“이라는 용어에 묶어 넣는 많은 요소입니다. What is Vibe Coding? 에서는 이 용어의 의미, 기원, 그리고 실제 효율성과 위험이 어떤 모습인지 설명합니다.

laptop-homeresver-claude-code-coffee-books

문서를 훑어볼 때 놓치기 쉬운 세부 사항이 하나 있습니다. 터미널 CLI(및 VS Code 인터페이스) 는 서드파티 제공자를 사용하도록 구성할 수 있습니다. 바로 여기서 Ollama 와 llama.cpp 가 등장합니다.

Claude Code 가 로컬 HTTP 엔드포인트를 지시하면, 런타임, 하드웨어 및 호스팅의 트레이드오프는 클라이언트 외부에 있게 됩니다. this comparison of LLM hosting in 2026 에서는 Ollama, 전용 추론 스택 및 클라우드 옵션을 한곳에 정리하여 비교합니다.

Claude Code 가 AI 기반 코딩 및 배포 워크플로우의 다른 도구들과 어떻게 비교되는지 보려면, this guide to AI developer tools 에서 Copilot 스타일의 어시스턴트, 자동화 및 에디터 패턴을 한곳에 정리한 가이드를 참조하세요.

동일한 범주에 속하는 코딩 어시스턴트의 도구별 조사를 원한다면, AI Coding Assistants Comparison 에서 이 설치 가이드보다 더 높은 수준에서 Cursor, Copilot, Cline 등 다른 도구들을 살펴볼 수 있습니다.

Claude Code 설치 및 빠른 시작

설치 옵션과 그 의미

여러 설치 경로가 있으며, 이들은 모두 동일하지 않습니다:

  • 네이티브 설치 스크립트는 자동 업데이트되므로 “항상 최신” 옵션입니다.
  • Homebrew 와 WinGet 은 명시적으로 업그레이드하므로 “제어된 변경” 옵션입니다.

설치 명령어 (공식 빠른 시작):

# macOS, Linux, WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

:: Windows CMD
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

그런 다음 프로젝트 폴더에서 인터랙티브 세션을 시작합니다:

cd /path/to/your/project
claude

로그인 및 계정 유형

Claude Code 를 1 차 모드로 실행하려면 계정이 필요합니다. 빠른 시작 플로우에서는 Claude 구독 (Pro, Max, Team, Enterprise), 콘솔 계정 (API 크레딧) 또는 지원되는 클라우드 제공자를 통한 로그인을 지원합니다. 유용한 운영상의 참고 사항: 콘솔에 처음 로그인하면 중앙 집중식 비용 추적을 위해 “Claude Code” 워크spaces 가 생성됩니다.

Claude Code 설정: settings.json 및 환경 변수

Claude Code 가 작동할 때 마법처럼 느껴진다면, 작동하지 않을 때는 종종 “신비하게” 느껴집니다. 해결책은 설정 계층화와 실제로 중요한 몇 가지 환경 변수를 이해하는 것입니다.

설정 파일과 우선순위

Claude Code 설정은 계층적이며 개발자가 직접 사용하는 세 가지 파일이 있습니다:

  • 사용자 범위 (전역 적용): ~/.claude/settings.json
  • 프로젝트 범위 (저장소 공유): .claude/settings.json
  • 로컬 범위 (기기별 오버라이드): .claude/settings.local.json (gitignored)

우선순위는 (높은 순서부터 낮은 순서까지): 관리 정책, CLI 플래그, 로컬, 프로젝트, 사용자입니다. 이 순서는 “왜 내 설정이 무시되나요?“라는 순간들을 설명합니다.

/config 명령을 통해 REPL 내부에서 설정 UI 를 열어 인터랙티브하게 설정을 관리할 수 있습니다.

제공자 라우팅을 제어하는 환경 변수

Claude Code 는 환경 변수를 통해 런타임 시 조종될 수 있습니다. 두 가지 동작 특성은 설계 제약으로 다루는 것이 좋습니다:

  1. ANTHROPIC_API_KEY 가 설정되면, 로그인 상태일지라도 Claude Code 는 구독 대신 해당 키를 사용합니다. 인쇄 모드 (-p) 에서는 키가 존재할 때 항상 사용됩니다.

  2. ANTHROPIC_BASE_URL 이 1 차 호스트가 아닌 (프록시, 게이트웨이 또는 로컬 서버) 곳으로 가리키면, 일부 기능이 의도적으로 보수적으로 작동합니다. 예를 들어, MCP 도구 검색은 명시적으로 재활성화하지 않는 경우 기본적으로 비활성화됩니다.

간단한 “게이트웨이 사용” 패턴은 다음과 같습니다:

export ANTHROPIC_BASE_URL=https://your-gateway.example
export ANTHROPIC_API_KEY=sk-your-key

게이트웨이 참고 사항: Claude Code 는 특정 API 포맷을 기대합니다. Anthropic Messages 포맷의 경우, 게이트웨이는 /v1/messages 및 /v1/messages/count_tokens 를 노출해야 하며 anthropic-beta 와 anthropic-version 헤더를 포워딩해야 합니다. 게이트웨이가 이러한 헤더를 거부하는 경우, 실험적 베타를 제거하는 전용 설정이 있습니다.

Anthropic 을 직접 사용하지 않을 때의 Claude Code 모델 선택

Claude Code 는 별칭 (opus, sonnet, haiku) 개념을 가지며 특정 모델 ID 를 고정하는 것도 지원합니다. 또한 서드파티 제공자를 통해 라우팅되더라도 모델 선택기에서 사용자가 선택할 수 있는 모델을 제한하는 허용 목록이 있습니다.

실용적인 패턴은 초기 모델을 설정하고 선택기를 제한한 다음, env 를 통해 “기본값"이 해결되는 모델을 고정하는 것입니다:

{
  "model": "claude-sonnet-4-5",
  "availableModels": ["claude-sonnet-4-5", "haiku"],
  "env": {
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4-5"
  }
}

Ollama 를 통한 자체 호스팅 LLM 실행

Ollama 는 현재 Claude Code 가 Anthropic 모델이 아닌 모델에서 실행되도록 만드는 가장 마찰이 적은 방법입니다. Claude Code 가 대화할 수 있도록 Anthropic 호환 API 를 노출하기 때문입니다.

ollama launch 를 통한 빠른 설정

Ollama 가 설치되어 실행 중이라면 빠른 경로는 다음과 같습니다:

ollama launch claude

또는 실행 시 모델을 지정합니다:

ollama launch claude --model glm-4.7-flash

명시적 환경 변수를 통한 수동 설정

Ollama 통합 문서에는 Claude Code 가 Anthropic 호환 API 엔드포인트를 통해 Ollama 와 대화하는 간단한 수동 배선 방법을 설명합니다:

export ANTHROPIC_AUTH_TOKEN=ollama
export ANTHROPIC_API_KEY=""
export ANTHROPIC_BASE_URL=http://localhost:11434

claude --model qwen3.5

이 패턴은 유용한 방식으로 의견이 있습니다: “제공자 라우팅"을 GUI 에서 클릭하는 것이 아닌 환경 문제로 취급합니다.

컨텍스트 윈도우 현실 점검

에이전트 코딩은 컨텍스트에 굶주립니다. Ollama 는 이를 단호하게 지적합니다: Claude Code 는 큰 컨텍스트 윈도우가 필요하며 최소 64 토큰 이상을 권장합니다. 로컬 모델이 8k 또는 16k 로 제한되면 Claude Code 는 여전히 실행되지만, “프로젝트 수준"의 약속은 취약해집니다.

비슷한 터미널 에이전트 설정 (Ollama 와 llama.cpp, 코딩 작업, 그리고 솔직한 실패 노트) 에서의 실제 로컬 모델 동작에 대해, Best LLMs for OpenCode - Tested Locally 는 Claude Code 를 위해 GGUF 또는 Ollama 태그를 단축할 때 유용한 교차 검증 자료입니다.

llama.cpp 를 통한 자체 호스팅 LLM 실행

llama.cpp 는 반대되는 이유로 매력적입니다: 플랫폼이 되려고 하지 않기 때문입니다. 이는 빠르게 OpenAI 호환 경로와 Anthropic Messages API 호환 경로를 모두 노출할 수 있는 경량 서버입니다.

설치 경로, llama-cli, 및 llama-server 동작에 대한 아래 스니펫을 넘어선 내용은 llama.cpp Quickstart with CLI and Server 에서 엔드투엔드 참조 자료로 제공됩니다.

서버 측에서 실행할 내용

llama.cpp HTTP 서버 (llama-server) 는 SSE 를 통한 스트리밍과 함께 POST /v1/messages 에서 Anthropic 호환 Messages API 를 지원합니다. 또한 /v1/messages/count_tokens 에서 count_tokens 를 제공합니다.

Claude Code 에 중요한 두 가지 세부 사항이 있습니다:

  • 서버는 전체 Anthropic API 사양 호환성에 대한 강력한 주장을 명시적으로 하지 않지만, 많은 애플리케이션에서 충분히 잘 작동한다고 명시합니다.
  • 도구 사용은 llama-server 를 –jinja 플래그로 시작해야 합니다. 이를 놓치면 Claude Code 는 에이전트처럼 작동하는 법을 갑자기 잊어버린 것처럼 행동합니다.

최소한의 로컬 실행은 다음과 같습니다:

# llama-server 빌드 또는 다운로드 후 GGUF 모델과 함께 실행
./llama-server -m /models/your-model.gguf --jinja --host 127.0.0.1 --port 8080

강력한 인증 경계를 원한다면, llama-server 는 API 키로 구성할 수 있습니다:

./llama-server -m /models/your-model.gguf --jinja --api-key my-local-key --host 127.0.0.1 --port 8080

llama-server 에 Claude Code 연결

서버가 실행 중이면, Claude Code 측에서는 대부분 기본 URL 오버라이드입니다:

export ANTHROPIC_BASE_URL=http://127.0.0.1:8080
export ANTHROPIC_API_KEY=my-local-key   # llama-server 에서 --api-key 를 활성화한 경우에만

claude --model your-model-alias

API 키 또는 인증 토큰을 설정하지 않으면, Claude Code 는 구독 로그인을 시도할 수 있으며, 이는 “왜 브라우저를 여나요?“라는 불만의 주요 원인입니다.

헬스 체크 및 첫 실패 트라이아지

llama-server 는 모델이 준비될 때까지 “모델 로딩 중"을 반환하고 사용 가능하면 “ok"를 반환하는 간단한 헬스 엔드포인트를 노출합니다. Claude Code 가 첫 요청에서 멈춘 것처럼 보일 때, /health 를 확인하면 “클라이언트 설정 버그"와 “서버 로딩 중"을 구분하는 빠른 방법입니다.

가격 및 비용 모델

Claude Code 가격은 “CLI 를 구매하는 것"보다는 “토큰을 뒷받침하는 결제 레일"에 더 가깝습니다.

구독 플랜에는 Claude Code 포함

Anthropic 은 유료 Claude 구독 티어에 Claude Code 를 포함합니다. 2026 년 4 월 기준, 공개된 가격 목록은 다음과 같습니다:

  • Pro 는 연간 할인 ($200 선납) 으로 월 $17, 또는 월 $20 과 함께 제공되며 Claude Code 를 포함합니다.
  • Max 플랜은 월 $100 부터 시작합니다.
  • Team 플랜은 좌석당 가격으로, 표준 좌석은 연간 결제 시 좌석당 월 $20 (월 $25), 프리미엄 좌석은 연간 결제 시 좌석당 월 $100 (월 $125) 입니다.

API 토큰 가격

API 결제를 통해 Claude Code 를 사용하면 비용은 토큰 레이트에 따릅니다. Anthropic 은 다음과 같은 모델의 백만 토큰 (MTok) 당 가격을 공개합니다:

  • Haiku 4.5: 입력 $1/MTok, 출력 $5/MTok
  • Sonnet 4.5: 입력 $3/MTok, 출력 $15/MTok
  • Opus 4.5: 입력 $5/MTok, 출력 $25/MTok

CLI 의 비용 제어

인쇄 모드 (-p) 는 –max-budget-usd 와 같은 직접 예산 상한을 지원하여, 스크립트 작업을 할 때 예측 가능한 지출을 원할 때 유용합니다.

인터랙티브 세션 내부에서는 /cost 명령으로 토큰 사용 통계를 확인할 수 있습니다.

로컬 백엔드는 물리학이 아닌 청구서만 변경

Claude Code 를 Ollama 또는 llama.cpp 로 라우팅하면 토큰당 API 청구는 사라지지만, 작업이 무료는 아닙니다. 클라우드 비용을 로컬 컴퓨팅, 메모리 및 “누군가가 가용성을 책임진다"는 것으로 바꾸는 것입니다. 일부 팀에게는 이 트레이드가 전체 목적입니다.

일반적인 워크플로우: 계획에서 PR 까지

제 견해는 Claude Code 를 챗봇이 아닌 워크플로우 엔진으로 취급할 때 가장 강력하다는 것입니다. 도구는 이를 암시합니다.

프롬프트가 아닌 권한 모델부터 시작

Claude Code 는 설계상 권한 게이트입니다. 문서는 계층적 모델을 설명합니다: 파일 읽기 및 grep 과 같은 읽기 전용 작업은 허용되지만, bash 명령 및 파일 수정은 승인이 필요합니다.

권한 모드는 마찰을 관리하기 위해 존재합니다. CLI 에서 Shift+Tab 으로 모드를 순환할 수 있습니다 (기본 -> acceptEdits -> plan). Plan 모드는 읽기 및 변경 제안만 하고 편집하지 않습니다. acceptEdits 모드는 Claude Code 가 프롬프트 없이 작업 디렉토리에서 파일을 생성하고 편집할 수 있게 하지만, 안전한 목록 외부의 부작용이 있는 명령에는 여전히 프롬프트를 표시합니다.

Auto 모드는 승인 분류기로 승인을 위임하여 프롬프트를 줄이는 더 새로운 옵션으로, 지속적인 프롬프트와 프롬프트 완전 비활성화 사이의 안전한 중간 경로로 포지셔닝됩니다. 이는 최소 Claude Code 버전과 특정 플랜 및 모델 요구 사항이 필요합니다.

내장 명령을 사용하여 세션을 정직하게 유지

몇 가지 명령은 Claude Code 를 “어시스턴트"에서 “도구"로 만듭니다:

  • /init 는 CLAUDE.md 프로젝트 가이드를 생성하여 일관된 컨텍스트를 공급하는 경량 방법입니다.
  • /diff 는 변경 사항의 인터랙티브 뷰를 제공하며 턴별 diff 를 포함합니다.
  • /rewind 는 체크포인트를 사용하여 대화 및/또는 코드를 이전 지점으로 되돌립니다.
  • /debug 는 세션 중간에 디버그 로깅을 활성화합니다.
  • /doctor 는 설치 및 설정을 진단하고 검증합니다.

이것들은 장난감이 아닙니다. 에이전트가 예상보다 더 많이 편집할 때 의지하는 안전 장치입니다.

비인터랙티브로 전환할 때

일회성 작업 (설명, 요약, 패치 계획 생성) 에는 인쇄 모드가 적합합니다:

claude -p "Summarise the repository architecture and list the riskiest modules"

이는 답변 후 종료되므로 스크립트 및 CI 에서 잘 작동합니다.

문제 해결 체크리스트

대부분의 Claude Code 문제는 위장된 설정 문제입니다. 여기 일반적인 증상을 근본 메커니즘으로 매핑하는 체크리스트가 있습니다.

로컬 서버 사용 중에도 Claude Code 가 계속 로그인하라고 요청함

이는 일반적으로 Claude Code 가 여전히 1 차 구독 인증을 사용하려고 시도한다는 것을 의미합니다. 프록시를 위한 명시적 인증 모드를 설정했는지 확인하세요:

  • X-Api-Key 를 기대하는 게이트웨이의 경우 ANTHROPIC_API_KEY 를 설정하세요.
  • 또는 Authorization Bearer 를 사용하는 게이트웨이의 경우 ANTHROPIC_AUTH_TOKEN 을 설정하세요.

로그인 상태일지라도 ANTHROPIC_API_KEY 가 구독 사용을 오버라이드한다는 것을 기억하세요. 인터랙티브 모드에서는 이 오버라이드를 한 번 승인해야 할 수도 있습니다.

게이트웨이가 anthropic-beta 헤더에서 오류 발생

일부 게이트웨이는 알려지지 않은 헤더나 베타 필드를 거부합니다. 이 정확한 실패 모드를 위해 설계된 환경 변수가 있습니다:

export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1

LLM 게이트웨이 문서에서도 Bedrock 또는 Vertex 와 함께 Anthropic Messages 포맷을 사용할 때 이 설정이 필요할 수 있다고 명시합니다.

llama.cpp 에서 도구 호출이 작동하지 않음

서버 플래그를 다시 확인하세요. llama-server 문서에서는 도구 사용에 –jinja 플래그가 필요하다고 명시합니다. 없으면 서버는 응답할 수 있지만 에이전트 루프는 저하됩니다.

권한 프롬프트가 모든 명령을 방해함

이는 모드와 권한 규칙에 따라 정상일 수 있습니다. 옵션은 다음과 같습니다:

  • 일시적으로 acceptEdits 로 전환 (파일 편집이 더 빠르게 진행됨).
  • settings.json 에 알려진 안전한 bash 명령에 대한 명시적 허용 규칙 작성.
  • bash 도구를 격리하면서 프롬프트를 줄이기 위해 /sandbox 사용.
  • 플랜 및 버전이 지원한다면 중간 지점으로 auto 모드 평가.

무언가 이상하고 가시성이 필요함

내장 기능을 사용하세요:

  • 설치 및 설정을 검증하는 /doctor
  • 해당 지점부터 로그 캡처를 시작하는 /debug
  • 인쇄 모드라면, 실험을 제한하기 위해 엄격한 최대 예산 및 최대 턴 고려.