[opencode 12일 집중 — 터미널 네이티브 AI 코딩 에이전트 완전 정복] 2/12화: opencode 설치부터 첫 세션까지, 5분 완전 가이드

이 글은 「opencode 12일 집중」 시리즈의 2일차로, opencode 설치부터 첫 세션 실행까지를 5분 안에 끝내는 실전 가이드입니다.

어제 1일차에서 opencode가 무엇인지, 왜 벤더 락인 없는 터미널 AI 코딩 에이전트가 지금 주목받는지 살펴봤습니다. 오늘은 말 대신 손을 움직입니다. 설치하고, 인증하고, 첫 대화를 나누는 것까지 — 진짜로 5분이면 됩니다.

오늘의 핵심 3가지

• 설치 방법 5가지 — curl 원라인, npm, Homebrew, Scoop/Choco, Arch AUR. 환경에 맞는 걸 하나만 고르면 됩니다.
• 인증 한 번 — opencode auth login 한 줄이면 API 키 등록 완료. BYOK니까 내 키, 내 모델입니다.
• 첫 세션 /init — 프로젝트 디렉터리에서 /init 한 번 치면 AGENTS.md가 생성되고, opencode가 코드베이스를 이해하기 시작합니다.

설치 — 5가지 방법 한눈에 비교

opencode는 단일 바이너리로 배포됩니다. Go로 작성된 TUI 애플리케이션이라 Python이나 Node.js 런타임이 필수는 아닙니다. 다만 npm을 통한 배포도 지원하므로, 이미 Node 환경이 갖춰져 있다면 그쪽이 편할 수 있습니다. 본인 환경에 맞는 방법 하나만 고르세요.

1. curl 원라인 스크립트 (macOS / Linux 추천)

가장 빠른 방법입니다. 터미널을 열고 한 줄만 붙여넣으세요.

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

스크립트가 OS와 아키텍처를 자동 감지해서 적절한 바이너리를 ~/.local/bin에 내려줍니다. 설치 후 셸을 새로 열거나 source ~/.bashrc(또는 ~/.zshrc)를 실행하면 바로 opencode 명령어를 쓸 수 있습니다.

장점: 의존성 제로, 가장 빠름, 공식 권장 방법
단점: 자동 업데이트 없음 — 새 버전이 나오면 같은 명령어를 다시 실행해야 합니다

2. npm 글로벌 설치

Node.js 18+ 환경이 이미 있다면 익숙한 방식으로 설치할 수 있습니다.

npm install -g opencode

또는 npx로 설치 없이 바로 실행할 수도 있습니다.

npx opencode

장점: Node 개발자에게 익숙, npm update로 업데이트 간편
단점: Node.js 런타임 필요, 전역 설치 시 권한 이슈 가능

3. Homebrew (macOS / Linux)

macOS 사용자라면 Homebrew가 가장 자연스럽습니다.

brew install opencode

장점: brew upgrade로 자동 업데이트, macOS 생태계와 자연스러운 통합
단점: Homebrew 자체 설치가 선행 필요

4. Scoop / Chocolatey (Windows)

Windows 사용자를 위한 패키지 매니저 설치입니다. WSL 없이 네이티브 Windows에서 구동할 때 씁니다.

# Scoop
scoop install opencode

# Chocolatey
choco install opencode

장점: Windows 네이티브 환경 지원, 패키지 매니저 업데이트 통합
단점: WSL을 이미 쓰고 있다면 curl 스크립트가 더 간단

이 시리즈에서는 macOS/Linux 기준으로 명령어를 보여주되, Windows는 WSL 환경을 가정합니다. 네이티브 Windows에서 돌리는 분은 Scoop 또는 Chocolatey로 설치하시면 동일하게 따라올 수 있습니다.

5. Arch Linux (AUR)

Arch 사용자라면 AUR 헬퍼를 통해 설치합니다.

# yay 사용 시
yay -S opencode

# paru 사용 시
paru -S opencode

장점: 시스템 패키지 매니저와 완전 통합, 롤링 업데이트
단점: AUR 빌드 시간 소요

어떤 방법을 골라야 할까?

결정이 안 선다면 이렇게 가세요.

• macOS → Homebrew가 있으면 brew install opencode, 없으면 curl 스크립트
• Linux → curl 스크립트 (가장 빠름)
• Windows + WSL → WSL 안에서 curl 스크립트
• Windows 네이티브 → Scoop 또는 Chocolatey
• 이미 Node 쓰는 프로젝트 → npm 글로벌 설치

어떤 방법이든 결과는 동일합니다. opencode라는 명령어가 터미널에서 동작하면 성공입니다.

설치 확인 — 버전 체크

설치가 끝났으면 확인부터 합시다.

opencode version

버전 번호가 출력되면 설치 완료입니다. 만약 command not found가 뜬다면 두 가지를 확인하세요.

