Oh My OpenCode 사용법 – Subagent API Key 셋팅하는 법 (무료·유료 완전 가이드)

Subagent API Key 세팅 포스트 대표 이미지

Oh My OpenCode는 여러 SubAgent가 역할을 나눠 협업하는 구조라서,
어떤 모델을 어디에 연결하느냐가 성능을 크게 좌우합니다.
前の投稿에서는 SubAgent API Key를 세팅 설명이 없어서
이걸 실제 어떻게 사용해야 하지 하는 궁금점이 있었을 겁니다.

그래서 이 글에서는 다음의 내용을 한번에 정리해드릴려고 해요.

  1. 가장 안정적인 “추천 세팅”(유료 위주)
  2. 비용 최소화 “무료 위주 세팅” + 작업 쪼개기 전략
  3. GPT-5 mini GitHub Copilot 무료 활용법
  4. SubAgent API Key 발급 & 주의사항

OpenCode는 터미널/데스크톱/IDE에서 돌아가는 오픈소스 AI 코딩 에이전트로
여러 LLM 제공자(Claude, GPT, Gemini, Copilot 등)를 자유롭게 붙일 수 있습니다.

추가로, Oh My OpenCode는여기에 서브에이전트(Oracle·Librarian·Explore 등)를 묶어서
“설계 → 코드 작성 → 문서화 → 리팩토링”을 한 팀처럼 자동화해 주는 플러그인으로 보시면 되어요.

OpenCode는 “무료 모델 포함 + 원하는 모델 아무나 연결” 컨셉이라,
처음 설치해도 Zen·로컬·저가 모델 등을 바로 쓸 수 있고,
원하면 OpenAI, Anthropic, Google, GitHub Copilot을 추가로 연결해서 쓸 수 있습니다.

1. 가장 안정한 추천 세팅 – “실제 개발용 기본 구성”

1-1. 어떤 조합이 좋은가?

테스트해보면 아래 역할 분담이 가장 덜 스트레스 받으면서 잘 돌아간다고 합니다.

역할추천 모델(예시)이유
설계/리뷰(oracle)opencode/claude-sonnet-4-5설계·리뷰·설명력 좋고 긴 맥락 안정적
코드 작성(code-writer)opencode/gpt-5-codex에이전트 코딩에 최적화된 최신 GPT-5 계열
문서/검색(librarian)opencode/gemini-3-pro문서 요약·검색·레퍼런스 정리에 강함
코드 탐색(explore)opencode/grok-code빠른 코드 스캔·파일 편집용으로 최적화

⚠️ 위 모델들은 OpenCode가 제공하는 Zen 유료 모델 예시입니다.
(실제 사용 시 /connect → OpenCode Zen 후 /models에서 선택) (OpenCode)

1-2. 설치 & 기본 연결

이전에도 다뤘지만 다시 한번 더 살펴보면 터미널에서 아래의 명령을 실행하면
opencode와 oh-my-opencode가 설치됩니다.

curl -fsSL https://opencode.ai/install | bash
# 또는
bunx oh-my-opencode install

설치 후 TUI(또는 CLI)에서 순서대로

/connect          # 또는 opencode auth login
# → Anthropic 선택 후 로그인 (Claude)
/connect
# → OpenCode Zen 또는 OpenAI 선택
/connect
# → Google (Gemini) 선택
/connect
# → Groq 등 필요시 추가

프로바이더 키는 ~/.local/share/opencode/auth.json에 저장됩니다.

1-3. Oh My OpenCode 서브에이전트 설정 예시

프로젝트 루트에서 json 파일을 만들고 예시를 보고 원하는 모델로 설정합니다.

mkdir -p .opencode
nano .opencode/oh-my-opencode.json # 혹은 에디터 이용

예시 설정:

{
  "agents": {
    "oracle":    { "model": "opencode/claude-sonnet-4-5" },
    "code-writer": { "model": "opencode/gpt-5.2" },
    "librarian": { "model": "opencode/gemini-3-pro" },
    "explore":   { "model": "opencode/grok-code" }
  },
  "ralph_loop": {
    "enabled": true,
    "default_max_iterations": 120
  }
}

이 구성은 긴 ultrawork 작업(리팩토링·대규모 코드 생성 등)에서도
설계 → 구현 → 문서화를 서브에이전트들이
릴레이처럼 이어받으며 끝까지 수행하는 데 유리합니다.

2. GitHub Copilot + GPT-5 mini 활용 – “추가 과금 없이 최대 활용”

OpenCode는 GitHub Copilot을 하나의 LLM 제공자로 지원합니다.

최근 GitHub가 GPT-5 mini를 Copilot에 기본 포함 모델(=무료 플랜 포함)로 제공하면서,
OpenCode에서도 이 모델을 추가 API 요금 없이 쓸 수 있게 된 것이 핵심 포인트입니다.

2-1. Copilot 연결 순서

  1. 터미널에서:opencode auth login
  2. 프로바이더 목록에서 GitHub Copilot 선택
  3. 화면에 뜨는 github.com/login/device 코드를 브라우저에서 입력 후 승인
  4. 다시 터미널에서:/models
    • copilot/gpt-5-mini 또는 비슷한 이름의 모델을 선택

