OpenCode 완전 가이드 — 자체 API 키로 Claude Code 대신 쓰는 오픈소스 터미널 에이전트

Claude Code는 월 $20입니다. OpenCode는 오픈소스에 자체 API 키를 씁니다. 같은 Claude Opus 4.7을 쓰면서 구독료가 없습니다.

[핵심 요약]
→ 정체: 오픈소스 터미널 기반 AI 코딩 에이전트
→ 개발: Anomaly (SST 팀, terminal.shop 개발자)
→ 라이센스: MIT — 완전 무료, 소스 공개
→ GitHub: 150,000개 스타, 850명 기여자, 6.5M 월간 사용자
→ 핵심: BYOK (Bring Your Own Key) — 자체 API 키로 75개+ 모델 사용
→ 실행: TUI (터미널), 데스크탑 앱, IDE 익스텐션 (VS Code, Cursor, Zed)
→ 특징: Plan/Build 모드, 멀티 에이전트, LSP 통합, MCP 지원, 세션 관리
→ 비용: OpenCode 자체는 무료, API 사용료만 부담 (월 $2~10 수준 가능)

---

OpenCode vs Claude Code — 뭐가 다른가

Claude Code:
→ Anthropic 독점 (Claude 모델만)
→ Pro $20/월 구독 필수
→ 사용량 한도 있음
→ 데이터: Anthropic 서버 통과
→ 소스: 비공개

OpenCode:
→ 75개+ 모델 (Claude, GPT, Gemini, Qwen, 로컬 모델)
→ OpenCode 자체: 무료 (API 사용료만)
→ 사용량: API 한도만 적용
→ 데이터: 자체 API 키 → 각 제공사 정책 따름
→ 소스: MIT 오픈소스
→ 로컬 모델: Ollama 연동으로 완전 오프라인 가능

[비용 현실 비교]
Claude Code Pro: $20/월 고정

OpenCode + Claude API:
→ 가벼운 사용 (1일 30분): ~$2~5/월
→ 중간 사용 (1일 2시간): ~$15~30/월
→ 무거운 사용 (풀타임): $50~100+/월

OpenCode + Gemini API:
→ 무료 티어: 1,000 req/일 (Gemini 3.1 Flash)
→ 사실상 무료로 꽤 쓸 수 있음

OpenCode + Ollama (로컬):
→ 완전 무료 (GPU 전기세만)
→ Qwen3.6-27B, bge-m3 로컬로 돌리면 API 비용 0원

---

실전 1 — 설치

# 방법 1: 공식 설치 스크립트 (가장 빠름, 60초)
curl -fsSL https://opencode.ai/install | bash

# 방법 2: npm/bun/pnpm/yarn
npm i -g opencode-ai
bun add -g opencode-ai

# 방법 3: macOS Homebrew (권장 — 최신 버전 유지)
brew install anomalyco/tap/opencode

# 방법 4: Windows (Scoop)
scoop install opencode

# 방법 5: Arch Linux
sudo pacman -S opencode      # 안정 버전
paru -S opencode-bin          # AUR 최신

# 방법 6: Nix
nix run nixpkgs#opencode

# 설치 확인
opencode --version

# 데스크탑 앱 (GUI 선호하는 경우)
brew install --cask opencode-desktop  # macOS
# Windows: opencode.ai/download에서 다운로드

---

실전 2 — API 키 설정 및 모델 연결

# 프로젝트 디렉토리에서 실행
cd your-project
opencode

# 첫 실행 시 모델 제공사 선택 안내 나옴
# → API 키 입력 → .opencode/config 에 저장

