로컬 코딩 에이전트 구축 — Qwen3-Coder + OpenCode 완전 설정 가이드

API 키 없이, 코드가 외부로 나가지 않고, 월 구독료 없이. Qwen3-Coder + OpenCode 조합은 Claude Code의 로컬 대안 중 현재 가장 현실적인 선택입니다.

---

핵심 요약 → OpenCode = 터미널 기반 오픈소스 코딩 에이전트, Claude Code와 동일한 UX, 75+ 프로바이더 지원 → Qwen3-Coder-30B-A3B: 총 30B 파라미터, 활성 3B — RTX 4090 1대로 실행 가능 → Qwen3-Coder-Next (80B/3B): 2026년 2월 출시, SWE-Bench Verified 70.6% → LM Studio: 로컬 추론 서버, OpenAI 호환 API → OpenCode가 그대로 붙음 → Qwen Code: Qwen 공식 오픈소스 에이전트 (Claude Code fork 기반) → 핵심 설정 함정: OpenCode 컨텍스트 길이 최소 16K 요구, Qwen 채팅 템플릿 수동 설정 필요 → 비용: $0 (추론 비용 없음) vs Claude Code 월 수만 원

---

왜 로컬 코딩 에이전트인가

# API 코딩 에이전트 vs 로컬 코딩 에이전트

API 에이전트 (Claude Code / Codex CLI):
  ✅ 최고 성능
  ✅ 관리 불필요
  ❌ 월 $20~200+ 구독 + 토큰 비용
  ❌ 소스코드가 외부 서버로 전송
  ❌ 기업 CISO 정책에 막힘

로컬 에이전트 (OpenCode + Qwen3-Coder):
  ✅ API 비용 $0
  ✅ 소스코드 방화벽 밖으로 안 나감
  ✅ 인터넷 연결 없어도 동작
  ✅ 오픈소스 — 커스터마이징 가능
  ❌ 성능 gap (SWE-Bench: 70.6% vs Claude Sonnet 79.6%)
  ❌ GPU 필요 (RTX 4090 또는 Apple M2 Ultra+)
  ❌ 초기 설정 필요

Qwen3-Coder-Next는 80B 총 파라미터에 3B 활성 파라미터로 Claude Sonnet 4.5에 필적하는 코딩 벤치마크 성능을 달성합니다. 활성 파라미터가 3B뿐이므로 고사양 소비자용 GPU에서도 실행이 현실적입니다.

---

1. 모델 선택 — 하드웨어별 최적 조합

# 모델별 하드웨어 요구사항 (2026.05 기준)

Qwen3-Coder-30B-A3B-Instruct (권장 시작점):
  총 파라미터: 30B   활성: 3B
  VRAM 요구:  FP16 ~20GB / Q4 ~10GB
  최소 GPU:   RTX 4090 (24GB) 1대
  Apple:      M2 Max (32GB) 이상
  SWE-Bench:  ~65%

Qwen3-Coder-Next (최고 성능):
  총 파라미터: 80B   활성: 3B
  VRAM 요구:  FP16 ~50GB / Q4 ~25GB
  최소 GPU:   RTX 4090 2대 또는 RTX 5090 1대
  Apple:      M2 Ultra (192GB) 이상
  SWE-Bench:  70.6%

Qwen3.6-35B-A3B (밸런스):
  총 파라미터: 35B   활성: 3B
  VRAM 요구:  Q4 ~12GB
  최소 GPU:   RTX 4090 (24GB) 1대
  SWE-Bench:  ~67%

# 하드웨어별 추천

RTX 4090 (24GB):      Qwen3-Coder-30B-A3B Q4
RTX 4090 × 2:         Qwen3-Coder-Next Q4
Apple M2 Max (32GB):  Qwen3-Coder-30B-A3B-Instruct-MLX-4bit
Apple M2 Ultra (64GB): Qwen3-Coder-Next-MLX-4bit
CPU 전용 (RAM 64GB):  Qwen3.6-7B-A3B (성능 타협)

---

2. LM Studio 설치 + 모델 로드

# LM Studio 다운로드
# https://lmstudio.ai/download
# macOS / Windows / Linux 지원

# 설치 후 CLI 초기화
lms bootstrap   # CLI 초기화 (설치 후 1회)