2-2. Oh My OpenCode에 gpt-5-mini 연결 예시

{
  "agents": {
    "code-writer": { "model": "copilot/gpt-5-mini" }
  },
  "small_model": "copilot/gpt-5-mini"
}

🔎 참고: 일부 이슈에서 small_model이 유료 gemini-3-flash로 잡히는 버그가 보고된 적이 있어,
가능하면 명시적으로 gpt-5-mini를 small_model로 지정하는 것이 안전합니다.

이렇게 설정하면

  • 일반 코딩: copilot/gpt-5-mini로 빠르고 가벼운 작업 처리

하는 “혼합 운용”이 가능합니다.

3. 무료 위주 세팅 – Gemini + 내부 모델로 “맛보기”

일단 뭘 알아야 유로로 사용하던지 하죠, 그쵸.
그래서 일단 돈 안 쓰고 써보는걸로 해보겠습니다.
대신 작업은 작게 쪼개고, 중요한 코드는 올리지 않는다로 가보겠습니다.

3-1. SubAgent API Key 발급(Gemini 무료 )

Gemini 무료 API 키 발급 이미지
  1. 브라우저에서 Google AI Studio 접속
  2. Googleアカウントでログイン
  3. 좌하단 Get API key 메뉴에서 새 키 발급(위치는 변경될 수 있습니다.)
  4. 발급받은 키를 환경변수 또는 /connect에 입력, 또는 opencode auth login # → Google / Gemini 선택 후 API 키 입력
  • 무료 티어 기준 gemini-1.5-flash는 꽤 넉넉한 요청 한도(RPM/TPM)를 제공합니다. (Google AI for Developers)

⚠️ 중요한 보안 포인트
무료 티어(특히 AI Studio)는 입력 데이터가 모델 개선에 활용될 수 있음이 명시돼 있습니다.
민감한 사내 코드·계약서 등은 유료 “Pay-as-you-go” 플랜 + 데이터 사용 안 함 설정을 권장합니다.

3-2. 무료 세팅용 oh-my-opencode.json 예시

{
  "agents": {
    "oracle":       { "model": "copilot/gpt-4o" },
    "code-writer":  { "model": "copilot/gpt-4o" },
    "librarian":    { "model": "google/gemini-1.5-flash" },
    "explore":      { "model": "opencode/grok-code" }
  },
  "small_model": "copilot/gpt-4o",
  "ralph_loop": {
    "enabled": true,
    "default_max_iterations": 40
  }
}
  • 모든 핵심 에이전트を gemini-1.5-flash에 붙여서
    설계·요약 등까지 한 번에 처리
  • ralph_loop 반복 횟수를 60 정도로 제한해 무한 루프·과도한 호출 방지

4. “대신 작업을 작게 쪼개서 실행!” — 진짜 중요한 실전 팁

대신 작업을 작게 쪼개서 실행 이미지

무료 플랜이든, Copilot gpt-5 mini든
성공·실패를 가르는 포인트는 “작업 쪼개기”입니다.

4-1. 왜 쪼개야 할까?

  • 무료/저가 모델은
    • 긴 맥락에서 사고력·정확도가 떨어지기 쉽고
    • 요청 제한(RPM/RPD)에 빨리 걸립니다.
  • 큰 작업 하나를 한 번에 던지면
    • 중간에 멈춤 or 맥락 손실
    • 어디까지 했는지 추적이 어려움

4-2. 쪼개는 기준 – “기능 단위 + 파일 단위”

예를 들어 Django + React 블로그를 만든다고 하면

  1. Step 0 – Plan부터 뽑기
    • 이 프로젝트의 전체 개발 계획을 5~7단계로 나눠서 써줘. 각 단계는 최대 20줄 설명, 산출물(파일명)까지 포함해.
  2. Step 1 – 백엔드 API만
    • Step 1만 수행해줘. Django로 Post 모델/Serializer/ViewSet/URL까지 작성해. 기존 코드에 patch 형식으로 수정해줘.
  3. Step 2 – React 목록 페이지
    • 이제 Step 2만 실행해줘. React로 /posts 목록 페이지를 만들고, Django API와 연동하는 코드만 작성해줘.
  4. Step 3 – 인증 & 권한
    • Step 3만 실행해줘. JWT 기반 인증을 붙이고, 인증된 사용자만 글을 작성할 수 있게 수정해줘.

こうすれば

  • 각 프롬프트가 짧아져 무료 모델의 한도 내에서 안전
  • 실패해도 해당 Step만 다시 실행하면 되므로 회복 쉬움

4-3. 멈췄을 때 이어 달리기 패턴

작업 도중 멈추면, 항상 같은 패턴으로 이어가면 됩니다.

continue from last step
혹은 지금까지 생성한 파일/코드 목록을 먼저 요약해주고, 그 다음에 Step 3부터 다시 이어서 진행해줘.)
  • 이전 컨텍스트를 스스로 요약하게 하면,
    무료 모델에서도 맥락 복구 성공률이 확 올라갑니다.

4-4. Ralph Loop와 함께 쓰는 법