// ~/.config/opencode/config.json (전역 설정)
// 또는 프로젝트/.opencode/config.json (프로젝트 별)
{
  "providers": {
    "anthropic": {
      "apiKey": "sk-ant-...",      // Claude
      "disabled": false
    },
    "openai": {
      "apiKey": "sk-...",          // GPT
      "disabled": false
    },
    "google": {
      "apiKey": "AIza...",         // Gemini
      "disabled": false
    },
    "groq": {
      "apiKey": "gsk_...",         // Groq (빠른 추론)
      "disabled": false
    }
  },
  "model": "anthropic/claude-sonnet-4-6",  // 기본 모델
  "autoshare": false,
  "autoapprove": false   // 파일 수정 전 항상 확인
}

# 환경변수로도 설정 가능
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."
export GOOGLE_API_KEY="AIza..."
export GROQ_API_KEY="gsk_..."

# 설정 후 실행
opencode

[지원 모델 제공사 75개+]
→ Anthropic: Claude Opus 4.7, Sonnet 4.6, Haiku 4.5
→ OpenAI: GPT-5.5, GPT-5.4, o3
→ Google: Gemini 3.1 Pro, Flash, Flash-Lite
→ AWS Bedrock: Claude, Titan, Llama
→ Azure OpenAI: GPT 모델들
→ Groq: Llama, Mixtral (초고속)
→ OpenRouter: 200개+ 모델 통합
→ Ollama: 로컬 모델 전부 (Qwen3.6, Granite 4.1 등)
→ LM Studio, Mistral AI, xAI (Grok), Together AI 등

---

실전 3 — 기본 사용법 (TUI)

# 기본 실행
opencode

# 특정 디렉토리에서 실행
opencode -c /path/to/project

# 디버그 모드
opencode -d

# 단일 프롬프트 실행 (비대화형)
opencode -p "이 코드에서 버그 찾아줘"

# JSON 출력 (스크립트/자동화용)
opencode -p "함수 이름 목록 줘" -f json

# 조용한 모드 (스피너 없음, CI/CD용)
opencode -p "테스트 실행해줘" -q

[TUI 키보드 단축키]

기본:
→ Enter: 메시지 전송
→ Tab: Build/Plan 에이전트 전환
→ Esc: 현재 작업 취소
→ Ctrl+C: 종료

파일/컨텍스트:
→ @파일명: 특정 파일 컨텍스트에 추가
→ @에이전트명: 다른 에이전트 호출

세션:
→ /sessions: 이전 세션 목록
→ /share: 세션 공유 링크 생성
→ /clear: 컨텍스트 초기화

모델 전환:
→ /model: 모델 변경
→ /model claude-opus-4.7: 특정 모델로 전환

---

실전 4 — Plan/Build 모드

# Plan 모드 (읽기 전용, 수정 없음)
# → Tab 키로 Plan 에이전트 선택
# → 코드베이스 분석, 변경 계획 수립
# → 파일 수정 없이 무엇을 할지만 설명

사용자: "인증 시스템 리팩토링 계획 짜줘"
Plan 에이전트: [파일 읽기만 함]
              "1단계: JWT 모듈 분리
               2단계: 미들웨어 추상화
               3단계: 테스트 추가"

# Build 모드 (실제 수정)
# → Tab 키로 Build 에이전트 선택
# → 계획 확인 후 실제 파일 수정 실행

# agents/ 디렉토리에 커스텀 에이전트 만들기
# ~/.config/opencode/agents/review.md

---
description: "코드 리뷰 전용 에이전트. 파일 수정 없이 리뷰만."
model: anthropic/claude-opus-4.7
temperature: 0.3
tools:
  - read        # 읽기만 허용
  - grep        # 검색 허용
  # write 제외 → 수정 불가
---

당신은 시니어 코드 리뷰어입니다.

코드를 읽고 다음을 검토하세요:
- 보안 취약점
- 성능 문제
- 코드 스타일
- 엣지 케이스

수정은 하지 말고 리뷰만 제공하세요.

# 커스텀 에이전트 사용
opencode
# TUI에서 @review 입력 → 리뷰 에이전트 호출

