AI 코딩 에이전트 월 청구액을 40% 이상 줄여주는 OpenCode 멀티 프로바이더 모델 라우팅 전략

AI 코딩 도구를 쓰다가 월말 청구서 보고 식은땀 흘린 경험 있으신가요? 저도 Claude Sonnet을 메인으로 쓰기 시작했을 때, 아키텍처 설계든 보일러플레이트 생성이든 무조건 같은 프론티어 모델을 때려 박았다가 예상보다 2배 가까운 금액이 찍혀서 당황했습니다. 실제로 혼자 개발하는 환경 기준으로, 이 전략을 적용하고 나서 월 $10 미만으로 클라우드 API 비용을 유지하게 됐습니다. 적당한 사용량의 개인 개발자 기준이고, 팀 환경이라면 절대 금액은 달라지지만 절감 비율은 비슷하게 나올 거라 생각합니다.

사실 설계 단계의 추론과 테스트 코드 한 줄 생성을 같은 모델로 처리할 이유는 전혀 없거든요. 지금 쓰는 비용의 절반으로 같은 품질을 유지할 수 있는 방법이 있는데, 그게 바로 작업 복잡도에 맞춰 모델을 자동으로 배정하는 멀티 프로바이더 계층화 전략입니다. OpenCode라는 터미널 기반 AI 코딩 에이전트가 이걸 단일 JSON 파일 하나로 구현하게 해줍니다.

이 글에서는 3단계 모델 계층화 구성부터, LiteLLM 게이트웨이로 설정을 단순화하는 방법, 민감한 코드베이스에서의 프라이버시 전략까지 실무에서 바로 적용 가능한 패턴들을 다룹니다. 개념을 먼저 살펴보고, 내 상황에 맞는 예시를 골라 바로 따라해볼 수 있도록 구성했습니다.

핵심 개념

OpenCode의 프로바이더 중립 아키텍처

OpenCode는 Go 언어로 작성된 MIT 라이선스 오픈소스 AI 코딩 에이전트입니다. 터미널에서 바로 쓰는 도구인데, Claude Code나 Cursor 같은 SaaS 도구들이 특정 클라우드 벤더에 종속된 것과 달리 동일한 에이전트 루프 안에서 어떤 프로바이더든 자유롭게 조합할 수 있는 구조로 설계됐습니다. 75개 이상의 LLM을 단일 opencode.json 파일 하나로 연결할 수 있다는 게 핵심입니다.

프로바이더 중립(Provider-Agnostic): 특정 LLM 벤더의 API에 종속되지 않고, 표준 인터페이스(주로 OpenAI 호환 API — ChatGPT와 같은 방식으로 호출 가능한 인터페이스)를 통해 어떤 모델이든 교체 가능한 아키텍처 설계 방식

설정 파일에서 주목할 핵심 필드는 두 개입니다.

• model: 기본 작업에 쓰이는 메인 모델
• small_model: 반복적이고 단순한 작업에 자동으로 배정되는 경량 모델

small_model이 어떻게 트리거되는지가 사실 제일 궁금한 부분일 텐데, 저도 처음에 이게 "무슨 기준으로 작은 모델을 쓰는 거지?" 하고 한참 헷갈렸습니다. OpenCode는 내부적으로 파일 요약, 제목 생성, 단순 완성 같은 보조적인 서브태스크를 small_model에 위임합니다. 메인 에이전트 루프가 돌아가는 동안 주요 태스크가 아닌 "주변 작업"에 해당하는 것들이죠. 토큰 수 기준이 아니라 작업 유형 기준입니다. 따라서 /model로 직접 전환하지 않는 한 복잡한 아키텍처 설계는 항상 model로 처리됩니다.

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-6",
  "small_model": "ollama/qwen3:30b-a3b",
  "provider": {
    "ollama": {
      "name": "Ollama",
      "baseURL": "http://localhost:11434/v1",
      "models": {
        "qwen3:30b-a3b": { "name": "Qwen3 30B MoE" },
        "devstral": { "name": "Devstral Small 24B" }
      }
    }
  }
}

이 파일은 프로젝트 루트에 opencode.json으로 저장하면 해당 프로젝트에만 적용되고, ~/.config/opencode/config.json에 두면 모든 프로젝트에 전역 적용됩니다.

비용 에스컬레이션 계층화 원칙

