[opencode 12일 집중 — 터미널 네이티브 AI 코딩 에이전트 완전 정복] 3/12화: opencode BYOK 설정 — 75개 프로바이더, 최적 모델 고르기

이 글은 「opencode 12일 집중」 시리즈의 3일차로, opencode에서 원하는 AI 모델을 자유롭게 연결하는 BYOK 설정법을 다룹니다.

어제는 opencode를 설치하고 첫 세션을 열어 봤습니다. 터미널에 글자가 흐르는 순간, “이 모델 말고 다른 걸 쓸 순 없나?” 하는 생각이 들지 않았나요? 오늘 그 답을 꺼냅니다.

오늘의 핵심 3가지

• BYOK(Bring Your Own Key) — opencode는 특정 벤더에 묶이지 않는다. 내 API 키 하나면 75개 이상의 프로바이더를 자유롭게 넘나든다.
• API 키 vs OAuth 로그인 — 인증 경로가 두 갈래다. 상황에 따라 골라 쓰는 법을 익힌다.
• 비용 시뮬레이션 — “하루에 얼마 나오지?”를 모델별로 미리 계산해 본다.

BYOK가 뭐길래 — 벤더 락인 없는 모델 선택

AI 코딩 에이전트 시장에서 가장 흔한 불만은 “왜 이 모델만 써야 하죠?”입니다. 특정 도구가 특정 API에 하드코딩되어 있으면, 모델 가격이 오르거나 성능이 마음에 안 들 때 도구째 갈아타야 합니다. opencode는 이 고리를 끊습니다.

BYOK — Bring Your Own Key. 말 그대로, 자기가 가진 API 키를 가져오면 됩니다. Anthropic이든, OpenAI든, Google이든, AWS Bedrock이든, OpenRouter든 — 75개 이상의 프로바이더를 지원합니다. 키만 바꾸면 모델이 바뀝니다. 도구는 그대로입니다.

이게 왜 중요한지, 실제 상황을 하나 떠올려 보겠습니다.

• 월요일: Claude Sonnet으로 리팩터링 작업을 한다. 추론 품질이 좋다.
• 화요일: 단순 보일러플레이트가 많은 작업이라 GPT-4o mini로 전환한다. 비용이 1/20로 줄어든다.
• 수요일: 복잡한 아키텍처 설계가 필요해서 Claude Opus로 올린다.
• 목요일: 사내 망분리 환경 테스트라 Ollama 로컬 모델로 돌린다.

이 모든 전환이 opencode 안에서, 설정 한 줄 변경으로 이루어집니다. 도구를 바꿀 필요가 없습니다. 워크플로우도 동일합니다. 이것이 BYOK의 진짜 가치입니다.

인증 두 갈래 — API 키 vs OAuth 로그인

opencode에서 모델에 연결하는 방법은 크게 두 가지입니다. 각각의 특성을 정확히 알아야 상황에 맞게 고를 수 있습니다.

경로 1: API 키 직접 설정 (BYOK 본류)

가장 보편적인 방법입니다. 프로바이더 웹사이트에서 API 키를 발급받고, 환경변수에 넣으면 끝입니다.

# Anthropic
export ANTHROPIC_API_KEY="sk-ant-api03-..."

# OpenAI
export OPENAI_API_KEY="sk-proj-..."

# Google AI (Gemini)
export GOOGLE_API_KEY="AIza..."

# 설정 후 바로 opencode 실행
opencode

API 키 방식의 장점은 명확합니다.

• 완전한 제어: 사용량·비용·한도를 프로바이더 대시보드에서 직접 관리한다.
• 팀 공유 용이: 팀용 키를 발급해 CI/CD나 공용 환경에 주입할 수 있다.
• 다중 프로바이더 동시 등록: 환경변수를 여러 개 설정해 두면, 설정 파일에서 프로바이더만 전환하면 된다.
• 엔터프라이즈 호환: AWS Bedrock, Azure OpenAI 같은 기업용 엔드포인트도 이 경로로 연결된다.

경로 2: OAuth 로그인 (구독 기반)

2화에서 잠깐 다뤘던 opencode auth login이 이 경로입니다. 프로바이더가 OAuth 인증을 지원하면, API 키 없이 브라우저 로그인만으로 연결됩니다.

# OAuth 로그인 (브라우저가 열림)
opencode auth login

OAuth 방식은 개인 사용자에게 편리합니다. API 키를 따로 발급·관리할 필요 없이, 기존 구독 계정을 그대로 씁니다. 다만 몇 가지 제약이 있습니다.

• 지원 프로바이더가 API 키 방식보다 제한적이다.
• 토큰 갱신 주기에 따라 재인증이 필요할 수 있다.
• CI/CD 같은 비대화형 환경에서는 사용이 어렵다.

한눈에 비교