[내장 에이전트 목록]
Build:    기본 에이전트, 풀 파일 접근
Plan:     읽기 전용, 분석/계획만
Research: 복잡한 멀티스텝 리서치, 파일 수정 가능
Explore:  코드베이스 탐색 전용, 수정 불가
Compact:  긴 컨텍스트 자동 압축 (시스템 내부용)

---

실전 5 — 비대화형 모드 & 자동화

# CI/CD 파이프라인에서 사용
# .github/workflows/ai-review.yml

# PR 자동 리뷰
opencode -p "이 PR의 변경사항 리뷰해줘: $(git diff main)" -q

# 테스트 실패 자동 수정
opencode -p "테스트 실패 수정해줘: $(pytest 2>&1 | tail -50)" -q

# 문서 자동 생성
opencode -p "이 모듈의 README 작성해줘" -f json | jq -r '.content' > README.md

# 배치 처리 스크립트
for file in src/**/*.py; do
    opencode -p "이 파일 타입 힌트 추가해줘: $(cat $file)" -q
done

# Python에서 OpenCode 비대화형 모드 활용
import subprocess
import json

def ask_opencode(prompt: str, format: str = "text") -> str:
    """OpenCode 비대화형 호출"""
    result = subprocess.run(
        ["opencode", "-p", prompt, "-f", format, "-q"],
        capture_output=True,
        text=True,
        cwd="/path/to/project"
    )

    if result.returncode != 0:
        raise RuntimeError(f"OpenCode 오류: {result.stderr}")

    if format == "json":
        return json.loads(result.stdout)
    return result.stdout.strip()


# 사용 예시
# 코드 리뷰
review = ask_opencode("auth/login.py 보안 리뷰해줘")
print(review)

# JSON 형식으로 버그 목록
bugs = ask_opencode("이 코드에서 버그 목록 JSON으로 줘", format="json")

---

실전 6 — MCP 연동

// .opencode/config.json에 MCP 서버 추가
{
  "mcp": {
    "servers": {
      "github": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-github"],
        "env": {
          "GITHUB_TOKEN": "ghp_..."
        }
      },
      "supabase": {
        "command": "npx",
        "args": ["-y", "@supabase/mcp-server-supabase@latest"],
        "env": {
          "SUPABASE_URL": "https://xxx.supabase.co",
          "SUPABASE_KEY": "eyJ..."
        }
      },
      "filesystem": {
        "command": "npx",
        "args": [
          "-y",
          "@modelcontextprotocol/server-filesystem",
          "/home/user/projects"
        ]
      }
    }
  }
}

# MCP 서버 연동 후 사용 예시
opencode

# GitHub 이슈 분석
> 이 레포의 오픈 이슈 목록 보고 우선순위 높은 것 수정해줘

# Supabase DB 조작
> users 테이블에서 30일 이상 미접속 계정 목록 조회해줘

---

실전 7 — Ollama로 완전 로컬 실행

# Ollama 설치 (ollama.ai)
curl -fsSL https://ollama.ai/install.sh | sh

# 로컬 모델 다운로드
ollama pull qwen2.5-coder:7b    # 코딩 특화, 빠름
ollama pull deepseek-coder:6.7b  # 코딩 특화
ollama pull granite3.3:8b        # IBM Granite (툴 호출)

# OpenCode에서 Ollama 연결

// config.json
{
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434",
      "disabled": false
    }
  },
  "model": "ollama/qwen2.5-coder:7b"  // 로컬 모델 사용
}

# 완전 오프라인 실행
opencode
# → 인터넷 없이 로컬 모델로 코딩 에이전트 실행
# → API 비용 0원, 데이터 외부 전송 없음

---

실전 8 — LSP 통합

// .opencode/config.json
{
  "lsp": {
    "python": {
      "command": "pylsp",    // pip install python-lsp-server
      "args": []
    },
    "typescript": {
      "command": "typescript-language-server",
      "args": ["--stdio"]    // npm i -g typescript-language-server
    },
    "go": {
      "command": "gopls",    // go install golang.org/x/tools/gopls@latest
      "args": []
    },
    "rust": {
      "command": "rust-analyzer",
      "args": []
    }
  }
}

