[opencode 시즌 2 심화 — 나만의 도메인 특화 에이전트 만들기] 5/12화: opencode 모델 라우팅 4단계 실전 가이드 2026

이 글은 「opencode 시즌 2 심화 — 나만의 도메인 특화 에이전트 만들기」 5일차입니다.

시즌 1에서 opencode의 모델 설정을 처음 다뤘을 때, 대부분의 독자분은 기본 모델 하나로 모든 작업을 처리했을 겁니다. “좋은 모델이면 다 잘하지 않나요?”라는 생각이 자연스러웠죠. 하지만 에이전트를 여러 개 운영하기 시작하면 이야기가 완전히 달라집니다. 오늘은 opencode 모델 라우팅의 세계로 들어갑니다 — 에이전트마다 다른 두뇌를 심는 기술입니다.

어제 4일차에서 allow·ask·deny 권한 매트릭스로 에이전트의 행동 반경을 통제했습니다. 에이전트가 “무엇을 할 수 있는가”를 정했으니, 오늘은 “무엇으로 생각하는가”를 결정할 차례입니다. 같은 지시를 받아도 어떤 모델이 처리하느냐에 따라 속도, 품질, 비용이 극적으로 달라지니까요.

오늘의 핵심 3가지

• provider/model-id 포맷으로 에이전트마다 독립적인 모델을 배치하는 구체적 방법
• temperature·top_p·reasoning effort 파라미터로 작업 성격에 맞게 출력을 미세 조정하는 기법
• 비용·속도·품질 트레이드오프 매트릭스와 BYOK 전략으로 운영 비용을 체계적으로 최적화하기

모든 에이전트에 같은 모델? — 모델 라우팅이 필요한 순간

3일차에서 만든 코드 리뷰 에이전트를 떠올려보세요. 리뷰어는 코드를 한 줄 한 줄 꼼꼼히 읽고 결함을 찾아내야 합니다. 이런 작업에는 추론 능력이 강한 대형 모델이 적합합니다. 반면, 프로젝트 파일 구조를 탐색하고 관련 모듈 목록을 정리하는 Explore 서브에이전트는 어떨까요? 디렉토리를 훑고 파일 목록을 반환하는 데 최상위 모델을 투입하는 건 마치 F1 레이싱카로 편의점에 가는 것과 같습니다. 비용만 들고, 도착 시간 차이는 미미합니다.

실제로 모델 라우팅 없이 에이전트 팀을 운영하면 다음 세 가지 문제가 반복적으로 발생합니다.

문제 1: 비용이 선형적으로 증가한다

에이전트 팀이 하나의 요청을 처리할 때, 내부적으로 여러 차례의 모델 호출이 발생합니다. “이 PR 리뷰해줘”라는 한 마디가 내부에서는 계획 수립 1회 → 파일 탐색 3~5회 → 코드 분석 2~3회 → 종합 보고 1회로 분해됩니다. 모든 호출에 고가 모델을 쓰면, 탐색 단계에서만 전체 비용의 절반 이상이 소모됩니다. 탐색은 가장 빈번하지만 가장 단순한 작업이니까요.

문제 2: 속도 병목이 엉뚱한 곳에 생긴다

사용자가 요청을 보내고 첫 응답을 받기까지의 시간은 Plan 에이전트의 응답 속도에 달려 있습니다. 그런데 Plan에 대형 모델을 두면 “작업을 분석하고 있습니다…”라는 메시지가 5~10초 뒤에야 나옵니다. 경량 모델은 같은 계획 수립을 1~2초에 끝냅니다. 사용자 체감으로는 이 차이가 “빠르다/느리다”를 가르는 핵심입니다.

문제 3: 모든 모델이 모든 작업에 최적은 아니다

대형 모델이 항상 더 나은 결과를 내는 것은 아닙니다. 예를 들어, 파일 목록을 정리하는 단순 작업에서 대형 모델은 “과도하게 친절한” 응답을 생성하기도 합니다 — 불필요한 설명, 요약, 제안을 덧붙이면서 오히려 후속 에이전트의 파싱을 방해합니다. 경량 모델은 지시한 대로 간결하게 결과만 반환하는 경향이 강해서, 파이프라인의 중간 단계에서는 오히려 더 적합합니다.

opencode 모델 라우팅은 이 세 가지 문제를 한 번에 해결합니다. 작업의 성격에 맞는 모델을 에이전트별로 독립 배치하면, 전체 시스템의 비용은 낮추면서 품질은 유지하거나 오히려 높일 수 있습니다.

opencode 모델 라우팅의 기본 구조

provider/model-id 포맷 완전 이해

opencode에서 모델을 지정하는 공식 포맷은 provider/model-id입니다. 슬래시(/) 앞이 프로바이더(API 공급자), 뒤가 해당 프로바이더의 모델 식별자입니다. 이 단순한 규칙 하나로 수십 개의 모델을 자유롭게 조합할 수 있습니다. 주요 프로바이더별 대표 모델을 정리합니다.

# ─── Anthropic 모델 ───
anthropic/claude-sonnet-4-5        # 균형형 — 빠르면서 높은 품질, 범용 기본값으로 추천
anthropic/claude-haiku-4-5         # 초경량 — 최고 속도, 최저 비용, 탐색·요약에 최적
anthropic/claude-opus-4-5          # 최강 — 복잡한 추론·대규모 리팩토링에 적합

# ─── OpenAI 모델 ───
openai/gpt-4o                      # 범용 강력 모델, 교차 리뷰에 유용
openai/gpt-4o-mini                 # 경량·저비용, 단순 분류·변환에 적합
openai/o3-mini                     # 추론 특화 (reasoning effort 파라미터로 깊이 조절)

# ─── Google 모델 ───
google/gemini-2.5-pro              # 대규모 컨텍스트 처리 (100만 토큰+)
google/gemini-2.5-flash            # 초고속 응답, 대용량 파일 스캔에 강점

# ─── 로컬 모델 (Ollama) ───
ollama/codestral:latest            # 코드 특화, 비용 제로, 로컬 GPU 필요
ollama/deepseek-coder-v2:latest    # 오픈소스 코드 모델, 망분리 환경에 적합

