OpenCode 2 마이그레이션 가이드: 설정·플러그인·권한 안전하게 옮기기

10월 13, 2026

OpenCode 2로 옮길 때 가장 위험한 선택은 기존 설정을 한꺼번에 새 형식으로 바꾸고 바로 일상 작업에 투입하는 것입니다. 공식 문서가 권하는 방향은 반대입니다. 기존 설정과 파일 기반 정의를 유지한 채 V2를 먼저 실행하고, 모델·인증·에이전트·권한·MCP 서버를 확인한 다음 플러그인과 서버 API 연동을 따로 이식해야 합니다.

이 글은 OpenCode 1 사용자와 처음 OpenCode를 설치하는 사용자를 나눠, 설치 위치부터 검증·롤백 기준까지 설명합니다. 2026년 10월 11일 공개된 OpenCode 1 v1.19.0은 opencode upgrade --major와 /update를 V2 전환 경로로 안내했으며 업데이트를 더 이상 자동 설치하지 않습니다. 따라서 업그레이드는 사용자가 시점과 검증 범위를 정하는 작업입니다.

먼저 알아둘 핵심: 전부 다시 만드는 업그레이드가 아니다

OpenCode 2의 의도적인 호환성 변경은 크게 세 부분입니다. 첫째, 플러그인은 새 API에 맞춰 옮겨야 합니다. 둘째, OpenCode 서버를 직접 호출하는 API와 클라이언트 계약이 바뀌었습니다. 셋째, 터미널 클라이언트 설정은 여러 tui.json(c) 파일 대신 전역 cli.json으로 정리되며 이 부분은 자동 마이그레이션 대상입니다.

반면 지원되는 서버 설정, 에이전트·명령·스킬 정의와 .opencode/ 아래의 일반 파일은 기존 형식을 계속 읽도록 설계됐습니다. V2 형식으로 즉시 변환하지 않아도 시험할 수 있다는 뜻입니다. 특히 V1과 V2가 같은 기본 설정 위치를 사용하므로, 새 형식으로 바꾼 파일을 V1에 다시 연결하는 방식은 피해야 합니다.

OpenCode 1 설정을 백업한 뒤 별도 검증 구간에서 권한, MCP, 플러그인과 API 연동을 확인하고 V2로 전환하는 흐름 — 기존 설정 보존, 분리된 검증, 플러그인·API 이식, 전환과 롤백을 한 흐름으로 관리한다.

시작 전 준비사항

설치 경로 확인: 기존 OpenCode를 curl, npm, pnpm, Bun, Homebrew 중 어떤 방식으로 설치했는지 기록합니다. 패키지 관리형 V1은 V2 설치 전에 제거해야 할 수 있고, V2 curl 설치기는 기존 V1 바이너리를 교체합니다.
설정 백업: ~/.config/opencode/opencode.json(c), 프로젝트의 opencode.json(c), .opencode/ 폴더를 복사합니다. 인증 키 자체를 문서나 저장소에 복사하지 말고 현재 사용 중인 환경변수 이름만 확인합니다.
검증용 저장소: 중요한 작업 저장소 대신 작은 테스트 저장소나 별도 Git worktree를 준비합니다. 읽기, 수정, 셸 명령, 외부 디렉터리 접근을 각각 시험할 수 있는 곳이 좋습니다.
연동 목록: 플러그인, MCP 서버, 사용자 정의 에이전트, 명령, OpenCode 서버 API를 호출하는 스크립트를 표로 정리합니다. 이 중 플러그인과 서버 API가 우선 점검 대상입니다.
비용 경계: OpenCode는 오픈소스지만 연결하는 모델 제공자의 API나 구독 비용은 별도입니다. 시험 단계에서는 모델과 호출 범위를 좁혀 예상치 못한 사용량을 막습니다.

OpenCode 2 설치와 첫 실행

1. 새 사용자라면 V2 설치 경로를 고른다

공식 V2 문서는 macOS·Linux에서 설치 스크립트, Homebrew, npm, Bun, pnpm, Yarn 등을 제공하고 Windows용 독립 실행 파일도 제공합니다. 예를 들어 설치 스크립트는 다음과 같습니다.

curl -fsSL https://opencode.ai/v2/install | bash

npm을 쓰면 npm install -g @opencode/cli, Homebrew를 쓰면 brew install anomalyco/tap/opencode-v2입니다. Windows 패키지 관리자는 공식 V2 문서에서 지원하지 않으므로 제공되는 x64 또는 ARM64 바이너리를 확인하는 편이 안전합니다.

