OpenCode 설치하고 시작하기

1단계: 설치

# 권장(macOS, Linux, WSL)
curl -fsSL https://opencode.ai/install | bash

# npm, 플랫폼 공통
npm install -g opencode-ai

# Homebrew
brew install anomalyco/tap/opencode

Windows에서는 공식 문서가 Chocolatey와 Scoop을 안내합니다. 이미 WSL을 쓰고 있다면 그 안에서 리눅스용 명령을 그대로 쓰면 됩니다. Docker 경로는 에이전트를 격리된 환경에서 돌려야 할 때를 위한 것인데, 사내 환경에서는 바로 그 조건이 있어야 승인이 나는 경우가 많습니다.

2단계: 제공자 연결

OpenCode는 제공자에 묶여 있지 않고, 공식 문서는 API 키를 통해 어떤 LLM 제공자와도 동작한다고 설명합니다. 실무적으로는 첫 세션 전에 유효한 키가 하나 필요하다는 뜻입니다. 어떤 모델이 어떤 작업에 맞는지 직접 고르기 번거롭다면 문서가 권하는 "OpenCode Zen"을 쓰면 됩니다. 선별·사전 검증된 모델 묶음입니다.

3단계: 첫 세션

프로젝트 디렉터리로 이동해 거기서 OpenCode를 시작합니다. 첫 작업은 작고 검증 가능한 것으로 잡으세요. 파일 하나를 설명하게 하거나, 테스트를 하나 추가하거나, 함수 이름을 바꾸는 정도. 그러면 감당 가능한 크기의 diff로 모델 선택과 컨텍스트가 맞는지 확인한 뒤 큰 변경으로 넘어갈 수 있습니다.

잘 안 될 때

• 설치 후 명령을 못 찾는 경우: 설치 스크립트가 실행 파일을 넣은 디렉터리가 PATH에 있어야 합니다. 터미널을 새로 열거나 셸 설정을 다시 불러오세요.
• 인증 실패: 키가 올바른 제공자에서 발급됐는지, 그쪽 잔액이 남아 있는지 확인하세요. OpenCode는 잔액이 빈 계정과 잘못된 키를 구분해 알려 주지 못합니다.
• 답이 맥락 없이 나올 때: 에이전트는 자기가 읽은 것만 압니다. 프로젝트 전체를 알 것이라 기대하지 말고 파일과 디렉터리를 명시하세요.
• 비용이 과하게 나올 때: 더 작은 모델을 고르고 컨텍스트를 제한하세요. 가장 비싼 세션은 거의 항상 너무 많이 읽은 세션입니다.

그다음은

첫 세션이 돌기 시작하면 볼 것이 둘 있습니다. 외부 데이터와 도구에 닿게 해 주는 MCP 연결, 그리고 아직 Claude Code와 저울질 중이라면 그 둘의 직접 비교입니다. 둘 다 한국어 문서로 연결해 두었습니다.