항목	API 키 (BYOK)	OAuth 로그인
설정 난이도	환경변수 1줄	브라우저 로그인 1회
지원 프로바이더	75개 이상	OAuth 지원 프로바이더만
비용 관리	프로바이더 대시보드에서 직접	구독 플랜에 포함
CI/CD 사용	가능 (시크릿으로 주입)	어려움
팀 공유	팀 키 발급 가능	개인 계정 단위
토큰 만료	키 폐기 전까지 유효	주기적 갱신 필요
추천 시나리오	실무·팀·자동화	개인 빠른 시작

실무 권장: 처음 시작할 때는 OAuth로 빠르게 연결하고, 본격 사용 단계에서는 API 키 방식으로 전환하는 것이 깔끔합니다. 두 방식이 충돌하지 않으므로 병행도 가능합니다.

프로바이더별 설정 실습 — 복사해서 바로 쓰기

opencode의 설정 파일은 프로젝트 루트의 opencode.json입니다. 여기에 프로바이더와 모델을 지정합니다. 주요 프로바이더 5개의 설정을 바로 쓸 수 있는 형태로 정리했습니다.

Anthropic (Claude)

# 1. API 키 설정
export ANTHROPIC_API_KEY="sk-ant-api03-..."

# 2. opencode.json 에서 프로바이더 지정
# provider → anthropic, model → 원하는 Claude 모델
opencode

Anthropic은 opencode에서 가장 많이 쓰이는 프로바이더입니다. Claude Sonnet 계열이 코딩 작업의 가성비 기준으로 인기가 높고, 복잡한 설계에는 Opus 계열을 올려 쓰는 패턴이 일반적입니다.

OpenAI (GPT)

# 1. API 키 설정
export OPENAI_API_KEY="sk-proj-..."

# 2. opencode 실행 — 설정에서 openai 프로바이더 선택
opencode

GPT-4o 시리즈는 범용성이 좋고, GPT-4o mini는 비용 대비 속도가 빨라 단순 작업에 적합합니다. o1/o3 같은 추론 특화 모델도 선택 가능합니다.

Google (Gemini)

# 1. API 키 설정
export GOOGLE_API_KEY="AIza..."

# 2. opencode 실행 — 설정에서 google 프로바이더 선택
opencode

Gemini 2.5 시리즈는 긴 컨텍스트 윈도우(최대 100만 토큰)가 강점입니다. 대규모 코드베이스를 통째로 넣어야 하는 상황에서 빛을 발합니다. 무료 티어도 있어 실험 용도로 부담이 없습니다.

AWS Bedrock

# 1. AWS 자격 증명 설정 (기존 AWS CLI 프로파일 사용 가능)
export AWS_ACCESS_KEY_ID="AKIA..."
export AWS_SECRET_ACCESS_KEY="..."
export AWS_REGION="us-east-1"

# 2. opencode 실행 — 설정에서 bedrock 프로바이더 선택
opencode

금융·공공 부문에서 AWS를 이미 사용 중이라면 Bedrock이 자연스러운 선택입니다. 기존 IAM 권한 체계를 그대로 쓸 수 있고, 데이터가 AWS 인프라 안에서 처리되므로 컴플라이언스 요건을 충족하기 쉽습니다.

OpenRouter (멀티 프로바이더 게이트웨이)

# 1. API 키 설정
export OPENROUTER_API_KEY="sk-or-..."

# 2. opencode 실행 — 설정에서 openrouter 프로바이더 선택
opencode

OpenRouter는 하나의 API 키로 여러 프로바이더의 모델을 쓸 수 있는 게이트웨이 서비스입니다. “API 키 하나만 관리하고 싶다”면 가장 편한 선택입니다. 다만 중간 계층이 하나 더 끼므로 레이턴시가 미세하게 늘어날 수 있고, 가격에 마진이 붙습니다.

OpenCode Zen — 큐레이션 모델이란

“프로바이더가 75개나 된다니, 대체 뭘 골라야 하죠?”

이 질문에 대한 opencode 팀의 답이 Zen입니다. Zen은 opencode가 자체적으로 큐레이션한 모델 추천 시스템입니다. 사용자가 직접 프로바이더와 모델을 고를 필요 없이, opencode가 작업 특성에 맞는 모델을 선별해 제공합니다.

Zen의 핵심 아이디어는 간단합니다.

• 진입 장벽 제거: API 키 발급·프로바이더 비교·모델 선택의 부담 없이, opencode 계정 하나로 바로 시작한다.
• 큐레이션: opencode 팀이 코딩 작업에 최적화된 모델을 선별·테스트해서 제공한다. 사용자는 “최고 성능”과 “가성비” 같은 프리셋 중에 고르면 된다.
• 단일 과금: 여러 프로바이더에 개별 결제하는 대신, opencode 구독 하나로 통합 관리한다.