ralph_loop는 “에이전트가 알아서 몇 번이고 재시도·검증”하게 만드는 루프입니다.

  • 유료/안정 세팅: default_max_iterations는 120~200
  • 무료/실험 세팅: 30~60 정도로 제한
"ralph_loop": {
  "enabled": true,
  "default_max_iterations": 40
}
  • 이렇게 해두면, 무료 모델이 중간에 실패하더라도
    스스로 몇 번 더 시도해주고,
    그래도 안 되면 거기서 멈추기 때문에
    “조용히 크레딧만 태우는” 상황을 줄일 수 있습니다.

5. 최종 정리 – 어떤 세팅을 언제 쓸까?

subagent api key 세팅 관련 이미지
項目추천(유료) 세팅무료 위주 세팅
메인 모델GPT-5.2 / Claude / Gemini Pro 등 ZenGemini 1.5 Flash, Copilot GPT4-o
安定性🟢 매우 높음🟡 중간 (작업 쪼개기 필수)
작업 규모대형 프로젝트, 긴 ultrawork토이 프로젝트, POC, 연습용
준비사항API 키 여러 개 + 약간의 비용구글 계정 + GitHub 계정 정도
보안/데이터유료 플랜 + 학습 제외 옵션 설정 가능무료는 입력 데이터가 학습에 쓰일 수 있음
권장 용도실제 회사/클라이언트 프로젝트개인 공부, 블로그 예제, 무료 체험

한 줄 요약:

  • 실제 업무: Zen + Copilot + 안정적인 유료 모델 조합
  • 연습/테스트: Gemini Flash + GPT4-o + 작업 쪼개기

실전에서는 “어떤 모델을 쓰느냐”보다 “어떻게 일을 나누느냐”가 더 중요합니다.
Oh My OpenCode의 서브에이전트 구조는 이미 “팀으로 일하는 AI”를 제공하니까,
우리는 그 팀에게 좋은 도구(API 키)를 쥐여주고,
작업 단위를 잘게 쪼개서 던져주기만 하면 됩니다.

  • 돈을 쓸 수 있다면 → Zen + Claude + GPT-5.2 조합으로 “에이전트 코딩 풀옵션”
  • 돈을 아끼고 싶다면 → Gemini Flash + Copilot GPT4-o로 “무료 팀” 구성

이 글의 설정 예시와 프롬프트 패턴만 따라 해도,
처음 AI 코딩을 쓰는 초보 개발자도 “혼자 하는 프로젝트를 팀 작업처럼” 진행할 수 있을 거예요.

===포스트를 업로드 후에 문서를 조금 더 보완했습니다.===

opencode 실행창 이미지
(오픈코드 실행창)
깃허브 코파일럿 무료제공 모델 선택 화면
(깃허브 코파일럿 무료제공 모델 선택 화면)
오픈코드에서 오더를 내리는 화면
(오픈코드에서 오더를 내리는 화면)
1️⃣ 프로젝트 폴더에서 OpenCode 실행

아래와 같이 원하는 터미널에서 프로젝트 폴더를 하나 만들고 오픈코드를 실행합니다.

mkdir cd-blog
cd cd-blog
opencode

👉 그러면 터미널 안에 위 그림처럼 “AI 콘솔(TUI)”가 열립니다.

여기서부터는 “명령 + 대화”로 프로젝트를 진행합니다.

2️⃣ 먼저 — “계획만 세우게” 시킵니다 (절대 코드부터 X)

AI에게 이렇게 말하세요
-----
plan:
React + Django 블로그를 만들 건데,
전체 개발을 6단계로 나눠서 계획만 세워줘.

각 단계마다:
- 할 일
- 만들어질 파일 목록
- 예상 난이도

코드는 지금 쓰지 말고, 계획만 작성해줘.
----
👉 결과: Step 1 ~ Step 6 같은 계획이 나옵니다.
(이게 “작게 쪼개기의 기준”이 됩니다.)

💡 중요한 포인트
AI가 스스로 계획을 세우도록 해야 합니다.
그래야 나중에
continue from last step 명령이 제대로 동작합니다.

3️⃣ 이제 — “Step 1만” 실행시키기

보통 Step 1은 이런 내용일 겁니다.

Django 프로젝트 생성 + Post 모델

그러면 이렇게 말하세요:

Step 1만 실행해줘.

이후 순차적으로 진행하면 됩니다.


혹시라도 작업이 멈췄다? 이렇게 말하면 됩니다
continue from last step
또는:
방금 하던 Step 3의 나머지 부분부터 계속해줘.
이미 만든 코드는 다시 만들지 마.


👉 AI가 스스로 요약 → 이어서 작업합니다.

위 작업을 무료로 진행하려다 보니 애로점이 많네요.
Oh My OpenCode의 제이슨 파일 설정이 제대로 돌아가는지도 확신이 안서네요.ㅜㅜ
조금 더 연구를 해보고 명확하게 알려드리겠습니다.

한가지 확실한 것은 gemini cli 외에 
무료로 cli 모드를 opencode로 이용할 수 있다는 사실입니다!!!(죄송해요. 다 알고 계셨다면...)

類似の投稿