Windows + WSL2(Ubuntu) 기준으로 OpenCode를 “처음부터 끝까지” 설치/실행하는 스텝 바이 스텝 가이드예요

아래는 Windows + WSL2(Ubuntu) 기준으로 OpenCode를 “처음부터 끝까지” 설치/실행하는 스텝 바이 스텝 가이드예요. (터미널에서 TUI/CLI로 쓰는 기준)

---

0) 오늘 목표(완료 상태)

WSL(Ubuntu)에서 아래가 되는 상태로 만들기:

• opencode --version 이 정상 출력
• opencode 실행하면 TUI가 뜸
• TUI에서 /connect로 모델(공급자) 연결 가능
• 프로젝트에서 /init으로 컨텍스트(AGENTS.md 등) 초기화 가능 (opencode.ai)

---

1) WSL2 설치(Windows PowerShell 관리자)

PowerShell(관리자)에서:

wsl --install

설치가 끝나면 재부팅 후, 기본 배포판(보통 Ubuntu) 설치가 진행됩니다.
이미 WSL이 있다면 버전 확인:

wsl -l -v

WSL2인지 확인하세요.

권장: Ubuntu 22.04 또는 24.04 (일부 환경에서 구버전 Ubuntu/터미널 조합이 TUI 문제를 만들 수 있다는 이슈가 보고됨) (GitHub)

---

2) Windows Terminal에서 Ubuntu(WSL) 열기

• Microsoft Store에서 Windows Terminal 설치(이미 있으면 OK)
• Terminal 탭에서 Ubuntu 선택해서 실행

---

3) Ubuntu 기본 업데이트 + 필수 패키지 설치

WSL Ubuntu 안에서:

sudo apt update && sudo apt -y upgrade
sudo apt -y install curl git ca-certificates

---

4) OpenCode 설치 (추천: 공식 설치 스크립트)

WSL Ubuntu에서 아래 실행:

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

이 설치 스크립트 방식은 공식 문서/가이드 흐름에서 안내되는 대표 경로 중 하나예요. (opencode.ai)

---

5) PATH 확인 (명령어가 “없다”는 경우)

설치 후에 바로 확인:

opencode --version

만약 command not found가 뜨면, 설치된 위치가 PATH에 안 잡힌 경우가 많습니다. 아래도 같이 점검:

which opencode
echo $PATH

일반적인 후보 경로들:

• ~/.local/bin
• /usr/local/bin

예: ~/.local/bin이 PATH에 없으면 .bashrc에 추가:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

---

6) 프로젝트 폴더에서 OpenCode 실행(TUI)

원하는 프로젝트로 이동:

cd /path/to/your/project
opencode

---

7) TUI에서 모델(공급자) 연결하기

TUI가 켜지면, 명령 팔레트로 연결:

1. /connect 입력
2. 공급자(OpenAI/Anthropic 등) 선택
3. 안내대로 인증/키 입력

문서상 기본 흐름이 /connect 중심으로 안내됩니다. (opencode.ai)

CLI 방식으로도 가능:

opencode auth login
opencode auth list   # 또는 opencode auth ls

(onedollarvps.com)

---

8) (중요) 프로젝트 컨텍스트 초기화: /init

처음 쓰는 프로젝트라면 TUI에서:

• /init

그러면 프로젝트 구조를 바탕으로 컨텍스트 파일(예: AGENTS.md)이 생성될 수 있고, 팀 단위 사용 시 커밋을 권장하는 흐름이 소개되어 있어요. (Engineering Blog by Dale Seo)

---

9) 가장 자주 쓰는 실행 방식(WSL 기준)

• TUI 실행:
• opencode
• 한 줄 질의(비대화식):
• opencode run "Explain this repository briefly"
• GitHub 연동(레포에 GitHub agent 설치):(opencode.ai)
• opencode github install

---

문제 해결(WSL에서 자주 겪는 것만)

A) opencode 실행했는데 화면이 비거나 렌더링이 이상함

WSL2 Ubuntu에서 “빈 화면” 이슈가 실제로 보고된 사례가 있어요. (GitHub)
이럴 땐 아래 순서로 해결을 많이 합니다:

1. Ubuntu를 22.04/24.04로 올리기(가능하면)
2. Windows Terminal 사용
3. OpenCode 업데이트:
4. opencode upgrade
5. 그래도 안 되면 **CLI(run)**로 우선 사용해 정상 동작 확인:
6. opencode run "hello"

B) Windows에서 “데스크톱 앱”을 원함 (WSL이 아니라)

OpenCode는 데스크톱 앱(Windows exe)도 따로 제공됩니다. 다만 이건 “WSL 터미널 설치”와는 다른 경로예요. (GitHub)

---

원하면, 당신 PC 환경에 맞춰서 딱 맞는 “원클릭 체크리스트”로도 줄게요.
예: WSL Ubuntu 버전, Node 설치 여부, 회사/기관 보안 정책(프록시/방화벽) 같은 조건에 따라 설치 루트가 살짝 달라질 수 있거든요.