솔직히 말하면, 처음에는 "그냥 좋은 모델 하나만 쓰면 되지 않나?" 싶었습니다. 근데 실제로 작업 유형을 분석해보면 대부분의 시간은 보일러플레이트 작성, 테스트 생성, 단순 리팩터링에 쓰이고, 진짜 복잡한 설계 결정은 전체 작업의 1020%에 불과합니다. 그 1020%에만 비싼 모델을 쓰는 게 핵심입니다.

비용 에스컬레이션: 가장 저렴한 옵션부터 시작해 작업 요구사항이 올라갈 때만 상위 티어 모델로 격상하는 단계적 비용 투입 전략

2025~2026년 로컬 모델의 성숙도

불과 1~2년 전만 해도 로컬 모델은 "쓸 순 있지만 결국 클라우드로 돌아오게 되는" 수준이었는데, 지금은 얘기가 달라졌습니다. SWE-bench 기준으로 Qwen3 30B-A3B가 73.4%, Devstral Small 24B가 68%를 기록하고 있습니다. 여기서 Ollama는 이 모델들을 로컬에서 구동하게 해주는 도구인데, OpenAI 호환 API 서버를 내장하고 있어 http://localhost:11434/v1로 바로 접근 가능합니다 — 설치는 ollama.com에서 할 수 있습니다.

"Devstral이 Claude Sonnet 대비 7배 비용 효율"이라는 수치는 API 요금 기준 비교입니다. Devstral을 클라우드 API로 쓸 때 대비 Sonnet을 쓸 때의 토큰 단가 차이를 말하는 거고, Ollama로 로컬 실행하면 API 비용 자체가 0이 됩니다. 물론 하드웨어 비용(전기료, GPU 감가상각)은 별개입니다. RTX 4090 기준으로는 API 절약분으로 3~6개월 내 회수 가능하다는 계산이 나오지만, 이미 고성능 맥이나 GPU를 갖고 있다면 추가 비용 없이 바로 혜택을 볼 수 있습니다.

실전 적용

예시를 보기 전에, 어떤 구성이 내 상황에 맞는지 먼저 확인해 보시면 좋습니다.

• 개인 개발자, 처음 설정하는 경우 → 예시 1 (3단계 계층화, 가장 단순)
• 여러 팀원이 같은 설정을 공유하거나 프로바이더를 자주 바꾸는 경우 → 예시 2 (LiteLLM 게이트웨이)
• 복잡한 자동화 워크플로를 원하는 경우 → 예시 3 (에이전트 분리)
• 핀테크·헬스케어 등 코드가 외부로 나가면 안 되는 환경 → 예시 4 (프라이버시 우선)

예시 1: 3단계 모델 계층화 구성

가장 간단하게 시작할 수 있는 구성입니다. small_model에 Ollama 로컬 모델을 배정하고, 복잡한 작업이 생길 때만 세션 내에서 /model 명령으로 클라우드로 전환하는 방식입니다.

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-6",
  "small_model": "ollama/qwen3:30b-a3b",
  "provider": {
    "anthropic": {
      "apiKey": "$ANTHROPIC_API_KEY"
    },
    "ollama": {
      "name": "Ollama",
      "baseURL": "http://localhost:11434/v1",
      "models": {
        "qwen3:30b-a3b": { "name": "Qwen3 30B MoE" },
        "devstral": { "name": "Devstral Small 24B" }
      }
    }
  }
}

"apiKey": "$ANTHROPIC_API_KEY" 부분은 OpenCode가 런타임에 셸 환경 변수를 읽어오는 방식입니다. 이 값을 그대로 복사하면 반드시 셸에 export ANTHROPIC_API_KEY=sk-ant-...가 설정되어 있거나, 프로젝트 루트에 .env 파일이 있어야 합니다. 없으면 리터럴 문자열 $ANTHROPIC_API_KEY가 API 키로 전송되어 인증 오류가 납니다. 저도 처음에 이걸 놓쳐서 한참 헤맸습니다.

ollama/qwen3:30b-a3b의 baseURL인 http://localhost:11434/v1은 Ollama 설치 후 ollama serve를 실행하면 기본으로 열리는 주소입니다. Docker 환경이거나 포트를 변경했다면 이 주소를 맞게 수정해줄 필요가 있습니다.

세션 중 모델을 바꾸고 싶을 때는 TUI에서 /model 명령어를 입력하거나 variant_cycle 키바인딩을 활용하면 실시간 전환이 됩니다.

개념을 파악했으니, 이제 각 상황별 구성을 더 깊이 살펴보겠습니다.

예시 2: LiteLLM 게이트웨이로 설정 단순화

