Oh My OpenCode(oh-my-openagent) 카테고리 라우팅으로 멀티 에이전트 AI 코딩 API 비용을 월 $11대로 낮춘 구성

"비싼 판단력은 아끼고, 싼 실행력은 넉넉히 쓴다."

💡 이 글은 2026년 5월 기준입니다. Oh My OpenCode(OMO)는 2026년 초 oh-my-openagent로 리브랜딩되어 GitHub 저장소가 code-yeongyu/oh-my-openagent로 이전됐습니다. 리브랜딩 이전 버전은 oh-my-opencode.json, 이후 현재 버전은 opencode.json을 설정 파일로 사용합니다.

솔직히 말하면, 멀티 에이전트 시스템을 처음 써보고 첫 달 청구서를 받았을 때 꽤 놀랐습니다. "코드 한 줄 짜는 데 이 돈이?" 싶었죠. 전부 Claude Opus로 굴리던 시절 한 달 API 비용이 수백 달러에 달했는데, Oh My OpenCode(이하 OMO)를 제대로 설정하고 나서 같은 규모 프로젝트를 월 $11대로 운영하게 됐습니다.

핵심 아이디어는 단순합니다. "모든 에이전트에게 같은 급의 모델을 쓸 필요가 없다"는 것입니다. 전략을 짜는 오케스트레이터에게는 고성능 모델을, 파일 탐색이나 문서 조회 같은 반복 작업을 처리하는 익스큐터에게는 저가 모델을 라우팅하면 됩니다. 이 글에서는 카테고리 기반 모델 라우팅과 Git Worktree 격리를 조합해 실제로 비용을 대폭 줄이는 구체적인 설정 구성을 살펴봅니다.

핵심 개념

3계층 아키텍처: 누가 무엇을 맡는가

OMO는 단일 AI 에이전트를 역할이 명확히 분리된 가상 개발팀으로 전환합니다. 처음 구조도를 봤을 때 "이게 정말 필요한가?" 싶었는데, 비용 내역을 보고 나서 생각이 바뀌었습니다.

에이전트 이름은 그리스 신화에서 따왔는데, 이름보다는 역할의 경계가 중요합니다. 오케스트레이터는 절대 코드를 직접 작성하지 않는다는 원칙이 이 구조 전체의 핵심입니다. 계획과 실행의 경계를 엄격히 유지함으로써 고가 모델이 소비하는 토큰을 의사결정에만 집중시킬 수 있습니다.

에이전트 간 통신은 tool call 형태로 이루어집니다. Sisyphus가 익스큐터를 "스폰한다"고 표현하지만, 실제로는 오케스트레이터가 명세된 도구를 호출하는 방식으로 작업을 위임하고 결과를 돌려받는 구조입니다.

왜 비용이 줄어드는가: MVI 원칙

MVI (Minimum Viable Intelligence): 주어진 작업을 수행하기에 충분한 최소 지능 수준의 모델을 선택한다는 원칙. "파일 검색에 Claude Opus를 쓰는 건 포크레인으로 화분 옮기는 것과 같다"는 비유가 잘 맞습니다.

파일 탐색이나 심볼 검색 같은 작업은 사실 정해진 도구를 올바른 인자로 호출하는 것이 전부입니다. Claude Haiku나 Gemini Flash로도 충분히 수행할 수 있고, 중간 규모 프로젝트의 코드베이스 탐색·심볼 검색 위주 반복 작업 기준으로 단일 작업당 토큰 소비가 8,000토큰에서 750토큰 수준까지 줄어든 사례가 보고됐습니다(약 90% 감소). 작업 유형에 따라 차이가 있을 수 있으나, 고가 모델을 반복 작업에 투입할 이유가 없다는 것만큼은 분명합니다.

카테고리 기반 라우팅이 핵심인 이유

에이전트별로 모델을 일일이 지정하는 방식은 유지보수가 번거롭습니다. 익스큐터 에이전트가 10개를 넘어가면 더욱 그렇죠. OMO가 채택한 카테고리 기반 라우팅은 이 문제를 깔끔하게 해결합니다.

에이전트 직접 지정 → 사용자 오버라이드 → 카테고리 폴백 → 시스템 기본값

Sisyphus가 하위 에이전트를 스폰할 때 모델명이 아닌 카테고리(execution, research 등)를 지정하면, 그 카테고리에 매핑된 모델이 자동으로 적용됩니다. 나중에 저가 모델을 교체하더라도 카테고리 설정 한 줄만 바꾸면 됩니다.

실전 적용

예시 1: 카테고리별 모델 라우팅 설정

