본문으로 바로가기
Zyss

News

06/02/2026 · zyss

opencode 설치방법부터 단계별 안내: 지원 모델과 주의사항 정리

opencode 공식 홈페이지에서 소개하는 opencode는 터미널, IDE, 데스크톱에서 사용할 수 있는 오픈소스 AI 코딩 에이전트입니다. 쉽게 말하면, 명령어 창에서 AI에게 코드 설명, 오류 분석, 기능 추가를 부탁할 수 있는 도구입니다.

아래 순서는 처음 쓰는 사람이 바로 따라 할 수 있도록 설치 방법부터 시작합니다. 설치한 뒤 모델을 연결하고, 지원 모델과 주의사항을 확인하면 됩니다.

1. opencode 설치방법

opencode 공식 문서 기준으로 가장 쉬운 설치 방법은 설치 스크립트를 사용하는 것입니다.

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

Node.js를 쓰는 경우에는 npm으로 설치할 수도 있습니다.

npm install -g opencode-ai

Bun을 사용하는 경우에는 아래 명령어를 사용할 수 있습니다.

bun install -g opencode-ai

macOS 또는 Linux에서 Homebrew를 쓴다면 아래 명령어를 사용할 수 있습니다.

brew install anomalyco/tap/opencode

2. 설치 확인하기

설치가 끝나면 아래 명령어로 opencode가 실행되는지 확인합니다.

opencode

Node.js 방식으로 설치했다면 아래 명령어로 Node.js와 npm 버전도 확인할 수 있습니다.

node -v
npm -v

Windows에서는 공식 문서가 WSL 사용을 권장합니다. WSL은 Windows 안에서 Linux처럼 명령어를 실행하게 해주는 환경입니다.

3. 모델 제공자 연결하기

opencode는 설치만으로 AI 모델이 바로 붙는 도구가 아닙니다. 사용할 모델 제공자를 연결해야 합니다. opencode를 실행한 뒤 아래 명령어를 입력합니다.

/connect

여기서 OpenAI, Google, GitHub Copilot, OpenCode Go 같은 제공자를 고를 수 있습니다. 제공자 목록은 opencode 정책과 각 모델 회사의 정책에 따라 바뀔 수 있습니다. API 키를 입력하라는 화면이 나오면 해당 제공자에서 발급받은 키를 넣습니다.

4. 사용 가능 조건 확인하기

opencode 자체는 오픈소스 도구이지만, 실제로 AI 모델을 쓰려면 모델 제공자의 계정, 구독, API 키, 또는 opencode Zen 같은 연결 방식이 필요할 수 있습니다.

무료 계정으로 시도하면 모델 선택이나 사용량에서 제한이 생길 수 있습니다. 설치 전에 내가 사용할 모델 제공자가 무엇인지 먼저 정하는 것이 좋습니다.

5. 지원 모델 정리

opencode 모델 문서에 따르면 opencode는 AI SDK와 Models.dev를 통해 75개 이상의 제공자를 지원합니다. 공식 문서가 예시로 든 추천 모델은 다음과 같습니다.

  • GPT 계열 모델
  • GPT Codex 계열 모델
  • DeepSeek V4 Flash
  • DeepSeek V4 Flash Free
  • Nemotron 3 Super Free
  • Big Pickle
  • MiniMax 계열 모델
  • Gemini 계열 모델
  • 로컬 모델

Claude 계열은 최근 지원·인증 정책 변동으로 opencode에서 안정적으로 사용할 수 없거나 목록에서 제외될 수 있습니다. 그래서 이 글에서는 Claude를 지원 모델 목록과 추천 모델 설명에서 제외했습니다.

GitHub 저장소 문서와 Providers 문서에는 여러 제공자가 예시로 정리되어 있지만, 실제 사용 가능 여부는 opencode 버전, 인증 방식, 각 모델 제공자의 정책에 따라 달라질 수 있습니다.

6. 무료·실험 모델 먼저 이해하기

OpenCode Zen 문서는 Big Pickle, DeepSeek V4 Flash Free, Nemotron 3 Super Free 같은 무료 모델을 별도로 안내합니다. 다만 무료 모델은 대부분 제한된 기간 동안 제공되며, 피드백 수집과 모델 개선을 목적으로 운영될 수 있습니다.

  • Nemotron 3 Super Free: NVIDIA Nemotron 3 Super 기반의 무료 모델입니다. NVIDIA 연구 문서에 따르면 Nemotron 3 Super는 120B 총 파라미터, 12B 활성 파라미터 구조의 MoE 모델이며 긴 문맥 처리와 에이전트 작업을 목표로 합니다. 무료 제공은 테스트 성격이 강하므로 민감한 코드는 넣지 않는 것이 좋습니다.
  • Big Pickle: OpenCode Zen에서 제한된 기간 무료로 제공되는 stealth 모델입니다. 이름 그대로 제공사가 명확히 드러나지 않는 실험형 모델로 볼 수 있습니다. 무료 기간 동안 수집된 데이터가 모델 개선에 쓰일 수 있으니 비공개 코드나 고객 정보는 넣지 않는 것이 좋습니다.
  • DeepSeek V4 Flash Free: DeepSeek V4 Flash의 무료 제공 모델입니다. 긴 문맥과 코딩·추론 작업에 맞춘 선택지로 볼 수 있지만, 무료 모델은 속도 제한, 요청 제한, 일시 중단이 생길 수 있습니다.
  • MiMo-V2.5 Free: OpenCode Zen 무료 목록에 포함된 모델입니다. 다른 무료 모델처럼 제한된 기간 동안 제공될 수 있으며, 안정성보다 테스트와 피드백 목적에 가깝게 보는 것이 안전합니다.