• PATH 등록 여부: curl 스크립트로 설치했다면 ~/.local/bin이 PATH에 포함되어 있는지 확인합니다. echo $PATH | tr ':' '\n' | grep local로 체크.
• 셸 재시작: 설치 직후에는 셸을 새로 열어야 PATH가 반영됩니다. exec $SHELL 또는 터미널 탭을 새로 여세요.

첫 인증 — opencode auth login

opencode는 BYOK(Bring Your Own Key) 모델입니다. 1일차에서 이야기한 것처럼, 여러분이 가진 API 키를 직접 등록해서 사용합니다. opencode 자체가 과금하는 것은 없습니다.

API 키 방식 (BYOK)

가장 일반적인 방식입니다. Anthropic, OpenAI, Google 등 원하는 프로바이더의 API 키를 등록합니다.

opencode auth login

이 명령어를 실행하면 대화형 프롬프트가 뜹니다. 프로바이더를 선택하고 API 키를 붙여넣으면 됩니다. 키는 로컬 설정 파일에 안전하게 저장됩니다.

또는 환경변수로 직접 설정할 수도 있습니다. .bashrc나 .zshrc에 추가해두면 영구 적용됩니다.

# Anthropic Claude를 사용하는 경우
export ANTHROPIC_API_KEY="sk-ant-..."

# OpenAI를 사용하는 경우
export OPENAI_API_KEY="sk-..."

# Google Gemini를 사용하는 경우
export GEMINI_API_KEY="..."

75개 이상의 프로바이더를 지원하므로 AWS Bedrock, Azure OpenAI, OpenRouter 등도 가능합니다. 어떤 프로바이더를 쓸지, 비용 시뮬레이션은 어떻게 하는지는 내일 3일차에서 상세히 다룹니다.

OAuth 방식 (구독 기반)

일부 프로바이더는 API 키 대신 OAuth 인증을 지원합니다. 이 경우 opencode auth login 실행 시 브라우저가 열리며 로그인 플로우를 거칩니다. 구독 플랜에 포함된 크레딧을 사용하는 방식이라 별도 API 키 관리가 필요 없다는 장점이 있습니다.

어떤 방식이든, 인증이 완료되면 opencode는 해당 프로바이더의 모델을 바로 사용할 수 있습니다.

opencode 첫 세션 시작하기

설치하고 인증했으면 이제 진짜 써볼 차례입니다. opencode는 프로젝트 디렉터리 기반으로 동작합니다. 터미널에서 작업할 프로젝트 폴더로 이동한 뒤 실행하는 것이 기본 흐름입니다.

1단계: 프로젝트 디렉터리로 이동

# 기존 프로젝트가 있다면 해당 폴더로
cd ~/projects/my-app

# 연습용이라면 빈 폴더를 하나 만들어도 됩니다
mkdir ~/opencode-playground && cd ~/opencode-playground
git init

opencode는 Git 저장소를 인식합니다. .git 디렉터리가 있으면 프로젝트 루트를 자동 감지하고, 변경 이력을 활용한 되돌리기(/undo) 기능도 사용할 수 있습니다. 연습용 폴더라도 git init을 해두는 걸 권합니다.

2단계: opencode 실행

opencode

이 한 단어면 TUI(Terminal User Interface)가 열립니다. Go의 Bubble Tea 프레임워크로 만들어진 인터페이스가 터미널 전체를 채우며, 하단에 입력창이 나타납니다. 마우스 클릭이 아닌 키보드로 모든 것을 제어합니다.

처음 실행하면 모델 선택 화면이 나올 수 있습니다. 등록된 API 키에 맞는 모델 목록이 표시되며, 원하는 모델을 선택하면 됩니다. 나중에 언제든 바꿀 수 있으니 일단 기본 추천 모델로 시작하세요.

3단계: /init으로 AGENTS.md 생성

TUI가 열리면 가장 먼저 할 일이 있습니다. 입력창에 이렇게 치세요.

/init

이 명령 하나로 opencode가 프로젝트 루트에 AGENTS.md 파일을 자동 생성합니다. AGENTS.md는 opencode의 컨텍스트 매니저 — 이 프로젝트가 어떤 프로젝트인지, 어떤 기술 스택을 쓰는지, 코딩 컨벤션은 무엇인지를 AI에게 알려주는 설정 파일입니다.

기존 프로젝트에서 /init을 실행하면 opencode가 디렉터리 구조, package.json, pyproject.toml 등 프로젝트 메타데이터를 읽어서 초기 AGENTS.md를 자동으로 채워줍니다. 빈 프로젝트라면 최소한의 템플릿이 생성됩니다.

AGENTS.md의 상세한 활용법은 7일차에서 깊이 다루지만, 지금은 이것만 기억하세요 — /init은 opencode와 프로젝트의 첫 악수입니다.

첫 대화 — 실제로 뭘 시켜볼까

AGENTS.md까지 만들었으면, 이제 opencode에게 무언가를 요청해봅시다. 아래는 설치 직후 바로 시도할 수 있는 대화 예시입니다.