여기서 중요한 점은 프로바이더마다 별도의 API 키가 필요하다는 것입니다. anthropic/ 접두어를 쓰려면 Anthropic API 키가, openai/를 쓰려면 OpenAI API 키가 환경에 등록되어 있어야 합니다. 로컬 모델(ollama/)은 API 키 없이 로컬에서 Ollama 서버만 구동하면 됩니다. 키 등록 방법은 뒤의 BYOK 섹션에서 자세히 다룹니다.

model-id 부분은 각 프로바이더의 공식 식별자를 그대로 씁니다. Anthropic은 claude-sonnet-4-5, OpenAI는 gpt-4o 같은 식입니다. 오타가 나면 opencode 시작 시 “unknown model” 에러가 발생하니 철자를 정확히 확인하세요. 각 프로바이더의 공식 모델 목록은 Anthropic 모델 문서, OpenAI 모델 문서에서 확인할 수 있습니다.

설정 계층과 우선순위 — 충돌 시 누가 이기는가

opencode의 모델 설정은 여러 레벨에서 지정할 수 있습니다. 같은 에이전트에 대해 여러 곳에서 모델을 지정하면 어떻게 될까요? 답은 간단합니다: 더 구체적인 설정이 이깁니다. 우선순위를 높은 것부터 정리하면 다음과 같습니다.

1. 에이전트 정의 파일의 model 키 (최우선) — .opencode/agents/reviewer.md의 YAML frontmatter에 적힌 모델. 가장 구체적이므로 다른 모든 설정을 덮어씁니다.
2. opencode.json의 agent별 model — JSON 파일에서 특정 에이전트 이름에 지정한 모델. 에이전트 정의 파일에 model이 없을 때 적용됩니다.
3. opencode.json의 글로벌 model — 전체 프로젝트의 기본 모델. 어떤 에이전트에도 개별 모델이 지정되지 않았을 때 사용됩니다.
4. 글로벌 설정 (~/.config/opencode/) — 사용자 머신 전체에 걸린 기본값. 프로젝트별 설정이 없을 때 폴백합니다.
5. opencode 내장 기본값 (최후순위) — 어떤 설정도 없을 때 opencode가 자체적으로 선택하는 모델.

이 계층 구조 덕분에 “평소에는 Sonnet으로 쓰다가 보안 감사 에이전트만 Opus로” 같은 세밀한 배치가 가능합니다. 또한 글로벌 설정에 기본 모델을 두고, 특정 프로젝트에서만 다른 모델을 쓰는 것도 자연스럽습니다.

기본 모델 — 무엇을 글로벌 기본값으로 삼을 것인가

프로젝트의 opencode.json에서 "model" 키에 적는 값이 글로벌 기본 모델입니다. 개별 오버라이드가 없는 모든 에이전트가 이 모델을 사용하므로, 신중하게 선택해야 합니다. 추천 기준은 다음과 같습니다.

• 비용과 품질의 균형: 가장 비싼 모델도 가장 저렴한 모델도 아닌, 중간 계층이 적합합니다. anthropic/claude-sonnet-4-5나 openai/gpt-4o 같은 모델이 범용 기본값으로 많이 쓰입니다.
• 코드 작업 품질: 에이전트 팀의 주 업무가 코드라면, 코드 생성 벤치마크 점수가 높은 모델을 우선합니다.
• 응답 속도: 기본값이 너무 느리면 전체 워크플로가 지체됩니다. 평균 응답 시간이 3초 이내인 모델이 바람직합니다.

// opencode.json — 글로벌 기본 모델 설정
{
  "model": "anthropic/claude-sonnet-4-5"
}

이 한 줄이 모든 에이전트의 출발점이 됩니다. 이제 여기에 에이전트별 오버라이드를 얹어봅시다.

에이전트별 opencode 모델 라우팅 — 4가지 핵심 전략

모델 라우팅의 실전은 “어떤 에이전트에 어떤 모델을 배치할 것인가”입니다. 지난 4일간 설계한 에이전트 아키텍처(1일차), 정의 방식(2일차), 시스템 프롬프트(3일차), 권한(4일차) 위에 오늘 모델 배치를 얹으면 에이전트 설계의 핵심 축이 모두 완성됩니다. 실무에서 검증된 4가지 전략을 하나씩 살펴보겠습니다.

전략 1: 계획은 빠르게, 구현은 강력하게

가장 기본적이면서도 효과가 큰 전략입니다. opencode의 Primary 에이전트인 Plan과 Build의 역할 차이를 직접 활용합니다.

• Plan 에이전트: 사용자와 대화하며 작업을 분석하고 실행 계획을 세웁니다. 이 단계에서는 빠른 응답이 사용자 경험에 직결됩니다. 계획 수립은 “무엇을 해야 하는지”를 판단하는 일이라 대형 모델이 아니어도 충분히 잘합니다.
• Build 에이전트: 실제 코드를 읽고, 수정하고, 새로 작성합니다. 여기서는 코드의 정확성과 품질이 핵심이므로 더 강력한 모델이 적합합니다.

// opencode.json — 전략 1: Plan은 경량, Build는 중상위

{
  "model": "anthropic/claude-sonnet-4-5",
  "agent": {
    "plan": {
      "model": "anthropic/claude-haiku-4-5"
    },
    "build": {
      "model": "anthropic/claude-sonnet-4-5"
    }
  }
}

Plan에 Haiku를 배치하면 사용자가 “이 모듈 리팩토링해줘”라고 입력했을 때, Plan 단계의 분석과 전략 수립이 1~2초 안에 끝납니다. “네, 해당 모듈의 의존성을 분석하고 3단계로 리팩토링하겠습니다”라는 응답이 거의 즉각적으로 나옵니다. 이후 Build가 Sonnet으로 실제 코드를 수정할 때는 약간 더 걸리지만, 사용자 입장에서는 “바로 시작했다”는 체감이 생깁니다.

대규모 아키텍처 설계나 전체 모듈 재작성처럼 복잡한 작업이라면, Build에 Opus를 넣어 최대 추론 능력을 확보할 수도 있습니다.

// opencode.json — 대규모 리팩토링 프로젝트용 강화 배치

