컨텐츠로 건너뛰기
학습 비교 레시피 생태계 소스 코드 문서

업그레이드 가이드

OpenCode 를 새 버전으로 올릴 때 이 가이드를 사용하세요. CLI, TUI, Web, Desktop, SDK 의 관계, 갱신이 필요할 수 있는 설정 파일, 문제 발생 시 롤백 절차를 설명합니다.

시작하기 전에

  1. 현재 버전 확인: opencode --version
  2. releases 페이지에서 대상 버전을 선택.
  3. 현재 버전과 대상 버전 사이의 릴리스 노트 를 읽기.
  4. 설정 파일 (opencode.json, ~/.opencode/, 워크스페이스 전용 설정) 을 백업.

컴포넌트 관계

OpenCode 는 같은 릴리스 라인에서 여러 컴포넌트를 함께 제공합니다. 일반적으로 같은 마이너 버전으로 맞추면 예기치 않은 차이를 피할 수 있습니다.

컴포넌트실행 위치비고
CLI로컬 터미널다른 컴포넌트의 기준
TUI로컬 터미널CLI 기반
Web브라우저 + 로컬 서버로컬 서버는 CLI 와 동일한 바이너리
Desktop네이티브 윈도우 (macOS, Windows, Linux)베타. CLI 와 기능 동기화
SDK자신의 앱에 임베드CLI 공개 API 를 따름

CLI 와 TUI 만 사용한다면 그 자리에서 업그레이드할 수 있습니다. Web 서버나 Desktop 클라이언트도 함께 사용한다면 같이 업그레이드해 동작을 일관되게 유지하세요.

설정 마이그레이션

OpenCode 는 대부분의 설정에서 하위 호환을 유지하지만, 일부 키는 이름이 바뀌거나 대체되었습니다. 흔한 예:

  • 기존 tools boolean 설정은 permission 으로 통합되었습니다. 기존 키는 계속 받아들이지만 deprecation 경고를 출력합니다. permission 으로 이전하는 것을 권장합니다.
  • ~/.opencode/ 의 커스텀 도구와 명령은 Commands 와 Tools 의 현재 스키마를 따릅니다.

opencode doctor 또는 TUI 가 deprecation 경고를 표시하면 다음 메이저 버전 이전에 마이그레이션을 완료하세요.

모델 교체

모델 제공 여부는 자주 바뀝니다. 업그레이드 전:

  • Models 개요 에서 대상 버전에서 새로 deprecation 된 모델을 확인.
  • 날짜가 박힌 모델 ID (예: <provider>/<model>) 는 안정 별칭 또는 provider 가 권장하는 최신 이름으로 교체.
  • OpenCode Zen 을 사용한다면 opencode.ai/zen 에서 최신 카탈로그와 요금을 확인.

업그레이드 절차

명령은 설치 방법에 따라 다릅니다.

  • macOS / Linux (설치 스크립트): 스크립트를 다시 실행하면 현재 버전을 감지해 그 자리에 교체합니다. curl -fsSL https://opencode.ai/install | bash
  • Homebrew: brew upgrade anomalyco/tap/opencode (공식 formula 를 사용한다면 opencode 업그레이드)
  • npm / pnpm / yarn: npm i -g opencode-ai@latest (해당 패키지 매니저에 맞춰)
  • Scoop / Chocolatey: scoop update opencode 또는 choco upgrade opencode
  • Docker: 새 이미지를 받아 컨테이너를 재시작. 지원 태그는 Docker 가이드 참조.
  • 데스크톱 앱: 앱 내 업데이터 (Help → Check for Updates) 를 사용하거나 다운로드 페이지 에서 재설치.

업그레이드 후:

  1. opencode --version 으로 새 버전 확인.
  2. opencode doctor (제공되는 경우) 또는 TUI 를 실행해 설정 경고 점검.
  3. 작은 대표 작업을 한 번 실행한 뒤 일상 사용으로 복귀.

롤백

업그레이드 후 중요한 워크플로가 깨졌다면:

  1. 같은 설치 방식으로 이전 버전을 다시 설치.
  2. 백업해 둔 opencode.json 과 ~/.opencode/ 의 설정을 복원.
  3. 새 기본 모델이 provider 와 호환되지 않는 경우 모델 ID 를 다시 고정.
  4. 실패한 버전, 재현 절차, 에러 출력을 첨부해 GitHub issue 를 작성.

업그레이드를 건너뛰어도 되는 경우

모든 릴리스를 따라갈 필요는 없습니다. 다음과 같은 상황이면 건너뛰어도 됩니다.

  • 릴리스 노트에 나에게 영향을 주는 변경이 없다.
  • 의존하는 핵심 플러그인이나 provider 통합이 새 버전에서 아직 검증되지 않았다.
  • 장애 대응 중이며 그 장애에 대한 수정도 새 버전에 포함되어 있지 않다.

관련 링크