OpenCode란 무엇인가

OpenCode는 오픈 소스 (open-source) 코딩 에이전트입니다. 사용자가 평이한 언어로 목표를 제시하면, 에이전트는 계획을 세우고, 파일을 읽고 쓰고, 명령어를 실행하며, 결과를 보고합니다. 이 에이전트는 터미널이나 브라우저 인터페이스에서 동작하며, 팀 동료가 일하는 방식과 동일하게 작동합니다: 저장소 (repo)를 열고, 변경 사항을 적용하고, 실행한 뒤, 오류가 발생하면 수정합니다.

이 가이드에서 중요한 세부 사항은 OpenCode가 모델과 통신하는 방식입니다. OpenCode는 OpenAI 호환 API (OpenAI-compatible API)를 노출하는 모든 엔드포인트 (endpoint)와 통신할 수 있습니다. 즉, 특정 클라우드 벤더 (cloud vendor)에 종속되지 않는다는 의미입니다. 사용자는 자신의 기기에서 실행 중인 모델을 포함하여 원하는 어떤 모델 엔드포인트로든 지정할 수 있습니다.

이것이 바로 핵심 아이디어입니다. 에이전트 루프 (agent loop)를 위한 OpenCode, 지능을 위한 로컬 모델, 이 두 가지 모두 사용자가 제어하는 하드웨어 위에서 작동하는 것입니다.

// Detect dark theme var iframe = document.getElementById('tweet-2069412641416843506-783'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=2069412641416843506&theme=dark" }

코딩 에이전트에게 로컬 환경이 기본값이어야 하는 이유

모델이 단순히 채팅만 할 때는 모델이 어디에서 실행되는지가 주로 개인정보 보호 (privacy)의 문제입니다. 하지만 모델이 사용자의 저장소를 읽고 명령어를 실행하는 코딩 에이전트를 구동할 때는 제어 (control)의 문제가 됩니다. 에이전트는 사용자의 기기에서 동작합니다. 만약 그 배후의 모델이 타인의 데이터 센터 (datacenter)에 있다면, 모델이 읽는 모든 파일과 실행하는 모든 명령어는 사용자가 소유하지 않은 시스템에 의존하게 됩니다. 즉, 시스템의 가동 시간 (uptime), 지연 시간 (latency), 약관 (terms), 그리고 액세스 정책 (access policy)에 의존하게 되며, 이 중 어느 것이라도 예고 없이 변경될 수 있습니다.

모델을 로컬에서 실행하는 것은 단순히 정책을 바꾸는 것이 아니라, 속성 (property) 자체를 변화시킵니다:

• 코드가 기기에 그대로 남습니다. 에이전트가 읽는 파일, 작성하는 코드, 실행하는 명령 중 그 어떤 것도 모델에 도달하기 위해 사용자의 디스크를 벗어나지 않습니다.
• 오프라인에서 작동합니다. 모델을 한 번 다운로드하면, 완전히 연결을 끊고 계속 작업할 수 있습니다. 네트워크를 꺼도 에이전트는 여전히 응답합니다.
• 토큰당 비용이 발생하지 않습니다. 사용량에 따라 비용이 청구되는 API를 사용할 때라면 막대한 비용이 들었을 긴 코딩 세션도 로컬에서는 비용이 전혀 들지 않습니다.
• 조용한 모델 교체가 없습니다. 가중치(weights)는 사용자의 디스크에 있는 파일입니다. 세션 사이에 사용자 모르게 변경되지 않습니다.

코딩 에이전트에게 이는 하나의 단순한 속성으로 귀결됩니다: 작업과 그 작업을 수행하는 지능이 모두 당신의 것입니다.

QVAC, 그리고 당신이 이미 사용 중인 도구들

QVAC는 로컬 실행을 실용적으로 만드는 핵심 요소입니다. 이는 Tether에서 제공하는 오픈 소스 SDK 및 CLI로, 모든 주요 GPU 백엔드(NVIDIA, AMD 및 Vulkan을 통한 Intel, Metal을 통한 Apple Silicon)에서 사용자의 기기에서 모델을 실행하며, OpenAI 호환 서버를 함께 제공합니다. 그 서버가 바로 코딩 에이전트가 연결되는 가교 역할을 합니다.

