Ch1. 설치/업데이트
macOS/Linux/Windows/컨테이너별 설치 채널, 설치 경로 우선순위, Bun·Node.js 런타임 지원, opencode upgrade와 v1.3.0 대화형 업데이트, 팀 버전 핀 표준화를 다룹니다.
핵심 요약
- OpenCode는 TUI·데스크톱 앱·IDE 확장을 지원하는 오픈소스 AI 코딩 에이전트로, 설치 스크립트·Homebrew·npm/Bun/pnpm·Chocolatey·Docker 등 다양한 채널을 제공합니다.
- 설치 경로는
$OPENCODE_INSTALL_DIR→$XDG_BIN_DIR→$HOME/bin→$HOME/.opencode/bin순으로 결정됩니다. - v1.3.0부터 기존 Bun 외에 Node.js 20.x+에서도 실행할 수 있습니다.
opencode upgrade [version]으로 업데이트하며, v1.3.0의 대화형 플로우는 메이저/마이너 업데이트 시 확인 대화상자로 브레이킹 체인지를 알립니다.- 팀은 패키지 매니저를 통일하고
opencode-ai@1.3.2처럼 버전 핀과 CI 컨테이너로 환경 차이를 없앱니다.
OpenCode는 터미널(TUI), 데스크톱 앱, IDE 확장을 지원하는 오픈소스 AI 코딩 에이전트입니다. v1.3.2 기준 GitHub 113K+ 스타, 월 250만+ 활성 개발자가 사용 중입니다.
설치 옵션 요약
# 공식 설치 스크립트 (권장)
curl -fsSL https://opencode.ai/install | bash
# Homebrew
brew install anomalyco/tap/opencode
# npm / Bun / pnpm / Yarn
npm i -g opencode-ai@latest
bun i -g opencode-ai
pnpm i -g opencode-ai
yarn global add opencode-ai
# mise
mise use -g opencode
# Arch Linux
sudo pacman -S opencode
paru -S opencode-bin설치 경로 우선순위
OpenCode는 아래 순서로 설치 경로를 결정합니다.
| 우선순위 | 경로 |
|---|---|
| 1 | $OPENCODE_INSTALL_DIR |
| 2 | $XDG_BIN_DIR |
| 3 | $HOME/bin |
| 4 | $HOME/.opencode/bin |
런타임 지원
v1.3.0부터 Bun 외에 Node.js에서도 실행할 수 있습니다. 전에는 Bun이 필수였지만, 이제 Node.js 환경에서도 기능이 똑같이 돌아갑니다.
| 런타임 | 최소 버전 | 비고 |
|---|---|---|
| Bun | 1.x | 기존 권장 런타임 |
| Node.js | 20.x+ | v1.3.0부터 공식 지원 |
데스크톱 앱 (Beta)
opencode.ai/download에서 데스크톱 앱을 받을 수 있습니다.
| 플랫폼 | 형식 |
|---|---|
| macOS | .dmg (Apple Silicon / Intel) |
| Windows | .exe (x64 / ARM64) |
| Linux | .deb, .rpm, AppImage |
IDE 확장
VS Code, Cursor, Windsurf, VSCodium을 지원합니다.
IDE 통합 터미널에서 opencode를 실행하면 확장이 자동 설치됩니다.
| 동작 | Mac | Windows/Linux |
|---|---|---|
| OpenCode 열기 | Cmd+Esc | Ctrl+Esc |
| 새 세션 | Cmd+Shift+Esc | Ctrl+Shift+Esc |
| 파일 참조 삽입 | Cmd+Option+K | Alt+Ctrl+K |
업데이트 관리
# 최신 버전으로 업그레이드
opencode upgrade
# 특정 버전 지정
opencode upgrade 1.2.15자동 업데이트는 기본 활성화되어 있으며, 비활성화하려면:
{ "autoupdate": false }또는 환경 변수 OPENCODE_DISABLE_AUTOUPDATE=true로 제어합니다.
Interactive Update Flow (v1.3.0+)
메이저나 마이너 업데이트 때는 확인 대화상자가 뜹니다. 브레이킹 체인지가 들어간 업데이트를 실수로 적용하는 일을 막아 줍니다.
- 메이저 업데이트: 브레이킹 체인지 목록과 마이그레이션 안내 표시
- 마이너 업데이트: 주요 변경사항 요약 표시
- 패치 업데이트: 기존처럼 자동 적용
멀티윈도우 Electron (v1.2.27+)
데스크톱 앱에서 여러 창을 동시에 열 수 있습니다. 프로젝트마다 별도 창에서 작업하면 컨텍스트 전환이 한결 편합니다.
고급 팁: 팀 표준 설치
하나의 설치 경로만 표준화
CLI 버전이나 설정 문제를 줄이려면 팀에서 패키지 매니저를 하나로 통일하세요.
npm i -g opencode-ai@1.3.2처럼 버전 핀을 박아 두면 팀원 간 차이가 사라집니다.
CI에서는 컨테이너 사용
Docker 이미지로 워크플로우 재현성을 확보합니다.
IDE 확장 설치 표준화
팀 .vscode/extensions.json에 OpenCode 확장을 포함하세요.
참고 문서
- OpenCode 공식 사이트: https://opencode.ai
- 설치 가이드: https://opencode.ai/docs
- 다운로드: https://opencode.ai/download
- IDE 확장: https://opencode.ai/docs/ide/
- 체인지로그: https://opencode.ai/changelog