2. V1 사용자라면 자동 업데이트로 가정하지 않는다

OpenCode 1 v1.19.0에서는 터미널에서 opencode upgrade --major, 앱 안에서는 /update로 V2 전환을 시작할 수 있습니다. V1과 V2는 기본적으로 같은 opencode 명령을 사용하므로 나란히 설치된다고 가정하면 안 됩니다. 먼저 백업을 끝내고 현재 설치 방식에 맞춰 전환합니다.

3. 모델과 제공자 연결을 확인한다

V2를 시작한 뒤 TUI의 /connect에서 사용할 모델 제공자를 연결합니다. 기존 인증이 보이더라도 실제 프로젝트에서 모델 목록과 선택 상태를 다시 확인합니다. 인증 값을 프로젝트 JSON에 직접 적기보다 환경변수나 제공자가 지원하는 인증 흐름을 유지합니다.

안전한 마이그레이션 순서

기존 형식 그대로 시작: V1 설정을 먼저 V2가 읽는지 확인합니다. 초기에 전체 파일을 새 형식으로 변환하면 어느 변경이 문제를 일으켰는지 찾기 어렵습니다.
핵심 다섯 항목 확인: 모델, 제공자 자격증명, 에이전트, 권한, MCP 서버 상태를 점검합니다. MCP는 opencode mcp list에서 연결 상태를 확인합니다.
플러그인 별도 이식: V1 플러그인 구현은 V2에서 그대로 실행되지 않습니다. 사용하는 플러그인의 V2 지원 버전과 마이그레이션 문서를 먼저 찾고, 대체 버전이 없으면 업그레이드 완료 조건에서 제외하거나 기능을 임시로 비활성화합니다.
서버 API 연동 교체: 자동화 스크립트나 내부 도구가 OpenCode 서버를 호출한다면 새 @opencode/client와 V2 API 계약으로 옮깁니다. 터미널이 실행된다는 이유만으로 API 연동도 정상이라고 판단하면 안 됩니다.
선택적으로 V2 형식 변환: 동작 검증 뒤 설정을 새 형식으로 정리합니다. 공식 문서는 OpenCode에 “동작과 관련 없는 설정을 보존하면서 V1 설정과 파일 정의를 V2 형식으로 마이그레이션하라”고 요청하는 방법도 안내합니다.

OpenCode 공식 V1에서 V2 마이그레이션 문서의 세 가지 호환성 변경 안내 화면 — OpenCode 공식 문서는 플러그인 API, 서버 API·클라이언트, 터미널 설정을 핵심 변경 지점으로 명시한다. 출처: OpenCode 공식 문서, 2026년 10월 13일 확인.

권한 규칙은 이름과 순서를 함께 확인한다

V2 권한은 permissions 배열로 구성되며 뒤에 있는 일치 규칙이 우선합니다. V1의 permission, bash, task는 각각 permissions, shell, subagent로 바뀝니다. 처음에는 셸 전체를 묻도록 하고, 상태 확인 같은 저위험 명령만 허용하며, 푸시는 명시적으로 차단하는 구성이 이해하기 쉽습니다.

{
  "$schema": "https://opencode.ai/config.json",
  "permissions": [
    { "action": "shell", "resource": "*", "effect": "ask" },
    { "action": "shell", "resource": "git status *", "effect": "allow" },
    { "action": "shell", "resource": "git diff *", "effect": "allow" },
    { "action": "shell", "resource": "git push *", "effect": "deny" }
  ]
}

shell은 호스트 사용자의 파일 시스템·프로세스·네트워크 권한으로 실행됩니다. 명령 문자열에서 위험한 경로를 완벽히 추론한다고 가정하지 말고 좁은 허용 목록을 사용해야 합니다. 프로젝트 밖 디렉터리는 external_directory 승인과 실제 read 또는 edit 승인이 모두 필요할 수 있습니다.

MCP 서버는 연결과 권한을 나눠 검증한다

V2에서는 서버가 mcp.servers 아래에 들어가며, 연결을 끄려면 enabled: false가 아니라 disabled: true를 사용합니다. 원격 서버는 기본적으로 OAuth를 사용하며, opencode mcp add context7 --url https://mcp.context7.com/mcp처럼 추가한 뒤 opencode mcp list로 상태를 봅니다. needs authentication이 표시되면 /mcps에서 서버를 선택해 로그인합니다.