또한 이는 단일 도구로 끝나는 트릭이 아닙니다. QVAC는 OpenCode 및 OpenClaw를 위한 퍼스트 클래스(first-class) 로컬 프로바이더(provider)이며, 서버가 표준 OpenAI API를 지원하기 때문에 Cline, Aider, Continue, Roo를 포함하여 개발자들이 이미 사용 중인 다른 코딩 도구들과도 호환됩니다. 특히 OpenCode의 경우, 단 한 줄의 설정(아래 참조)만으로 전체 시스템을 연결해 주는 전용 플러그인인 @qvac/opencode-plugin이 있습니다. 로컬에서 실행되는 당신만의 모델을 이미 선호하는 에이전트에 가져오기만 하면 됩니다. QVAC는 Apache 2.0 라이선스이며, API 키, 속도 제한(rate limits), 토큰당 비용이 없습니다.

작동 모습

QVAC를 통해 Qwen3.6-35B-A3B를 로컬에서 실행했을 때(한 번 다운로드 후 네트워크를 끈 상태), OpenCode는 세 가지 일반적인 개발자 작업을 연속해서 처리했습니다:

• 프롬프트로부터 빌드하기. 단 한 문장으로, 커서에 반응하며 떠다니는 800개의 빛나는 입자를 애니메이션화하는 독립적인 페이지를 작성한 뒤 브라우저에서 바로 열었습니다. 라이브러리 없이 모든 코드가 해당 기기에서 생성되었습니다.
• 생소한 저장소(Repo) 설명하기. 특정 저장소가 무엇을 하는지 물었을 때, 코드를 읽고 원형 궤도를 따라 행성들이 공전하는 태양계 시뮬레이션이라고 설명했습니다. 페이지를 열어 확인한 결과 사실로 밝혀졌습니다.
• 버그 찾기 및 수정하기. 합계가 숫자가 아닌 깨진 텍스트로 표시되는 쇼핑카트 코드를 건네주자, 원인을 찾아내고 파일을 수정하여 합계가 올바르게 계산되도록 했습니다.

이 모든 과정은 오픈 소스 기반의 무료 스택을 통해 로컬에서 실행되었습니다.

어떤 모델을 실행할 것인가

코딩 에이전트 작업(저장소 읽기, 파일 생성, 버그 수정)은 채팅보다 모델에 더 많은 요구 사항을 전달하므로, 역량 있는 모델을 실행하는 것이 가치가 있습니다. 플러그인 설정(아래 2단계)에서 ID를 통해 모델을 선택하며, 해당 ID는 OpenCode의 모델 선택기(Model picker)로 직접 전달됩니다.

해당 ID는 사용자가 제공하는 파일 경로가 아니라 QVAC 모델 참조(Reference)입니다. 처음 실행할 때 QVAC는 해당 모델을 자신의 로컬 저장소로 한 번 다운로드하며, 그 이후부터는 네트워크 연결 없이 로컬에서 제공합니다. QVAC 자체 복사본을 가져오기 때문에, 다른 도구에서 이미 가지고 있는 .gguf 파일은 재사용되지 않습니다.

데모에서는 Qwen3.6-35B-A3B를 사용합니다. 350억 개의 파라미터(Parameters) 지식을 보유하고 있지만, 토큰당 활성화되는 파라미터는 약 30억 개뿐이어서 크기에 비해 빠른 속도를 유지합니다. 대부분의 노트북에서는 Qwen3.5-4B 또는 기본값인 9B 모델이 더 나은 시작점입니다.

GPU가 있으면 도움이 되지만 필수 사항은 아닙니다. QVAC는 Apple Silicon에서는 Apple Metal을, NVIDIA, AMD, Intel에서는 Vulkan을 사용합니다. CPU 전용 머신에서도 실행은 가능하지만 속도가 더 느립니다. 시작하기 전에 하드웨어가 무엇을 지원하는지 확인하려면 npx -y @qvac/cli doctor를 실행하세요 (설치 불필요).

설정하기

두 번째 터미널도, 수동 서버 설정도 필요 없습니다. OpenCode는 프로젝트 설정에서 QVAC 플러그인을 읽어와 스스로 관리형 QVAC 서버를 실행하고, 해당 서버를 가리키도록 설정하며, 종료 시 서버를 닫습니다.