[LSP 통합 효과]
→ 에이전트가 실제 컴파일러 에러 확인 가능
→ "이 코드 고쳐줘" → LSP로 실제 타입 에러 확인 → 정확한 수정
→ 환각 감소: "함수가 없다" 대신 실제 LSP 진단 기반 수정
→ go, python, typescript, rust, java 등 모든 LSP 지원 언어 가능

---

OpenCode Zen — 자체 API 키 없이 쓰는 방법

자체 API 키 발급이 번거롭다면 OpenCode Zen을 사용합니다.

[OpenCode Zen이란?]
→ OpenCode 팀이 직접 테스트/벤치마크한 모델 큐레이션 서비스
→ 자체 API 키 없이 사용 가능
→ 모든 모델이 코딩 에이전트에 최적화 설정됨
→ 월 사용량 한도 설정 가능
→ Zero-retention: 코드/데이터 훈련에 사용 안 함
→ 현재 얼리 액세스 대기 중 (opencode.ai/zen)

[Zen vs 자체 API 키]
Zen:         설정 간편, 최적화된 모델, 월정액
자체 API 키: 완전 제어, 비용 투명, 더 저렴 가능

---

경쟁 툴 비교

항목 OpenCode Claude Code Aider Cursor

라이센스	MIT (무료)	유료 구독	Apache 2.0	유료 구독
모델	75개+ 멀티벤더	Claude 전용	멀티벤더	멀티벤더
인터페이스	TUI+데스크탑+IDE	터미널	터미널	GUI IDE
Plan/Build	✅	/ultrareview	❌	✅
LSP 통합	✅	제한적	❌	✅
MCP 지원	✅	✅	❌	✅
로컬 모델	✅ Ollama	❌	✅	✅
비대화형	✅	❌	✅	❌
GitHub Stars	150K+	비공개	20K+	비공개

---

마무리

✅ OpenCode 써야 할 때
→ Claude Code/Cursor 월 구독료가 부담될 때
→ 특정 모델에 락인되기 싫을 때 (멀티벤더)
→ 민감한 코드를 외부 서버에 보내기 싫을 때 (로컬 모델)
→ 터미널 퍼스트 워크플로우 선호 (Neovim, tmux 사용자)
→ CI/CD 파이프라인에 AI 에이전트 통합
→ Gemini 무료 티어로 거의 무료 코딩 에이전트 원할 때

❌ 다른 툴이 나을 때
→ GUI 중심 워크플로우 → Cursor 3
→ Claude 최고 성능 + 구독 있음 → Claude Code
→ Git 통합 우선 → Aider (git 네이티브 통합)
→ 세련된 IDE 경험 → Cursor 3 또는 VS Code + Copilot
→ 팀 공유 Cloud Agent → Cursor 3 Cloud Agent

[오늘 당장 시작하는 법]
1. curl -fsSL https://opencode.ai/install | bash
2. ANTHROPIC_API_KEY 또는 GOOGLE_API_KEY 설정
3. cd 프로젝트 && opencode
4. Tab 키로 Plan/Build 전환하면서 사용

---

관련 글:

https://cell-devlog.tistory.com/39

AI 코딩 툴 3대장 완전 비교 — Cursor vs Claude Code vs GitHub Copilot

https://cell-devlog.tistory.com/126

Continue.dev 완전 가이드 — GitHub Copilot 대신 쓰는 무료 오픈소스 AI 코딩 어시스턴트

https://cell-devlog.tistory.com/62

MCP 서버 직접 만들기 — 내 서비스를 Claude에 연동하는 법

https://cell-devlog.tistory.com/129

Qwen3.6-27B 완전 분석 — 27B 모델이 397B MoE 능가

 

---