서문: 왜 165k+ 개발자가 OpenCode를 선택했을까?

2026년, AI 프로그래밍 도구는 "코드 자동완성 보조"에서 "개발 작업 자율 수행"으로 진화했습니다. 이 분야에서 OpenCode(github.com/sst/opencode)는 놀라운 속도로 성장 중입니다—GitHub Star 수가 165,000개를 돌파하며 현재 가장 인기 있는 오픈소스 터미널 AI 프로그래밍 Agent가 되었습니다.

Claude Code나 Cursor 같은 클로즈드 소스 도구와 달리, OpenCode의 핵심 철학은 "모델과 도구 분리"입니다. GPT-4o, Claude, Qwen, DeepSeek는 물론 로컬 Ollama 모델까지—all in one 터미널 도구에서 자유롭게 선택할 수 있습니다.

오늘 이 글에서는 OpenCode를 제로베이스에서 시작해 설치·설정부터 심화 활용까지, 한 번에 정리해 드립니다.

1. OpenCode란 무엇인가?

OpenCode는 SST 팀에서 개발한 오픈소스 CLI 프로그래밍 Agent입니다. 핵심 아키텍처는 두 레이어로 구성됩니다:

  • Harness(도구 레이어): 파일 읽기/쓰기, Shell 명령 실행, 테스트 결과 수집 등 환경 조작 담당
  • Model(모델 레이어): OpenAI 호환 API를 통해 임의의 대형 언어 모델에 연결

이러한 분리 설계의 의미는 "특정 벤더에 락인될 필요가 없다"는 것입니다. 오늘은 Claude, 내일은 GPT, 모레 로컬 Qwen—같은 도구에서 매끄럽게 전환할 수 있습니다.

핵심 특징 한눈에 보기

특징 설명
🧠 다중 모델 지원 Claude, GPT-4o, Gemini, Qwen, DeepSeek, Ollama 로컬 모델
🖥️ 터미널 우선 순수 CLI 도구, IDE 플러그인 불필요
📦 제로 설정 시작 설치 즉시 사용, 합리적 기본 설정 내장
🔌 MCP 통합 MCP 프로토콜 지원, 도구 체인 확장 가능
📋 플래닝 모드 내장 Agent 플래닝 기능, 자율 작업 분해 가능
🔓 완전 오픈소스 Apache 2.0 라이선스

OpenCode vs 다른 도구

도구 오픈소스 다중 모델 터미널 우선 GitHub Stars
OpenCode ✅ ✅ ✅ 165k+
OpenAI Codex CLI ✅ ⚠️ OpenAI 편향 ✅ 30k+
OpenHands ✅ ✅ ❌ GUI 편향 40k+
Claude Code ❌ ❌ Claude 전용 ✅ N/A
Aider ✅ ✅ ✅ 40k+

OpenCode의 핵심 강점은 모델 유연성과 터미널 경험의 완벽한 결합입니다.

2. 빠른 설치

OpenCode는 여러 설치 방법을 제공합니다. 가장 적합한 방법을 선택하세요:

방법 1: npm 설치 (추천)

BASH 
npm install -g opencode-ai

방법 2: Homebrew (macOS/Linux)

BASH 
brew install opencode

방법 3: 원클릭 설치 스크립트

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

설치 확인

BASH 
opencode --version

3. 빠른 시작: 첫 사용

3.1 API Key 설정

OpenCode는 최소 하나의 AI 모델 API Key를 설정해야 합니다. 가장 간단한 방법은 환경 변수 설정입니다:

BASH 
# OpenAI 사용
export OPENAI_API_KEY="sk-your-key-here"

# 또는 Anthropic Claude 사용
export ANTHROPIC_API_KEY="sk-ant-your-key-here"

💡 팁: ~/.opencode/config.json에 설정을 저장해 두면 매번 터미널을 열 때마다 환경 변수를 설정할 필요가 없습니다.

3.2 프로젝트에서 OpenCode 시작

BASH 
# 프로젝트 디렉토리로 이동
cd ~/projects/my-app

# OpenCode 시작
opencode

OpenCode는 자동으로 프로젝트 구조를 감지하고 컨텍스트를 로드한 뒤, 대화를 시작할 수 있게 합니다:

$ opencode

🤖 OpenCode v1.x - AI Coding Agent

> src/auth.py의 로그인 로직을 확인해서 보안 문제 없는지 봐줘

3.3 첫 작업 예시

OpenCode에 구체적인 작업을 맡겨 보세요:

> Python FastAPI 프로젝트를 만들어줘. 구조는 다음과 같이:
> - main.py (애플리케이션 진입점)
> - routers/users.py (사용자 라우팅)
> - models/user.py (사용자 모델)
> - requirements.txt (의존성)

OpenCode는 단계별로 작업을 수행합니다: 프로젝트 구조 읽기 → 파일 생성 → 코드 작성, 그리고 각 단계마다 확인을 요청합니다.

4. 심화 설정: 다중 모델 전환

4.1 설정 파일

~/.opencode/config.json을 생성하세요:

JSON 
{
  "providers": {
    "openai": {
      "type": "openai",
      "apiKey": "sk-your-openai-key",
      "model": "gpt-4o"
    },
    "anthropic": {
      "type": "anthropic",
      "apiKey": "sk-ant-your-key",
      "model": "claude-sonnet-4-20250514"
    },
    "ollama": {
      "type": "openai",
      "baseUrl": "http://localhost:11434/v1",
      "model": "qwen2.5-coder:32b"
    }
  },
  "defaultProvider": "anthropic"
}