무료 모델은 “돈이 전혀 들지 않는 영구 모델”이라는 뜻이 아닐 수 있습니다. 무료 기간, 요청 제한, 데이터 처리 방식, 사용 가능 여부가 바뀔 수 있으므로 실제 사용 전 모델 목록과 개인정보 안내를 확인해야 합니다.

7. 모델별 특징 쉽게 보기

모델 성능과 지원 여부는 자주 바뀝니다. 아래 내용은 Claude 계열을 제외하고 선택 기준을 쉽게 잡기 위한 설명입니다. 실제 최신 목록은 모델 문서에서 확인해야 합니다.

  • GPT Codex 계열: 코딩 작업을 목적으로 고르기 좋은 모델입니다. 코드 수정, 테스트 작성, 파일 단위 작업에 우선 후보로 볼 수 있습니다.
  • GPT 계열: 넓은 범용 작업과 추론 작업에 적합한 선택지입니다. 복잡한 요구사항을 정리하거나 큰 구조를 설계할 때 후보가 됩니다.
  • Gemini 계열: Google 계정이나 Google AI 환경과 함께 쓰는 경우 후보가 됩니다. 긴 문맥을 다루는 작업에서 선택지로 볼 수 있습니다.
  • 로컬 모델: Ollama, LM Studio, llama.cpp 같은 환경과 함께 쓰면 내 컴퓨터에서 모델을 실행할 수 있습니다. 대신 컴퓨터 성능이 중요합니다.

8. 모델 선택하기

모델 제공자를 연결한 뒤에는 아래 명령어로 사용할 모델을 고릅니다.

/models

기본 모델을 설정하려면 opencode 설정 파일에서 모델 ID를 지정할 수 있습니다. 모델 ID는 보통 provider_id/model_id 형식입니다.

{
  "$schema": "https://opencode.ai/config.json",
  "model": "opencode/gpt-5.1-codex"
}

9. 프로젝트 폴더에서 시작하기

작업할 코드 폴더로 이동한 뒤 opencode를 실행합니다.

cd /path/to/project
opencode

특정 폴더를 바로 지정해서 실행할 수도 있습니다.

opencode -c /path/to/project

프로젝트를 처음 분석하게 하려면 opencode 안에서 아래 명령어를 실행합니다.

/init

이 명령은 프로젝트를 분석하고 AGENTS.md 파일을 만들 수 있습니다. 공식 문서는 이 파일을 Git에 커밋하는 것을 권장합니다.

10. 주의사항

  • API 키 보안: API 키는 비밀번호처럼 다룹니다. 절대 공개 저장소나 채팅에 올리지 않습니다.
  • 무료 모델은 임시 제공일 수 있음: Big Pickle, DeepSeek V4 Flash Free, Nemotron 3 Super Free 같은 모델은 제한된 기간 동안 무료로 제공될 수 있습니다.
  • 민감한 정보 금지: 무료·실험 모델에는 고객 정보, 비밀번호, 비공개 소스코드, 영업 비밀을 넣지 않는 것이 안전합니다.
  • 요청 제한: 무료 모델은 속도 제한, 일일 요청 제한, 일시 중단이 생길 수 있습니다.
  • 비용 확인: 모델 제공자에 따라 API 사용료가 발생할 수 있습니다.
  • 무료 계정 제한: 무료 계정은 사용량, 모델, 속도 제한이 있을 수 있습니다.
  • Claude 지원 변동: Claude 계열은 opencode에서 제외되거나 인증 방식이 제한될 수 있으므로 최신 모델 목록을 먼저 확인합니다.
  • 코드 백업: AI가 파일을 수정하기 전에 Git 커밋을 해두는 것이 좋습니다.
  • 계획 먼저: 큰 작업은 바로 수정시키지 말고 먼저 계획을 만들게 합니다.
  • Windows: Windows에서는 WSL 사용이 권장됩니다.
  • 개인정보: opencode 공식 홈페이지는 코드와 컨텍스트 데이터를 저장하지 않는다고 안내하지만, 연결한 모델 제공자의 정책도 함께 확인해야 합니다.

11. 처음 써볼 프롬프트

처음에는 프로젝트 설명을 부탁하는 것이 안전합니다.

이 프로젝트의 폴더 구조를 보고, 어떤 기능을 하는지 초등학생도 이해할 수 있게 설명해줘.

수정 작업을 맡기기 전에는 계획을 먼저 요구합니다.

이 기능을 추가하기 전에 수정 계획을 먼저 단계별로 작성해줘. 아직 파일은 수정하지 마.

문제가 생겼을 때는 원인 분석부터 시킵니다.

현재 오류의 원인을 분석하고, 어떤 파일을 확인해야 하는지 먼저 알려줘.

정리

  1. opencode를 먼저 설치합니다.
  2. opencode 명령어로 실행을 확인합니다.
  3. /connect로 모델 제공자를 연결합니다.
  4. /models로 모델을 선택합니다.
  5. 프로젝트 폴더에서 작은 요청부터 시작합니다.

opencode는 설치보다 모델 연결이 중요합니다. 어떤 모델을 쓸지 먼저 정하면 훨씬 쉽게 시작할 수 있습니다.

출처

댓글 남기기