프로젝트 루트의 opencode.json에서 카테고리와 모델을 연결합니다. 동시성(concurrency) 값이 비용에 직접 영향을 주므로 신중하게 설정하는 것을 권장합니다.

{
  "categories": {
    "planning": {
      "model": "anthropic/claude-opus-4-7",
      "concurrency": 1
    },
    "execution": {
      "model": "google/gemini-2.0-flash",
      "concurrency": 4
    },
    "research": {
      "model": "anthropic/claude-haiku-4-5",
      "concurrency": 6
    }
  }
}

모델 식별자 형식은 플랫폼마다 다릅니다. 위 예시는 OpenRouter 기준이며, Vertex AI나 직접 API를 사용하는 경우 해당 플랫폼의 모델 식별자를 별도로 확인해보시면 됩니다.

오케스트레이터 동시성을 1로 제한하는 이유는 간단합니다. 여러 오케스트레이터가 동시에 익스큐터를 스폰하면 비용이 기하급수적으로 불어나고, 에이전트 간 충돌이 생길 수 있습니다. 저도 처음엔 "병렬로 돌리면 빠르지 않나?" 싶어서 2로 설정했다가 청구서를 보고 바로 되돌렸습니다.

예시 2: 반복 작업 전담 익스큐터 에이전트 정의

.opencode/agents/ 디렉터리에 Markdown 파일로 익스큐터를 정의합니다. YAML frontmatter는 10줄 미만으로 유지하는 것이 좋습니다. 컨텍스트 윈도우 낭비를 막기 위해서입니다.

---
description: 코드베이스 탐색 및 심볼 검색 전담 에이전트
mode: subagent
model: anthropic/claude-haiku-4-5
temperature: 0.0
---
You are a codebase explorer. Your only job is to search, read,
and summarise code. Never write or modify files.
Always return structured findings to the orchestrator.

시스템 프롬프트를 영어로 작성한 것은 의도적입니다. 현재 대부분의 모델이 영어 지시문에서 도구 호출 정확도와 응답 형식 일관성이 더 높습니다. 한국어 프롬프트도 동작은 하지만, 도구 호출이 잦은 반복 실행 익스큐터에는 영어를 권장합니다.

temperature: 0.0을 익스큐터에 적용하면 반복 작업의 결과 일관성이 높아집니다. 같은 파일을 두 번 탐색했을 때 다른 형식으로 결과를 돌려주는 상황을 막을 수 있고, 불필요한 재시도도 줄어듭니다.

예시 3: Git Worktree 기반 병렬 격리 실행

Git Worktree는 하나의 저장소에서 여러 브랜치를 동시에 서로 다른 디렉터리에 체크아웃하는 기능입니다. 에이전트마다 독립 작업 공간을 부여하면서 Git 오브젝트 저장소는 공유하기 때문에 디스크 낭비 없이 격리를 구현할 수 있습니다.

# 병렬 실행을 위한 워크트리 준비
git worktree add ../worktree-explorer-a feature/search-a
git worktree add ../worktree-explorer-b feature/search-b
git worktree add ../worktree-explorer-c feature/search-c
 
# 작업 완료 후 반드시 정리 (방치하면 디스크 낭비가 쌓입니다)
git worktree remove ../worktree-explorer-a
git worktree remove ../worktree-explorer-b
git worktree remove ../worktree-explorer-c

실행 흐름은 다음과 같습니다.

Sisyphus (Orchestrator, Opus)
├── Explorer × 3 (Haiku, worktree-A/B/C 병렬)  ← 파일 탐색
├── Librarian (Haiku)                            ← 문서 조회
└── Frontend Engineer (Flash)                    ← UI 코드 작성

Atlas가 각 워크트리의 결과를 통합합니다. 여기서 "통합"은 Git merge가 아니라, 각 익스큐터가 돌려준 결과(구조화된 탐색 결과, 코드 조각, 의존성 목록 등)를 에이전트 레벨에서 하나의 컨텍스트로 합치는 과정입니다. /start-work 명령 실행 시 Atlas는 Prometheus가 작성한 플랜을 읽고 TODO를 하나씩 처리하며, 각 TODO마다 적합한 카테고리의 익스큐터를 스폰합니다. 고가 모델은 오직 계획·오케스트레이션 단계에만 집중됩니다.

오픈소스 모델 조합 사례

OpenAI나 Anthropic API만 쓸 필요는 없습니다. 오픈소스 대안 모델을 활용하면 비용을 더 낮출 수 있습니다.

아래는 실제 사용자가 보고한 구성 사례입니다. 모델 이름과 API 제공 여부는 빠르게 변하므로, 도입 전에 각 모델의 현재 가용성과 도구 호출 지원을 직접 확인해보시는 것을 권장합니다.

