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

API 키 없이, 코드가 외부로 나가지 않고, 월 구독료 없이. Qwen3-Coder + OpenCode 조합은 Claude Code의 로컬 대안 중 현재 가장 현실적인 선택입니다. 기업 보안 정책상 소스코드 외부 전송이 불가하거나, API 비용 없이 에이전트를 돌리고 싶은 개발자에게 특히 적합합니다. 이 글에서는 모델 선택부터 LM Studio 설정, OpenCode 연결, 트러블슈팅까지 한 번에 정리합니다.

---

핵심 요약

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 채팅 템플릿을 수동으로 설정해야 합니다. 비용은 초기 GPU 비용을 제외하면 추론 비용이 $0이며, Claude Code 월 수만 원과 비교됩니다.

---

왜 로컬 코딩 에이전트인가

API 에이전트와 로컬 에이전트는 각각 명확한 장단점이 있습니다. 어떤 상황에서 로컬이 유리한지 파악하는 것이 선택의 핵심입니다.

API 에이전트(Claude Code / Codex CLI)는 최고 성능에 관리가 필요 없지만, 월 $20~200 이상의 구독료와 토큰 비용이 발생하고 소스코드가 외부 서버로 전송됩니다. 기업 CISO 정책에 막히는 경우도 많습니다.

로컬 에이전트(OpenCode + Qwen3-Coder)는 API 비용이 $0이고 소스코드가 방화벽 밖으로 나가지 않으며 인터넷 없이도 동작합니다. 오픈소스라 커스터마이징도 가능합니다. 다만 SWE-Bench 기준으로 성능 갭이 있고(70.6% vs Claude Sonnet 79.6%), RTX 4090 또는 Apple M2 Ultra급 GPU가 필요하며 초기 설정이 필요하다는 점은 감안해야 합니다.

Qwen3-Coder-Next는 80B 총 파라미터에 활성 파라미터 3B만 사용하기 때문에, 고사양 소비자용 GPU에서도 Claude Sonnet 4.5에 필적하는 코딩 벤치마크 성능을 현실적으로 달성할 수 있습니다.

---

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

보유 GPU에 따라 모델 선택이 달라집니다. 모델별 VRAM 요구사항과 벤치마크 성능을 정리했습니다.

모델 총 파라미터 활성 VRAM (Q4) 최소 GPU SWE-Bench

Qwen3-Coder-30B-A3B	30B	3B	~10GB	RTX 4090 1대	~65%
Qwen3.6-35B-A3B	35B	3B	~12GB	RTX 4090 1대	~67%
Qwen3-Coder-Next	80B	3B	~25GB	RTX 4090 2대	70.6%

하드웨어별 추천 조합은 다음과 같습니다. RTX 4090(24GB) 1대라면 Qwen3-Coder-30B-A3B Q4, RTX 4090 2대라면 Qwen3-Coder-Next Q4가 적합합니다. Apple Silicon은 M2 Max(32GB)라면 Qwen3-Coder-30B-A3B-Instruct-MLX-4bit, M2 Ultra(64GB 이상)라면 Qwen3-Coder-Next-MLX-4bit를 선택하세요. GPU 없이 CPU만 있다면(RAM 64GB) Qwen3.6-7B-A3B로 성능을 타협해야 합니다.

---

2. LM Studio 설치 + 모델 로드

LM Studio는 로컬 추론 서버를 가장 쉽게 띄울 수 있는 방법입니다. GUI 기반이라 별도 서버 설정 지식 없이도 OpenAI 호환 API를 바로 사용할 수 있습니다.

먼저 https://lmstudio.ai/download 에서 운영체제에 맞는 버전을 다운로드합니다. macOS, Windows, Linux 모두 지원합니다.

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

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