Zen은 특히 “일단 빠르게 써 보고 싶다”는 개인 사용자나, API 키 관리가 번거로운 소규모 팀에게 매력적입니다. 반면 다음과 같은 경우에는 BYOK가 더 적합합니다.

• 특정 모델을 지정해야 하는 경우 (예: 사내 정책상 Bedrock만 사용)
• 비용을 세밀하게 통제해야 하는 경우
• 에어갭 환경이나 자체 호스팅 모델을 써야 하는 경우
• 이미 프로바이더와 볼륨 할인 계약이 있는 경우

정리하면: Zen은 “고르기 귀찮을 때”의 좋은 출발점이고, BYOK는 “내가 직접 고르겠다”는 사용자를 위한 자유도입니다. 둘 다 opencode 안에서 공존하며, 언제든 전환할 수 있습니다.

모델별 비용 시뮬레이션 — 하루에 얼마나 나올까

BYOK의 자유에는 책임이 따릅니다 — 비용 관리입니다. “AI 코딩 에이전트를 하루 종일 쓰면 얼마가 나오지?”라는 질문에 답하기 위해, 주요 모델의 비용을 시뮬레이션해 봤습니다.

가정

• 하루 사용량: 코딩 에이전트 세션 약 20회, 회당 평균 입력 2,000토큰 + 출력 1,500토큰
• 하루 총 사용량: 입력 약 40K 토큰, 출력 약 30K 토큰
• 가격은 2026년 상반기 기준 공개 가격표 참고 (실제 가격은 프로바이더에서 확인하세요)

프로바이더	모델	입력 ($/1M토큰)	출력 ($/1M토큰)	하루 예상 비용	월 예상 (22일)
Anthropic	Claude Haiku	$0.25	$1.25	$0.05	$1.0
Anthropic	Claude Sonnet	$3	$15	$0.57	$12.5
Anthropic	Claude Opus	$15	$75	$2.85	$62.7
OpenAI	GPT-4o mini	$0.15	$0.60	$0.02	$0.5
OpenAI	GPT-4o	$2.50	$10	$0.40	$8.8
Google	Gemini 2.5 Flash	$0.15	$0.60	$0.02	$0.5
Google	Gemini 2.5 Pro	$1.25	$10	$0.35	$7.7
로컬	Ollama (자체 GPU)	$0	$0	$0	전기세만

표를 보면 패턴이 보입니다.

• 가성비 구간: Haiku, GPT-4o mini, Gemini Flash — 월 $1 이하. 단순 코드 생성·테스트 작성·보일러플레이트에 충분합니다.
• 밸런스 구간: Sonnet, GPT-4o, Gemini Pro — 월 $8~13. 대부분의 실무 코딩을 커버합니다.
• 프리미엄 구간: Opus — 월 $60 이상. 복잡한 아키텍처 설계, 대규모 리팩터링 등 고난도 작업에 한정 사용이 현명합니다.
• 제로 코스트: Ollama 로컬 — API 비용 $0. 다만 GPU 하드웨어와 전기세는 별도. 12회차에서 자세히 다룹니다.

실전 절약 팁: 모델 스위칭 전략

opencode의 BYOK가 빛나는 순간은 바로 이 모델 스위칭입니다. 하나의 모델에 올인하지 말고, 작업 성격에 따라 전환하세요.

# 아침: 복잡한 설계 → 고성능 모델로 시작
# opencode.json 에서 프로바이더/모델을 Sonnet 또는 Opus로 설정

# 오후: 단순 작업 → 가성비 모델로 전환
# opencode.json 에서 모델을 Haiku 또는 GPT-4o mini로 변경

# opencode TUI 안에서도 모델 전환 가능
# 설정 변경 후 새 세션 시작

이 전략을 쓰면, 체감 품질은 Sonnet급을 유지하면서 월 비용을 $5~8 수준으로 관리할 수 있습니다.

실무 추천 조합 — 시나리오별 가이드

상황별로 어떤 프로바이더·모델 조합이 좋을지 정리했습니다.

시나리오 1: 개인 사이드 프로젝트

• 추천: Anthropic Claude Sonnet (메인) + Haiku (서브)
• 이유: 코딩 품질 우수, 비용 합리적. 단순 작업은 Haiku로 내려 비용 절감.
• 월 예상: $5~10

시나리오 2: 스타트업 팀 (3~5인)

• 추천: OpenRouter (단일 키 관리) 또는 Zen (관리 최소화)
• 이유: 팀원마다 프로바이더 키를 관리하기 번거로움. 하나의 키 또는 구독으로 통합.
• 월 예상: 인당 $10~15

시나리오 3: 금융·대기업 (규제 환경)