{
  "model": "anthropic/claude-sonnet-4-5",
  "agent": {
    "plan": {
      "model": "anthropic/claude-sonnet-4-5"
    },
    "build": {
      "model": "anthropic/claude-opus-4-5"
    }
  }
}

이 경우 Plan도 Sonnet으로 올렸습니다. 복잡한 프로젝트에서는 계획 수립 자체가 어려운 작업이 될 수 있으니, 속도보다 계획의 정확도를 우선한 겁니다. 프로젝트 성격에 따라 유연하게 조절하면 됩니다.

전략 2: 탐색·스카우트는 경량 모델로

opencode의 Subagent 중 Explore와 Scout는 코드베이스를 탐색하고 정보를 수집하는 역할입니다. 파일 트리를 읽고, grep으로 패턴을 찾고, 구조를 요약합니다. 이 작업은 복잡한 추론 능력보다 속도와 대용량 컨텍스트 처리 능력이 중요합니다.

# .opencode/agents/scout-fast.md

---
description: "프로젝트 구조를 빠르게 파악하고 관련 파일을 찾아줍니다"
model: google/gemini-2.5-flash
---

프로젝트 코드베이스를 탐색하여 요청된 정보를 찾습니다.
파일 경로, 함수 시그니처, 의존성 관계를 정리해서 보고합니다.
상세 분석은 하지 않으며, 위치와 구조만 빠르게 전달합니다.

Gemini Flash는 응답 속도가 매우 빠르고, 100만 토큰 이상의 대용량 컨텍스트를 처리할 수 있어 탐색 에이전트에 잘 맞습니다. 물론 anthropic/claude-haiku-4-5나 openai/gpt-4o-mini도 좋은 선택입니다. 핵심은 탐색 단계에서 비싼 모델을 쓸 이유가 없다는 것입니다.

왜 탐색 모델 선택이 전체 비용에 그렇게 큰 영향을 줄까요? 에이전트 팀 운영 시 호출 빈도를 분석해보면, 탐색 관련 호출이 전체의 40~60%를 차지합니다. Build가 코드를 수정하기 전에 “이 함수가 어디서 쓰이지?” “관련 테스트 파일이 있나?” 같은 탐색을 여러 번 거치기 때문입니다. 이 구간 하나만 경량 모델로 내려도 전체 비용에 체감할 만큼 큰 차이가 납니다.

전략 3: 리뷰어는 다른 프로바이더의 눈으로

조금 색다르지만 강력한 전략입니다. 코드를 작성하는 에이전트와 리뷰하는 에이전트에 서로 다른 프로바이더의 모델을 배치합니다. 이유는 명확합니다 — 같은 프로바이더의 모델군은 학습 데이터와 추론 패턴에서 비슷한 편향(bias)을 가질 수 있기 때문입니다.

Claude가 작성한 코드를 Claude가 리뷰하면, 코드의 스타일이나 패턴에 대한 “눈에 익음”이 생겨 잠재적 문제를 놓칠 확률이 올라갑니다. GPT-4o가 같은 코드를 보면, 다른 관점에서 문제를 포착할 가능성이 높아집니다. 마치 사람 팀에서 다른 배경의 개발자가 리뷰하면 더 다양한 관점이 나오는 것과 같습니다.

# .opencode/agents/cross-reviewer.md

---
description: "구현 코드를 다른 관점에서 리뷰합니다. Build 에이전트와 다른 모델을 사용하여 편향을 줄입니다"
model: openai/gpt-4o
temperature: 0.3
---

당신은 코드 리뷰어입니다.
다른 AI가 작성한 코드를 받아 다음을 검토합니다:

1. 원본 요구사항과의 일치 여부
2. 엣지 케이스 누락 — 특히 null, 빈 배열, 경계값
3. 성능 병목 가능성 — O(n²) 루프, 불필요한 복사, 메모리 누수
4. 가독성과 유지보수성 — 변수명, 함수 분리, 주석 필요 여부

"이 코드가 맞다"는 가정 없이, 처음 보는 코드를 검토하는 자세로 임합니다.
문제를 발견하면 수정 코드 예시를 반드시 함께 제공합니다.

이 전략은 두 개의 프로바이더 API 키가 모두 필요하므로, 비용과 관리 복잡도가 올라갑니다. 그만한 가치가 있는 프로젝트 — 금융 시스템의 핵심 로직, 보안에 민감한 인프라 코드, 대규모 오픈소스 라이브러리 등 — 에서 선택적으로 적용하세요. 일상적인 유틸리티 코드에까지 교차 리뷰를 돌릴 필요는 없습니다.

전략 4: 로컬 모델로 비용 제로 구간 만들기

Ollama 같은 로컬 추론 서버를 운영하고 있다면, 반복적이고 기계적인 작업에 로컬 모델을 배치할 수 있습니다. API 호출 비용이 0원이 되는 구간을 만드는 겁니다. 네트워크 왕복도 없으니 응답 속도도 대부분 더 빠릅니다 (물론 로컬 GPU 성능에 의존합니다).

# .opencode/agents/formatter.md

---
description: "코드 포맷팅, 린트 수정, 임포트 정리 같은 기계적 작업을 처리합니다"
model: ollama/codestral:latest
temperature: 0.0
---

당신은 코드 포맷터입니다.
요청받은 파일의 다음 항목을 기계적으로 수정합니다:

- 들여쓰기 통일 (프로젝트 설정 기준)
- 미사용 임포트 제거
- 임포트 순서 정리 (stdlib → third-party → local)
- 후행 공백 제거
- 연속 빈 줄 2개 이상 → 1개로 축소

코드 로직은 절대 변경하지 않습니다.
수정 전·후 diff만 출력합니다.

포맷팅, 임포트 정리, 간단한 변수명 일괄 변경 같은 작업은 34B 이상의 코드 특화 로컬 모델로도 충분합니다. temperature: 0.0으로 두면 매번 일관된 결과를 내므로, 기계적 작업에 딱 맞습니다.

