[Agent] ClaudeCode + Local LLM 설치부터 간단한 바이브코딩까지

시작

연구용으로 사용하는 DgxSpark 장비에 LLM모델을 서빙해서 개발자 PC에서 ClaudeCode를 설치하여 바이브코딩을 해보고자 한다.

이 레퍼런스로 추후 폐쇄망 작업시 Spark장비와 개발장비만 들고 들어가 어느 정도 AI의 도움(?)을 받을 수 있는 유용한 레퍼런스가 될 수 있다.

구성도 및 개발 정보

장비

클라이언트 장비: Windows11

서버 장비: DGX Spark (192.168.0.179)

서버 인프라: Docker

클라이언트 설치

윈도우 클라이언트에서 아래 명령어로 ClaudeCode를 설치한다(WSL X)

irm https://claude.ai/install.ps1 | iex

이후 터미널을 닫고 다시 열어 아래 명령어 수행 시 버전이 출력되어야 한다

claude --version

그대로 안될 경우

[Environment]::SetEnvironmentVariable("PATH", "$env:PATH;$env:USERPROFILE\.local\bin", [EnvironmentVariableTarget]::User)

Claude모델을 사용하진 않을거지만 그래도 로그인은 해야 사용 가능하다.

클라이언트 설정

윈도우 홈(`C:\Users\{사용자}`)디렉토리에 `. claude`라는 폴더가 생겼을 것이다

.claude 디렉토리에서 settings.json 파일을 아래 내용처럼 수정한다

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://192.168.0.179:4000",
    "ANTHROPIC_API_KEY": "dummy",
    "ANTHROPIC_AUTH_TOKEN": "dummy",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "qwen3.5-35b",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "qwen3.5-35b",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "qwen3.5-35b",
    "CLAUDE_CODE_ATTRIBUTION_HEADER": "0"
  }
}

 

옵션 명	옵션 설명
ANTHROPIC_BASE_URL	API 요청을 보낼 엔드포인트를 재정의. 여기서는 로컬 vLLM 서버로 라우팅
ANTHROPIC_API_KEY	X-Api-Key 헤더로 전송되는 API 키. 로컬 서버는 인증을 검증하지 않으므로 더미 값 사용
ANTHROPIC_AUTH_TOKEN	Authorization: Bearer 헤더에 들어갈 값. 마찬가지로 인증 우회용 더미 값
ANTHROPIC_DEFAULT_OPUS_MODEL	Claude Code가 "Opus" 티어를 선택할 때 실제로 API에 보낼 모델 ID
ANTHROPIC_DEFAULT_SONNET_MODEL	"Sonnet" 티어 선택 시 사용할 실제 모델 ID
ANTHROPIC_DEFAULT_HAIKU_MODEL	"Haiku" 티어 선택 시 사용할 실제 모델 ID
CLAUDE_CODE_ATTRIBUTION_HEADER	시스템 프롬프트 앞의 attribution 블록(클라이언트 버전, 프롬프트 지문) 생략. 프록시/게이트웨이 경유 시 prompt caching 적중률 향상 목적
CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS	실험적 베타 기능(beta 헤더로 활성화되는 기능) 비활성화. 서드파티 백엔드가 미지원 베타 기능으로 오류 내는 것을 방지

settings.json 내용 더 보기

https://code.claude.com/docs/ko/env-vars

환경 변수 - Claude Code Docs

서버 설정

docker-compose를 이용해 서버 인프라를 구성했다.

구성도는 아래와 같다

모델 다운로드

`~/llm-stack/models` 디렉토리에 모델을 다운로드하여 넣는다. 

직접 받아와서 넣거나 `hf`(huggingface_hub)를 이용하여 넣는다

[참고] `hf`로 모델 다운로드

# Python 가상환경 생성
python3 -m venv venv

# Python 가상환경 진입
source venv/bin/activate

# hf 설치
pip install -U huggingface_hub

# hf를 이용해 디렉토리에 LLM 모델 설치
hf download Qwen/Qwen3.5-35B-A3B-FP8 --local-dir ~/llm-stack/models/qwen3.5-35b-fp8

# Python 가상환경 나가기
deactivate

docker-compose.yml

혼자 및 2인이하로 사용할 경우의 옵션

