OpenCode V2는 V1과 무엇이 다를까? 안전한 마이그레이션 방법

버전 번호만으로 마이그레이션 비용을 알 수는 없습니다. 실제로 사용하는 터미널 클라이언트, 플러그인, 서버 API, 설정을 나눠서 살펴보세요. 지원되는 프로젝트 파일과 실행 가능한 플러그인 코드 또는 API 클라이언트는 같은 호환성 범주가 아닙니다.

이 표는 점검 범위를 정리한 것이며 모든 이전 필드가 지원된다는 보장은 아닙니다. 마이그레이션 문서는 지원되는 값, 허용되지만 지원되지 않는 값, 허용되지 않는 값을 구분합니다. 보안, 프로바이더 액세스, 자동화 관련 설정을 바꾸기 전에 최신 안내를 확인하고 시작 시 표시되는 경고를 살펴보세요.

메이저 버전 번호만 보지 말고 호환성과 복구 가능성을 기준으로 판단하세요. 내장 기능을 쓰는 개인 환경과 커스텀 플러그인 및 에디터 연동이 있는 저장소의 마이그레이션 비용은 다릅니다.

다음 조건이라면 V2를 시험해 볼 수 있습니다

• 주로 지원되는 설정, 프로바이더, 내장 명령, 에이전트, skills, MCP를 사용하며 샘플 프로젝트에서 각각 점검할 수 있습니다.
• V2 CLI나 데스크톱을 원하고 현재 환경을 복원할 수 있는 사본을 남길 수 있습니다.
• 필요한 플러그인이나 서버 클라이언트의 V2 버전이 있거나, 이를 포팅하고 테스트할 담당자와 시간이 있습니다.

다음 조건이라면 당분간 V1을 유지하세요

• 중요한 V1 플러그인, 서버 엔드포인트, IDE 클라이언트, 자동화 작업을 V2 계약으로 아직 검증하지 않았습니다.
• 문제가 생겼을 때 패키지, 설정 또는 세션 데이터를 복원할 수 없습니다.
• 팀에서 함께 사용하지만 개발 환경, 문서, 지원 계획이 아직 없습니다.

확신이 없으면 일회용 테스트 프로젝트에서 명령, 패키지 관리자, OpenCode 버전, 기대 결과를 기록하며 시험하세요. 예를 들어 에이전트와 프로바이더만 쓰는 담당자는 저장소 사본에서 확인하고, 서버 플러그인을 쓰는 다른 담당자는 V1을 유지할 수 있습니다. 새 메이저 버전이 무조건 더 좋다는 가정 대신 확인 가능한 항목을 바탕으로 결정하게 됩니다.

공식 V2 시작 안내에는 여러 터미널 설치 경로가 나와 있습니다. 이미 사용하는 패키지 관리자를 우선하고 운영체제 지원 여부를 포함한 최신 지침을 따르세요. 마이그레이션 중에는 오래된 V1 패키지 명령을 확인 없이 재사용하지 마세요.

V2 문서는 Bun, pnpm 등 다른 경로도 설명합니다. 플랫폼별 지원이 다르므로 Windows에서는 모든 패키지 관리자가 가능하다고 가정하지 말고 안내된 바이너리를 확인하세요. Yarn, Vite+, AUR도 최신 공식 V2 명령을 사용하고, 제3자 다운로드 링크는 피하세요.

설치 전에 V1을 어떻게 설치했는지 확인하세요. 공식 마이그레이션 안내는 두 버전이 같은 opencode 명령을 사용하므로 패키지 관리형 V1을 먼저 제거해야 할 수 있다고 설명합니다. V2 curl 설치 프로그램은 V1 바이너리를 대체합니다. 패키지를 제거하며 공유 설정이나 데이터까지 삭제하지 않도록 따로 백업하고 패키지 관리자가 삭제할 항목을 살펴보세요.

첫 시도는 되돌릴 수 있어야 합니다. 첫날의 목표는 V2가 시작되고 프로젝트가 작동하는지 확인하는 것이지 모든 설정 파일을 다시 쓰는 것이 아닙니다. 사용하는 OS와 패키지에 맞는 공식 지침을 따르세요.