요구 사항: Node.js 22.17 이상 (node --version, nodejs.org에서 확인 가능). 디스크 및 RAM 용량은 선택한 모델에 따라 다릅니다. 데모에서 사용하는 Qwen3.6-35B-A3B는 약 21 GB의 디스크 공간과 32 GB의 RAM이 필요하며, 더 가벼운 기본 모델인 qwen3.5-9b는 훨씬 적은 자원을 필요로 합니다.

1. OpenCode 설치.

npm install -g opencode-ai

2. 프로젝트에 QVAC 플러그인 추가. 코딩을 진행할 폴더에 opencode.json 파일을 생성하세요. 파일 전체는 플러그인의 기본 모델(qwen3.5-9b)을 사용하는 한 줄로 구성됩니다:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@qvac/opencode-plugin"]
...

대신 데모와 동일하게 가장 강력한 모델을 사용하려면(더 무거움: 디스크 약 21 GB, RAM 약 32 GB 필요), 다음과 같이 명시적으로 이름을 지정하세요:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": [["@qvac/opencode-plugin", { "model": "QWEN3_6_35B_A3B_MULTIMODAL_Q4_K_M" }]]
...

3. OpenCode 실행.

opencode web        # 브라우저 UI, 가장 시각적임
opencode            # 터미널 UI
opencode run "..."  # 원샷 (one-shot)

이것으로 모든 설정이 완료되었습니다. 처음 실행할 때 플러그인이 스스로를 설치하고, 백그라운드에서 관리형 QVAC 서버를 생성하며(모델을 한 번 다운로드함), OpenCode를 로컬 qvac 프로바이더(provider)로 연결하고, 종료 시 서버를 정리합니다. 직접 실행해야 하는 qvac serve 명령도, 작성해야 할 프로바이더 블록도, 설정해야 할 toolsMode도 없습니다. 플러그인이 이 모든 것을 처리하며, 사용 중인 인터페이스에 맞춰 시작 시 자동으로 로드됩니다.

좋은 첫 번째 테스트 방법: 모델에게 클라우드에서 실행 중인지 아니면 로컬 머신에서 실행 중인지 물어본 다음, 네트워크를 끄고 다시 물어보세요. 아무것도 외부로 전송되지 않았기 때문에 계속해서 올바른 답변을 유지할 것입니다.

다음에 시도해 볼 것

여기서부터는 동일한 설정을 통해 코딩 에이전트(coding agent)가 수행하는 나머지 작업들을 처리할 수 있습니다. OpenCode를 프로젝트 폴더로 지정하여 코드를 읽고 수정하게 하거나, 프롬프트(prompt)로부터 작은 앱을 생성하고, 생소한 저장소(repository)를 설명하거나, 버그를 추적하게 할 수 있습니다. 에이전트 루프(agent loop)는 클라우드 환경에서의 경험과 동일합니다. 유일하게 달라진 점은 그 이면의 모델이 당신의 하드웨어에서 구동되는 당신의 모델이며, 기기 외부로 나가는 데이터가 전혀 없다는 것입니다.

참고 사항 및 제한 사항

• 당신의 기기에 적합한 모델은 프런티어 클라우드 모델(frontier cloud model)이 아닙니다. 따라서 더 명확하고 집중된 지침(instruction)이 필요할 수 있음을 예상해야 하며, 길고 개방적인 작업보다는 단일 목표를 가진 작업을 부여하십시오.
• 현재로서는 로컬 응답이 클라우드 API보다 오래 걸릴 수 있습니다. 단일 로컬 워커(worker)에서 35B 모델을 사용한 도구 사용(tool-using) 턴은 약 20~30초 정도 소요되며, 더 작은 모델은 더 빠릅니다. 로컬 하드웨어의 속도가 향상되고 소형 모델이 개선됨에 따라 이 격차는 빠르게 줄어들고 있습니다.
• 기기당 하나의 QVAC 워커가 실행되며, 여러 개의 OpenCode 창이 이를 공유합니다. 만약 OpenCode 데스크톱 앱이 열려 있다면 터미널에서 필요한 잠금(locks)을 점유할 수 있으므로, 터미널에서 opencode를 실행할 때는 앱을 종료하십시오.
• QVAC는 Apache 2.0 라이선스이며 무료입니다. 모델은 한 번 다운로드되면 로컬에 캐시(cached)됩니다. 소스 및 문서: github.com/tetherto/qvac 및 docs.qvac.tether.io.