# 터미널에서 모델 다운로드 (선택사항)
lms get qwen3-coder-30b-a3b-instruct-mlx-4bit   # Apple Silicon
lms get qwen3-coder-30b-a3b-instruct-gguf-q4    # NVIDIA GPU

# LM Studio GUI 설정 (핵심 설정 3가지)

1. 모델 로드
   검색창에: Qwen3-Coder-30B-A3B-Instruct-MLX-4bit
   다운로드 → Load Model 클릭

2. 컨텍스트 길이 설정 ← 중요!
   Load 탭 → Context Length: 32768 (최소 16384)
   GPU Offload: Max
   → OpenCode가 16K+ 컨텍스트 강제 요구

3. 로컬 서버 활성화
   Developer 탭 (CTRL+2) → Status: Running
   → http://localhost:1234/v1 에서 OpenAI 호환 API 시작

# 서버 동작 확인
curl http://localhost:1234/v1/models

# 정상 응답 예시:
# {
#   "data": [{
#     "id": "qwen3-coder-30b-a3b-instruct-mlx-4bit",
#     "type": "model"
#   }]
# }

---

3. Qwen 채팅 템플릿 설정 — 가장 흔한 함정

OpenCode에서 Qwen3-Coder-30B를 사용하려면 Qwen의 기본 채팅 템플릿을 수동으로 설정해야 합니다. 이 설정 없이는 모델이 툴 호출을 올바르게 실행하지 못합니다.

# LM Studio GUI에서 채팅 템플릿 설정

Model Settings 탭 → Chat Template 섹션

다음 시스템 프롬프트 추가:
"You are Qwen, a helpful coding assistant.
When using tools, always follow the tool calling format exactly.
Do not add extra text before or after tool calls."

Tokenization → Chat Template:
  chatml 선택 (또는 Custom 선택 후 아래 적용)

# 채팅 템플릿 문제 확인 방법
# 아래처럼 직접 API 테스트

import requests
import json

response = requests.post(
    "http://localhost:1234/v1/chat/completions",
    json={
        "model": "qwen3-coder-30b-a3b-instruct-mlx-4bit",
        "messages": [{"role": "user", "content": "Hello"}],
        "tools": [{
            "type": "function",
            "function": {
                "name": "test_tool",
                "description": "테스트 툴",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "message": {"type": "string"}
                    }
                }
            }
        }]
    }
)

result = response.json()
# tool_calls가 올바르게 파싱되는지 확인
# 없으면 → 채팅 템플릿 설정 재확인
print(json.dumps(result, indent=2, ensure_ascii=False))

---

4. OpenCode 설치

# macOS (Homebrew)
brew install sst/tap/opencode

# 또는 공식 설치 스크립트
curl -fsSL https://opencode.ai/install | sh

# Windows (winget)
winget install opencode

# npm (플랫폼 무관)
npm install -g opencode-ai

# 설치 확인
opencode --version

---

5. OpenCode + LM Studio 연결 설정

# 방법 1: /connect 커맨드 (UI 방식, 권장)

opencode   # OpenCode 실행
# 내부에서:
/connect   # 프로바이더 선택 화면
# → "LM Studio" 선택
# → API Key 입력: "lm-studio" (아무 값이나 가능)
# → Base URL: http://localhost:1234/v1

// 방법 2: config.json 직접 편집
// 위치: ~/.opencode/config.json (없으면 생성)

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "lmstudio": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "LM Studio (Local)",
      "options": {
        "baseURL": "http://localhost:1234/v1"
      },
      "models": {
        "qwen3-coder-30b-a3b-instruct-mlx-4bit": {
          "name": "Qwen3-Coder-30B (Local)"
        }
      }
    }
  },
  "model": "lmstudio/qwen3-coder-30b-a3b-instruct-mlx-4bit",
  "small_model": "lmstudio/qwen3-coder-30b-a3b-instruct-mlx-4bit"
}

# 인증 등록 (config 수정과 별개로 필요)
opencode auth login
# Provider: lmstudio (또는 Other 선택)
# API Key: lm-studio (임의값 — LM Studio는 키 검증 안 함)

# OpenCode 재시작 후 모델 확인
/models   # lmstudio/qwen3-coder... 표시되면 성공

