OpenCode V2とV1の違いは？安全に移行する手順

バージョン番号だけでは移行の負担は判断できません。実際に使うターミナルクライアント、プラグイン、サーバーAPI、設定を分けて確認します。サポート対象のプロジェクトファイルと、実行コードであるプラグインやAPIクライアントは、同じ互換性問題ではありません。

この表は確認範囲を整理するもので、すべての旧項目がサポートされる保証ではありません。移行ガイドはサポート対象、受け付けられるが非サポートの値、非対応の値を区別しています。セキュリティ、プロバイダー接続、自動化を制御する設定は、最新の公式説明と起動時の警告を確認してから変更してください。

メジャーバージョンの数字ではなく、互換性と元に戻せるかで判断します。組み込み機能を使う個人環境と、独自プラグインやエディター連携を持つリポジトリでは、移行コストが異なります。

次の条件ならV2の試用を検討できます

• 主にサポート対象の設定、プロバイダー、標準コマンド、agents、skills、MCPを使い、テスト用プロジェクトで確認できる。
• V2のCLIまたはデスクトップを使いたく、現在の環境の動作するコピーを残せる。
• 必要なプラグインやサーバークライアントがV2版を提供している、または移植とテストの担当者を確保できる。

次の条件なら当面V1を残してください

• 重要なV1プラグイン、サーバーエンドポイント、IDEクライアント、自動処理があり、V2の契約で未検証である。
• 問題発生時にパッケージ、設定、セッションデータを復元できない。
• チームで使っているが、開発環境、ドキュメント、サポートの更新計画がない。

迷う場合は使い捨てのプロジェクトで試し、コマンド、パッケージマネージャー、OpenCodeのバージョン、期待する結果を記録します。たとえばagentsとプロバイダーしか使わない担当者はリポジトリのコピーで検証し、サーバープラグインを使う担当者はV1を保持できます。これにより「新しい版だから良い」という印象ではなく、具体的な確認項目をもとに判断できます。

V2の公式イントロダクションには、ターミナルから使える複数の経路が記載されています。既に利用している管理ツールを優先し、OSの対応状況を含め最新の説明に従ってください。移行時に、古いV1パッケージのコマンドを確認せず流用しないでください。

V2ガイドにはBun、pnpmなどの方法もあります。プラットフォームごとに対応状況が異なるため、Windowsでは汎用パッケージマネージャーが使えると決めつけず、案内されたバイナリを確認してください。Yarn、Vite+、AURについても現行の公式V2手順を参照し、第三者のダウンロードリンクは使わないでください。

導入前に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の互換性を判断するのに役立ちます。

公式ドキュメントは一部の旧設定を「受け付けるが非サポート」と分類し、警告が出る場合があると説明しています。ファイル権限、ツール制限、プロバイダー接続に関わる設定では、アプリが起動しただけで安心せず、ログと期待する保護動作を示すテストを確認しましょう。

テスト用プロジェクトで短い受け入れ確認を実施し、結果を更新記録と一緒に保存します。チームでは他のPCでも同じ確認ができます。個人利用なら、V2を継続するかV1に戻すかを具体的な情報で判断できます。

• 実行されたコマンドが想定のインストールを指し、V2のバージョンを表示する。
• プロバイダー、認証情報、モデルが動き、ログに秘密情報が出ない。
• 必要なagents、コマンド、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パッケージ