• 추천: AWS Bedrock 또는 Azure OpenAI
• 이유: 기존 클라우드 계약·IAM·감사 로그 체계 활용. 데이터가 지정된 리전을 벗어나지 않음.
• 월 예상: 볼륨 할인 적용 시 공개 가격표 대비 20~40% 절감 가능

시나리오 4: 에어갭 / 망분리 환경

• 추천: Ollama + 로컬 모델 (12회차에서 상세)
• 이유: 네트워크 외부 호출 제로. 코드가 조직 밖으로 나가지 않음.
• 월 예상: $0 (하드웨어 비용 별도)

환경변수 관리 — 셸 프로파일에 정리하기

프로바이더를 여러 개 등록해 두면, 필요할 때 설정 파일의 프로바이더 이름만 바꿔 전환할 수 있습니다. 환경변수는 셸 프로파일에 한 번 넣어 두면 매번 입력할 필요가 없습니다.

# ~/.bashrc 또는 ~/.zshrc 에 추가
# (Windows WSL 사용 시 동일)

# --- opencode 프로바이더 키 ---
export ANTHROPIC_API_KEY="sk-ant-api03-..."
export OPENAI_API_KEY="sk-proj-..."
export GOOGLE_API_KEY="AIza..."

# 선택: OpenRouter (멀티 프로바이더)
export OPENROUTER_API_KEY="sk-or-..."

# 선택: AWS Bedrock
export AWS_ACCESS_KEY_ID="AKIA..."
export AWS_SECRET_ACCESS_KEY="..."
export AWS_REGION="us-east-1"

# 적용
source ~/.bashrc

보안 주의: API 키가 포함된 프로파일 파일은 chmod 600으로 권한을 제한하세요. 절대 Git에 커밋하지 마세요. .env 파일을 쓴다면 .gitignore에 반드시 추가합니다.

# .gitignore 에 추가
.env
.env.local

opencode 빠른 검증 — 연결이 됐는지 확인하기

환경변수를 설정했으면, opencode를 열어 빠르게 검증합니다.

# opencode 실행
opencode

# TUI가 열리면 간단한 프롬프트로 테스트
# "hello" 한 마디만 쳐도 모델 응답이 오면 연결 성공

# 또는 비대화형으로 한 줄 테스트
opencode run "say hello"

응답이 정상적으로 오면 프로바이더 연결이 완료된 것입니다. 응답이 오지 않으면 가장 먼저 확인할 것은 API 키의 유효성과 환경변수가 현재 셸에 로드됐는지입니다.

Gotcha 미니 코너 — 흔히 빠지는 함정

함정: 환경변수를 설정했는데 opencode가 키를 못 찾는다

가장 많이 보이는 실수입니다. export ANTHROPIC_API_KEY="..."를 터미널에 입력했는데, 새 터미널 탭을 열면 키가 사라집니다. export는 현재 셸 세션에서만 유효하기 때문입니다.

해결: 반드시 ~/.bashrc, ~/.zshrc, 또는 ~/.profile에 추가하세요. 추가한 뒤 source ~/.bashrc로 즉시 적용하거나, 새 터미널을 여세요.

# 확인: 현재 셸에 키가 로드됐는가?
echo $ANTHROPIC_API_KEY
# 값이 출력되면 OK, 빈 줄이면 로드 안 된 것

# 영구 등록 확인
grep "ANTHROPIC_API_KEY" ~/.bashrc
# 해당 줄이 보이면 OK

Windows (PowerShell) 사용자는 $env:ANTHROPIC_API_KEY로 확인하고, 영구 등록은 [System.Environment]::SetEnvironmentVariable 또는 시스템 환경변수 GUI를 사용합니다.

# PowerShell — 현재 세션 확인
$env:ANTHROPIC_API_KEY

# PowerShell — 사용자 환경변수로 영구 등록
[System.Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "sk-ant-api03-...", "User")

오늘의 정리

opencode의 BYOK는 단순한 기능이 아니라 철학입니다. 도구에 종속되지 않고, 모델을 자유롭게 고르고, 비용을 직접 통제합니다. 오늘 다룬 내용을 한 줄씩 되짚으면:

• BYOK = 내 키를 가져와서 75개 이상 프로바이더 중 자유롭게 선택
• API 키 방식은 실무·팀·자동화에, OAuth는 개인 빠른 시작에 적합
• 모델 스위칭 전략으로 품질은 유지하되 비용은 절반 이하로 줄일 수 있다
• Zen은 고르기 귀찮을 때의 좋은 출발점, BYOK는 직접 제어의 자유도

환경변수 설정, 해 보셨나요? 프로바이더 연결이 확인됐다면, 이제 opencode의 진짜 무대 — TUI — 를 본격적으로 탐험할 차례입니다.

내일 4일차 예고: TUI 단축키 치트시트 — ctrl+x leader 키 하나로 opencode를 손에 익히는 시간입니다.

---