Agent/💻 코딩에이전트/images/opencode-01-설치-diagram.svg
OpenCode를 사용하려면 Node.js 18 이상과 npm이 필요합니다. 이 가이드는 Windows, macOS(맥북), Ubuntu 기준 설치 경로를 함께 안내합니다.
OS별 빠른 설치 경로
macOS (맥북, Homebrew 권장)
# Homebrew가 없다면 먼저 설치
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# Node.js LTS 설치
brew update
brew install node
# 확인
node --version
npm --version- Apple Silicon(M1/M2/M3)과 Intel 맥 모두 위 경로로 설치 가능합니다.
- 설치 후
which node결과가 Homebrew 경로(/opt/homebrew/bin/node또는/usr/local/bin/node)인지 확인하세요.
Ubuntu (22.04+, NodeSource LTS 권장)
sudo apt update
sudo apt install -y curl ca-certificates gnupg
# Node.js LTS 저장소 등록
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
# 설치
sudo apt install -y nodejs build-essential
# 확인
node --version
npm --version- 기업/서버 환경이면
apt policy nodejs로 배포 버전과 설치 버전을 함께 점검하세요. - 프론트엔드 빌드가 많다면
build-essential을 함께 설치해 네이티브 모듈 컴파일 오류를 예방할 수 있습니다.
Windows
- 아래의 방법 A/B/C 중 하나를 선택하면 됩니다.
- 상세 단계는 기존 Windows 절차를 그대로 따르면 됩니다.
설치 전 확인
먼저 Node.js와 npm이 이미 설치되어 있는지 확인하세요.
PowerShell에서 확인
## Node.js 버전 확인
node --version
## npm 버전 확인
npm --version예상 결과 (이미 설치된 경우):
v20.11.0
10.2.4
에러가 발생하면 Node.js가 설치되지 않은 것입니다. 아래 설치 방법을 따라주세요.
방법 A: 공식 설치 프로그램 (권장)
1단계: 설치 파일 다운로드
1-1. nodejs.org 접속
1-2. LTS 버전 다운로드 (안정적인 장기 지원 버전)
- 예:
node-v20.11.0-x64.msi - LTS (추천): 안정적, 장기 지원
- Current: 최신 기능, 실험적
2단계: 설치 실행
2-1. 다운로드한 .msi 파일 실행
2-2. 설치 마법사 진행
┌─────────────────────────────────────┐
│ Node.js Setup Wizard │
│ ───────────────────────────── │
│ [✓] Node.js runtime │
│ [✓] npm package manager │
│ [✓] Add to PATH │
│ [✓] Chocolatey (선택사항) │
└─────────────────────────────────────┘
중요:
- ✅ Add to PATH 옵션 반드시 체크
- ✅ npm package manager 포함 확인
2-3. Install 클릭
2-4. 설치 완료 후 Finish
3단계: 설치 확인
3-1. 새로운 PowerShell 창 열기 (기존 창은 PATH 업데이트 안 됨)
3-2. 버전 확인
node --version
npm --version예상 결과:
v20.11.0
10.2.4
방법 B: PowerShell로 자동 설치
관리자 권한 PowerShell에서 스크립트로 자동 설치할 수 있습니다.
1단계: PowerShell 관리자 권한으로 실행
1-1. Windows 키 누르기
1-2. PowerShell 입력
1-3. 우클릭 → 관리자 권한으로 실행
2단계: 실행 정책 변경
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser -Force💡 스크립트 실행을 허용하는 설정입니다.
3단계: Node.js 다운로드 및 설치
## 최신 LTS 버전 URL 설정
$nodeVersion = "20.11.0"
$downloadUrl = "https://nodejs.org/dist/v$nodeVersion/node-v$nodeVersion-x64.msi"
$installerPath = "$env:TEMP\nodejs-installer.msi"
## 다운로드
Write-Host "Node.js 다운로드 중..." -ForegroundColor Green
Invoke-WebRequest -Uri $downloadUrl -OutFile $installerPath
## 설치 실행
Write-Host "Node.js 설치 중..." -ForegroundColor Green
Start-Process msiexec.exe -ArgumentList "/i `"$installerPath`" /quiet /norestart" -Wait
## 임시 파일 삭제
Remove-Item $installerPath -Force
Write-Host "설치 완료!" -ForegroundColor Green4단계: PATH 환경 변수 새로고침
## 환경 변수 새로고침
$env:Path = [System.Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [System.Environment]::GetEnvironmentVariable("Path","User")5단계: 설치 확인
node --version
npm --version예상 결과:
v20.11.0
10.2.4
방법 C: Chocolatey 패키지 매니저
Windows용 패키지 매니저를 사용한 설치 방법입니다.
1단계: Chocolatey 설치
1-1. PowerShell 관리자 권한으로 실행
1-2. Chocolatey 설치
Set-ExecutionPolicy Bypass -Scope Process -Force
[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072
iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))1-3. 설치 확인
choco --version2단계: Node.js 설치
choco install nodejs-lts -y예상 결과:
Chocolatey installed 1/1 packages.
3단계: 터미널 재시작 후 확인
node --version
npm --version설치 후 설정
npm 글로벌 경로 확인
npm config get prefix예상 결과:
C:\Users\YourName\AppData\Roaming\npm
이 경로가 PATH에 자동으로 추가되어야 합니다.
npm 업데이트 (선택사항)
npm install -g npm@latest자주 발생하는 문제 해결
문제 1: “node 명령을 찾을 수 없습니다”
원인: PATH 환경 변수에 Node.js가 없음
해결:
1. 시스템 환경 변수 편집
- Windows 검색 → “환경 변수” 입력
- “시스템 환경 변수 편집” 클릭
- “환경 변수” 버튼 클릭
2. Path 변수 확인
- 사용자 변수 → Path 선택 → 편집
- 다음 경로가 있는지 확인:
C:\Program Files\nodejs\ C:\Users\YourName\AppData\Roaming\npm
3. 없으면 추가:
- “새로 만들기” 클릭
- 경로 입력 후 확인
4. 모든 창 닫고 새 PowerShell 열기
문제 2: “액세스가 거부되었습니다”
원인: 관리자 권한 필요
해결:
- PowerShell을 관리자 권한으로 실행
- 또는 설치 경로를 사용자 폴더로 변경
문제 3: PowerShell 스크립트 실행 차단
원인: 실행 정책 제한
해결:
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser문제 4: 구버전 Node.js가 설치되어 있음
원인: 이전 버전과 충돌
해결:
1. 기존 버전 제거
## 프로그램 제거
## 제어판 → 프로그램 추가/제거 → Node.js 제거2. 수동 삭제
## 남은 파일 삭제
Remove-Item -Path "C:\Program Files\nodejs" -Recurse -Force
Remove-Item -Path "$env:APPDATA\npm" -Recurse -Force
Remove-Item -Path "$env:APPDATA\npm-cache" -Recurse -Force3. 최신 버전 재설치
문제 5: npm이 느림
원인: npm 캐시 문제
해결:
## npm 캐시 정리
npm cache clean --force
## 레지스트리 확인 (한국 사용자)
npm config get registry
## 기본값으로 설정
npm config set registry https://registry.npmjs.org/다음 단계
Node.js와 npm 설치가 완료되었다면:
→ OpenCode 셋팅 가이드로 이동하세요.
버전 관리 도구 (고급)
여러 Node.js 버전을 사용해야 한다면 버전 관리 도구를 사용하세요.
nvm-windows (Node Version Manager)
설치:
## Chocolatey로 설치
choco install nvm -y사용법:
## 사용 가능한 버전 목록
nvm list available
## 특정 버전 설치
nvm install 20.11.0
## 버전 전환
nvm use 20.11.0
## 현재 버전 확인
nvm current요약 체크리스트
- Node.js 18+ 설치 완료
- npm 설치 확인
-
node --version명령 작동 -
npm --version명령 작동 - PATH 환경 변수 설정 완료
- 새 PowerShell 창에서 테스트 성공
모두 완료했다면 OpenCode 셋팅 가이드로 이동하세요! 🎉