GUI에서 반드시 확인해야 할 핵심 설정이 세 가지입니다. 첫째, 모델 로드입니다. 검색창에 Qwen3-Coder-30B-A3B-Instruct-MLX-4bit를 입력하고 다운로드 후 Load Model을 클릭합니다. 둘째, 컨텍스트 길이 설정입니다. OpenCode가 최소 16K 컨텍스트를 강제로 요구하기 때문에 Load 탭에서 Context Length를 32768로 설정하고 GPU Offload는 Max로 올려야 합니다. 셋째, 로컬 서버를 활성화합니다. Developer 탭(CTRL+2)에서 Status를 Running으로 바꾸면 http://localhost:1234/v1에서 OpenAI 호환 API가 시작됩니다.

서버가 제대로 떴는지 확인하는 방법은 간단합니다. 아래 curl 명령으로 모델 목록이 반환되면 정상입니다.

curl http://localhost:1234/v1/models
# 정상 응답: { "data": [{ "id": "qwen3-coder-30b-a3b-instruct-mlx-4bit", "type": "model" }] }

---

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

OpenCode에서 Qwen3-Coder를 사용할 때 가장 많이 겪는 문제입니다. 이 설정 없이는 모델이 툴 호출을 올바르게 실행하지 못하고 에이전트 동작이 이상해집니다.

LM Studio GUI에서 Model Settings 탭 → Chat Template 섹션으로 들어가세요. Tokenization 항목에서 chatml을 선택하거나, Custom으로 설정하고 아래 시스템 프롬프트를 추가합니다.

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.

설정이 제대로 됐는지 확인하려면 직접 API를 테스트하는 것이 가장 확실합니다. 툴을 포함한 요청을 보내서 tool_calls가 올바르게 파싱되는지 확인하세요. 응답에 tool_calls 필드가 없거나 텍스트로 출력된다면 채팅 템플릿 설정을 다시 확인해야 합니다.

import requests, 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()
print(json.dumps(result, indent=2, ensure_ascii=False))
# tool_calls가 올바르게 파싱되는지 확인 → 없으면 채팅 템플릿 재설정

---

4. OpenCode 설치

운영체제에 맞는 방법으로 설치합니다. npm 방식이 플랫폼에 무관하게 가장 범용적입니다.

# 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 연결 설정

연결 방법은 두 가지입니다. UI 방식이 간편하고, config.json 직접 편집은 팀 공유나 자동화에 유용합니다.

방법 1: /connect 커맨드 (권장)

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로 선택한 뒤 API Key에 임의값을 입력합니다. LM Studio는 키 검증을 하지 않습니다. 재시작 후 /models를 실행해서 lmstudio/qwen3-coder...가 표시되면 성공입니다.

---

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

팀 단위로 GPU 서버를 공유하거나 운영 환경에 배포할 때는 vLLM을 씁니다. OpenAI 호환 API를 동일하게 제공하므로 OpenCode 설정만 base URL을 서버 IP로 바꾸면 됩니다.

vLLM 서버를 먼저 띄웁니다. GPU 2대를 병렬로 쓰려면 --tensor-parallel-size 2를 추가하세요.

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

서버가 뜨면 ~/.opencode/config.json에서 baseURL만 서버 주소로 바꾸면 됩니다.

