OpenCode 2.0 업그레이드 방법: v1 설정·플러그인·세션 마이그레이션 가이드

Name

Soren Atelier

업데이트 2026. 11. 4.

짧은 답: OpenCode 폴더를 백업하고, 최신 1.x 릴리스로 올린 다음, 메이저 업그레이드를 실행하세요.

# 1. 설정과 데이터 백업 (세션은 data 폴더에 있습니다)
cp -R ~/.config/opencode ~/opencode-v1-config-backup
cp -R ~/.local/share/opencode ~/opencode-v1-data-backup
 
# 2. 먼저 최신 1.x로 올리기 (--major는 v1.19.0부터 있습니다)
opencode upgrade
 
# 3. OpenCode 2로 이동
opencode upgrade --major

터미널 UI 안에서는 /update가 같은 일을 합니다. 클린 설치를 원한다면 v1 패키지를 먼저 지우고, 아래 3단계에 있는 v2 설치 명령 중 하나를 사용하세요.

대부분의 v1 설정은 그대로 동작합니다. 의도적으로 깨지는 것은 세 가지입니다. v1 플러그인이 로드되지 않고, 서버 API가 새로 바뀌었고, tui.json이 cli.json으로 대체됩니다. 눈에 덜 띄지만 사람들을 당황하게 만드는 변경도 두 가지 있습니다. v2는 더 이상 CLAUDE.md를 읽지 않으며, 기본값으로 프로젝트 밖 폴더 접근을 허용합니다. 이 가이드는 각 항목과 함께, 2.x 출시 후 첫 몇 주 동안 알려진 버그도 정리합니다.

확인한 것과 확인하지 않은 것: 2026년 10월 25일, macOS에 OpenCode 1.18.19를 설치한 상태에서 v1 쪽을 확인했습니다. upgrade, export, session, debug paths 명령을 직접 살펴봤습니다. 또 @opencode/cli 2.1.4의 npm registry 데이터와 아래에 인용한 GitHub issue, 메인테이너 답변을 읽었습니다. 이 가이드를 위해 OpenCode 2를 직접 실행하지는 않았습니다. v2 동작에 관한 내용은 모두 공식 마이그레이션 가이드 (opens in a new tab), v2 문서 (opens in a new tab), OpenCode 2.0 발표글 (opens in a new tab), 그리고 해당 메인테이너 답변에서 가져왔습니다. 출처는 각각 링크했습니다. 2026년 11월 4일에는 @opencode/cli 2.2.5와 opencode-ai 1.19.5를 기준으로 버전, 릴리스 페이지, issue 스레드를 다시 확인했습니다.

지금 업그레이드해야 할까?

OpenCode 2.0은 2026년 9월 11일 @opencode/cli라는 이름으로 npm에 올라왔습니다. 그런데 npm이나 설치 스크립트로 설치한 v1 사용자 상당수는 10월에야 이를 접했습니다(Homebrew core 사용자는 더 일찍 받았습니다. 3단계의 Homebrew 함정을 참고하세요). opencode upgrade --major 경로가 10월 11일 v1.19.0에서 추가됐고, 팀이 10월 14일에 2.0을 발표했기 때문입니다. 발표글은 Hacker News에서 888점을 받았습니다. 10월 11일 이후 저장소에는 4,000개가 넘는 새 issue가 올라왔고, 그중 130개가 2.0을 언급합니다.