다만 로컬 모델의 품질 한계를 명확히 인식해야 합니다. 복잡한 리팩토링, 아키텍처 설계, 보안 감사 같은 높은 추론 능력이 필요한 작업에는 적합하지 않습니다. 역할을 “기계적 변환”으로 엄격하게 한정하고, 시스템 프롬프트에서도 “로직 변경 금지”를 명시하는 것이 핵심입니다.

또한 망분리 환경에서는 외부 API 접근이 불가하므로, 로컬 모델이 유일한 선택지가 됩니다. 이 경우 Build에 70B 이상의 코드 모델(ollama/deepseek-coder-v2:latest 등)을 배치하면, 클라우드 모델에 미치지는 못하지만 합리적인 수준의 코드 작업이 가능합니다.

종합 — 에이전트 역할별 모델 배치 매트릭스

네 가지 전략을 하나의 표로 정리합니다. 프로젝트에 그대로 적용할 수 있는 참고 기준입니다.

에이전트 역할	권장 모델 계층	대표 모델 예시	이유
Plan (계획·대화)	경량	Haiku, Flash, GPT-4o-mini	빠른 첫 응답 → 사용자 체감 속도 향상
Build (코드 구현)	중상위	Sonnet, GPT-4o	코드 정확성·품질 확보
Explore / Scout (탐색)	경량	Haiku, Flash	빈번한 호출(40~60%) → 비용 최적화 핵심
Reviewer (코드 리뷰)	중상위 (다른 프로바이더 권장)	GPT-4o (Build가 Claude일 때)	교차 프로바이더로 편향 감소
Security Auditor (보안 감사)	최상위	Opus	보안 결함은 한 건도 놓치면 안 됨
Formatter (포맷팅)	로컬 모델	ollama/codestral	기계적 작업 → 비용 제로, 응답 즉각적

temperature·top_p·reasoning effort — 파라미터 미세 조정

모델을 배치한 다음 단계는 파라미터 튜닝입니다. 같은 모델이라도 파라미터 하나로 출력의 성격이 크게 달라집니다. “이 모델로 무엇을 하느냐”에 맞춰 파라미터를 조절하면, 모델의 잠재력을 최대한 끌어낼 수 있습니다. opencode의 에이전트 정의에서 조절할 수 있는 주요 파라미터 세 가지를 살펴봅니다.

파라미터별 역할 한눈에

파라미터	범위	낮으면	높으면	주 용도
temperature	0.0 ~ 2.0	결정적·예측 가능한 출력	창의적·다양한 출력	전반적 출력 다양성 제어. 가장 자주 조절하는 파라미터
top_p	0.0 ~ 1.0	상위 소수 토큰만 고려	더 넓은 토큰 풀에서 선택	temperature와 함께 사용 (보통 둘 중 하나만 크게 조절)
reasoning effort	low / medium / high	빠른 응답, 얕은 추론	느린 응답, 깊은 사고	o3-mini 등 추론 모델 전용. 추론 깊이를 직접 조절

실무에서 가장 자주 건드리는 건 temperature입니다. 간단히 말해서, temperature는 모델의 “모험심”을 조절하는 다이얼입니다. 0에 가까우면 가장 확률 높은 토큰만 골라서 안정적이지만 뻔한 답을 내놓고, 1 이상이면 낮은 확률의 토큰도 선택해서 창의적이지만 불안정한 답이 나옵니다.

top_p는 temperature와 비슷한 효과를 내지만 메커니즘이 다릅니다. 토큰 확률을 누적해서 상위 p%에 해당하는 토큰만 후보에 남기는 방식입니다. 두 파라미터를 동시에 극단적으로 변경하면 예측 불가능한 결과가 나올 수 있으므로, 일반적으로 temperature를 주로 조절하고 top_p는 기본값(0.9~1.0)을 유지하는 것이 안전합니다.

reasoning effort는 OpenAI의 o3 시리즈처럼 추론 전용 모델에서만 지원하는 특수 파라미터입니다. 이 파라미터는 모델이 답변 전에 “얼마나 깊이 생각할 것인가”를 직접 조절합니다. low로 설정하면 빠르게 직관적 답을 내놓고, high로 설정하면 단계별 추론 체인을 깊게 탐색합니다. 수학, 로직 퍼즐, 복잡한 조건 분기가 많은 코드에서 특히 유용합니다.

작업 유형별 권장 파라미터 매트릭스

작업 성격에 따른 권장 파라미터 범위를 정리했습니다. 이 표는 출발점이지 정답은 아닙니다 — 팀의 경험과 프로젝트 특성에 따라 미세 조정하세요.

작업 유형	temperature	top_p	reasoning effort	설명
코드 구현	0.2 ~ 0.4	0.95	high	정확한 코드가 목표. 약간의 변동은 허용하되 안정적으로
코드 리뷰	0.1 ~ 0.3	0.9	high	놓침 없는 일관된 판단. 매번 같은 결함을 찾아야 합니다
테스트 생성	0.3 ~ 0.5	0.95	medium ~ high	엣지 케이스 발견에 약간의 창의성 필요
문서 작성	0.5 ~ 0.7	0.95	medium	자연스럽고 읽기 좋은 문장을 위해 자유도 확보
탐색·요약	0.1 ~ 0.2	0.9	low ~ medium	사실 기반의 빠른 정리. 창의성보다 정확성
브레인스토밍·아이디어	0.8 ~ 1.2	0.98	medium	아이디어 발산이 목표. 높은 다양성
보안 감사	0.0 ~ 0.1	0.85	high	가장 보수적. 결정적 출력 + 깊은 추론

이 표에서 몇 가지 패턴이 보입니다. 정확성이 중요한 작업(코드 구현·리뷰·보안)은 temperature를 낮추고, 다양성이 중요한 작업(테스트·문서·브레인스토밍)은 올립니다. reasoning effort는 작업의 논리적 복잡도에 비례하여 설정합니다.

이 매트릭스를 실제 에이전트 정의 파일에 적용한 예시를 보겠습니다.

# .opencode/agents/test-generator.md

---
description: "주어진 코드에 대한 단위 테스트를 자동 생성합니다"
model: anthropic/claude-sonnet-4-5
temperature: 0.4
---

당신은 테스트 엔지니어입니다.
코드를 받으면 다음 기준으로 단위 테스트를 작성합니다:

