OpenCode 실전 가이드 — Claude Code 대신 쓸 수 있나

Claude Code 요금제 보다가 "이거 너무 비싼데" 싶었던 분들, OpenCode라는 이름 한 번쯤 들어봤을 겁니다. GitHub 스타 165,000개, 월 활성 개발자 750만 명. 근데 실제로 Claude Code 대신 쓸 수 있는지가 핵심이죠. 결론부터 말하면 — 상황에 따라 다릅니다.

---

핵심 요약

→ OpenCode는 MIT 라이선스 오픈소스 터미널 코딩 에이전트 — 설치 무료, 모델은 직접 선택
→ 75개 이상 AI 제공자 지원 — Claude API·GPT-5.5·Gemini·DeepSeek·Ollama 로컬 모델까지
→ 2026년 1월 Anthropic이 구독 OAuth 차단 — Claude Pro/Max 구독으로는 더 이상 사용 불가
→ Claude API 키 직접 발급하면 OpenCode에서 Claude 모델 여전히 사용 가능
→ 같은 작업 기준 Claude Code보다 약 78% 느림 — 클라이언트-서버 아키텍처 오버헤드
→ LSP(Language Server Protocol) 통합으로 컴파일러 오류를 모델에 실시간 피드백 — Claude Code에 없는 기능
→ 데스크탑 앱 지원 (Mac·Windows·Linux) — Claude Code는 현재 CLI 우선
→ 멀티 세션 — 같은 프로젝트에서 여러 에이전트 병렬 실행 가능
→ AGENTS.md로 프로젝트 메모리 관리 — Claude Code의 CLAUDE.md와 동일한 개념
→ 완전 오프라인 가능 — Ollama 연결 시 인터넷 없이 로컬에서만 실행
→ 비용 절감이 핵심 장점 — Qwen 3.7이나 DeepSeek V4 Pro로 Claude Code 대비 90% 이상 저렴

---

OpenCode가 뭔가

2025년 말 SST(현재 Anomaly로 리브랜딩)가 만든 오픈소스 터미널 코딩 에이전트입니다. 한 줄로 정의하면 "모델을 직접 고를 수 있는 Claude Code"입니다.

Claude Code는 Anthropic 모델만 씁니다. OpenCode는 모델을 직접 가져옵니다. Claude API 키를 꽂으면 Claude가 쓰이고, Gemini API 키를 꽂으면 Gemini가 쓰이고, Ollama를 연결하면 인터넷 없이 로컬 모델로 돌아갑니다.

아키텍처는 클라이언트-서버 구조입니다. Go로 짠 TUI(터미널 UI)가 프론트엔드고, Bun 기반 JavaScript HTTP 서버가 백엔드입니다. 여러 프론트엔드가 같은 서버에 붙을 수 있어서, 터미널·데스크탑 앱·IDE 확장을 동시에 쓸 수 있습니다.

---

실전 1 — 설치

세 가지 방법 중 하나 골라서 설치하면 됩니다.

# 방법 1: curl (가장 빠름, Linux/Mac)
curl -fsSL https://opencode.ai/install | bash

# 방법 2: Homebrew (Mac)
brew install opencode

# 방법 3: npm
npm install -g opencode-ai

설치 후 프로젝트 디렉토리에서 opencode를 실행하면 처음 실행 시 프로바이더 설정 화면이 뜹니다.

cd your-project
opencode
# → 프로바이더 선택 화면 진입
# → API 키 입력
# → 완료

개념 박스 — AGENTS.md OpenCode는 프로젝트 루트에 AGENTS.md 파일을 두고 프로젝트 컨텍스트를 저장합니다. Claude Code의 CLAUDE.md와 동일한 역할입니다. 코드베이스 구조, 컨벤션, 반복 지시사항을 여기에 써두면 매 세션마다 자동으로 읽어옵니다.

---

실전 2 — 프로바이더 설정

Claude API 키로 Claude를 쓰거나, 더 저렴한 모델로 갈아탈 수 있습니다.

# opencode.json 또는 ~/.config/opencode/config.json
{
  "model": "anthropic/claude-sonnet-4-6",  # Claude API 키 필요
  "providers": {
    "anthropic": {
      "apiKey": "sk-ant-..."
    }
  }
}

# Gemini로 전환할 때
{
  "model": "google/gemini-3.5-flash",
  "providers": {
    "google": {
      "apiKey": "AIza..."
    }
  }
}

# Ollama 로컬 모델 (비용 0원, 인터넷 불필요)
{
  "model": "ollama/qwen3:14b",
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434"
    }
  }
}

세션 중에도 모델을 바꿀 수 있습니다. /model 커맨드를 입력하면 현재 지원되는 모델 목록이 뜨고, 바로 전환됩니다. Claude Code는 이게 안 됩니다.

---

실전 3 — 주요 커맨드

Claude Code를 써본 분이라면 80%는 그대로입니다.

# 기본 사용
opencode "auth 모듈 리팩토링해줘"

# 계획 모드 (실행 전 확인)
opencode --plan "DB 스키마 변경사항 적용해줘"