멀티 프로바이더 설정에서 가장 번거로운 부분이 각 프로바이더별 API 키 관리와 URL 설정입니다. LiteLLM 프록시를 로컬에 띄워두면 OpenCode 입장에서는 단일 엔드포인트 하나만 바라보면 되고, 실제 라우팅은 LiteLLM이 처리합니다.

{
  "$schema": "https://opencode.ai/config.json",
  "model": "gateway/claude-sonnet-4-6",
  "small_model": "gateway/ollama/qwen3:30b-a3b",
  "provider": {
    "gateway": {
      "name": "LiteLLM Gateway",
      "baseURL": "http://localhost:4000/v1",
      "apiKey": "sk-local",
      "models": {
        "claude-sonnet-4-6": {},
        "ollama/qwen3:30b-a3b": {},
        "ollama/devstral": {}
      }
    }
  }
}

"apiKey": "sk-local"이 좀 이상해 보일 수 있는데, 로컬 프록시라서 그렇습니다. LiteLLM을 로컬에 띄우면 실제 API 키 검증을 거치지 않고 임의 값을 그냥 통과시키도록 설정할 수 있습니다. 외부로 나가는 게 아니니 보안 위험도 없고, 어떤 문자열을 넣어도 동작합니다.

LiteLLM 프록시: Anthropic, OpenAI, Ollama, Gemini 등 100개 이상의 LLM을 단일 OpenAI 호환 엔드포인트 뒤에 묶어주는 오픈소스 게이트웨이. pip install litellm으로 설치 후 litellm --config config.yaml로 로컬 실행 가능

이 패턴의 진짜 장점은 OpenCode 설정을 손대지 않고도 LiteLLM 설정 파일만 수정해서 프로바이더를 교체하거나 새 모델을 추가할 수 있다는 점입니다. 팀에서 공유하는 설정이라면 특히 유용합니다.

예시 3: 역할별 특화 에이전트 구성 (Oh My OpenCode)

더 나아가면 오케스트레이터·플래너·익스큐터·리서처 역할을 각각 다른 모델에 배정하는 "버추얼 팀" 구조도 가능합니다. 이 agents 필드는 Oh My OpenCode(OpenCode 위에 올라가는 에이전트 워크플로 프레임워크)의 설정 스키마입니다. OpenCode 기본 opencode.json에 직접 추가하는 것과는 구분됩니다 — Oh My OpenCode를 따로 설치해야 이 구성이 동작합니다.

{
  "$schema": "https://opencode.ai/config.json",
  "agents": {
    "orchestrator": {
      "model": "anthropic/claude-haiku-4-5",
      "description": "작업 분배 및 계획 수립"
    },
    "fixer": {
      "model": "ollama/devstral",
      "description": "버그 수정 및 코드 편집"
    },
    "oracle": {
      "model": "ollama/qwen3:30b-a3b",
      "description": "코드 분석 및 리뷰"
    },
    "architect": {
      "model": "anthropic/claude-opus-4-7",
      "description": "아키텍처 결정 및 설계"
    }
  }
}

description 필드는 단순 주석이 아니라 Oh My OpenCode가 작업을 어느 에이전트에 라우팅할지 판단할 때 참조하는 메타데이터입니다. 고빈도로 호출되는 오케스트레이터를 저렴한 Haiku로 처리하고, 실제 무거운 연산은 무료 로컬 모델이 담당하는 구조입니다.

예시 4: 민감한 코드베이스를 위한 프라이버시 우선 구성

핀테크나 헬스케어처럼 코드가 외부 서버로 전송되면 안 되는 환경에서는 Ollama 100% 로컬 구성으로 시작하는 게 안전합니다.

{
  "$schema": "https://opencode.ai/config.json",
  "model": "ollama/qwen3:30b-a3b",
  "small_model": "ollama/devstral",
  "provider": {
    "ollama": {
      "name": "Ollama (Local Only)",
      "baseURL": "http://localhost:11434/v1",
      "models": {
        "qwen3:30b-a3b": { "name": "Qwen3 30B MoE" },
        "devstral": { "name": "Devstral Small 24B" }
      }
    }
  }
}

baseURL의 http://localhost:11434/v1은 Ollama 기본 주소입니다. 표준 포트로 로컬 설치했다면 이 주소를 그대로 써도 됩니다. Docker Compose 환경이거나 포트를 바꿨다면 그에 맞게 수정이 필요합니다.

클라우드 프로바이더 섹션을 아예 제거하면 실수로라도 민감한 코드가 외부로 나가는 상황을 원천 차단할 수 있습니다.