이 구성으로 월 약 $11 수준으로 운영 가능하다는 사례가 보고됐습니다. 중소 규모 프로젝트 기준, 하루 수십 회 에이전트 실행을 가정한 수치입니다. 전부 Claude Opus로 돌릴 때와의 차이는 상당하지만, 본인의 사용 패턴과 프로젝트 규모를 기준으로 예상 비용을 직접 계산해보시면 더 정확한 판단을 할 수 있습니다.

장단점 분석

장점

단점 및 주의사항

BYOA (Bring Your Own Agent): OMO가 지원하는 커스텀 에이전트 정의 모드. .opencode/agents/ 디렉터리에 Markdown 파일을 추가하는 것만으로 에이전트를 등록할 수 있습니다. 기존 시스템 에이전트를 건드리지 않고도 팀 고유의 워크플로를 확장할 수 있는 방법입니다.

실무에서 가장 흔한 실수

1. 익스큐터 frontmatter를 과도하게 작성하는 것. 에이전트 설명, 예시, 주의사항을 길게 적으면 그 자체가 매번 컨텍스트에 포함되어 절약하려던 토큰이 오히려 낭비됩니다. YAML frontmatter는 10줄 미만, 시스템 프롬프트는 핵심 역할 정의만 담는 것이 좋습니다.

2. 로컬 모델을 도구 호출 신뢰성 검증 없이 오케스트레이터에 투입하는 것. 비용 줄이려고 로컬 7B 모델을 Sisyphus에 붙여봤을 때, JSON 형식의 도구 호출을 틀리거나 오케스트레이션 루프에서 빠져나오지 못하는 상황이 직접 생겼습니다. 새 모델을 도입할 때는 단독 에이전트로 먼저 간단한 도구 호출 테스트를 해보시면 나중에 낭패를 피할 수 있습니다.

3. Git Worktree 정리를 잊는 것. 실행할 때마다 워크트리를 추가하고 정리하지 않으면 디스크 낭비가 쌓입니다. git worktree list로 남아있는 워크트리를 확인하고, 작업이 끝나면 git worktree remove로 정리하는 습관을 들이시면 됩니다.

마치며

오케스트레이터-익스큐터 분리의 본질은 "비싼 판단력은 아끼고, 싼 실행력은 넉넉히 쓴다"는 원칙입니다. 설정 자체는 JSON 파일 몇 줄과 Markdown 에이전트 정의 파일로 충분하고, 처음부터 완벽한 구성을 목표로 할 필요는 없습니다.

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

1. oh-my-openagent GitHub(code-yeongyu/oh-my-openagent)의 dev 브랜치에서 예시 opencode.json을 복사해 프로젝트 루트에 추가하고, 모든 카테고리의 concurrency를 1로 설정해두시면 됩니다. 비용 걱정 없이 구조를 먼저 체험해보는 가장 안전한 방법입니다.

2. .opencode/agents/에 탐색 전용 익스큐터 Markdown 파일을 하나 만들어보시면 됩니다. mode: subagent, model: anthropic/claude-haiku-4-5, temperature: 0.0 세 줄이면 기본 설정은 완성됩니다.

3. 이틀쯤 사용해본 뒤 API 대시보드에서 카테고리별 토큰 소비 비율을 확인해보시면 됩니다. execution과 research 카테고리에서 절감 효과가 눈에 띄기 시작하면, 그때 concurrency를 조금씩 올리고 병렬 Worktree 구성을 추가해볼 수 있습니다.

이 구성을 CI/CD 파이프라인에 통합할 때 가장 먼저 부딪히는 벽은 병렬로 동작하는 에이전트들 사이의 브랜치 충돌입니다. 멀티 에이전트 환경에서 Git 전략을 어떻게 잡아야 하는지는 별도로 정리할 주제입니다.

참고 자료

• Agent Orchestration Overview (Sisyphus) — DeepWiki
• Atlas: Plan Executor — DeepWiki
• Oh My Opencode Specialised Agents Deep Dive and Model Guide — Rost Glukhov
• Oh My Opencode Review: Honest Results, Billing Risks — Rost Glukhov
• What Is Oh My OpenAgent (OMO)? Complete 2026 Guide — a2a-mcp.org
• Oh My Opencode Specialised Agents Deep Dive — DEV Community
• Deep Dive into OpenCode Agent Orchestration — DEV Community
• Agents 공식 문서 — OpenCode
• Multi-Agent AI Coding Workflow: Git Worktrees That Scale — The Agentic Blog