1. V1 설치 정보를 기록합니다. 패키지 관리자나 설치 프로그램, 버전, 환경 변수, 설정 경로를 적습니다. 이전 패키지나 신뢰할 수 있는 재설치 방법을 보존합니다.
2. 날짜가 표시된 백업을 만듭니다. 설정, 프로젝트 정의, 복구할 데이터를 저장합니다. 백업을 읽을 수 있는지 확인하고 임시 폴더에만 두지 마세요.
3. 실행 의존성을 목록화합니다. 플러그인, API 클라이언트, CI 명령, 에디터 연동을 기록하고 V2 확인 완료, 포팅 필요, 미사용으로 분류합니다.
4. 맞는 경로로 설치합니다. 공식 안내에서 요구할 때만 V1 패키지를 제거하세요. V1의 일반 업데이트 명령은 V2 설치 명령이 아닙니다.
5. 설정을 점검합니다. 테스트 프로젝트에서 V2를 시작하고 중요한 작업 전 이전 필드 경고, 모델, 인증 정보, 권한, MCP 연결을 검토합니다.
6. 코드와 클라이언트를 업데이트합니다. 플러그인을 새 API로 포팅하고 서버 클라이언트를 갱신합니다. 오류 처리와 권한도 테스트하세요.
7. 환경설정 변환은 나중에 합니다. 지원되는 터미널 설정은 전역 cli.json으로 이동합니다. 기본 흐름을 검증한 뒤 네이티브 V2 설정으로 바꿔도 됩니다.

첫 검증 단계에서는 지원되는 V1 형식의 설정을 그대로 둡니다. 공식 안내에 따르면 V2는 지원되는 기존 설정을 메모리에서 정규화하면서 원본 파일은 다시 쓰지 않습니다. 설치, 플러그인 포팅, 설정 변환을 나누면 회귀 원인을 찾고 이전 상태로 되돌리기 쉽습니다.

현재 V2 안내에서 명시적으로 지원하는 동작만 호환된다고 간주하세요. 이렇게 구분하면 모든 예전 필드나 확장 기능이 계속 작동한다고 오해하지 않고 OpenCode V2 호환성을 판단할 수 있습니다.

공식 문서는 일부 예전 설정을 허용되지만 지원되지 않는 값으로 분류하며 경고가 발생할 수 있다고 설명합니다. 파일 권한, 도구 범위, 프로바이더 액세스를 제어하는 옵션은 앱이 시작되는 것만으로 충분하지 않습니다. 로그를 확인하고 기대한 보호 동작이 유지되는지 보여 주는 테스트를 실행하세요.

샘플 프로젝트에서 짧은 인수 테스트를 하고 결과를 업그레이드 기록과 함께 보관하세요. 팀은 다른 컴퓨터에서 이 목록을 재사용할 수 있고, 개인은 구체적인 근거를 바탕으로 V2를 유지할지 V1로 돌아갈지 정할 수 있습니다.

• 실행되는 명령이 예상한 설치를 가리키고 V2 버전을 표시합니다.
• 프로바이더, 자격 증명, 모델이 작동하며 로그에 비밀 키가 노출되지 않습니다.
• 필요한 에이전트, 명령, skills가 기대한 결과를 냅니다.
• 읽기 및 쓰기 권한이 프로젝트 규칙을 따릅니다.
• MCP 서버에 연결되고 오류가 예상하지 않은 동작을 일으키지 않습니다.
• 필수 플러그인과 클라이언트에 V2 호환 버전이 있습니다.
• 필요한 세션을 이용할 수 있거나 확인된 백업이 있습니다.
• 실제 작업이 성공적으로 끝나고 출력을 검토할 수 있습니다.

중요한 검사 하나라도 실패하면 해당 작업에서 V2를 중단하고 보존한 V1 설치나 패키지로 돌아가세요. V1이 V2 전용 설정을 읽게 하지 마세요. 롤백 방법은 패키지 관리자에 따라 다르므로 이전 패키지를 보관하고 사용자 데이터와 설치 프로그램을 분리하세요. 정상 작업 주기를 완료할 때까지 백업을 삭제하지 않는 것이 좋습니다.

V2를 설치한 후의 일반 업데이트는 V2 CLI의 opencode upgrade를 사용하며 update가 별칭입니다. 이 명령은 이미 V2인 환경을 업데이트합니다. V1에서 메이저 버전을 이동하는 과정에는 별도의 패키지 및 설치 안내가 필요합니다.

설치 명령과 호환성 정보는 2026년 10월 3일에 공식 자료를 기준으로 확인했습니다. 패키지와 안내는 바뀔 수 있으므로 메이저 마이그레이션 전에 다시 확인하세요.

• OpenCode V2 소개 및 설치
• V1에서 V2로 공식 마이그레이션
• V2 CLI 명령 레퍼런스
• V1 플러그인 마이그레이션
• npm의 OpenCode CLI 패키지