Claude Code CLI를 llama.cpp와 연결하여 완전한 로컬 코딩 환경 구축하기

커뮤니티 반응

작성자의 상세한 벤치마크와 설정 공유에 대해 긍정적인 반응이며, 로컬 코딩 에이전트로서의 실용성에 주목하고 있다.

주요 논점

01찬성다수

Claude Code는 현존하는 코딩 에이전트 CLI 중 가장 성능이 뛰어나며 로컬 모델과도 잘 작동한다.

합의점 vs 논쟁점

합의점

Claude Code의 시스템 프롬프트가 매우 크기 때문에 Prefix Caching 없이는 사용이 어렵다.
Qwen 3.5 27B 모델은 로컬 코딩 작업에 충분한 지능을 갖추고 있다.

논쟁점

웹 검색 기능은 Anthropic 서버 없이는 작동하지 않으며, 이를 대체하기 위해 SearXNG와 MCP를 연결하는 대안이 논의 중이다.

실용적 조언

환경 변수 대신 ~/.claude/settings.json 파일을 사용하여 설정을 관리하는 것이 더 안정적이다.
컨텍스트 압축 기능을 사용하려면 CLAUDE_CODE_MAX_OUTPUT_TOKENS를 16,384 이상으로 설정해야 요약 생성이 실패하지 않는다.
비전 기능을 사용하려면 llama-server 실행 시 --mmproj 옵션으로 비전 프로젝터 모델을 함께 로드해야 한다.

섹션별 상세

Claude Code의 로컬 연동을 위해 환경 변수와 settings.json을 활용한 설정법이 제시됐다. ANTHROPIC_BASE_URL을 로컬 서버 주소로 변경하고 텔레메트리 및 자동 업데이트 관련 옵션을 모두 비활성화하여 오프라인 상태를 유지한다. settings.json 방식이 환경 변수 설정보다 더 안정적이고 제어가 용이하다는 점이 확인됐다.

bash

export ANTHROPIC_BASE_URL="http://127.0.0.1:8001"
export ANTHROPIC_API_KEY="not-set"
export ANTHROPIC_AUTH_TOKEN="not-set"
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
export CLAUDE_CODE_ENABLE_TELEMETRY=0
export DISABLE_AUTOUPDATER=1
export DISABLE_TELEMETRY=1
export CLAUDE_CODE_DISABLE_1M_CONTEXT=1
export CLAUDE_CODE_MAX_OUTPUT_TOKENS=4096
export CLAUDE_CODE_AUTO_COMPACT_WINDOW=32768

Claude Code를 로컬 서버에 연결하고 텔레메트리를 비활성화하기 위한 환경 변수 설정 예시

json

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://127.0.0.1:8001",
    "ANTHROPIC_MODEL": "qwen3.5-27b",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
    "CLAUDE_CODE_MAX_OUTPUT_TOKENS": "32768",
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "90",
    "DISABLE_TELEMETRY": "1"
  }
}

환경 변수보다 안정적인 제어가 가능한 claude/settings.json 설정 파일 구성

llama.cpp 서버 실행 시 Qwen 3.5 27B GGUF 모델을 사용하며 하드웨어 특성에 맞는 최적화 파라미터를 적용했다. Strix Halo 하드웨어를 위해 ROCBLAS_USE_HIPBLASLT=1 설정을 추가하고 65,536 토큰의 컨텍스트 크기와 Flash Attention을 활성화했다. KV 캐시 타입을 q8_0으로 설정하여 메모리 효율과 성능 사이의 균형을 맞췄다.

bash

ROCBLAS_USE_HIPBLASLT=1 ./build/bin/llama-server \
--model models/Qwen3.5-27B-Q4_K_M.gguf \
--alias "qwen3.5-27b" \
--port 8001 --ctx-size 65536 --n-gpu-layers 999 \
--flash-attn on --jinja --threads 8 \
--temp 0.6 --top-p 0.95 --top-k 20 --min-p 0.00 \
--cache-type-k q8_0 --cache-type-v q8_0

Strix Halo 하드웨어에서 Qwen 3.5 모델을 구동하기 위한 llama.cpp 서버 실행 명령어

컨텍스트 사용량 증가에 따른 성능 변화를 7회차의 테스트를 통해 수치화했다. 컨텍스트가 23K에서 65K로 늘어남에 따라 생성 속도가 9.71 t/s에서 7.42 t/s로 약 24% 감소하는 경향이 나타났다. Claude Code의 시스템 프롬프트가 약 22,870 토큰을 차지하여 전체 컨텍스트 예산의 상당 부분을 점유하므로 효율적인 관리가 필요하다.

컨텍스트 자동 압축(Auto-compaction) 기능의 한계와 해결 방안이 논의됐다. Claude Code는 기본적으로 200K 컨텍스트를 가정하므로 65K 제한 환경에서는 압축 임계값에 도달하기 전에 시스템이 충돌할 수 있다. 이를 해결하기 위해 CLAUDE_AUTOCOMPACT_PCT_OVERRIDE를 90%로 조정하고 출력 토큰 제한을 16K 이상으로 높여 압축 요약이 생성될 공간을 확보해야 한다.

용어 해설

원격 측정(Telemetry): — 소프트웨어 사용 데이터를 개발사 서버로 전송하는 기능이다. 완전한 로컬 및 오프라인 환경을 구축하기 위해서는 이 기능을 명시적으로 비활성화해야 한다.
접두사 캐싱(Prefix Caching): — 프롬프트의 공통된 앞부분(시스템 프롬프트 등)에 대한 계산 결과를 저장하여 재사용하는 기술이다. Claude Code처럼 거대한 시스템 프롬프트를 사용하는 도구에서 추론 속도를 높이는 핵심 역할을 한다.
양자화(Quantization): — 모델의 가중치를 낮은 비트(예: 4비트)로 표현하여 메모리 사용량을 줄이고 실행 속도를 높이는 기법이다. 본문에서는 Q4_K_XL 양자화 모델을 사용하여 27B 모델을 로컬 하드웨어에서 구동했다.
컨텍스트 윈도우(Context Window): — 모델이 한 번에 처리할 수 있는 토큰의 최대 범위이다. 본문에서는 65,536 토큰으로 설정했으나, 컨텍스트가 가득 찰수록 생성 속도가 저하되는 현상이 관찰됐다.

언급된 도구

Claude Code추천

Anthropic에서 개발한 코딩 에이전트 CLI

llama.cpp추천

로컬 LLM 추론 엔진

Qwen 3.5 27B추천

코딩 및 비전 성능이 뛰어난 오픈소스 LLM

언급된 리소스

튜토리얼How to connect Claude Code CLI to a local llama.cpp server