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 の設定はほとんどそのまま動きます。意図的に壊れるのは 3 つです。v1 のプラグインは読み込まれない、サーバー API が新しくなった、tui.json が cli.json に置き換わった、の 3 点です。気づきにくい変更も 2 つあります。v2 は CLAUDE.md を読まなくなり、プロジェクト外のフォルダへのアクセスがデフォルトで許可になりました。この記事ではそれぞれの対処と、2.x 公開後の数週間で見つかった既知のバグを順に説明します。

確認したこと・していないこと： 2026 年 10 月 25 日に、OpenCode 1.18.19 を入れた macOS で v1 側を確認しました。upgrade、export、session、debug paths の各コマンドを調べています。あわせて @opencode/cli 2.1.4 の npm レジストリ情報と、下で引用している 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 で、チームが 2.0 を正式に発表したのが 10 月 14 日だったためです。発表は Hacker News で 888 ポイントを集めました。10 月 11 日以降、リポジトリには 4,000 件を超える新しい issue が立ち、そのうち 130 件が 2.0 に触れています。

現在、2 つのバージョンが並行して配布されています。npm の opencode-ai は今も v1（10 月 28 日時点で 1.19.5）です。@opencode/cli が v2（10 月 30 日時点で 2.2.5）です。v2.2.0（10 月 27 日）からは GitHub Releases (opens in a new tab) にも 2.x のビルドが載るようになりましたが、Latest と表示されているリリースは今も 1.x です。これは意図的な措置です。v1 は Latest のリリースを見て更新を探すため、チームは v1 の自動更新でユーザーが 2.x に飛ばされないようにしています（#57675 (opens in a new tab)）。

ステップ 1：何かを触る前にバックアップする

公式の移行ガイドは「テスト中は v1 の環境のコピーを残しておく」と書いていますが、何をコピーすればよいかまでは書いていません。macOS と Linux では opencode debug paths でフォルダの一覧が出ます。手元の 1.18.19 では次のとおりでした。

上の 2 つをコピーしてください（このページ冒頭のコマンドです）。セッションのデータベース（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 と v2 はデフォルトでは共存できないため、パッケージマネージャーで入れた v1 は先に削除する必要があります。そのうえで、公式の 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 なら --trust、pnpm なら --allow-build=@opencode/cli を付けてください。付けないとバイナリが入りません。
• コマンド名が 2 つ。 npm パッケージは bin フィールドに opencode と opencode2 の両方を登録しています（レジストリのメタデータで確認しました）。
• mise が v2 を入れるのは mise 2026.10.9 以降です。それより古い mise では OpenCode 1 が入ります。
• Windows のパッケージマネージャー（Scoop、Chocolatey）は v2 に対応しておらず、opencode upgrade --major でもこれらで入れた環境は切り替えられません。v2 のインストールページ (opens in a new tab)から 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 のファイルはそのまま残ります。

信用する前に、実際のプロジェクトを開いて 5 点を確認してください。モデル、プロバイダーの認証情報、エージェント、権限、MCP サーバーです。移行ガイドも同じチェックリストを挙げています。

あとで v2 ネイティブの設定に移したくなったときに、特に重要なフィールドの変更は次のとおりです。

移行ミスの大半は、ガイドにある次の 2 つのルールで防げます。

1. 1 つのエントリーは 1 つの形式で書く。 トップレベルでは v1 と v2 の書き方を混ぜてもかまいません。ただし 1 つの 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 形式へ移行し、挙動と無関係な設定はすべて維持する、という指示です。）採用する前に差分を必ず確認してください。

v2 が無視する v1 のフィールド

以下は警告が出るだけで、何も効きません。

エージェント単位の temperature、top_p、options も効かなくなります。v2 はこれらをエージェントの request.body に残しますが、送信はしません。代わりにモデルの variant 側で設定してください。

次の v1 フィールドは古く見えますが、v2 が自動で変換するため、警告なしでそのまま動きます。設定を整理するときに削除しないでください。

LSP の設定は残りますが、実行されません。 OpenCode の LSP 診断に頼っていた場合は、lint、型チェック、コンパイラのコマンドをエージェントに明示的に渡してください（たとえば 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 ではこのフォールバックもなくなりました。グローバルの AGENTS.md がない場合は、そこへコピーします。

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