# TUI 입력창에 자연어로 입력
이 프로젝트의 구조를 설명해줘

opencode가 디렉터리를 탐색하고 파일들을 읽어서 프로젝트 구조를 요약해줍니다. 기존 프로젝트라면 놀라울 정도로 정확한 요약을 받아볼 수 있습니다.

조금 더 실용적인 것을 시도해봅시다.

# 빈 프로젝트에서 시도
Python으로 간단한 TODO CLI 앱을 만들어줘. argparse로 add, list, done 커맨드를 지원하게.

opencode는 현재 Build 모드(기본값)로 동작합니다. 파일을 생성하고, 코드를 작성하고, 필요하면 수정까지 직접 합니다. 코드를 쓰기 전에 계획만 먼저 보고 싶다면 Tab 키를 눌러 Plan 모드로 전환할 수 있습니다. Plan과 Build 모드의 상세한 활용법은 5일차에서 다룹니다.

opencode가 파일을 생성하거나 수정할 때는 변경 사항을 diff 형태로 보여주며, 승인 여부를 묻습니다. 처음에는 하나씩 확인하며 익숙해지세요.

유용한 기본 단축키 3개

TUI 안에서 바로 쓸 수 있는 단축키를 세 개만 기억해두세요. 전체 단축키 치트시트는 4일차에서 정리합니다.

• Tab — Plan 모드 ↔ Build 모드 전환. 코드를 바로 쓸지, 계획만 세울지 토글합니다.
• @ — 파일 퍼지 검색. 프로젝트 내 파일을 빠르게 찾아서 컨텍스트에 추가합니다.
• Ctrl+X — leader 키. 이 키를 누른 뒤 후속 키를 입력하면 다양한 명령을 실행할 수 있습니다.

5분 설치 요약 — 복사·붙여넣기 풀 시퀀스

여기까지의 모든 과정을 한 번에 정리합니다. macOS/Linux 기준, 터미널에서 순서대로 실행하세요.

# 1. 설치 (curl 원라인)
curl -fsSL https://opencode.ai/install | bash

# 2. 셸 재시작 (PATH 반영)
exec $SHELL

# 3. 설치 확인
opencode version

# 4. 인증 (대화형 — 프로바이더 선택 후 API 키 입력)
opencode auth login

# 5. 프로젝트 디렉터리로 이동
cd ~/projects/my-app    # 또는 원하는 프로젝트 경로

# 6. opencode 실행
opencode

# 7. TUI 안에서 /init 입력 → AGENTS.md 생성
# 8. 자연어로 첫 요청 입력 → 끝!

8단계지만, 실제로 손이 가는 시간은 5분이 채 안 됩니다. 설치 스크립트 다운로드가 대부분이고, 나머지는 복사·붙여넣기입니다.

Gotcha 미니 코너 — PATH 함정

증상: curl 스크립트로 설치했는데 opencode: command not found가 뜬다.

원인: 설치 스크립트가 바이너리를 ~/.local/bin에 놓았지만, 이 경로가 시스템 PATH에 등록되어 있지 않은 경우입니다. 특히 Ubuntu의 기본 .bashrc는 ~/.local/bin이 존재할 때만 PATH에 추가하는 조건부 로직을 갖고 있어서, 해당 디렉터리가 원래 없었다면 설치 스크립트가 디렉터리를 새로 만들어도 이미 로딩된 셸에는 반영되지 않습니다.

해결:

# 방법 1: 셸을 완전히 새로 시작
exec $SHELL

# 방법 2: PATH에 수동 추가 (영구 적용)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# 방법 3: 즉시 확인 (임시)
~/.local/bin/opencode version

Homebrew나 npm으로 설치했다면 이 문제는 거의 발생하지 않습니다. 패키지 매니저가 PATH 관리를 대신해주기 때문입니다. curl 스크립트의 속도와 간편함에는 이 한 가지 함정이 따라오니 기억해두세요.

설치 후 체크리스트

오늘 작업이 제대로 됐는지 아래 네 가지를 확인하세요.

• ☑️ opencode version이 버전 번호를 출력하는가
• ☑️ opencode auth login으로 최소 하나의 프로바이더를 등록했는가
• ☑️ 프로젝트 디렉터리에서 opencode를 실행하면 TUI가 뜨는가
• ☑️ /init으로 AGENTS.md가 생성되었는가

네 가지 모두 체크되면, opencode를 사용할 준비가 완료된 것입니다. 오늘은 여기까지입니다 — 2일차치고 충분히 많은 걸 했습니다.

내일 예고

3일차: BYOK 전략 — API 키 vs 구독, 어떤 모델을 골라야 할까? opencode가 지원하는 75개 이상의 프로바이더 중 실무에서 쓸 만한 모델을 추리고, 월간 비용 시뮬레이션 표를 만들어봅니다. 같은 질문을 던졌을 때 모델마다 응답 품질이 얼마나 달라지는지, 직접 비교합니다.

---