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

로컬 모델 백엔드를 갖춘 에이전틱 코딩

Page content

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

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

Anthropic은 이 차이를 명확히 구분합니다. 코드 완성 기능은 입력하는 대로 다음 줄을 제안하는 반면, Claude Code는 프로젝트 수준에서 작동하며 여러 파일에 걸쳐 계획을 세우고, 변경 사항을 실행하며, 테스트를 실행하고, 실패 시 반복합니다. 실제로 이는 속도는 빠르지만 여전히 검토가 필요한 터미널 네이티브 주니어 엔지니어와 더 비슷합니다.

이러한 속도와 감독 사이의 긴장은 사람들이 흔히 ‘Vibe Coding’이라는 용어로 묶는 것의 대부분을 차지합니다. Vibe Coding이란 무엇인가?에서는 이 용어, 그 기원, 그리고 실제 효율성과 위험이 어떻게 나타나는지 자세히 설명합니다.

laptop-homeresver-claude-code-coffee-books

문서를 빠르게 훑어볼 때 놓치기 쉬운 세부 사항 하나: Terminal CLI(및 VS Code 환경)는 서드파티 제공업체를 사용하도록 구성할 수 있습니다. 바로 여기서 Ollama와 llama.cpp가 등장합니다.

Claude Code가 로컬 HTTP 엔드포인트를 가리키도록 설정되면 런타임, 하드웨어, 호스팅에 따른 trade-off는 클라이언트 외부에 있게 됩니다. 2026년 LLM 호스팅 비교에서는 Ollama, 전용 추론 스택, 클라우드 옵션을 한 곳에서 정리하고 있습니다.

Claude Code가 다른 AI 지원 코딩 및 배포 워크플로우와 어떻게 맞물리는지 보려면, AI 개발 도구 가이드를 참고하세요. 여기에는 Copilot 스타일 어시스턴트, 자동화, 에디터 패턴이 한데 모여 있습니다.

같은 범주에 속하는 코딩 어시스턴트를 도구별로 조사하려면, AI 코딩 어시스턴트 비교를 참조하세요. 이 가이드는 설치 가이드보다 높은 수준에서 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), Console 계정(API 크레딧), 또는 지원되는 클라우드 제공업체를 통한 로그인을 지원합니다. 유용한 운영상 참고 사항: Console에서 처음 로그인하면 중앙 집중식 비용 추적을 위해 “Claude Code” 워크스페이스가 생성됩니다.

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는 로그인 상태여도 Claude 구독 대신 키를 사용합니다. 인쇄 모드(-p)에서는 키가 항상 사용됩니다.

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

서드파티 에이전트 스택에서 현재 시행 중인 특정 구독 경계에 대해, OpenClaw 워크플로우를 위한 Claude 정책 업데이트는 왜 API 기반 사용이 필요한지 설명합니다.

게이트웨이를 사용하는 최소 패턴은 다음과 같습니다.

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를 고정(pinning)하는 것도 지원합니다. 또한 모델 피커에서 사용자가 선택할 수 있는 것을 제한할 수 있는 허용 목록(allowlist)도 있습니다.

실용적인 패턴은 초기 모델을 설정하고 피커를 제한한 다음, “기본"이 어떤 값으로 해결되는지 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에는 큰 컨텍스트 윈도우가 필요하며 최소 64k 토큰을 권장합니다. 로컬 모델이 8k나 16k에 불과하다면 Claude Code는 여전히 실행되지만, “프로젝트 수준"의 약속은 취약해집니다.

유사한 터미널 에이전트 설정(Ollama 및 llama.cpp, 코딩 작업, 그리고 솔직한 실패 노트)에서의 실용적인 로컬 모델 동작에 대해서는, OpenCode를 위한 최고의 LLM - 로컬 테스트가 Claude Code를 위한 GGUF 또는 Ollama 태그를 선별할 때 유용한 교차 확인 자료입니다.

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

llama.cpp는 반대적인 매력으로 인해 매력적입니다. 플랫폼이 되려고 하지 않기 때문입니다. 이는 OpenAI 호환 루트와 Anthropic Messages API 호환 루트 모두를 노출할 수 있는 빠르고 가벼운 서버입니다.

설치 경로, llama-cli, llama-server 동작에 대한 아래 스니펫을 넘어선 내용은 llama.cpp CLI 및 서버 빠른 시작이 엔드투엔드 참조 자료입니다.

서버 측에서 실행할 내용

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

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

  • 서버는 완전한 Anthropic API 사양 호환성을 강력하게 주장하지 않지만, 많은 앱에 충분히 잘 작동한다고 명시합니다.
  • 도구 사용(tool use)은 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

Claude Code를 llama-server로 연결

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

가격 및 비용 모델

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

구독 플랜에 Claude Code 포함

Anthropic은 유료 Claude 구독 티어에 Claude Code를 포함시킵니다. 2026년 4월 기준, 발표된 가격은 다음과 같습니다.

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

API 토큰 가격

Claude Code를 API 청구로 사용하면 비용은 토큰 요금을 따릅니다. 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 청구는 제거되지만, 작업이 무료가 되는 것은 아닙니다. 클라우드 비용을 로컬 컴퓨팅, 메모리, 그리고 “누가 업타임을 책임질 것인가"로 교환하는 것입니다. 일부 팀에게는 이 trade-off가 전체 목적입니다.

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

제 편향은 Claude Code를 채팅봇이 아닌 워크플로우 엔진으로 취급할 때 가장 강력하다는 것입니다. 툴링이 이를 암시합니다.

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

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

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

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

세션을 정직하게 유지하기 위해 내장 명령 사용

몇 가지 명령이 Claude Code를 “어시스턴트"에서 “툴링"으로 전환합니다.

  • /init는 CLAUDE.md 프로젝트 가이드를 생성하며, 이는 일관된 컨텍스트를 피드하는 가벼운 방법입니다. CLAUDE.md 위에 있는 재사용 가능한 플레이북 및 반복 가능한 워크플로우에 대해서는, 개발자를 위한 Claude Skills이 SKILL.md 레이아웃, IDE 호환성, 트리거 튜닝, 테스트를 다룹니다.
  • /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 모드 평가.

뭔가 이상하고 가시성(observability)이 필요함

내장 기능을 사용하세요.

  • 설치를 검증하고 설정을 확인하기 위해 /doctor.
  • 그 시점부터 로그를 캡처하기 시작하기 위해 /debug.
  • 인쇄 모드에 있다면, 실험을 제한된 상태로 유지하기 위해 조밀한 최대 예산과 최대 턴을 고려하세요.

Anthropic의 보호된 1차 파티 도구로서의 Claude Code의 위치는 2026년 4월 전략적으로 중요해졌는데, 이는 Anthropic이 서드파티 에이전트 프레임워크에 대한 Claude 구독 접근을 차단하면서도 Claude Code는 구독 청구에 유지했기 때문입니다. OpenClaw의 부상과 몰락 타임라인이 해당 사건과 이것이 Anthropic의 1차 파티 대 서드파티 툴링 접근 방식에 대해 무엇을 드러내는지 다룹니다.

구독하기

시스템, 인프라, AI 엔지니어링에 관한 새 글을 받아보세요.