# 특정 파일만 컨텍스트로
opencode --include src/auth/** "여기서 버그 찾아줘"

# 멀티 세션 (병렬 실행)
opencode --session test-session-1 "테스트 코드 작성" &
opencode --session test-session-2 "문서 업데이트" &

# undo / redo (git 스냅샷 기반)
/undo   # 마지막 변경사항 되돌리기
/redo   # 되돌린 것 다시 적용

# 모델 전환
/model  # 모델 선택 화면

# 세션 공유 링크 생성
/share  # 디버깅용 세션 링크 생성

개념 박스 — LSP 통합 OpenCode의 가장 차별화된 기능입니다. Language Server Protocol 서버를 실행해서 컴파일러 오류, 타입 오류, lint 경고를 실시간으로 모델에 피드백합니다. 모델이 코드를 수정한 직후 컴파일러가 "이 타입 틀렸다"고 알려주면 OpenCode가 자동으로 다시 수정 시도합니다. Claude Code에는 없는 기능입니다.

---

실전 4 — Anthropic 차단 사태, 지금 상황 정리

이게 OpenCode 쓸 때 제일 먼저 알아야 할 내용입니다.

2026년 1월 9일 새벽 2시 20분(UTC), Anthropic이 서버 사이드에서 OAuth 인증을 차단했습니다. 그전까지는 Claude Pro/Max 구독($100~$200/월)을 OpenCode에 연결해서 쓸 수 있었는데, 하룻밤 사이에 막혀버린 겁니다. 에러 메시지는 명확했습니다.

"This credential is only authorized for use with Claude Code 
and cannot be used for other API requests."

이후 흐름은 이렇습니다.

날짜 사건

2026.01.09	Anthropic OAuth 차단 (사전 공지 없음)
2026.01.12	OpenCode GitHub 스타 하루 +2,087 — 오히려 관심 폭발
2026.02.19	Anthropic ToS 공식 개정 — 구독 OAuth의 서드파티 사용 명시 금지
2026.02.19	OpenCode Claude OAuth 코드 전량 삭제
2026.04.04	최종 차단 — Claude Pro/Max로 OpenCode 완전 사용 불가

지금 OpenCode에서 Claude를 쓰려면 Claude API 키를 별도로 발급받아 직접 꽂아야 합니다. API는 여전히 허용됩니다. 다만 API는 사용량 기반 과금이라 구독 대비 비쌀 수 있습니다.

---

실전 5 — 비용 비교 실전 계산

이게 OpenCode로 갈아타는 핵심 이유입니다.

시나리오: 하루 코딩 작업 4시간, 월 20일 기준

Claude Code (Max 플랜)
  월 $200 고정
  Claude Sonnet/Opus 모델 사용

OpenCode + Claude API (Sonnet 4.6)
  입력 $3/백만 토큰, 출력 $15/백만 토큰
  일반적인 개발 세션: 월 50~100달러 수준

OpenCode + Gemini 3.5 Flash
  입력 $1.5/백만 토큰, 출력 $9/백만 토큰
  동일 작업량: 월 20~40달러 수준

OpenCode + DeepSeek V4 Pro
  입력 $0.27/백만 토큰, 출력 $1.1/백만 토큰
  동일 작업량: 월 3~8달러 수준

OpenCode + Ollama 로컬 (Qwen3:14B 등)
  월 $0 (전기세만)

성능이 Claude Code에 미치지 못하는 건 사실이지만, 비용 차이가 10~60배 나는 경우도 생깁니다. 실험적 작업, 반복 자동화, 개인 프로젝트에서는 이 차이가 결정적입니다.

---

Claude Code vs OpenCode 한 줄 비교

항목 Claude Code OpenCode

라이선스	독점	MIT 오픈소스
지원 모델	Claude 전용	75개 이상
속도	빠름	~78% 느림
데스크탑 앱	❌ (CLI 우선)	✅ Mac·Win·Linux
LSP 통합	❌	✅
멀티 세션 병렬	제한적	✅
로컬 모델	❌	✅ (Ollama)
오프라인 사용	❌	✅
Claude 구독 연동	✅	❌ (2026.04 차단)
월 비용	$20~$200 고정	모델 따라 $0~유동

---

✅ OpenCode를 써야 하는 경우

✅ Claude Code 비용이 부담스러운 개인 개발자
✅ 회사 보안 정책상 독점 툴을 쓸 수 없는 환경
✅ 여러 모델을 작업 성격에 따라 바꿔가며 쓰고 싶은 경우
✅ 완전 오프라인·로컬 실행이 필요한 경우
✅ CI/CD 파이프라인에 코딩 에이전트를 붙이는 배치 자동화

❌ Claude Code를 유지해야 하는 경우

❌ 속도가 중요한 인터랙티브 개발 세션
❌ Claude 모델 성능을 최대로 뽑아야 하는 프로덕션 작업
❌ Anthropic의 공식 지원과 업데이트 주기가 필요한 팀 환경
❌ Claude Code Max 구독으로 비용이 이미 정리된 경우