API 키를 쓰는 서버는 비밀값을 JSON에 직접 넣지 말고 {env:MCP_API_KEY} 형태의 환경변수 치환을 사용합니다. 연결 성공은 도구 실행 허용과 같은 뜻이 아닙니다. 서버 이름과 도구 이름을 정규화한 권한 액션으로 특정 MCP 도구를 차단할 수 있습니다.

활용 예시 3가지

개인 프로젝트를 읽기 중심으로 먼저 검증

목표는 코드 수정 전에 설정 호환성을 확인하는 것입니다. 테스트 저장소에서 모델 연결과 git status·git diff만 허용하고, 편집과 푸시는 묻거나 차단합니다. 에이전트에게 구조 설명과 변경 계획만 요청한 뒤 실제 파일 변경이 없고 외부 디렉터리 승인이 불필요했는지 확인합니다. 이 단계의 산출물은 코드가 아니라 “어떤 권한과 도구가 필요한지”에 대한 검증 기록입니다.

팀 플러그인과 서버 API를 분리해 전환

목표는 터미널 사용자와 자동화 사용자의 장애 범위를 나누는 것입니다. 일반 사용자는 기존 설정으로 V2 TUI를 시험하고, 담당자는 플러그인 새 API와 @opencode/client 기반 연동을 별도 브랜치에서 이식합니다. 검토 기준은 명령 이름, 요청·응답 타입, 오류 처리, 기존 자동화의 승인 지점입니다. 모든 기능을 한 번에 바꾸지 않으면 문제가 플러그인인지 API인지 구분하기 쉽습니다.

MCP를 최소 권한으로 다시 연결

목표는 문서 검색 서버와 쓰기 권한 도구를 같은 수준으로 허용하지 않는 것입니다. 먼저 읽기 전용 서버 하나만 프로젝트 범위에 추가하고 OAuth를 완료한 뒤 연결 상태를 확인합니다. 필요한 도구만 허용하고, 쓰기·배포·외부 시스템 변경 도구는 ask 또는 deny로 둡니다. 산출물은 연결 서버 목록, 허용한 도구 패턴, 저장된 영구 승인 목록입니다.

자주 막히는 상황과 해결 순서

opencode가 여전히 V1을 연다: which opencode 또는 운영체제의 명령 위치 확인 방법으로 PATH를 확인하고, 기존 패키지 관리형 설치가 남아 있는지 살핍니다. 같은 명령 이름을 사용하므로 실행 파일 위치가 핵심입니다.
기존 설정이 일부 무시된다: 지원되지 않는 레거시 필드 경고를 확인합니다. V1과 V2 항목은 최상위에서 섞을 수 있지만 개별 agent, provider, command, model 항목 내부를 두 형식으로 뒤섞지 않는 편이 안전합니다.
플러그인이 로드되지 않는다: V2 플러그인 API 대응 여부를 확인합니다. V1 플러그인이 그대로 실행될 것이라고 기대하지 말고, 플러그인을 끈 상태에서 핵심 기능부터 검증합니다.
MCP가 인증 대기 상태다: /mcps 또는 opencode mcp auth 서버이름으로 OAuth를 완료합니다. 다른 계정으로 바꾸려면 opencode mcp logout 서버이름으로 저장된 인증을 지웁니다.
명령이 예상과 다르게 허용된다: 권한 배열에서 마지막 일치 규칙이 우선한다는 점을 확인합니다. 프로젝트에 저장된 “항상 허용” 규칙도 검토하되, 명시적인 deny는 저장 승인으로 덮어쓸 수 없습니다.

완료 확인 체크리스트

V2 실행 파일과 버전을 원하는 설치 경로에서 확인했다.
모델·자격증명·에이전트·권한·MCP 상태를 검증용 저장소에서 확인했다.
V1 플러그인과 서버 API 연동을 별도 작업으로 분리했다.
셸, 외부 디렉터리, 비밀 파일, 푸시 명령에 좁은 권한 규칙을 적용했다.
V1 백업과 롤백 조건을 유지한 채 실제 프로젝트 적용 범위를 단계적으로 늘린다.

핵심은 “설정 파일을 새 문법으로 바꾸는 것”이 아니라, 기존 작업 방식의 권한과 연동 경계를 V2에서 다시 증명하는 것입니다. 플러그인과 서버 API를 먼저 위험 구간으로 분리하고, 나머지는 기존 형식으로 읽히는지부터 확인하면 중단 시간을 줄이고 되돌릴 기준도 분명해집니다.

Read the English version of this guide

공식 자료

자료 확인일: 2026년 10월 13일

이 블로그 검색

스택핀치