---

6. vLLM 사용 시 — 서버 배포 환경

# vLLM으로 Qwen3-Coder 서빙 (GPU 서버)
pip install vllm

python -m vllm.entrypoints.openai.api_server \
    --model Qwen/Qwen3-Coder-30B-A3B-Instruct \
    --served-model-name Qwen3-Coder-30B-A3B-Instruct \
    --port 8000 \
    --max-model-len 32768 \
    --tensor-parallel-size 2  # GPU 2대 병렬

// vLLM → OpenCode 설정
// ~/.opencode/config.json

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "vllm": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "vLLM (Local Server)",
      "options": {
        "baseURL": "http://192.168.1.100:8000/v1"
      },
      "models": {
        "Qwen3-Coder-30B-A3B-Instruct": {
          "name": "Qwen3-Coder-30B (vLLM)"
        }
      }
    }
  },
  "model": "vllm/Qwen3-Coder-30B-A3B-Instruct",
  "small_model": "vllm/Qwen3-Coder-30B-A3B-Instruct"
}

---

7. Ollama 사용 시 — 가장 간단한 방법

# Ollama 설치 (macOS)
brew install ollama

# Qwen3-Coder 모델 다운로드
ollama pull qwen3-coder:30b-a3b   # 30B MoE 버전

# 서버 시작
ollama serve   # http://localhost:11434

# OpenCode에서 Ollama 연결
opencode auth login
# Provider: ollama
# API Key: ollama (임의값)

// Ollama → OpenCode config
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (Local)",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "qwen3-coder:30b-a3b": {
          "name": "Qwen3-Coder-30B (Ollama)"
        }
      }
    }
  },
  "model": "ollama/qwen3-coder:30b-a3b"
}

// ⚠️ Ollama 주의사항:
// Qwen 기본 채팅 템플릿이 LM Studio와 다를 수 있음
// 툴 호출 실패 시 → Modelfile에서 TEMPLATE 직접 설정

---

8. OpenCode 실전 사용

# 프로젝트 디렉토리에서 실행
cd ~/my-project
opencode

# 주요 내부 명령
/models         # 모델 전환
/connect        # 프로바이더 추가
/providers      # 현재 연결된 프로바이더 목록
/cost           # 현재 세션 토큰 사용량 (로컬이면 $0)

# 에이전트에게 작업 지시
> 이 프로젝트의 README를 읽고 FastAPI 엔드포인트 추가해줘
> 테스트가 실패하고 있어, 원인 찾아서 고쳐줘
> authentication.py 파일의 보안 취약점 찾아줘

# Claude Code와 동일한 UX:
# - 파일 읽기/쓰기 자동
# - bash 명령 실행
# - 멀티파일 편집
# - 결과 확인 후 계속

---

9. Qwen Code — 공식 오픈소스 에이전트 (대안)

Qwen Code는 터미널용 오픈소스 AI 에이전트로 Qwen 시리즈 모델에 최적화되어 있습니다. OpenAI·Anthropic·Gemini 호환 API, Alibaba Cloud, OpenRouter, Fireworks AI를 지원합니다. 프레임워크와 Qwen3-Coder 모델이 모두 오픈소스이며 함께 발전합니다.

# Qwen Code 설치 (npm)
npm install -g @qwen/qwen-code

# 또는 pip
pip install qwen-code

# 로컬 LM Studio 연결
export OPENAI_API_KEY="lm-studio"
export OPENAI_BASE_URL="http://localhost:1234/v1"

qwen --model qwen3-coder-30b-a3b-instruct-mlx-4bit

# OpenCode vs Qwen Code 선택 기준:
# OpenCode:   75+ 프로바이더, 클라우드 ↔ 로컬 전환 쉬움
# Qwen Code:  Qwen 모델과 가장 잘 맞음, Skills·SubAgents 내장

---

10. 성능 최적화 팁

# 로컬 에이전트 성능 극대화 설정

# 1. 컨텍스트 길이 최적화
# - 너무 짧으면 에이전트가 컨텍스트 잃음 (Thrashing)
# - 너무 길면 처리 속도 저하
OPTIMAL_CONTEXT = {
    "RTX_4090":      32_768,   # 24GB VRAM
    "M2_Max_32GB":   32_768,
    "M2_Ultra_64GB": 65_536,
    "RTX_4090x2":    65_536,
}