4.2 실행 중 모델 전환

OpenCode 대화 중에 언제든지 모델을 전환할 수 있습니다:

> /model openai
OpenAI GPT-4o로 전환됨

> /model ollama
로컬 Ollama 모델로 전환됨

4.3 DeepSeek 연결 (국내 개발자 추천)

중국 개발자에게 DeepSeek는 가성비 면에서 매우 훌륭한 선택입니다:

JSON 
{
  "providers": {
    "deepseek": {
      "type": "openai",
      "baseUrl": "https://api.deepseek.com/v1",
      "apiKey": "your-deepseek-key",
      "model": "deepseek-coder"
    }
  }
}

SiliconFlow 같은 중계 플랫폼을 사용할 수도 있습니다:

JSON 
{
  "providers": {
    "siliconflow": {
      "type": "openai",
      "baseUrl": "https://api.siliconflow.cn/v1",
      "apiKey": "your-siliconflow-key",
      "model": "Qwen/Qwen2.5-Coder-32B-Instruct"
    }
  }
}

5. 실전 시나리오

5.1 시나리오 1: 레거시 코드 리팩토링

BASH 
# 레거시 프로젝트로 이동
cd ~/projects/legacy-app

# OpenCode 시작
opencode

> src/utils.js의 콜백 함수를 모두 async/await 스타일로 바꿔줘
> 기존 기능은 그대로 유지하고, 적절한 에러 처리도 추가해줘

OpenCode는 다음과 같이 작동합니다: 1. src/utils.js 내용 읽기 2. 모든 콜백 함수 구조 분석 3. async/await로 하나씩 변환 4. try/catch 에러 처리 추가 5. diff를 보여주고 확인 대기

5.2 시나리오 2: 단위 테스트 작성

> src/auth/login.ts의 Jest 단위 테스트를 작성해줘
> 다음 시나리오를 커버해야 해:
> 1. 정상 로그인 성공
> 2. 비밀번호 오류
> 3. 사용자 존재하지 않음
> 4. 토큰 만료
> 5. 동시 로그인 요청

OpenCode는 mock 데이터와 assertion 로직이 포함된 완전한 테스트 파일을 생성합니다.

5.3 시나리오 3: 버그 트러블슈팅

> 대용량 JSON 데이터 처리 시 메모리 오버플로우가 발생해
> 프로젝트 구조는 src/ 디렉토리에 있어
> 가능한 원인을 분석하고 수정 방안을 제시해줘

OpenCode는 코드를 스캔하여 잠재적 메모리 누수 지점(미해제 참조, 무한 증가 배열 등)을 식별하고 구체적인 수정 방안을 제시합니다.

5.4 시나리오 4: 로컬 모델 개발 (프라이버시 우선)

민감한 코드를 다루며 클라우드에 업로드하고 싶지 않다면:

BASH 
# 1. Ollama 설치
brew install ollama

# 2. 프로그래밍 전용 모델 가져오기
ollama pull qwen2.5-coder:32b

# 3. OpenCode 시작 후 로컬 모델로 전환
opencode
> /model ollama

이제 모든 추론이 로컬에서 처리되며, 코드가 머신 밖으로 나가지 않습니다.

6. MCP 통합: 도구 체인 확장

OpenCode는 MCP(Model Context Protocol)를 지원하여 외부 도구 및 서비스와 연결할 수 있습니다.

MCP Server 설정

JSON 
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    }
  }
}

설정 후 OpenCode는 GitHub 직접 조작(PR 생성, Issue 확인 등)이 가능해져 기능 범위가 크게 확장됩니다.

7. FAQ

Q1: OpenCode와 Aider는 뭐가 다른가요?

  • OpenCode는 터미널 상호작용 경험과 다중 모델 유연성에 더 중점을 둡니다
  • Aider는 git 통합과 페어 프로그래밍에 더 특화되어 있습니다
  • 둘 다 장점이 있으니, 자신의 워크플로우에 더 맞는 도구를 찾아보세요

Q2: 무료 모델로 충분한가요?

일상적인 개발에는 무료 모델(Qwen2.5-Coder-32B 로컬 배포, DeepSeek 무료 할당량 등)로 충분합니다. 대규모 프로젝트 리팩토링이라면 더 나은 코드 품질을 위해 Claude나 GPT-4o를 권장합니다.

Q3: Windows를 지원하나요?

OpenCode는 공식적으로 Linux와 macOS를 지원합니다. Windows 사용자는 WSL2를 통해 이용할 수 있습니다.

Q4: token 소비를 어떻게 통제하나요?

JSON 
{
  "chat": {
    "maxTokens": 4000,
    "temperature": 0.3
  }
}

maxTokens와 temperature를 낮추면 한 번 대화당 token 사용량을 줄일 수 있지만, 코드 품질에 영향을 줄 수 있습니다.

정리

OpenCode는 2026년 AI 프로그래밍 도구의 중요한 트렌드를 대표합니다: 오픈소스, 모델 독립, 터미널 우선. 특정 벤더의 폐쇄 생태계가 아니라 오픈 도구 체인—가장 적합한 모델, 최저 비용, 최고의 개발 경험을 자유롭게 선택할 수 있습니다.

AI 프로그래밍 도구를 하나만 쓴다면, 2026년에는 OpenCode를 추천합니다. 커뮤니티 활성도, 기능 성숙도, 모델 유연성 면에서 현재 완전히 따라잡는 경쟁자가 없습니다.

🔗 관련 링크: - GitHub: github.com/sst/opencode - 문서: opencode.ai - 유사 도구: Aider, OpenHands