services:
  vllm:
    image: nvcr.io/nvidia/vllm:26.06-py3
    container_name: vllm-qwen35
    restart: unless-stopped
    network_mode: host
    ipc: host
    volumes:
      - ./models/qwen3.5-35b-fp8:/models/qwen3.5-35b-fp8
    command:
      - vllm
      - serve
      - /models/qwen3.5-35b-fp8
      - --host
      - "0.0.0.0"
      - --port
      - "8000"
      - --served-model-name
      - qwen3.5-35b
      - --max-model-len
      - "262144"
      - --gpu-memory-utilization
      - "0.85"
      - --kv-cache-dtype
      - fp8
      - --max-num-batched-tokens
      - "2096"
      - --enable-auto-tool-choice
      - --tool-call-parser
      - qwen3_coder
      - --reasoning-parser
      - qwen3
      - --enable-prefix-caching
      - --max-num-seqs
      - "2"
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 10s
      retries: 5
      start_period: 600s

  litellm:
    image: ghcr.io/berriai/litellm:main-latest
    container_name: litellm-proxy
    restart: unless-stopped
    network_mode: host
    environment:
      - LITELLM_MASTER_KEY=dummy
    volumes:
      - ./litellm-config.yaml:/app/config.yaml
    command: ["--config", "/app/config.yaml", "--port", "4000"]
    depends_on:
      - vllm

3인이상 5인 사용할 경우 vllm에서 command옵션을 변경

- --max-model-len
- "65536"

- --max-num-seqs
- "8"

참고로 해당 권장 사용 인원(DGX 1대 기준)은 4명 이하, 하드유저의 경우 2인이하이다.

더 많은 인원이 사용하면 코딩의 품질이 저하되고, 많은 응답을 할 수 없어진다.

litellm-config.yaml

litellm은 추후에 올라마나 LM Studio 등 LLM 서빙 플랫폼을 바꿀 때 서버단에서만 변경하거나 다른 서버에서 서빙하는 LLM을 쉽게 가져오기 위해 사용하였다.

아직은 하나뿐이니 내용은 간단하다

model_list:
  - model_name: qwen3.5-35b
    litellm_params:
      model: openai/qwen3.5-35b
      api_base: http://localhost:8000/v1
      api_key: dummy

가동

이제 `docker compose up -d` 명령어로 docker-compose.yml에 정의된 컨테이너들을 모두 올리면 된다.

최종적으로 아래 로그가 표출되어야 모델이 메모리까지 적재가 완료된 것이며 사용 준비는 모두 끝난 것이다.

(APIServer pid=1) INFO 07-08 07:13:32 [base.py:224] Multi-modal warmup completed in 10.660s
(APIServer pid=1) INFO 07-08 07:13:33 [base.py:224] Readonly multi-modal warmup completed in 0.553s
(APIServer pid=1) INFO 07-08 07:13:33 [api_server.py:596] Starting vLLM server on http://0.0.0.0:8000
(APIServer pid=1) INFO 07-08 07:13:33 [launcher.py:37] Available routes are:
(APIServer pid=1) INFO 07-08 07:13:33 [launcher.py:46] Route: /openapi.json, Methods: HEAD, GET
(APIServer pid=1) INFO 07-08 07:13:33 [launcher.py:46] Route: /docs, Methods: HEAD, GET
(APIServer pid=1) INFO 07-08 07:13:33 [launcher.py:46] Route: /docs/oauth2-redirect, Methods: HEAD, GET
(APIServer pid=1) INFO 07-08 07:13:33 [launcher.py:46] Route: /redoc, Methods: HEAD, GET
(APIServer pid=1) INFO 07-08 07:13:33 [launcher.py:46] Route: /tokenize, Methods: POST
(APIServer pid=1) INFO 07-08 07:13:33 [launcher.py:46] Route: /detokenize, Methods: POST
(APIServer pid=1) INFO 07-08 07:13:33 [launcher.py:46] Route: /load, Methods: GET
(APIServer pid=1) INFO 07-08 07:13:33 [launcher.py:46] Route: /version, Methods: GET
(APIServer pid=1) INFO 07-08 07:13:33 [launcher.py:46] Route: /health, Methods: GET
(APIServer pid=1) INFO 07-08 07:13:33 [launcher.py:46] Route: /metrics, Methods: GET
(APIServer pid=1) INFO 07-08 07:13:33 [launcher.py:46] Route: /v1/models, Methods: GET
(APIServer pid=1) INFO 07-08 07:13:33 [launcher.py:46] Route: /ping, Methods: GET
(APIServer pid=1) INFO 07-08 07:13:33 [launcher.py:46] Route: /ping, Methods: POST
(APIServer pid=1) INFO 07-08 07:13:33 [launcher.py:46] Route: /invocations, Methods: POST
(APIServer pid=1) INFO 07-08 07:13:33 [launcher.py:46] Route: /v1/chat/completions, Methods: POST
(APIServer pid=1) INFO 07-08 07:13:33 [launcher.py:46] Route: /v1/chat/completions/batch, Methods: POST
(APIServer pid=1) INFO 07-08 07:13:33 [launcher.py:46] Route: /v1/responses, Methods: POST
(APIServer pid=1) INFO 07-08 07:13:33 [launcher.py:46] Route: /v1/responses/{response_id}, Methods: GET
(APIServer pid=1) INFO 07-08 07:13:33 [launcher.py:46] Route: /v1/responses/{response_id}/cancel, Methods: POST
(APIServer pid=1) INFO 07-08 07:13:33 [launcher.py:46] Route: /v1/completions, Methods: POST
(APIServer pid=1) INFO 07-08 07:13:33 [launcher.py:46] Route: /v1/messages, Methods: POST
(APIServer pid=1) INFO 07-08 07:13:33 [launcher.py:46] Route: /v1/messages/count_tokens, Methods: POST
(APIServer pid=1) INFO 07-08 07:13:33 [launcher.py:46] Route: /inference/v1/generate, Methods: POST
(APIServer pid=1) INFO 07-08 07:13:33 [launcher.py:46] Route: /scale_elastic_ep, Methods: POST
(APIServer pid=1) INFO 07-08 07:13:33 [launcher.py:46] Route: /is_scaling_elastic_ep, Methods: POST
(APIServer pid=1) INFO 07-08 07:13:33 [launcher.py:46] Route: /generative_scoring, Methods: POST
(APIServer pid=1) INFO 07-08 07:13:33 [launcher.py:46] Route: /v1/chat/completions/render, Methods: POST
(APIServer pid=1) INFO 07-08 07:13:33 [launcher.py:46] Route: /v1/completions/render, Methods: POST
(APIServer pid=1) INFO:     Started server process [1]
(APIServer pid=1) INFO:     Waiting for application startup.
(APIServer pid=1) INFO:     Application startup complete.