Claude Code は今では CLAUDE.md がないときに AGENTS.md を読むので、1 つのファイルを両方のツールで使い続けられます。設定方法は Claude Code で AGENTS.md を読む方法 にまとめています。フォールバックを復活させてほしいという要望は #53402 (opens in a new tab) としてオープンのままです。

プロジェクト外のフォルダがデフォルトで許可になった

v1 では、エージェントがプロジェクト外のディレクトリに触れる前に確認していました。v2 では外部ディレクトリへのアクセスがデフォルトで許可です。v1 の挙動に戻すには、permissions に次のルールを追加します。

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

OpenCode を自動承認で動かしている場合や、リポジトリの外に機密ファイルがあるマシンで使う場合は、最初の v2 セッションの前にこのルールを入れてください。

Todo がオフになった

v1 では todo リストがデフォルトでオンでした。v2 ではオフです。"experimental": { "todo": true } で元に戻せます。

ユーザーアカウント全体で 1 つのバックグラウンドサービスが動く

v2 は共有のバックグラウンドサーバーを 1 つ起動します。TUI、Web UI、デスクトップアプリはすべてここに接続します。opencode pair（5 分で失効するワンタイムリンク）やバックグラウンドタスク（Ctrl+B）が動くのはこの仕組みのおかげです。不要なら次のようにします。

opencode service set disabled true   # 停止し、自動起動もやめる
opencode service unset disabled      # 再び有効にする
opencode --standalone                # この実行だけ専用サーバーを使う

サービスを無効にしている間はペアリングが使えません。また、サービスは 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 で読み込まれ、スタンドアロンアプリ omo（OmO Native）を案内する通知が出ることをメンテナーが確認しました。OpenCode をアップグレードする前に、oh-my-openagent を 5.1.38 以降に更新してください。omo に移りたい場合は、README にあるとおり omo setup を一度実行すれば、プロバイダーキー、MCP サーバー、スキル、モデル選択を引き継げます。ハーネス自体が初めてなら、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 です。対処法は各スレッドのメンテナー、報告者、またはプロジェクトの bot によるものです。

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 チームは、廃止作業中だったレガシーシステムに不正アクセスがあったと発表しました（Hacker News に引用された声明 (opens in a new tab)）。Console ワークスペースに保存されていたサードパーティのプロバイダーキーが「漏えいした可能性がある」としています。推奨されている対応は、各プロバイダーのダッシュボードでキーを失効・再発行し、最近の利用状況を確認することです。後日の投稿では、影響を受けた Console ユーザーは 1.4% とされ、共同創業者の Dax Raad は CLI とデスクトップアプリには影響がなかったと述べています（TechCrunch (opens in a new tab)）。OpenAI や Anthropic などのキーを Console に保存したことがあるなら、アップグレードの前後どちらかでローテーションしてください。

2.0 で実際に増えたもの

アップグレードを終えるためにこの節の内容は必要ありません。アーキテクチャが変わった理由を説明する機能です。

• バックグラウンドサービス： TUI、Web UI、デスクトップアプリで共有。Web からのアクセス用に opencode pair もあります。
• バックグラウンドタスク： Ctrl+B を押すと、実行中のシェルコマンドやサブエージェントをバックグラウンドに回し、メインのエージェントは作業を続けます。
• Code Mode： MCP サーバーや OpenAPI エンドポイントを関数に変換し、エージェントが 1 ステップでつなげて呼べるようにします。MCP サーバーではデフォルトで有効です。
• ホットリロード： OpenCode がセッション中に自分用のプラグインを書き、すぐに使えます。
• @opencode/sdk と @opencode/client： CLI の中身にあたるコードで、独自のクライアントを作るためのものです。

アップグレードではなく、ターミナルエージェントを一から選ぶ場合は、Codex の使い方で最も近い代替を紹介しています。

関連ガイド

• OpenCode の使い方ガイド：始め方、実践 Tips、Oh My OpenCode との使い分け
• Claude Code で AGENTS.md を読む方法：Codex・OpenCode・Cursor と 1 ファイルを共有
• Codex の使い方
• DeepSeek Harness の使い方
• 並列コードエージェント入門