기준 버전: opencode1.18.30· 문서 확인일2026-09-13
이 글은 Windows 기준이에요. 버전이 다르면 화면과 명령이 조금씩 다를 수 있어요.
앞선 글 「AI 비서 여러 명에게 일 시키기 — herdr 30분 실습」에서
opencode --version을 쳤는데 command not found가 나와 멈추셨죠? 걱정 마세요. 설치가 한 번에 안 되는 건 아주 흔한 일이에요. 오늘 목표는 딱 하나예요. opencode를 설치하고, 켜서 인사 한 번 시키기.0. 도입: 설치에서 막히셨나요?
설치는 "파는 곳"이 여러 군데라서 헷갈려요. Windows에는 원래
winget(윙겟, Windows 기본 앱 설치 도구)이라는 게 있어서 많은 분이 이걸 먼저 떠올려요. 그런데 확인해 보니 opencode는 공식 문서에 winget 설치 방법이 없고, winget 패키지도 확인되지 않았어요. 그래서 이 글은 공식 문서에 실제로 있는 방법으로 안내해요.⚠️ 인터넷에winget install opencode가 돌아다녀도, 이 글 기준(2026-09-13)으로는 공식 지원이 아니에요. 될 수도 있지만 보장되지 않으니 기본 길로 안내하지 않아요.
오늘은 기본 추천(Scoop) 한 길만 따라오면 돼요. 다만 Scoop은 정책 설정 1회 + 원격 설치 스크립트 실행이 필요한 방법이라, 이게 부담되면 3-4 수동 바이너리(정책 변경 불필요)나 3-3 npm(Node가 있다면 한 줄)으로 가도 돼요. 막히면 대안으로 내려가면 되고, 컴퓨터는 안 망가져요.
1. 설치 전 5분 점검
민수님 같은 분(Windows 11 노트북, PowerShell은 열어봤지만 관리자 권한은 낯섦)을 기준으로 해요.
1-1. 내 Windows 버전 확인 — GUI 경로
시작 → 설정 → 시스템 → 정보 를 클릭하면 "Windows 사양"이 보여요. Windows 10 또는 Windows 11이면 충분해요.⚠️ opencode 공식 문서에는 최소 Windows 버전이 명시돼 있지 않아요. Windows 10/11이면 무리 없이 따라올 수 있어요(32비트는 지원 자산이 없으니 64비트여야 해요).
1-2. PowerShell 열기
시작 버튼을 누르고 PowerShell이라고 입력한 뒤, **"Windows PowerShell"**을 클릭해요. 파란(또는 검은) 글자 창이 열리면 성공이에요.💡 "관리자 권한으로 실행"은 꼭 필요한 때만 눌러요. 관리자 권한은 "이 컴퓨터에 프로그램 설치를 허용"하는 버튼이라, 습관적으로 누르면 좋지 않아요.
1-3. 준비물 요약
| 준비물 | 필요한가 | 확인 방법 |
|---|---|---|
| Windows 10/11 (64비트) | 필수 | 설정 → 시스템 → 정보 |
| PowerShell | 필수 | 시작에서 "PowerShell" 검색 |
| 인터넷 연결 | 필수 | — |
| 관리자 권한 | Scoop 경로는 불필요 | — |
| Node.js | npm 경로만 필요 | node --version |
2. 내게 맞는 설치 방법 고르기
공식 문서에 있는 Windows 설치 방법은 이래요.
| 방법 | 명령 | 난이도 | 전제조건 | 추천 대상 | 관리자 권한 |
|---|---|---|---|---|---|
| Scoop (기본 추천) | scoop install opencode | ★★☆ | Scoop 부트스트랩 1회 | 대부분의 비개발자 | 불필요(사용자 폴더 설치) |
| WSL (공식 권장) | wsl --install 후 리눅스에서 설치 | ★★★★ | WSL2 | 성능·호환 최우선 | WSL 설치 시 필요 |
| npm | npm install -g opencode-ai | ★★☆ | Node.js LTS | Node가 이미 있는 분 | 보통 불필요 |
| 수동 바이너리 | Releases에서 zip 해제 → PATH | ★★★★ | 없음(우회용) | 위 방법이 모두 막힘 | PATH 편집 방식에 따라 |
| Chocolatey | choco install opencode | ★★★ | Chocolatey 별도 설치 | 관리자 권한 있는 개인 PC | 필요 |
| Mise | mise use -g github:anomalyco/opencode | ★★★ | mise | 개발 도구 익숙 | 상황에 따라 |
| Docker | docker run -it --rm ghcr.io/anomalyco/opencode | ★★★★ | Docker Desktop | 개발자 | 필요 |
⚠️ winget은 위 공식 목록에 없어요. 확인일 기준 winget 패키지도 검색되지 않았어요.
기본 추천 결정 문장
고민되면 Scoop부터. 관리자 권한 없이 내 사용자 폴더에 설치되고, 공식 문서에도 있는 방법이에요.
다만 Scoop은 ① 실행 정책 설정 1회 + ②get.scoop.sh원격 설치 스크립트 실행이 필요해요. 이게 부담되면 수동 바이너리(정책 변경·원격 스크립트 불필요)가 가장 조용한 길이고, Node.js가 이미 있으면 npm이 한 줄로 끝나는 최단 경로예요.
Scoop이 어렵거나 막히면 → npm(Node.js가 이미 있을 때), 둘 다 안 되면 → 수동 바이너리로 내려가세요.
그림 1. 설치 방법 선택 결정 트리
그림 1 설명: 세 번만 물어보면 내 설치 방법이 정해져요. 대부분은 "Scoop 또는 WSL" 두 갈래에서 끝나요. winget은 공식 지원이 아니라 트리에서 뺐어요.
3. 설치하기 (기본 추천: Scoop 경로)
3-1. Scoop 준비 (처음 한 번만)
먼저 PowerShell에서 실행 정책을 "내 계정만" 부드럽게 풀어요.
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
- 왜 치나요: 스크립트 실행을 허용하는 안전한 범위 설정이에요.
CurrentUser는 "내 계정에만"이라는 뜻이라 컴퓨터 전체를 건드리지 않아요. - 이렇게 나오면 성공: 실행 규칙을 묻는 안내가 나오면
Y를 입력해요. 에러 없이 프롬프트로 돌아오면 성공이에요. - 참고:
-Scope CurrentUser는 원칙적으로 관리자 권한이 필요 없어요. 만약 관리자 권한을 요구하면 회사/학교 정책일 수 있으니 6장 F를 확인하세요.
이어서 Scoop을 설치해요.
irm get.scoop.sh | iex
💡get.scoop.sh는 Scoop 공식 부트스트랩 주소예요(ScoopInstaller가 배포).irm ... | iex는 원격 스크립트를 바로 실행하는 방식이라 낯설 수 있는데, 이 주소에서 받는 건 공식 절차예요. 그래도 부담되면 3-4 수동 바이너리로 가도 돼요.
- 왜 치나요: Scoop(윈도우용 앱 설치 도우미)을 내 사용자 폴더에 설치해요. 관리자 권한 없이 설치돼요.
- 이렇게 나오면 성공:
Scoop was installed successfully!같은 메시지가 나와요. - 막히면: 빨간 글씨면 6장 C(실행 정책)를 보세요. 회사 PC라 차단되면 6장 F를 보세요.
PowerShell 창을 한 번 닫고 새로 열어요. 그리고 확인:
scoop --version
- 왜 치나요: 설치가 잘 됐는지 보려고요.
- 이렇게 나오면 성공:
Current Scoop version:같은 버전 정보가 나와요. - 막히면:
scoop이 인식 안 되면 6장 A(PATH) → 새 창에서 다시 시도하세요.
3-2. opencode 설치
scoop install opencode
- 왜 치나요: opencode를 내려받아 설치해요. 파일 이름은
opencode.exe예요. - 이렇게 나오면 성공:
opencode (1.18.30) was installed successfully!같은 메시지가 나와요. - 막히면: 다운로드가 차단되면 6장 F(백신·방화벽)를 보고, 권한 오류(
Access is denied,EPERM)면 6장 D를 보세요. 그래도 안 되면 대안(npm → 수동)으로 내려가세요.
3-3. 대안 A: npm으로 설치
Node.js가 이미 있다면(
node --version으로 확인) 이 한 줄이면 돼요.npm install -g opencode-ai
- 왜 치나요: npm 저장소의
opencode-ai패키지를 전역으로 설치해요. - 이렇게 나오면 성공:
added 1 package같은 메시지가 나와요. - 막히면: 권한 오류(
EPERM,Access is denied)면 6장 D를 보고, 관리자 권한으로 다시 시도하거나 수동 설치로 가세요.
3-4. 대안 B: 수동 바이너리 (가장 확실한 우회)
- 브라우저에서 https://github.com/anomalyco/opencode/releases 로 가요.
- 최신 릴리스에서
opencode-windows-x64.zip를 내려받아요. (ARM 노트북이면opencode-windows-arm64.zip) - 압축을 풀면
opencode.exe가 나와요. 원하는 폴더(예:C:\Users\민수\opencode)에 둬요. 시작 → "환경 변수" 검색 → 시스템 환경 변수 편집 → 환경 변수 → 사용자 변수 Path → 편집 → 새로 만들기로 그 폴더를 추가해요.- 새 PowerShell 창에서
opencode --version으로 확인해요.
- 막히면: PATH를 편집한 뒤에는 반드시 새 PowerShell 창을 열어야 반영돼요. 그래도 인식이 안 되면 재부팅 후
opencode --version으로 다시 확인하세요.
⚠️ 공식 배포처는github.com/anomalyco/opencode와opencode.ai뿐이에요. 다른 곳에서 받은 파일은 실행하지 마세요.
그림 2. 설치 전체 흐름도 (성공/실패 분기)
그림 2 설명: 설치가 실패해도 길이 끊기지 않아요. 상자의 문제해결(§6)을 따라가면 다른 길로 우회할 수 있어요.
4. 설치 확인하기
opencode --version
- 왜 치나요: 설치가 됐는지, 어떤 버전인지 확인해요.
- 이렇게 나오면 성공:
1.18.30처럼 버전 숫자가 나와요. - 막히면:
command not found가 나오면 새 PowerShell 창에서 다시 시도해요(6장 A).
설치 위치도 확인해 볼 수 있어요.
Get-Command opencode
- 왜 치나요:
opencode.exe가 어디에 설치됐는지 보여줘요. - 이렇게 나오면 성공:
Source항목에...\scoop\shims\opencode.exe같은 경로가 보여요. - 막히면: 아무것도 안 나오면 6장 A(PATH)로 가세요. (예전엔
where opencode를 썼지만, PowerShell에서는Get-Command가 더 정확해요.)
💡 앞선 글에서opencode --version이 안 됐던 이유는 대부분 PATH(프로그램 목록)에 등록이 안 됐기 때문이에요. 설치 후 새 창을 열면 해결되는 경우가 많아요.
5. 프로젝트 폴더 만들고 첫 실행
5-1. 폴더 만들기 (탐색기 GUI)
바탕화면에서
내 PC → 문서 로 들어가요. 빈 곳에서 마우스 오른쪽 → 새로 만들기 → 폴더 를 눌러 이름을 my-first-opencode로 지어요.⚠️ 폴더 이름에 한글과 공백이 섞이면(내 프로젝트) 가끔 문제가 생겨요. 처음엔 영문·숫자만 쓰는 게 안전해요.
5-2. PowerShell에서 폴더로 이동
cd "C:\Users\민수\Documents\my-first-opencode"
- 왜 치나요: opencode에게 "여기서 일해"라고 작업 폴더를 알려주는 거예요.
민수자리에는 실제 사용자 이름을 넣어요. - 이렇게 나오면 성공: 프롬프트 앞에 그 폴더 경로가 표시돼요.
- 막히면: 경로에 공백/한글이 있으면 항상 큰따옴표로 감싸요.
cd "C:\Users\민수\Documents\my project"
5-3. opencode 실행
opencode
- 왜 치나요: opencode의 첫 화면(TUI, 글자로 조작하는 화면)을 켜요.
- 이렇게 나오면 성공: 로고와 함께 입력창이 뜨고, 처음에는 모델 연결 안내가 보일 수 있어요.
- 막히면: 화면이 깨져 보이면 Windows Terminal 사용을 권장해요. 안 켜지면
opencode --print-logs로 원인을 확인해요.
5-4. 모델 연결 (첫 대화 전)
첫 화면에서
/connect를 입력하면 사용할 AI(모델)를 고르고 API 키를 넣을 수 있어요. 키는 sk-... 같은 내 비밀값이니 절대 남에게 보여주거나 글에 붙이지 마세요.⚠️ 설치만 하면 AI가 바로 코딩하는 건 아니에요. 실제 답변을 받으려면 모델 연결(API 키 등)이 필요해요. 공식 문서는 API 키를 전제조건으로 안내하고, 설치 스크립트는 "무료 모델이 포함된다"고 안내해요. 첫 화면 안내를 따라가면 돼요.
- 이렇게 나오면 성공:
/connect후 사용할 provider(제공자)를 고르면 입력창이 다시 활성화돼요. - 막히면: API 키가 없으면 무료 모델 안내(예: OpenCode Zen)를 따라가도 돼요. 연결 상태가 궁금하면
opencode auth list로 확인해요.
5-5. 첫 인사 시키기
입력창에 이렇게 써 보세요.
이 폴더에 memo.md 파일을 만들고 "첫 실행 성공!"이라고 한 줄 적어줘.
- 왜 치나요: opencode가 실제로 파일을 만들 수 있는지 확인하는 가장 간단한 부탁이에요.
- 이렇게 나오면 성공: 파일을 만들겠다는 승인 요청이 뜨거나, 결과 요약이 보여요.
- 막히면: 승인 요청이 뜨면 허용해 주세요. 모델 연결이 안 돼 있으면 5-4로 돌아가요.
5-6. 종료하기
/exit
- 왜 치나요: opencode를 안전하게 끄는 정식 명령이에요. (
/quit,/q도 같아요. 단축키는ctrl+x다음q) - 이렇게 나오면 성공: PowerShell 프롬프트(
PS C:\...>)로 돌아와요. - 막히면: 아무 반응이 없으면
Ctrl+C를 눌러요(강제 종료보다는 안전한 편).
그림 3. 설치 확인부터 첫 대화, 종료까지
그림 3 설명: 설치 확인부터 첫 대화, 종료까지의 시간 순서예요. 점선(
-->>)은 "프로그램이 나에게 보여주는 것"이에요.6. 자주 겪는 Windows 문제
| # | 증상 | 원인 | 해결 |
|---|---|---|---|
| A | 설치했는데 opencode가 인식 안 됨 (command not found) | PATH 미반영 | 새 PowerShell 창에서 재시도. Get-Command opencode로 위치 확인. 안 되면 재부팅 |
| B | scoop이 인식 안 됨 | Scoop 미설치/미반영 | 3-1로 돌아가 Scoop 설치 → 새 창. 그래도 안 되면 npm 경로 |
| C | 이 시스템에서 스크립트를 실행할 수 없으므로... (빨간 글씨) | 실행 정책(ExecutionPolicy) | 뜻: "스크립트 실행이 막혀 있다". 3-1의 -Scope CurrentUser 명령으로 내 계정만 허용. 영구 전체 변경은 지양 |
| D | Access is denied, EPERM | 권한 부족 | 시작에서 PowerShell 관리자 권한으로 실행. npm은 관리자로 재시도 |
| E | 한글/공백 경로에서 이상하게 실패 | 경로 파싱 | 경로를 항상 큰따옴표로: cd "C:\Users\민수\Documents\my project". 폴더명은 영문 권장 |
| F | 다운로드가 삭제되거나 차단됨 | 백신/방화벽/회사 정책 | 오탐일 수 있어요. 백신 예외는 IT 담당자 확인 후 진행. 공식 배포처인지 먼저 확인 |
| G | "Windows의 PC 보호" 파란 경고(SmartScreen) | 서명/평판 부족 | 추가 정보 → 실행. 단, 출처가 github.com/anomalyco/opencode·opencode.ai가 맞는지 먼저 확인 |
| H | WSL에서 설치했는데 PowerShell에서 안 됨 | 설치 위치 불일치 | 설치한 곳에서만 명령이 먹어요. 어디에 설치했는지 확인하고 실행 창을 맞춰요 |
| I | 여러 줄 명령이 일부만 실행됨 | 복붙 문제 | 명령은 한 줄 원칙으로 복붙해요 |
| J | 매번 관리자 권한 창이 떠요 | 습관적 관리자 실행 | 관리자 권한은 설치가 막힐 때만 사용해요 |
| K | WSL에서 Windows 파일이 안 보임 | 경로 규칙 | C:는 /mnt/c/, D:는 /mnt/d/ 예: cd /mnt/c/Users/YourName/project |
| L | 데스크톱 앱 화면이 하얗게 나옴 | WebView2 미설치 | 데스크톱 앱 전용 문제예요. CLI만 쓰면 해당 없음. WebView2 Runtime 설치 |
| M | 예전 버전과 꼬임 | 중복 설치 | Get-Command opencode, opencode --version 확인 후 필요 시 opencode uninstall |
참고: 내 PC 어디에 뭐가 저장되나요? (공식 문서 기준)
- 저장/세션:
%USERPROFILE%\.local\share\opencode - 로그:
%USERPROFILE%\.local\share\opencode\log - 캐시:
%USERPROFILE%\.cache\opencode - 설정:
%USERPROFILE%\.config\opencode\opencode.jsonc - 인증 키: 위 저장 폴더의
auth.json→ 절대 공유 금지
💡WIN+R을 누르고 위 경로를 붙여 넣으면 탐색기로 바로 열려요.
7. 마무리 & 다음 단계
오늘 한 것: opencode를 설치하고, 켜서 파일 하나 만들게 한 것. 여기까지 되면 앞선 글의 실습을 이어서 할 준비가 끝난 거예요.
- 모델 연결은 별도 글로 다뤄요. 여러 AI 구독을 하나로 묶는 멀티탭(CLIProxyAPI) 이야기도 그때 해요.
- 업그레이드는
opencode upgrade, 제거는opencode uninstall이에요. Scoop으로 설치했다면scoop update opencode도 돼요. - 앞선 글 「herdr 30분 실습」으로 돌아가, 이번엔
opencode --version이 버전 숫자를 뱉는 걸 확인하고 이어가세요.
설치가 한 번에 안 돼도 괜찮아요. 컴퓨터는 안 망가져요. 오늘도 안전하게 한 걸음 걸었어요.