장단점 분석

장점

단점 및 주의사항

instruction-following: 모델이 주어진 지시사항(예: "이 파일만 수정해", "JSON으로만 응답해")을 얼마나 정확하게 따르는지 측정하는 능력. 코딩 에이전트에서는 SWE-bench 점수만큼이나 중요한 실용 지표

실무에서 자주 마주치는 함정

1. 속도 저하가 모델 문제라고 오해하는 경우 — 현재 OpenCode의 Ollama 경유 속도 저하 버그(#4182)가 진행 중입니다. 로컬 모델인데 응답이 이상하게 느리다면 모델 교체 전에 이 이슈를 먼저 확인해보시면 좋습니다. LiteLLM 게이트웨이를 경유하면 임시 우회가 되는 경우가 있었습니다.

2. 컨텍스트 윈도우 확인 없이 모델을 고르는 경우 — 저도 처음에 벤치마크 점수만 보고 골랐다가 멀티파일 작업 중간에 컨텍스트가 잘려 에이전트가 이상하게 동작하는 상황을 만났습니다. 64K 토큰 이상을 지원하는 모델인지 먼저 확인하는 것을 권장합니다.

3. 처음부터 멀티 에이전트 구성을 시도하는 경우 — 예시 3의 에이전트 분리 구성은 강력하지만, 초기에는 model + small_model 두 필드만으로 시작해서 실제 비용과 품질을 측정한 뒤 점진적으로 확장하는 게 훨씬 안정적입니다. 복잡한 구성일수록 어디서 문제가 생기는지 추적하기 어렵습니다.

마치며

모델 전략 자체보다 더 중요한 건 자신의 작업 패턴을 데이터로 측정하는 습관입니다. 어떤 작업에 얼마나 쓰는지 실측해야 진짜 최적화가 시작됩니다.

지금 바로 시작해볼 수 있는 3단계:

1. Ollama를 설치하고 Qwen3 30B-A3B 모델을 내려받아볼 수 있습니다. ollama pull qwen3:30b-a3b 명령어로 모델을 받고 ollama serve로 로컬 서버를 띄워두면 http://localhost:11434/v1에서 OpenAI 호환 API로 접근됩니다. 하드웨어가 24GB VRAM에 미치지 못한다면 devstral이나 더 작은 모델부터 시도해보시면 좋습니다.

2. 프로젝트 루트의 opencode.json에 "small_model": "ollama/qwen3:30b-a3b" 한 줄을 추가해볼 수 있습니다. 기존 클라우드 메인 모델은 그대로 두고 small_model만 Ollama로 전환하면, 단순 반복 작업부터 로컬 처리가 시작됩니다. 어떤 작업이 로컬로 빠지는지 관찰해보시면 패턴이 보입니다.

3. 일주일 정도 사용한 뒤 클라우드 API 비용 변화를 확인해보시면 좋습니다. Anthropic는 console.anthropic.com → Usage 탭에서 일별·모델별 토큰 사용량과 비용을 확인할 수 있습니다. 절감 효과가 체감된다면 LiteLLM 게이트웨이나 에이전트 분리 구성으로 점진적으로 확장해나가는 것을 고려해볼 수 있습니다.

참고 자료

공식 문서

• OpenCode 공식 문서 - Providers
• OpenCode 공식 문서 - Models
• OpenCode 공식 문서 - Config
• Ollama 공식 OpenCode 통합 가이드
• LiteLLM + OpenCode 통합 퀵스타트 | LiteLLM 공식 문서

커뮤니티 가이드

• OpenCode + Ollama 홈랩 구축 가이드 | Virtualization Howto
• Ollama로 OpenCode 로컬 AI 코딩 환경 구축 | DevelopersIO
• OpenCode + Ollama 프라이버시 가이드 | Lushbinary
• OpenCode Go + Oh My OpenAgent 모델 라우팅 | Medium
• Oh My OpenCode 특화 에이전트 심층 분석 | Medium
• OpenCode + Vercel AI Gateway 활용 가이드 | Vercel
• groxaxo/opencode-local-setup | GitHub
• OpenCode 모델 중립 AI 코딩 어시스턴트 | Red Hat Developer

벤치마크 및 모델 분석

• 코딩 에이전트를 위한 최고의 Ollama 모델 순위 | haimaker.ai
• OpenCode용 LLM 로컬 비교 테스트 | Rost Glukhov
• OpenCode 커스텀 프로바이더 설정 | haimaker.ai