{
  "$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 사용 시 — 가장 간단한 방법

설치 과정이 가장 단순합니다. LM Studio처럼 GUI가 없어도 CLI 몇 줄로 서버가 올라가기 때문에 빠르게 테스트하고 싶을 때 적합합니다.

brew install ollama
ollama pull qwen3-coder:30b-a3b   # 30B MoE 버전 다운로드
ollama serve                       # http://localhost:11434

OpenCode 연결 설정은 base URL만 Ollama 포트로 바꾸면 됩니다.

{
  "$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 실전 사용

모든 설정이 완료됐다면 프로젝트 디렉토리에서 opencode를 실행하면 됩니다. Claude Code와 동일한 방식으로 자연어 명령을 입력하면 에이전트가 파일을 읽고, 수정하고, 터미널 명령을 실행합니다.

cd ~/my-project
opencode

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

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

파일 읽기·쓰기, bash 명령 실행, 멀티파일 편집, 결과 확인 후 계속 작업하는 사이클이 Claude Code와 동일하게 동작합니다. /cost 명령에서 토큰 비용이 $0으로 표시되는 것이 로컬 에이전트의 핵심 장점입니다.

---

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

Qwen Code는 Alibaba가 공식 제공하는 터미널용 오픈소스 AI 에이전트입니다. Claude Code fork 기반이며 Qwen 시리즈 모델에 최적화돼 있고, OpenAI·Anthropic·Gemini 호환 API, Alibaba Cloud, OpenRouter, Fireworks AI를 지원합니다. 프레임워크와 모델이 모두 오픈소스라 함께 발전한다는 점이 장점입니다.

npm install -g @qwen/qwen-code   # 또는 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와 Qwen Code의 선택 기준은 명확합니다. OpenCode는 75개 이상 프로바이더를 지원하고 클라우드와 로컬 전환이 쉬워서 혼용 환경에 맞습니다. Qwen Code는 Qwen 모델과 궁합이 가장 좋고 Skills·SubAgents가 내장돼 있어 Qwen 모델을 전용으로 쓸 계획이라면 더 적합합니다.

---

10. 성능 최적화 팁

설정 몇 가지로 로컬 에이전트 성능을 눈에 띄게 높일 수 있습니다.

컨텍스트 길이 최적화는 에이전트 동작 품질에 직접 영향을 줍니다. 너무 짧으면 에이전트가 컨텍스트를 잃고 같은 작업을 반복하는 Thrashing이 발생합니다. 너무 길면 처리 속도가 저하됩니다. RTX 4090이나 M2 Max(32GB)는 32,768, M2 Ultra(64GB) 이상이나 RTX 4090 2대는 65,536이 적정값입니다.

양자화 선택은 VRAM과 성능의 트레이드오프입니다. Q4_K_M이 최소 VRAM으로 원본 대비 성능 95% 유지가 가능해 권장됩니다. Q5_K_M은 VRAM 25% 증가로 98%, Q8_0은 50% 증가로 99%를 유지합니다.

GPU Offload 100% 확인도 중요합니다. LM Studio에서 GPU Offload가 Max가 아니면 일부 레이어가 CPU로 빠져서 속도가 크게 떨어집니다. Apple Silicon에서는 Metal GPU 가속 활성화 여부를, NVIDIA에서는 CUDA 12.1 이상 버전을 확인하세요.

---

Claude Code vs OpenCode + Qwen3-Coder 비교

실전 비교 핵심 수치입니다.

항목 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
속도 (토큰/초)	~80 t/s	RTX 4090: ~40 t/s (Q4)
멀티모달	✅	❌
인터넷 없이 사용	❌	✅
기업 CISO 통과	어려움	쉬움 (데이터 로컬)

---

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

문제 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 모델 ID와 불일치하는 경우입니다. 아래 명령으로 정확한 모델 ID를 확인하고 config.json에 그대로 복사하세요.

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은 12.1 이상 필요)을 확인하세요.

문제 5: 인증 오류

opencode auth login을 재실행하고 Provider ID가 config.json의 provider 키와 일치하는지 확인하세요.

---

결론

선택은 세 가지 상황으로 나뉩니다. 성능이 최우선이라면 Claude Code가 여전히 SWE-Bench 79.6%로 우위입니다. 비용과 프라이버시가 우선이라면 OpenCode + Qwen3-Coder가 가장 현실적인 대안입니다. 기업 보안 요구사항이 있는 환경이라면 OpenCode에 내부 서버 vLLM 조합이 최적입니다.

지금 바로 시작할 수 있는 조합은 하드웨어에 따라 다릅니다. 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가 권장 조합입니다.

---

관련 글

• AI 코딩 도구 6파전 — Cursor, Copilot, Claude Code, Windsurf, Kiro, Cline 완전 비교
• AI 코딩 도구 Eval 설계 — Claude Code·Cursor·Copilot 팀 도입 전 성능 측정 방법론