1. 정상 경로 (happy path) 최소 2개
2. 경계값 (boundary) 최소 1개 — 빈 배열, 0, MAX_INT 등
3. 예외/에러 경로 최소 1개 — null 입력, 타입 불일치, 네트워크 실패
4. 조합 케이스 — 여러 조건이 동시에 만족/불만족하는 시나리오

테스트 프레임워크는 프로젝트의 기존 설정을 따릅니다.
불필요한 모킹은 최소화하고, 실제 동작을 검증하는 테스트를 우선합니다.

테스트 생성에 temperature: 0.4를 쓴 이유를 주목하세요. 테스트는 컴파일되고 실행돼야 하므로 정확해야 하지만, 동시에 “사람이 놓치기 쉬운 엣지 케이스”를 발견하려면 약간의 탐험적 사고가 필요합니다. 0.0으로 두면 매번 동일한 뻔한 테스트만 나오고, 0.8 이상이면 컴파일조차 안 되는 엉뚱한 테스트가 나올 수 있습니다. 0.3 ~ 0.5 범위가 “정확하면서도 다양한 케이스를 커버하는” 최적 지점입니다.

o3-mini의 reasoning effort — 특수 활용 팁

OpenAI의 o3-mini는 reasoning_effort 파라미터를 지원하는 대표적인 추론 모델입니다. 이 모델은 답변 전에 내부적으로 “사고 과정”을 시뮬레이션하는데, reasoning_effort가 이 사고의 깊이를 조절합니다.

• low: 빠른 직관적 판단. “이 변수명 더 좋은 거 있어?” 같은 간단한 질문에 적합. 응답 시간 1~2초.
• medium: 일반적인 코드 작업. 함수 구현, 리팩토링 등. 응답 시간 3~8초.
• high: 복잡한 알고리즘 설계, 동시성 버그 추적, 수학적 증명이 필요한 최적화. 응답 시간 10~30초 이상.

에이전트 팀에서 o3-mini를 활용한다면, 알고리즘 최적화 전용 에이전트를 만드는 것이 효과적입니다.

# .opencode/agents/algorithm-optimizer.md

---
description: "알고리즘 복잡도를 분석하고 최적화 방안을 제시합니다. 수학적 증명이 필요한 작업에 특화됩니다"
model: openai/o3-mini
reasoning_effort: high
temperature: 0.1
---

당신은 알고리즘 전문가입니다.
코드를 받으면 다음을 수행합니다:

1. 현재 시간 복잡도·공간 복잡도 분석
2. 병목 구간 식별 (프로파일링 관점)
3. 최적화된 대안 알고리즘 제시 (Big-O 개선 증명 포함)
4. 최적화 전·후 예상 성능 비교

단순 상수 배수 개선이 아닌, 복잡도 클래스 자체를 낮추는 것이 목표입니다.
개선이 불가능하면 그 이유와 하한(lower bound)을 설명합니다.

비용·속도·품질 트레이드오프 — 한 장 정리

opencode 모델 라우팅의 핵심은 결국 비용·속도·품질의 삼각형에서 작업마다 최적 지점을 찾는 것입니다. 주요 모델의 특성을 비교한 종합표를 준비했습니다. 특정 가격이 아닌 상대적 위치로 표기했으므로, 프로바이더의 요금 변경과 무관하게 참고할 수 있습니다.

프로바이더/모델	상대 비용	응답 속도	추론 품질	코드 생성력	최적 용도
anthropic/claude-opus-4-5	★★★★★	느림	최상	최상	보안 감사, 대규모 리팩토링, 아키텍처 설계
anthropic/claude-sonnet-4-5	★★★☆☆	보통	상	상	코드 구현, 일반 리뷰, 범용 기본값
anthropic/claude-haiku-4-5	★☆☆☆☆	매우 빠름	중	중	계획, 탐색, 요약, 대화
openai/gpt-4o	★★★☆☆	보통	상	상	교차 리뷰, 문서 생성, 멀티모달
openai/gpt-4o-mini	★☆☆☆☆	빠름	중	중	탐색, 분류, 단순 변환
openai/o3-mini	★★☆☆☆	가변*	가변*	중상	알고리즘, 수학적 추론 (effort에 따라 변동)
google/gemini-2.5-flash	★☆☆☆☆	매우 빠름	중	중	대용량 파일 스캔, 초고속 요약
ollama/codestral	무료	로컬 GPU 의존	중하	중	포맷팅, 임포트 정리, 기계적 변환

* o3-mini는 reasoning_effort 파라미터에 따라 속도와 품질이 크게 변동합니다. low면 Haiku급 속도에 중급 품질, high면 Opus 이상의 추론 능력이 나오지만 응답이 10배 이상 느려집니다.

비용 시뮬레이션 — 혼합 배치의 위력

이 표를 실제 비용에 대입해봅시다. 하루에 에이전트 호출이 100회 발생한다고 가정합니다. 호출 분포는 실제 에이전트 팀 운영 데이터를 기반으로 한 평균적인 비율입니다.

배치 전략	호출 분포	상대 일일 비용
전부 Opus	100회 × Opus	100% (기준)
전부 Sonnet	100회 × Sonnet	약 35~40%
전부 Haiku	100회 × Haiku	약 5~8%
혼합 배치 (4전략 적용)	50회 Haiku + 30회 Sonnet + 15회 Opus + 5회 로컬	약 25%

혼합 배치로 비용을 원래의 약 1/4로 낮출 수 있습니다. 그러면서 정작 품질이 중요한 보안 감사(Opus)와 코드 구현(Sonnet) 작업에서는 최고 수준의 품질을 유지합니다. 탐색과 계획에서 절약한 비용으로 핵심 작업에 더 좋은 모델을 쓸 수 있는 셈이죠.

이것이 opencode 모델 라우팅의 핵심 가치입니다. 전체 예산은 고정인데, 그 안에서 비용을 어디에 집중할 것인가를 에이전트 설계 시점에 결정하는 것입니다.

BYOK 전략과 멀티 프로바이더 구성

