재훈의 공개 노트

AI-OPENCODE-GUIDE

6 min read

OpenCode 가이드

정보 출처 표시

  • 공식: 공식 페이지에서 확인된 정보
  • 추측/참고: 일반적인 경험 기반 제안

개요

OpenCode는 터미널에서 동작하는 오픈소스 AI 코딩 에이전트입니다. Claude Code의 오픈소스 대안으로, 다양한 AI 모델을 선택해서 사용할 수 있습니다.

항목내용
공식 사이트https://opencode.ai
GitHubhttps://github.com/sst/opencode
라이선스MIT
GitHub Stars47,000+
월간 사용자650,000+

주요 특징

다중 AI 제공자 지원

  • 무료 모델 포함: 별도 API 키 없이 사용 가능
  • 75+ 모델 지원: Claude, GPT, Gemini, Groq, 로컬 모델 등
  • Claude Pro 연동: Anthropic 계정으로 Pro/Max 플랜 사용 가능

핵심 기능

  • TUI 인터페이스: Bubble Tea 기반 터미널 UI
  • LSP 통합: 언어별 코드 인텔리전스 자동 로드
  • MCP 지원: 외부 도구와 표준 프로토콜 연동
  • 다중 세션: 동일 프로젝트에서 병렬 에이전트 실행
  • 데이터 프라이버시: 코드/컨텍스트 저장 안 함

설치 방법

# 공식 스크립트 (권장)
curl -fsSL https://opencode.ai/install | bash
 
# Homebrew (macOS/Linux)
brew install opencode
 
# npm
npm i -g opencode-ai@latest
 
# Go
go install github.com/opencode-ai/opencode@latest

기본 사용법

# TUI 시작
opencode
 
# 비대화형 모드 (단일 프롬프트)
opencode run "이 함수를 리팩토링해줘"
 
# 헤드리스 서버 시작
opencode serve
 
# 웹 인터페이스 시작
opencode web

주요 서브커맨드

명령어기능
opencodeTUI 시작
opencode run [message]비대화형 모드
opencode serveAPI 서버 시작
opencode web웹 인터페이스 시작
opencode agent에이전트 관리
opencode auth인증 관리
opencode models사용 가능 모델 표시
opencode session세션 관리
opencode stats토큰/비용 통계

Claude Code와 비교

기능 비교

기능OpenCodeClaude Code
오픈소스✅ MIT❌
모델 선택75+ 모델Claude 전용
무료 사용✅ 무료 모델 포함❌ API 비용
TUI✅✅
MCP✅✅
LSP✅✅

호환성 정리

호환되는 것

기능설명
스킬 경로.claude/skills/ 경로 그대로 인식
MCP 서버동일한 MCP 프로토콜 사용
기본 도구Read, Write, Edit, Bash 동일

변환이 필요한 것

Claude CodeOpenCode
TodoWriteupdate_plan
Task (서브에이전트)@mention
Skilluse_skill

호환 안 되는 것

기능이유
CLAUDE.mdOpenCode는 opencode.json 사용
훅 (Hooks)Claude 4개 이벤트 vs OpenCode 32개+
슬래시 커맨드내장 커맨드 체계가 다름

스킬 마이그레이션

스킬 경로

OpenCode는 Claude 스킬 경로를 자동 인식합니다:

# Claude 호환 경로 (자동 인식)
.claude/skills/<name>/SKILL.md      # 프로젝트
~/.claude/skills/<name>/SKILL.md    # 전역

# OpenCode 전용 경로
.opencode/skill/<name>/SKILL.md     # 프로젝트
~/.config/opencode/skill/<name>/SKILL.md  # 전역

SKILL.md 형식

---
name: my-skill          # 필수
description: 스킬 설명   # 필수 (1-1024자)
license: MIT            # 선택
compatibility:          # 선택
  - claude
  - opencode
---
 
# 스킬 프롬프트 내용

이름 규칙

  • 1-64자의 소문자 영숫자
  • 단일 하이픈 구분자 허용
  • 정규식: ^[a-z0-9]+(-[a-z0-9]+)*$

에이전트별 모델 지정

OpenCode의 강력한 기능 중 하나는 에이전트별로 다른 모델을 지정할 수 있다는 점입니다.

opencode.json 설정 예시

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5",
 
  "agent": {
    "code-reviewer": {
      "description": "코드 리뷰 전문",
      "model": "anthropic/claude-haiku-4-5",
      "prompt": "You are a code reviewer...",
      "tools": { "write": false, "edit": false }
    },
    "researcher": {
      "description": "조사 전문 (무료 모델 사용)",
      "model": "groq/llama-4-scout"
    },
    "debugger": {
      "description": "디버깅 전문",
      "model": "openai/gpt-4.1"
    }
  }
}

모델 ID 형식

provider/model-id
Provider예시
Anthropicanthropic/claude-sonnet-4-5
OpenAIopenai/gpt-4.1
Groq (무료)groq/llama-4-scout
Googlegoogle/gemini-2.5-pro
OpenCode Zenopencode/gpt-5.1-codex

기본 동작

  • 주 에이전트: 전역 model 설정 사용
  • 서브에이전트: 모델 미지정 시 → 호출한 주 에이전트의 모델 상속
  • small_model: 제목 생성 등 가벼운 작업용

비용 최적화 전략

용도권장 모델이유
메인 코딩Claude Opus/Sonnet높은 정확도
코드 리뷰Claude Haiku빠르고 저렴
조사/검색Groq Llama (무료)비용 없음
디버깅GPT-4.1논리적 추론

마이그레이션 난이도

난이도항목
쉬움스킬, MCP 서버
중간에이전트 (도구명 변환 필요)
어려움훅, 커스텀 슬래시 커맨드

상세 가이드

단계별 마이그레이션 방법은 마이그레이션 가이드 참조

언제 OpenCode를 선택할까?

  • Claude 외 다른 모델을 사용하고 싶을 때
  • API 비용을 절약하고 싶을 때 (무료 모델 제공)
  • 오픈소스 도구를 선호할 때
  • 로컬 모델을 사용하고 싶을 때

참고 링크

tags:
  - type/guide
  - topic/ai
  - topic/devtools
  - status/active

백링크