설정 확인

이제 정상적으로 연결되고, 클라이언트에서 추론 시 내 Claude토큰을 먹는 것이 아닌 로컬 LLM을 이용하는지 확인해야 한다.

`claude` 명령어로 Claude code를 실행시키고 `/config` 명령어로 확인해 본다

내 DGX 서버와 내 qwen3.5 모델만 사용하는 것을 확인할 수 있다.

추론

자기소개

간단하게 자기소개로 어떤 모델을 쓰는지 잘 말해준다(지가 Claude모델이 아닌 것도 말해준다 ㅋㅋ)

또한 내가 질문하는 순간 DGX 대시보드에서 GPU사용률이 100%를 찍으면서 내 로컬 LLM을 매우 잘 사용하고 있다는 표시도 확 보인다.

위 응답은 위에서 설정해 준 값 그 이상도 이하도 추가로 해준 것도 없으며 대화 퀄리티도 괜찮다.

'안녕? 너의 LLM모델이름과 너의 특징을 30줄 이상 이야기해 봐' 이 대화도 18초 정도로 응답한 거면 나쁘지 않다.

바이브코딩(Vibe Coding)

간단하게 내 윈도우 PC를 모니터링하라는 Python기반의 앱을 제작하라고 해봤다.

산출물은 아래 링크에 있다.

GitHub - hbcha0916/WMA: 로컬LLM + ClaudeCode 바이브코딩

이야기로만 아래 퀄리티로 뽑아냈다.

윈도우 프로그램으로 바이브코딩

처음엔 이 창에 오류만 잔뜩 표시해 주길래 오류 내용을 커맨트로 계속 쓰면서 "고쳐줘", "해줘" 하니까 위 사진처럼 잘 나오고

나는 웹으로 표출할 줄 알았는데 윈도우 프로그램형태로 하길래 웹으로도 해주고 프로그램 시작 시 `--web` 플래그가 있으면 Web모드 없으면 위 프로그램 띄우기 이런 식으로 추가 요청하였다

웹으로 추가요청

대충 볼만하게 괜찮게 잘 만들지만 돈 내고 쓰는 모델(GPT, Claude)만큼 퀄은 좋지 않다

하지만 이 정도만 해도 많은 도움이 된다.

그다지 답답하다 느낄 정도로 느리지도 않았고 확실히 내가 순수 짜는 코딩보단 몇천 배는 빠르다.

아직까진 난 웹페이지에서 챗봇형태가 익숙하지 Ai 클라이언트를 깔아서 커맨드 해보는 것은 처음이라 여러 클라이언트 옵션을 좀 더 익혀야 된다.

이제 MCP 같은 것도 사용해 보려고 하는데 로컬 LLM으로 MCP를 잘 활용할지는 앞으로 또 해봐야 할 과제인 것 같다.