BYOK(Bring Your Own Key)는 자신의 API 키를 직접 관리하면서 여러 프로바이더를 동시에 활용하는 전략입니다. opencode의 provider/model-id 포맷은 처음부터 멀티 프로바이더를 전제로 설계되었으므로, 여러 프로바이더를 혼용하는 것이 자연스럽습니다.

API 키 등록과 프로바이더 활성화

각 프로바이더의 API 키는 환경 변수로 등록합니다. 키가 등록된 프로바이더의 모델만 사용할 수 있습니다.

# PowerShell (Windows 11) — 현재 세션에만 유효
$env:ANTHROPIC_API_KEY = "sk-ant-api03-..."
$env:OPENAI_API_KEY = "sk-proj-..."
$env:GOOGLE_API_KEY = "AIzaSy..."

# 영구 등록 (사용자 환경변수) — 재부팅 후에도 유지
[System.Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "sk-ant-api03-...", "User")
[System.Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "sk-proj-...", "User")
[System.Environment]::SetEnvironmentVariable("GOOGLE_API_KEY", "AIzaSy...", "User")

키가 등록되면 opencode.json에서 해당 프로바이더의 모델을 자유롭게 사용할 수 있습니다. 등록되지 않은 프로바이더의 모델을 지정하면 opencode가 시작 시 경고를 표시합니다. 로컬 모델(ollama/)은 Ollama 서버가 로컬에서 실행 중이면 API 키 없이도 자동 연결됩니다.

멀티 프로바이더 활용 시나리오

여러 프로바이더를 동시에 쓰는 이유는 단순히 “쓸 수 있으니까”가 아닙니다. 실질적인 이점이 있습니다.

• 편향 감소: 전략 3에서 다뤘듯이, 작성과 리뷰에 다른 프로바이더를 쓰면 교차 검증 효과가 생깁니다.
• 장애 대응: 특정 프로바이더에 장애가 발생해도 다른 프로바이더의 에이전트는 계속 작동합니다. Plan이 Anthropic, Build가 OpenAI라면, Anthropic 장애 시에도 코드 구현은 계속 가능합니다.
• 특화 기능 활용: 각 프로바이더의 강점을 살릴 수 있습니다. 대용량 컨텍스트는 Gemini, 추론 깊이는 o3-mini, 범용 코드 작업은 Claude Sonnet처럼 각자의 장기를 활용합니다.
• 비용 다각화: 프로바이더마다 요금 체계와 할인 정책이 다릅니다. 사용량에 따라 한 곳에 집중하거나 분산할 수 있습니다.

규제 환경에서의 BYOK 고려사항

금융, 의료, 공공 분야처럼 규제가 강한 환경에서 BYOK를 적용할 때는 추가 고려사항이 있습니다.

• 프로바이더 승인: 조직의 정보보안 정책에서 승인된 프로바이더만 사용해야 합니다. 어떤 금융사에서는 “Anthropic API만 승인, OpenAI는 심사 중”일 수 있습니다. opencode.json에 비승인 프로바이더 모델을 넣으면 규정 위반이 됩니다. 팀 차원에서 허용 프로바이더 목록을 관리하세요.
• 데이터 잔존: API로 전송된 코드가 프로바이더 서버에 학습 데이터로 사용되는지 확인하세요. 주요 프로바이더들은 API 입력을 학습에 사용하지 않는다고 명시하고 있지만, 조직의 법무·컴플라이언스 팀과 반드시 확인이 필요합니다.
• 키 관리: API 키를 코드에 하드코딩하거나 Git에 커밋하는 것은 절대 금지입니다. 환경 변수, Windows Credential Manager, 또는 조직의 시크릿 관리 시스템(HashiCorp Vault 등)을 사용하세요.
• 감사 추적: 어떤 에이전트가 어떤 프로바이더의 어떤 모델을 몇 번 호출했는지 기록을 남겨야 하는 규제 요구사항이 있을 수 있습니다. opencode의 로그 출력을 파일로 저장하고, 프로바이더별 사용량 대시보드를 별도로 구축하는 것을 고려하세요.
• 망분리 환경: 외부 인터넷 접근이 차단된 환경에서는 ollama/ 같은 로컬 모델만 사용 가능합니다. 이 경우 GPU 서버에 충분한 크기의 코드 모델을 올려서 전체 에이전트 팀을 로컬에서 운영해야 합니다.

주의: 모델 전환 시 프롬프트 호환성

한 가지 놓치기 쉬운 점이 있습니다. 에이전트의 시스템 프롬프트를 A 모델에 맞춰 최적화한 뒤, 모델을 B로 바꾸면 프롬프트의 효과가 달라질 수 있습니다. 3일차에서 다뤘듯이, Claude 계열은 메커니즘 중심의 체크리스트형 프롬프트에 잘 반응하고, GPT 계열은 원칙 중심의 간결한 지시에 잘 반응하는 경향이 있습니다.

따라서 교차 프로바이더 전략(전략 3)을 적용할 때는, 리뷰어 에이전트의 시스템 프롬프트를 해당 모델에 맞게 별도 작성하는 것이 좋습니다. 같은 프롬프트를 다른 프로바이더 모델에 그대로 복사하면, 의도한 것과 다른 형식이나 깊이의 응답이 나올 수 있습니다.

실전 완성 — 코드 리뷰 팀의 완전한 모델 라우팅 설정

지금까지 배운 모든 내용을 종합해서, 코드 리뷰에 특화된 에이전트 팀의 전체 모델 라우팅 설정을 완성합니다. 이 설정은 그대로 복사해서 프로젝트에 적용할 수 있는 완전한 파일들입니다.

디렉토리 구조부터 확인합니다.

my-project/
├── opencode.json                      # 글로벌 모델 + Primary 에이전트 오버라이드
└── .opencode/
    └── agents/
        ├── code-reviewer.md           # 교차 프로바이더 코드 리뷰어
        ├── security-auditor.md        # 최강 모델 보안 감사관
        ├── quick-scanner.md           # 경량 모델 코드베이스 스캐너
        └── test-generator.md          # 테스트 자동 생성기

먼저 프로젝트 루트의 opencode.json입니다.