현재 두 버전은 나란히 배포됩니다. npm의 opencode-ai는 여전히 v1입니다(10월 28일 기준 1.19.5). @opencode/cli는 v2입니다(10월 30일 기준 2.2.5). v2.2.0(10월 27일)부터는 2.x 빌드도 GitHub Releases (opens in a new tab)에 올라오지만, Latest 표시가 붙은 릴리스는 여전히 1.x입니다. 의도된 것입니다. v1은 Latest 릴리스를 보고 업데이트를 찾는데, 팀은 v1 자동 업데이트가 사용자를 2.x로 넘기지 않기를 원합니다(#57675 (opens in a new tab)).

1단계: 아무것도 건드리기 전에 백업하기

공식 마이그레이션 가이드는 테스트하는 동안 v1 설정의 사본을 보관하라고 합니다. 하지만 무엇을 복사해야 하는지는 알려주지 않습니다. macOS와 Linux에서는 opencode debug paths로 폴더 목록을 볼 수 있습니다. 1.18.19 설치 환경에서는 다음과 같이 나왔습니다.

앞의 두 폴더를 복사하세요(이 페이지 맨 위의 명령). 세션 데이터베이스(opencode.db와 그 -wal 파일)가 일관된 상태로 복사되도록 먼저 OpenCode를 종료하세요. 중요하게 쓰는 프로젝트 단위 opencode.json과 .opencode/ 폴더도 복사해 두세요. 이 파일들은 저장소 안에 있으므로 대부분 git이 이미 추적하고 있습니다.

중요한 대화를 따로 보관하고 싶다면 업그레이드 전에 v1에서 내보내세요.

opencode session list
opencode export <sessionID> > my-session.json

opencode export는 세션을 JSON으로 저장합니다. 파일을 공유할 계획이라면 --sanitize를 붙여 민감한 대화 내용과 파일 데이터를 제거하세요.

2단계: 최신 1.x로 올리기

opencode upgrade --major는 v1.19.0부터만 존재합니다. 1.18.19 설치 환경에서 opencode upgrade --help를 실행하면 --major 플래그가 보이지 않았습니다. 1.18 이하라면 먼저 일반 업그레이드를 실행하세요.

opencode --version
opencode upgrade

그다음 opencode --version이 1.19.x를 출력하는지 확인하세요. v1.19.0부터는 업데이트가 자동으로 설치되지 않습니다. 이 명령을 직접 실행하기 전까지 오래된 버전은 그대로 남아 있습니다.

3단계: v2로 업그레이드하거나 새로 설치하기

제자리 업그레이드 (1.19.x에서):

opencode upgrade --major

클린 설치. 마이그레이션 가이드는 패키지 매니저로 설치한 v1을 먼저 지우라고 안내합니다. 기본 설정에서는 v1과 v2가 나란히 설치되지 않기 때문입니다. 그다음 공식 v2 명령 중 하나를 고르세요.

# 공식 설치 스크립트 (v1 바이너리를 대체)
curl -fsSL https://opencode.ai/v2/install | bash
 
# Homebrew (-v2 formula에 주의, v1 brew 설치는 먼저 제거)
brew uninstall opencode
brew install anomalyco/tap/opencode-v2
 
# npm (새 패키지 이름)
npm uninstall -g opencode-ai
npm install -g @opencode/cli

패키지 매니저 함정:

• npm 패키지 이름. v1은 opencode-ai, v2는 @opencode/cli입니다. 지금 npm install -g opencode-ai를 실행하면 여전히 1.19.5가 설치됩니다.
• Homebrew core와 tap의 차이. tap 없이 brew install opencode로 설치하면 9월 28일부터 OpenCode 2가 설치됩니다. 그래서 이렇게 설치했다면 --major 없이 brew upgrade만으로도 2.x로 넘어갑니다. 1.x formula는 anomalyco/tap/opencode, 2.x formula는 anomalyco/tap/opencode-v2입니다. 둘은 서로 충돌하므로 다른 쪽을 설치하기 전에 brew uninstall opencode를 실행하세요.
• 설치 스크립트. v2 npm 패키지는 postinstall 스크립트로 네이티브 바이너리를 고릅니다. Bun이나 pnpm을 쓴다면 --trust(Bun) 또는 --allow-build=@opencode/cli(pnpm)를 붙이세요. 이 플래그가 없으면 바이너리가 빠집니다.
• 명령 이름이 두 개. npm 패키지는 bin 필드에 opencode와 opencode2를 모두 등록합니다(registry 메타데이터로 확인했습니다).
• mise는 mise 2026.10.9부터만 v2를 설치합니다. 그보다 오래된 mise는 OpenCode 1을 설치합니다.
• Windows 패키지 매니저(Scoop, Chocolatey)는 v2를 지원하지 않으며, opencode upgrade --major로도 이렇게 설치한 것을 전환할 수 없습니다. v2 설치 페이지 (opens in a new tab)에서 standalone Windows CLI 바이너리나 데스크톱 앱을 내려받거나, WSL을 쓰세요. WSL에서 v2가 멈춘다는 중국어 보고(#55033 (opens in a new tab))는 정보 부족으로 10월 16일에 종료됐습니다.
• Docker: 버전별 이미지가 있습니다. 예: ghcr.io/anomalyco/opencode:2.0.0.

opencode --version을 실행해 2.x가 출력되는지 확인하세요.

4단계: v2가 v1 설정에서 무엇을 가져왔는지 확인하기

설정을 다시 쓸 필요는 없습니다. v1과 v2는 같은 위치(~/.config/opencode/opencode.json, 프로젝트의 opencode.json, .opencode/)를 읽습니다. v2는 v1 필드 이름을 메모리에서 변환하며, 파일 자체는 다시 쓰지 않습니다. v2를 처음 실행하면 전역 tui.json 설정이 새 파일 ~/.config/opencode/cli.json으로 옮겨집니다. v1 파일은 그대로 남습니다.

믿고 쓰기 전에 실제 프로젝트를 열어 다섯 가지를 확인하세요. 모델, provider 인증 정보, agent, 권한, MCP 서버입니다. 마이그레이션 가이드도 같은 체크리스트를 사용합니다.

나중에 네이티브 v2 설정으로 바꾸고 싶다면, 가장 중요한 필드 변경은 다음과 같습니다.

가이드에 나온 두 가지 규칙만 지켜도 마이그레이션 실수 대부분을 막을 수 있습니다.

1. 항목 하나에는 한 가지 형식만 쓰세요. 최상위에서는 v1과 v2 문법을 섞어도 됩니다. 하지만 agent, provider, command, model 항목 하나 안에서는 한 형식을 골라야 합니다.
2. 변환한 파일을 v1에 물리지 마세요. 두 버전은 같은 경로를 읽습니다. 파일을 v2 전용 문법으로 바꾸면 v1은 그 파일을 더 이상 읽지 못합니다. 롤백할 가능성이 있다면 변환은 마지막에 하세요.

가이드는 변환 자체를 OpenCode에게 맡기는 방법도 제안합니다. 프로젝트에서 v2를 실행하고 이 프롬프트를 입력하세요. "Migrate my OpenCode configuration, including file-based definitions, from the V1 format to the native V2 format. Preserve its behavior and all unrelated settings." (파일 기반 정의를 포함한 OpenCode 설정을 V1 형식에서 네이티브 V2 형식으로 옮기고, 동작과 관련 없는 설정은 모두 유지하라는 뜻입니다.) 결과를 유지하기 전에 diff를 꼭 검토하세요.

v2가 무시하는 v1 필드

아래 필드는 경고만 출력하고 아무 효과가 없습니다.

agent 단위의 temperature, top_p, options도 더 이상 동작하지 않습니다. v2는 이 값들을 agent의 request.body에 보관하지만 실제로 보내지는 않습니다. 대신 모델 variant에서 설정하세요.

아래 v1 필드는 오래된 것처럼 보이지만, v2가 알아서 변환하므로 경고 없이 그대로 동작합니다. 정리하면서 지우지 마세요.

LSP 설정은 유지되지만 실행되지 않습니다. OpenCode의 LSP 진단에 의존했다면, 대신 agent에게 lint, typecheck, 컴파일러 명령을 명시적으로 알려주세요(예: AGENTS.md에 적기).

5단계: 나중에 문제를 일으키는 동작 변경

아래 항목은 바뀌어도 에러가 나지 않기 때문에 가장 많이 놀라게 되는 부분입니다.

v2는 CLAUDE.md를 읽지 않는다

v1은 AGENTS.md가 없으면 CLAUDE.md로 대체했습니다. v2는 그렇지 않습니다. 프로젝트 규칙이 CLAUDE.md에 있다면 v2는 규칙 없이 시작하고, 아무 경고도 하지 않습니다. 해결은 1분이면 됩니다.

# CLAUDE.md만 있는 각 저장소에서
git mv CLAUDE.md AGENTS.md

v1은 ~/.config/opencode/AGENTS.md가 없을 때 ~/.claude/CLAUDE.md를 전역 규칙으로도 사용했습니다. v2는 이 fallback도 없앴습니다. 전역 AGENTS.md가 없다면 그 위치로 복사하세요.

cp ~/.claude/CLAUDE.md ~/.config/opencode/AGENTS.md

이제 Claude Code는 CLAUDE.md가 없을 때 AGENTS.md를 읽으므로, 파일 하나로 두 도구를 함께 쓸 수 있습니다. 설정 방법은 Claude Code AGENTS.md 사용법에 정리돼 있습니다. 이 fallback을 되살려 달라는 기능 요청은 #53402 (opens in a new tab)로 열려 있습니다.

프로젝트 밖 폴더 접근이 기본으로 허용된다

v1에서는 agent가 프로젝트 밖 디렉터리를 건드리기 전에 물어봤습니다. v2에서는 외부 디렉터리 접근이 기본값으로 허용됩니다. v1 동작으로 되돌리려면 permissions에 다음 규칙을 추가하세요.

{
  "permissions": [
    { "action": "external_directory", "resource": "*", "effect": "ask" }
  ]
}

OpenCode를 자동 승인으로 실행하거나, 저장소 밖에 민감한 파일이 있는 머신에서 쓴다면 첫 v2 세션 전에 이 규칙을 추가하세요.

Todo가 꺼져 있다

v1에서는 todo 목록이 기본으로 켜져 있었습니다. v2에서는 꺼져 있습니다. "experimental": { "todo": true }로 다시 켤 수 있습니다.

사용자 계정 전체에서 백그라운드 서비스 하나가 돈다

v2는 공유 백그라운드 서버 하나를 시작합니다. TUI, 웹 UI, 데스크톱 앱이 모두 여기에 연결됩니다. opencode pair(5분 뒤 만료되는 일회용 링크)와 백그라운드 작업(Ctrl+B)이 동작하는 것도 이 덕분입니다. 원하지 않는다면 다음처럼 끌 수 있습니다.

opencode service set disabled true   # 서비스 중지 및 자동 시작 해제
opencode service unset disabled      # 다시 켜기
opencode --standalone                # 이번 실행에만 쓰는 개인 서버 하나

서비스를 끈 상태에서는 pairing이 동작하지 않습니다. 또 서비스는 cli.json을 읽지 않으므로, 터미널 UI 설정은 터미널 클라이언트에만 적용됩니다.

6단계: 플러그인, Oh My OpenCode, VS Code 확장

v1 플러그인은 v2에서 로드되지 않습니다. 플러그인 API가 새로 바뀌었습니다. 설정에서 plugin을 plugins로 이름만 바꿔서는 안 됩니다. 각 플러그인 코드를 포팅해야 합니다(공식 플러그인 마이그레이션 가이드 (opens in a new tab) 참고).

가장 흔한 실패 사례는 Oh My OpenCode(oh-my-openagent)였습니다. OpenCode 2.0.27에서 버전 5.1.32가 Plugin must export a default definition with an id and an effect or setup function 에러로 실패했습니다(oh-my-openagent #10089 (opens in a new tab)). 수정(#10439 (opens in a new tab))은 10월 18일 병합됐고, 이 수정이 들어간 첫 npm 릴리스는 5.1.38입니다. 11월 2일 메인테이너는 현재 버전이 OpenCode 2에서 로드되며, standalone omo 앱인 OmO Native를 안내하는 알림을 띄운다고 확인했습니다. OpenCode를 업그레이드하기 전에 oh-my-openagent를 5.1.38 이상으로 업데이트하세요. omo로 옮기고 싶다면, README 안내대로 omo setup을 한 번 실행해 provider 키, MCP 서버, skills, 모델 선택을 가져오면 됩니다. harness 자체가 처음이라면 OpenCode 사용법 가이드부터 보세요.

VS Code 확장 에러 Unrecognized flag: --port. 오래된 확장은 opencode --port <port>로 CLI를 시작합니다. v2에서는 이 플래그가 제거됐습니다. 확장을 v1.0.0 이상으로 업데이트하세요(Marketplace 또는 Open VSX). 업데이트 전까지는 VS Code에서 터미널을 열고 opencode를 직접 실행하세요(#55219 (opens in a new tab)).

서버를 호출하는 직접 만든 스크립트. v1 서버 API는 없어졌습니다. @opencode/client 패키지로 옮기세요. 이 패키지는 백그라운드 서비스도 알아서 찾습니다. 셸에서는 opencode api로 같은 API를 호출할 수 있습니다. OPENCODE_SERVER_USERNAME은 더 이상 지원되지 않으며, 사용자 이름은 항상 opencode입니다. OpenCode GitHub Action은 2.2.0에서 제거됐습니다.

업그레이드 후 알려진 문제

2.x 출시 첫 몇 주 동안 열렸거나 최근 고쳐진 GitHub issue입니다. 해결 방법은 각 스레드의 메인테이너, 보고자, 또는 프로젝트 봇이 제시한 것입니다.

1.x로 롤백하는 방법

마이그레이션 가이드는 되돌아가는 방법을 다루지 않습니다. 안전한 순서는 다음과 같습니다.

1. v2를 제거합니다. opencode uninstall --dry-run으로 무엇이 지워질지 확인할 수 있습니다. 그다음 opencode uninstall을 실행하면 프로그램만 지우고 세션, 설정, 상태는 디스크에 남겨 둡니다.
2. 버전을 고정해 v1을 다시 설치합니다: npm install -g opencode-ai@1.19.5 또는 brew install anomalyco/tap/opencode(-v2가 없는 formula).
3. 설정 파일을 v2 전용 문법으로 바꿨다면 ~/opencode-v1-config-backup에서 복원합니다.
4. v2가 사용한 뒤 v1이 세션 데이터베이스를 읽지 못하면 ~/opencode-v1-data-backup을 복원합니다. v2가 쓴 데이터베이스를 v1이 열 수 있는지는 테스트하지 않았습니다. 백업을 전제로 계획하세요.

보안 참고: OpenCode Console 침해 사고

업그레이드와는 별개지만 같은 주에 일어난 일입니다. 10월 17일 OpenCode 팀은 폐기 중이던 legacy 시스템에 누군가 무단으로 접근했다고 밝혔습니다(Hacker News에 인용된 성명 (opens in a new tab)). Console workspace에 저장된 서드파티 provider 키가 "may have been exposed"(노출됐을 수 있음)라고 했습니다. 팀의 권고는 각 provider 대시보드에서 해당 키를 폐기하고 교체한 뒤, 최근 사용 내역을 검토하라는 것입니다. 이후 게시글에서는 영향을 받은 Console 사용자 비율을 1.4%로 밝혔고, 공동 창업자 Dax Raad는 CLI와 데스크톱 앱은 영향을 받지 않았다고 말했습니다(TechCrunch (opens in a new tab)). OpenAI, Anthropic 등의 키를 Console에 저장한 적이 있다면 업그레이드 전이든 후든 키를 교체하세요.

2.0에서 실제로 새로워진 것

업그레이드를 마치는 데 아래 내용은 필요하지 않습니다. 아키텍처가 바뀐 이유를 설명해 주는 기능들입니다.

• 백그라운드 서비스: TUI, 웹 UI, 데스크톱 앱이 공유하며, 웹 접속용 opencode pair도 함께 제공됩니다.
• 백그라운드 작업: Ctrl+B를 누르면 실행 중인 셸 명령이나 subagent를 백그라운드로 보내고, 메인 agent는 계속 작업합니다.
• Code Mode: MCP 서버와 OpenAPI 엔드포인트를 agent가 한 번에 이어서 호출할 수 있는 함수로 바꿉니다. MCP 서버는 기본으로 이 모드를 씁니다.
• 핫 리로드: OpenCode가 세션 도중 스스로 플러그인을 작성하고 바로 사용할 수 있습니다.
• @opencode/sdk와 @opencode/client: CLI를 구성하는 코드로, 직접 클라이언트를 만들 때 사용합니다.

업그레이드가 아니라 터미널 agent를 처음부터 고르는 중이라면, Codex 사용법 가이드에서 가장 가까운 대안을 확인해 보세요.

관련 가이드

• OpenCode 사용법 가이드: 시작 방법, 실전 팁, Oh My OpenCode와 함께 쓰는 법
• Claude Code AGENTS.md 사용법: Codex·OpenCode와 파일 하나 공유하기
• Codex 사용법 가이드
• DeepSeek Harness 사용법
• 병렬 코드 에이전트 가이드