OpenCode 사용법 가이드 — 16만 개 이상의 스타를 가진 Cursor 대체재 (2026)

WebToolsHub에서 최초 공개됨 — 현대 개발자를 위한 무료 브라우저 기반 개발자 도구.

최근 GitHub 피드에서 OpenCode를 많이 보셨을 겁니다. 16만 개 이상의 스타와 2026년 6월 기준으로 월간 활성 사용자 750만 명에 달합니다. 이 정도의 성장세는 잠시 멈춰서 실제로 주목하게 만듭니다.

저는 이 글을 쓰기 전에 실제 Next.js SaaS 프로젝트에서 3주 동안 OpenCode를 사용했습니다. 단순히 '설치하고 스크린샷 찍기' 식의 작업이 아니라, 실제 프로덕션 워크플로우 테스트였습니다. 대부분의 가이드가 건너뛰는 내용을 포함하여 제가 배운 모든 것을 공유합니다.

🤔 잠깐, OpenCode가 대체 무엇인가요?

대부분 사람들은 이것을 Copilot 같은 또 다른 자동 완성 도구라고 생각합니다. 하지만 그렇지 않습니다.

OpenCode는 터미널 네이티브 에이전트형 코딩 어시스턴트입니다. 프로젝트 전체를 이해하고, 계획을 수립한 다음, 여러 단계의 작업을 자율적으로 실행합니다. 마치 다음과 같은 일을 할 수 있는 주니어 개발자라고 생각하시면 됩니다:

• 프로젝트 파일 전체 읽기
• 새 코드 작성 및 기존 파일 수정
• 쉘 명령어 실행 및 패키지 설치
• 테스트 실행 및 실패 건 수정
• 각 단계에서 자신이 무엇을 하고 있는지 설명하기

가장 혁신적인 기능은 **모델 비종속성(model agnosticism)**입니다. OpenCode는 75개 이상의 AI 제공업체에 연결됩니다. Claude, GPT, Gemini, DeepSeek, Groq뿐만 아니라 Ollama를 통한 완전 로컬 모델까지 지원합니다. 사용자가 자신의 API 키를 가져와 토큰당 비용을 지불합니다. 두 시간 후에 속도 제한(rate limits)에 걸리는 월 $20 구독료는 없습니다.

📦 설치 (원하는 방법을 선택하세요)

방법 1: 공식 스크립트 — 가장 빠른 옵션

macOS, Linux, WSL에서 작동합니다. 다음 명령어를 실행하세요:

curl -fsSL https://opencode.ai/install | bash

작동 여부 확인:

opencode --version
# v1.17.4 이상 (2026년 6월 기준)

방법 2: npm

npm install -g opencode-ai

Node.js 패키지 관리자를 통해 버전 관리를 원한다면 이 방법을 사용하면 좋습니다.

방법 3: Homebrew (macOS)

brew install opencode

방법 4: Go Install (고급 / 소스 코드 컴파일)

go install github.com/sst/opencode@latest

⚠️ 중요: 2026년 1월 9일부터 Anthropic은 일반 사용자용 OAuth (Claude Pro/Max)를 통한 OpenCode의 Claude 사용을 차단했습니다. Claude 모델을 사용하려면 console.anthropic.com에서 발급받은 API 키가 필요합니다. Gemini 2.5 Pro와 DeepSeek V4는 훌륭한 대안이며, 솔직히 저는 현재 Gemini Flash를 80%의 시간 동안 사용하고 있습니다.

⚙️ AI 제공자 (AI Provider) 설정하기

대화형 설정을 실행하세요:

opencode auth

또는 홈 디렉토리나 프로젝트 루트에 .opencode.json 파일을 수동으로 생성하세요:

{
  "provider": "google",
  "model": "gemini-2.5-pro",
...

완전히 무료로 사용하고 싶으신가요? 로컬 모델과 함께 Ollama를 사용하세요:

{
  "provider": "ollama",
  "model": "llama3:8b",
...

⚠️ 로컬 모델은 다단계 작업 (multi-step tasks)에서 눈에 띄게 성능이 떨어집니다. 빠른 편집에는 좋지만, 복잡한 리팩토링 (refactor)에는 이상적이지 않습니다. 정확성이 중요한 경우에는 프런티어 모델 (frontier model)을 사용하세요.

로컬 AI를 사용하여 OpenCode를 Next.js 프로젝트에 통합하려는 경우, WebToolsHub의 Ollama + Next.js 가이드에서 전체 설정 과정을 자세히 다룹니다.

🔍 아무도 말하지 않는 기능: LSP 통합

이것은 OpenCode의 가장 과소평가된 장점입니다. 네이티브 언어 서버 프로토콜 (Language Server Protocol, LSP) 통합 기능은 — 올바른 언어 서버 (TypeScript, Python, Go...)를 자동으로 실행하고, 모든 편집 후에 실제 컴파일러 진단 (compiler diagnostics) 정보를 AI에게 다시 전달합니다.

이것이 중요한 이유: OpenCode가 Next.js 컴포넌트를 리팩토링하다가 TypeScript 타입 오류를 발생시킨다고 가정해 봅시다. LSP가 없다면 AI는 이를 알지 못합니다. 하지만 LSP가 있다면, 오류 정보가 자동으로 다음 프롬프트에 전달되어 모델이 스스로 수정합니다. 터미널에서 오류 메시지를 복사하여 붙여넣을 필요가 없습니다.

Builder.io의 헤드 투 헤드(head-to-head) 테스트(Claude Sonnet 4.5 사용, 동일한 작업 수행) 결과, OpenCode는 동일한 코드베이스에서 Claude Code보다 21개의 테스트를 더 작성했습니다. LSP 피드백 루프(LSP feedback loop)가 그 주요 원인입니다.

이는 대규모 TypeScript 코드베이스를 다루는 멀티 파일 리팩터링 (multi-file refactors) 시 가장 중요하게 작용합니다. 복잡한 API 타입을 다루고 있다면, 에이전트가 작업하는 동안 타입을 정확하게 유지할 수 있도록 JSON to TypeScript converter를 함께 사용하세요.

⚔️ OpenCode vs Claude Code: 솔직한 평가

저는 두 도구를 모두 집중적으로 사용해 보았습니다. 필터링 없는 제 의견은 다음과 같습니다.

Claude Code가 승리하는 부분

속도. Builder.io의 벤치마크에 따르면, 동일한 Claude 모델을 실행할 때 OpenCode는 동일한 작업당 약 78% 더 많은 시간이 소요됩니다. 이러한 오버헤드는 OpenCode의 클라이언트-서버 아키텍처(client-server architecture)에서 비롯됩니다. 로컬에서 실행하더라도 TUI가 백엔드 프로세스와 통신하기 때문입니다. 빠른 속도의 개발(rapid-fire development)을 진행 중이라면 그 격차를 체감하게 될 것입니다.

OpenCode가 승리하는 부분

사실상 그 외 모든 것:

요소	OpenCode	Claude Code
비용	토큰당 결제	월 $20 + 속도 제한
...

실제 권장 사항: 둘 다 사용하세요. 속도가 중요한 프로덕션 작업에는 Claude Code를 사용하세요. 실험적인 작업, 개인정보 보호가 중요한 코드베이스, 그리고 구독료를 지불하지 않고 모델 유연성을 확보하고 싶을 때는 OpenCode를 사용하세요.

WebToolsHub의 Claude Code 기술 가이드도 읽어볼 가치가 있습니다. 해당 가이드의 대부분의 마크다운(markdown) 기술 파일들은 약간의 수정만 거치면 OpenCode에서도 작동합니다.

🚀 OpenCode를 활용한 실제 Next.js 워크플로우

이것은 제가 실제 프로덕션 프로젝트에서 사용하는 워크플로우입니다.

1단계: 프로젝트 컨텍스트 초기화

cd my-nextjs-app
opencode

OpenCode 세션 내부에서:

/init

이 명령은 코드베이스를 분석하고, 귀하의 컨벤션(conventions)과 패턴을 이해하며, 지속적인 컨텍스트(persistent context)를 담은 .opencode/ 디렉토리를 생성합니다. 항상 이 작업을 가장 먼저 수행하세요.

2단계: 새로운 기능을 위한 플래닝 모드 (Planning Mode) 사용

파일을 수정하기 전에:

/plan
Upstash Redis를 사용하여 모든 API 라우트에 rate limiting (속도 제한) 미들웨어 추가

OpenCode는 기존 라우트를 분석하고, 의존성 (dependencies)을 확인하며, 상세한 구현 계획을 생성합니다. "proceed (진행)"라고 말하기 전에 계획을 검토하세요. 이 30초의 습관이 몇 시간의 시간을 아껴줍니다.

3단계: 명확하고 범위가 지정된 지침 제공 (Explicit Scoped Instructions)

/src/components/UserCard.tsx를 shadcn Card 컴포넌트를 사용하도록 리팩터링(Refactor)하세요.
기존의 모든 props를 유지하세요. 부모 컴포넌트는 건드리지 마세요.
변경 사항을 적용한 후 TypeScript 체크를 실행하세요.

마지막 줄인 "TypeScript 체크를 실행하세요"가 바로 LSP 통합이 빛을 발하는 부분입니다. OpenCode는 tsc --noEmit을 실행하고, 에러를 확인한 뒤, 동일한 세션 내에서 이를 수정합니다.

4단계: /undo를 아낌없이 사용하기

OpenCode는 모든 변경 사항 전에 Git 기반의 스냅샷 (snapshots)을 찍습니다. /undo를 사용하면 즉시 되돌릴 수 있습니다. 이를 끊임없이 사용하세요. 이것이 에이전트 (agent)가 공격적으로 작업하도록 안전하게 맡길 수 있는 이유입니다.

💸 OpenCode의 실제 비용은 얼마인가요?

OpenCode 자체는: 평생 $0, MIT 라이선스입니다.

일반적인 개발자의 일일 사용량을 기준으로 한 모델 API 비용:

모델	비용	최적의 용도
Gemini 2.5 Flash	~$0.15/1M tokens	빠른 편집, 보일러플레이트 (boilerplate)
...

대부분의 개발자에게 Gemini Flash는 거의 제로에 가까운 비용으로 작업의 80%를 처리합니다. 무거운 모델은 어려운 문제들을 위해 아껴두세요. 본격적으로 사용하기 전에 WebToolsHub의 LLM API 비용 계산기를 사용하여 월간 지출액을 추산해 보세요.

❌ 초보자들이 저지르는 실수

1. /init 건너뛰기
프로젝트 초기화 (initialization) 없이는 OpenCode가 코드베이스 (codebase)를 추측하게 됩니다. 새로운 프로젝트에서는 항상 /init을 먼저 실행하세요.

2. 복잡한 리팩터링 (refactors)에 Llama 3 8B 사용하기
실망하게 될 것입니다. Ollama는 단일 파일 편집용으로 남겨두세요. 여러 파일에 걸친 작업에는 Gemini Pro 또는 Claude Sonnet을 사용하세요.

3. 계획을 검토하지 않는 것
모든 큰 변경 전에는 /plan을 실행해야 합니다. 이는 타협할 수 없는 원칙입니다. 계획을 읽는 데는 30초가 걸리지만, 20개 파일의 리팩터링을 되돌리는 데는 30분이 걸립니다.

4. 프로젝트 수준의 설정을 커밋하지 않는 것
.opencode.json 파일을 저장소 루트(repo root)에 두고 커밋하세요. 그러면 팀원들이 자동으로 일관된 모델 설정을 사용할 수 있습니다.

5. 세션 공유를 무시하는 것
OpenCode는 모든 세션에 대해 공유 가능한 링크를 생성합니다. 이는 비동기 디버깅 (async debugging) 시 매우 유용합니다. 버그가 발생한 정확한 세션을 공유할 수 있기 때문입니다.

🔮 OpenCode의 향후 업데이트 예정 사항

2026년 상반기(H1)의 출시 속도는 매우 인상적이었습니다:

• ✅ 백그라운드 서브 에이전트 (Background subagents, 여러 에이전트가 병렬로 실행됨)
• ✅ 외부 리서치를 위한 스카우트 에이전트 (Scout agent)
• ✅ 데스크톱 앱 베타 (macOS, Windows, Linux)
• 🔜 공식 플러그인 마켓플레이스 (Official plugin marketplace)
• 🔜 MCP 서버 지원 (이미 베타 버전 진행 중)

개발자의 85%가 매일 AI 도구를 사용하고, 2026년에는 모든 신규 코드의 약 46%를 AI가 생성함에 따라, 코딩 에이전트(coding agent)의 선택은 그 어느 때보다 중요해졌습니다. 모델 불가지론 (model agnosticism)과 오픈 소스 투명성에 대한 OpenCode의 베팅은 향후 AI 환경이 어떻게 변화하든 강력한 위치를 점하게 해줍니다.

⭐ 요약 (TL;DR)

• OpenCode = 무료, MIT 라이선스, 터미널 네이티브 (terminal-native) AI 코딩 에이전트
• 75개 이상의 제공업체 연결 — Claude, GPT, Gemini, Ollama
• 자동 오류 수정을 위한 네이티브 LSP 통합 (고유 기능)
• 동일한 작업 시 Claude Code보다 약 78% 느리지만, 더 저렴하고 더 프라이빗함
• 최적의 워크플로우: /init → /plan → 실행 → 필요 시 /undo
• 작업의 80%는 Gemini 2.5 Flash 사용, 까다로운 TypeScript 작업은 Claude Sonnet 4.6 API 사용

데이터를 어디에도 전송하지 않고, 브라우저에서 완전히 작동하는 동일한 방식의 무료 개발자 도구를 원하시나요? WebToolsHub를 확인해 보세요 — JSON→TypeScript 변환기, AI 프롬프트 최적화 도구 (AI Prompt Optimizer), 크론 잡 생성기 (Cron Job Generator)를 포함하여 개발자를 위한 100개 이상의 무료 도구를 제공합니다.

모든 WebToolsHub 도구는 100% 클라이언트 측 (client-side)에서 작동하며, 어떤 서버로도 데이터가 전송되지 않습니다.

이 기사는 원래 webtoolshub.online/blog/opencode-complete-guide-setup-2026에서 게시되었습니다.