{
  "model": "anthropic/claude-sonnet-4-5",
  "agent": {
    "plan": {
      "model": "anthropic/claude-haiku-4-5"
    },
    "build": {
      "model": "anthropic/claude-sonnet-4-5"
    }
  },
  "agents": {
    "directory": ".opencode/agents"
  }
}

글로벌 기본 모델은 claude-sonnet-4-5로, Plan은 빠른 claude-haiku-4-5로, Build는 기본값과 동일한 Sonnet으로 명시적 지정했습니다. Build의 모델을 기본값과 같더라도 명시하는 것은, 나중에 글로벌 기본값을 바꿔도 Build의 모델이 의도치 않게 변경되는 것을 방지하기 위해서입니다.

다음은 .opencode/agents/ 디렉토리의 커스텀 에이전트 파일들입니다.

# .opencode/agents/code-reviewer.md

---
description: "코드 변경사항을 리뷰하고 개선점을 제안합니다. git diff를 분석하여 버그, 성능 이슈, 코드 스멜을 찾습니다"
model: openai/gpt-4o
temperature: 0.2
---

당신은 10년차 시니어 개발자이자 코드 리뷰어입니다.

## 리뷰 기준
1. **정확성**: 로직 오류, 오프바이원, null 체크 누락, 조건문 반전
2. **성능**: O(n²) 이상의 루프, N+1 쿼리, 불필요한 객체 복사, 메모리 누수
3. **보안**: 입력 미검증, 하드코딩된 비밀값, SQL/XSS/SSRF 취약점
4. **가독성**: 불명확한 변수명, 과도한 중첩(3레벨 이상), 매직 넘버

## 출력 형식
각 발견 사항은 아래 형식으로 보고합니다:
- **[심각도]** 파일:라인 — 설명
- 수정 제안 코드 (있을 경우)

심각도: 🔴 Critical / 🟠 High / 🟡 Medium / 🔵 Low
Critical/High가 없을 경우에만 "LGTM" 판정을 내립니다.

# .opencode/agents/security-auditor.md

---
description: "보안 취약점을 전문적으로 탐지합니다. OWASP Top 10 기준으로 심층 감사를 수행합니다"
model: anthropic/claude-opus-4-5
temperature: 0.1
---

당신은 OWASP Top 10에 정통한 보안 감사관입니다.

## 감사 순서
1. **Injection 계열**: SQL, NoSQL, OS Command, LDAP, XPath
2. **인증·인가**: 세션 관리 결함, 권한 상승, IDOR, JWT 검증 우회
3. **민감 데이터**: 평문 저장/전송, 불충분한 암호화, 로그 내 개인정보
4. **설정 오류**: 디버그 모드, 기본 비밀번호, 과도한 에러 메시지 노출
5. **의존성**: 알려진 CVE가 있는 패키지 사용, 오래된 버전 고착

## 규칙
- false positive보다 false negative를 줄이는 것이 우선
- 발견된 취약점마다 CWE 번호와 수정 코드를 제시
- 즉시 대응이 필요한 항목은 [CRITICAL-BLOCK]으로 표시
- 감사 결과를 .opencode/audit-log/{date}_{scope}.md로 저장

# .opencode/agents/quick-scanner.md

---
description: "파일 구조와 의존성을 빠르게 스캔하여 리뷰에 필요한 컨텍스트를 수집합니다"
model: anthropic/claude-haiku-4-5
temperature: 0.1
---

당신은 코드베이스 스캐너입니다.
요청받은 범위의 파일을 빠르게 탐색하고 다음 정보를 간결하게 정리합니다:

1. 변경된 파일 목록과 각 파일의 한 줄 역할 설명
2. 변경 파일이 import하는 다른 모듈 목록 (순방향 의존성)
3. 변경 파일을 import하는 다른 모듈 목록 (역방향 의존성)
4. 관련 테스트 파일 존재 여부와 경로
5. 최근 1개월 내 같은 파일을 수정한 커밋 수

분석이나 판단은 하지 않습니다. 사실만 나열합니다.
출력은 Markdown 표 형식으로 통일합니다.

# .opencode/agents/test-generator.md

---
description: "주어진 코드에 대한 단위 테스트를 자동 생성합니다. 엣지 케이스와 예외 경로를 집중적으로 커버합니다"
model: anthropic/claude-sonnet-4-5
temperature: 0.4
---

당신은 테스트 엔지니어입니다.
코드를 받으면 다음 기준으로 단위 테스트를 작성합니다:

1. 정상 경로 (happy path) 최소 2개
2. 경계값 (boundary) 최소 1개 — 빈 배열, 0, MAX_INT, 빈 문자열
3. 예외/에러 경로 최소 1개 — null, undefined, 타입 불일치, 네트워크 실패
4. 조합 케이스 — 여러 조건이 동시에 만족/불만족하는 시나리오

테스트 프레임워크는 프로젝트의 기존 설정을 따릅니다 (jest, pytest, vitest 등).
불필요한 모킹은 최소화하고, 실제 동작을 검증하는 테스트를 우선합니다.
각 테스트의 이름은 should_예상동작_when_조건 형식으로 명확하게 짓습니다.

이 설정의 모델 배치를 종합하면 다음과 같습니다.

에이전트	모델	프로바이더	temperature	역할
Plan (내장)	claude-haiku-4-5	Anthropic	기본값	사용자 대화·작업 계획 (빠른 응답)
Build (내장)	claude-sonnet-4-5	Anthropic	기본값	코드 수정·구현 (정확한 코드)
code-reviewer	gpt-4o	OpenAI	0.2	교차 프로바이더 코드 리뷰 (편향 감소)
security-auditor	claude-opus-4-5	Anthropic	0.1	보안 심층 감사 (놓침 제로)
quick-scanner	claude-haiku-4-5	Anthropic	0.1	빠른 파일 탐색·컨텍스트 수집
test-generator	claude-sonnet-4-5	Anthropic	0.4	테스트 자동 생성 (적절한 탐험)

6개 에이전트가 3개 모델 계층(Haiku → Sonnet → Opus)과 2개 프로바이더(Anthropic + OpenAI)에 전략적으로 분산 배치되었습니다. 이 구조에서 “이 PR 리뷰해줘”라고 요청하면, 실제 흐름은 이렇게 전개됩니다.

