AI Tools5분 읽기

OpenCode 실전 가이드: 터미널 AI 코딩 에이전트

오픈소스 터미널 AI 코딩 에이전트 OpenCode(anomalyco/opencode)의 설치부터 로컬 모델 연결, BYOK 설정까지 공식 자료 기반으로 정리한 실전 가이드.

#OpenCode#로컬AI#터미널#오픈소스#AI코딩#Ollama#BYOK#CLI
OpenCode 실전 가이드: 터미널 AI 코딩 에이전트

TL;DR — OpenCode는 MIT 라이선스의 터미널 우선 AI 코딩 에이전트다. 공식 설치 한 줄로 시작하고, Ollama 로컬 모델부터 Claude·OpenAI 같은 클라우드 API(BYOK)까지 75개 이상의 프로바이더를 지원한다. 도구 자체는 무료이며, 비용은 선택한 모델 프로바이더에서만 발생한다.

OpenCode란 무엇인가

anomalyco/opencode는 Neovim 사용자 커뮤니티와 terminal.shop 제작팀이 개발한 오픈소스 AI 코딩 에이전트다. 완성도 높은 TUI(터미널 UI)를 갖추고 있으며, IDE나 브라우저 없이 터미널만으로 AI 코딩 워크플로를 완결할 수 있도록 설계되었다.

⚠️ GitHub의 opencode-ai/opencode 리포지토리는 현재 아카이브(read-only) 상태다. 활성 개발은 anomalyco/opencode에서 진행된다. 설치 명령이나 기능은 빠른 릴리스 주기에 따라 변경될 수 있으므로, 항상 공식 문서와 changelog를 교차 확인하라.

설치: 플랫폼별 공식 명령어

공식 README 기준의 설치 방법은 아래와 같다.

가장 빠른 시작 — 공식 설치 스크립트

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

macOS / Linux (Homebrew)

brew install anomalyco/tap/opencode

Homebrew tap 방식은 brew upgrade로 최신 버전을 유지할 수 있어 장기 운영에 편리하다.

Windows

# Scoop
scoop install opencode

# Chocolatey
choco install opencode

Arch Linux

sudo pacman -S opencode

Docker (CI·격리 환경)

docker run -it --rm ghcr.io/anomalyco/opencode

Node.js / SDK

# CLI 전역 설치
npm install -g opencode-ai

# JS/TS SDK
npm install @opencode-ai/sdk

데스크톱 앱이 필요하다면 macOS는 brew install --cask opencode-desktop, Windows는 공식 .exe 설치 파일을 제공한다.

두 가지 에이전트 모드

OpenCode는 용도에 따라 두 모드를 제공한다.

모드목적접근 권한
build개발 작업, 코드 생성·수정 (기본값)전체 접근
plan코드베이스 분석, 탐색, 설계 검토읽기 전용

plan 모드는 파일을 수정하지 않는다. 대형 코드베이스를 먼저 파악하거나, PR 리뷰 전 영향 범위를 점검할 때 유용하다.

로컬 모델 연결: Ollama·LM Studio·llama.cpp

OpenCode는 75개 이상의 프로바이더를 지원하며, Ollama·LM Studio·llama.cpp를 통한 로컬 추론을 공식 지원한다. API 비용 없이 운영하고 싶다면 로컬 모델이 핵심이다.

하드웨어 가이드라인

아래 수치는 유사 에이전트(Cline)의 공개 가이드(morphllm.com)를 참고한 것이며, OpenCode도 동일한 Ollama 기반 모델 규격에서 동작한다.

모델 규모권장 RAM/VRAM
소형·양자화 모델16–32 GB
중형 코딩 모델32–64 GB
대형 모델64 GB 이상

24 GB GPU 또는 32 GB Mac 환경에서는 Qwen 계열 27B 모델을 4비트 양자화(약 16–19 GB)로 실행할 수 있다.

로컬 모델 선택 팁

커뮤니티에서는 Qwen 2.5 Coder 32B가 많은 코딩 벤치마크에서 GPT-4o와 근접한 성능을 보인다고 평가하지만, 이는 커뮤니티 컨센서스이며 OpenCode 공식 측정값은 아니다. 모델 선택 전 본인의 하드웨어 스펙과 작업 규모를 먼저 확인하라.

BYOK: 클라우드 API 연결

로컬 GPU가 부족하거나 대형 코드베이스를 다뤄야 할 때는 클라우드 API를 키(BYOK, Bring Your Own Key) 방식으로 연결한다. OpenCode 설정 파일은 ~/.config/opencode/에 위치하며, 모델을 직접 지정할 수 있다.

공식 문서 예시(dev.to)에 따르면 다음과 같은 모델 조합이 소개된다.

  • 일상 코딩·버그 수정·PR 리뷰 → claude-opus-5
  • 대형 코드베이스·멀티 파일 리팩터·긴 에이전트 워크플로 → kimi-k3

클라우드 API를 사용하면 각 프로바이더(Anthropic, OpenAI, Gemini 등)의 요금이 발생한다. OpenCode 자체는 MIT 라이선스 무료 오픈소스이므로 도구 비용은 없다.

비용 구조 한눈에 보기

운영 방식OpenCode 비용모델 비용필요 조건
로컬 모델 (Ollama 등)무료없음충분한 GPU/RAM
클라우드 API (BYOK)무료프로바이더 요금API 키

개발자·크리에이터가 주목해야 할 이유

터미널 중심 개발 환경을 선호하거나, IDE 플러그인 의존 없이 AI 보조 코딩을 운영하고 싶은 경우 OpenCode는 유력한 선택지다. Docker 지원으로 CI 파이프라인에 통합할 수 있고, JS/TS SDK를 통해 커스텀 자동화 스크립트 안에서 에이전트를 호출하는 것도 가능하다.

단, 프로젝트는 빠른 릴리스 주기를 가지므로 명령어·설정 형식이 바뀔 수 있다. 운영 전 anomalyco/opencode 공식 README와 changelog를 반드시 확인하라.

참고 자료

커버 이미지: Peter Shanks from Hobart, Australia · CC BY 2.0. 자료 이미지이며 제품 화면은 아닙니다. 크기 조정 및 WebP 변환.

공유하기Twitter / X