# 2. 양자화 선택
QUANTIZATION_GUIDE = {
    "Q4_K_M": "최소 VRAM, 성능 95% 유지 (권장)",
    "Q5_K_M": "VRAM 25% 증가, 성능 98% 유지",
    "Q8_0":   "VRAM 50% 증가, 성능 99% 유지",
    "FP16":   "원본 성능, VRAM 2배 필요",
}

# 3. 배치 크기
# LM Studio: Settings → GPU → Max Batch = 512 (기본 512)
# vLLM: --max-num-seqs 256 (병렬 요청 수)

# 4. 스트리밍 활성화
# OpenCode: 기본 스트리밍 ON
# → 첫 토큰까지 대기 시간 체감 단축

---

Claude Code vs OpenCode + Qwen3-Coder 비교

# 실전 비교 (2026.05 기준)

항목                Claude Code           OpenCode + Qwen3-Coder-30B
─────────────────────────────────────────────────────────────────────
SWE-Bench Verified  79.6%                 ~65% (30B) / 70.6% (Next)
월 비용             $20~200+ + 토큰       $0 (초기 GPU 비용 제외)
소스코드 외부 전송  있음 (Anthropic)      없음 (완전 로컬)
설치 난이도         낮음                  중간 (GPU 설정 필요)
컨텍스트            1M 토큰               32K~64K (LM Studio 설정)
속도 (토큰/초)      ~80 t/s               RTX 4090: ~40 t/s (Q4)
멀티모달            ✅                    ❌ (텍스트만)
Computer Use        ✅                    ❌
인터넷 없이 사용    ❌                    ✅
기업 CISO 통과      어려움                쉬움 (데이터 로컬)

결론:
  성능 최우선         → Claude Code
  비용·프라이버시    → OpenCode + Qwen3-Coder
  기업 보안 요구사항 → OpenCode (+ 내부 서버 vLLM)

---

트러블슈팅 — 자주 겪는 문제

# 문제 1: 툴 호출이 안 됨 (가장 흔함)
# 원인: 채팅 템플릿 설정 미흡
# 해결:
# LM Studio → Model Settings → Chat Template → chatml 선택
# 또는 Qwen 공식 채팅 템플릿 수동 입력

# 문제 2: "context length exceeded" 오류
# 원인: OpenCode 최소 16K 컨텍스트 요구
# 해결: LM Studio Load 탭 → Context Length 32768로 변경

# 문제 3: OpenCode 모델 인식 안 됨
# 원인: config.json 모델 ID 불일치
# 해결: LM Studio API에서 정확한 모델 ID 확인
curl http://localhost:1234/v1/models | python3 -m json.tool
# → id 필드의 정확한 문자열을 config.json에 사용

# 문제 4: 속도 너무 느림
# 해결: Q4_K_M 양자화 사용 + GPU Offload 100% 확인
# Apple: Metal GPU 가속 활성화 확인
# NVIDIA: CUDA 버전 확인 (vLLM은 CUDA 12.1+)

# 문제 5: 인증 오류
# 해결: opencode auth login 재실행
# Provider ID가 config.json의 provider 키와 일치하는지 확인

---

결론

✅ 지금 바로 시작할 수 있는 조합

• RTX 4090 보유: Qwen3-Coder-30B-A3B Q4 + LM Studio + OpenCode
• Apple M2 Max: Qwen3-Coder-30B-A3B-MLX-4bit + LM Studio + OpenCode
• GPU 서버: Qwen3-Coder-Next + vLLM + OpenCode

✅ 로컬 에이전트가 확실히 유리한 케이스

• 소스코드 외부 전송이 정책상 불가한 기업
• API 비용을 줄이고 싶은 개인 개발자
• 인터넷 없는 환경 (오프라인, 보안망)
• 실험적 코드베이스 — 모델에게 보여주기 꺼려지는 코드

❌ API 에이전트가 여전히 더 나은 케이스

• 최고 성능 필요 (SWE-Bench 79.6% vs 70.6%)
• GPU 없음
• Computer Use 필요
• 멀티모달 입력 필요