1. Plan (Haiku, ~1초): “PR의 변경 범위를 파악하고 리뷰 전략을 수립합니다”
2. quick-scanner (Haiku, ~2초): 변경 파일 14개 스캔, 의존성 맵 수집, 관련 테스트 존재 여부 확인
3. code-reviewer (GPT-4o, ~10초): 코드 품질 리뷰 — 로직 오류 1건, 성능 이슈 2건 발견
4. security-auditor (Opus, ~15초): 보안 감사 — SQL Injection 가능성 1건 발견, CWE-89 분류
5. test-generator (Sonnet, ~8초): 발견된 이슈에 대한 회귀 테스트 3개 생성
6. Plan (Haiku, ~1초): 전체 결과 종합하여 사용자에게 보고

총 소요 시간 약 37초. 만약 모든 단계를 Opus로 돌렸다면? 탐색에만 10초, 리뷰에 20초, 감사에 25초, 테스트에 18초 — 합계 약 75초에 비용은 4배. 같은 결과를 절반의 시간과 1/4의 비용으로 얻는 셈입니다.

Gotcha 미니 코너 — 모델 라우팅에서 흔히 빠지는 함정

함정: “temperature를 0으로 두면 항상 같은 결과가 나온다”는 오해

temperature: 0.0으로 설정하면 “결정적(deterministic)” 출력이 된다고 흔히 알려져 있습니다. 하지만 실제로는 100% 동일한 결과를 보장하지 않습니다. 놓치기 쉬운 몇 가지 이유가 있습니다.

• 부동소수점 연산 순서: GPU의 병렬 연산 순서는 실행마다 미세하게 달라질 수 있고, 이 차이가 토큰 선택에 영향을 줄 수 있습니다. 특히 긴 출력에서 후반부일수록 누적 차이가 커집니다.
• 프로바이더 내부 캐시: 요청이 다른 서버 인스턴스로 라우팅되면, 캐시 상태 차이로 미세한 변동이 발생할 수 있습니다.
• 모델 업데이트: 프로바이더가 모델을 패치(마이너 업데이트)하면, 같은 model-id라도 내부 가중치가 변경되어 출력이 달라집니다. 이건 temperature와 무관한 변동입니다.

따라서 보안 감사처럼 재현성이 중요한 작업에서는 temperature: 0.0만 믿지 마세요. 출력을 파일로 저장하고, 이전 감사 결과와 비교하는 검증 단계를 두는 것이 안전합니다. 위의 security-auditor 에이전트에 .opencode/audit-log/에 결과를 저장하는 지시를 넣은 것이 바로 이런 이유입니다.

추가로, 같은 에이전트에게 같은 코드를 2~3회 반복 감사시킨 뒤 결과를 합집합하는 “N회 반복 감사” 패턴도 실무에서 사용됩니다. 1회 실행에서 놓친 취약점을 2회차에서 잡아내는 경우가 실제로 있기 때문입니다.

정리 — 오늘 만든 것, 내일 추가할 것

오늘 우리는 에이전트 팀에 모델 라우팅이라는 두뇌 배치 전략을 심었습니다. provider/model-id 포맷으로 에이전트마다 최적의 모델을 배치하고, temperature·top_p·reasoning effort 파라미터로 작업 성격에 맞게 미세 조정했습니다. 비용·속도·품질 트레이드오프 표로 혼합 배치의 위력을 확인했고, 코드 리뷰 팀의 완전한 6개 에이전트 설정까지 완성했습니다.

시즌 2의 흐름을 되짚어봅시다. 1일차에서 에이전트 아키텍처를, 2일차에서 정의 방식을, 3일차에서 시스템 프롬프트를, 4일차에서 권한을, 그리고 오늘 5일차에서 모델 라우팅을 다뤘습니다. Phase B ‘제어·라우팅’이 완성되었습니다. 에이전트 하나하나는 이제 정체성, 권한, 두뇌를 모두 갖춘 셈입니다.

내일 6일차부터는 Phase C ‘오케스트레이션·컨텍스트’에 진입합니다. 에이전트를 여러 개 만들어 놓기만 하면 뭐하나요? 이들이 서로 협력하는 오케스트레이션이 필요합니다. 1 Primary + N Subagent 패턴, description 기반 자동 위임 vs @멘션 수동 호출, 그리고 Reviewer·Tester·Refactor·SecurityAuditor의 역할 분담 매트릭스를 본격적으로 다룹니다. 개별 에이전트가 진짜 ‘팀’으로 움직이기 시작하는 날입니다.

Photo by Konevi on Pexels

---

자주 묻는 질문

opencode 모델 라우팅이란 무엇이고 왜 필요한가요?

opencode 모델 라우팅은 에이전트마다 서로 다른 AI 모델을 독립적으로 배치하는 기술입니다. 모든 에이전트에 같은 고가 모델을 쓰면 비용이 선형적으로 증가하고, 단순 탐색 작업에서 불필요한 지연이 발생하며, 대형 모델이 과도하게 친절한 응답을 생성해 파이프라인을 방해할 수 있기 때문에 작업 성격에 맞는 모델을 분리 배치하는 라우팅이 필요합니다.

opencode에서 에이전트별로 다른 모델을 지정하는 방법은 무엇인가요?

opencode에서는 provider/model-id 포맷으로 모델을 지정합니다. 슬래시 앞이 API 공급자(프로바이더), 뒤가 해당 프로바이더의 모델 식별자이며, 이 규칙 하나로 수십 개의 모델을 에이전트마다 독립적으로 조합할 수 있습니다. 예를 들어 anthropic/claude-sonnet-4-5 같은 형식으로 작성합니다.

opencode 모델 라우팅에서 temperature, top_p 같은 파라미터는 어떤 역할을 하나요?

temperature, top_p, reasoning effort 파라미터는 작업 성격에 맞게 모델의 출력을 미세 조정하는 데 사용됩니다. 이를 통해 코드 리뷰처럼 정밀한 추론이 필요한 작업과 파일 탐색처럼 간결한 응답이 필요한 작업에 각각 최적화된 출력을 얻을 수 있으며, 비용·속도·품질의 트레이드오프를 체계적으로 관리할 수 있습니다.