アップグレードガイド

OpenCode を新しいバージョンへ移行するときは本ガイドを参照してください。CLI、TUI、Web、Desktop、SDK の関係、設定ファイル、トラブル時のロールバック手順をまとめています。

開始前の準備

OpenCode は同じリリースラインで複数のコンポーネントを提供します。基本的に、同じマイナーバージョンに揃えると想定外の差分を避けられます。

コンポーネント	実行場所	補足
CLI	ローカル端末	他のコンポーネントの基準
TUI	ローカル端末	CLI ベース
Web	ブラウザ + ローカルサーバ	ローカルサーバは CLI と同じバイナリ
Desktop	ネイティブウィンドウ (macOS、Windows、Linux)	ベータ版。CLI と機能を揃える
SDK	自分のアプリに組み込み	CLI の公開 API に追従

CLI と TUI だけを使う場合はそのままアップグレードできます。Web サーバや Desktop クライアントも使う場合は、一緒にアップグレードして挙動を揃えてください。

OpenCode はほとんどの設定で後方互換を維持していますが、一部のキーはリネームや置き換えが行われました。代表的な例:

旧 tools ブール設定は permission に統合されました。旧キーは引き続き受け付けますが、非推奨警告が表示されます。permission への移行を推奨します。
~/.opencode/ 配下のカスタムツールとコマンドは Commands と Tools の最新スキーマに従ってください。

opencode doctor や TUI が非推奨警告を出力した場合は、次のメジャーバージョンまでに移行してください。

モデルの提供状況は頻繁に変わります。アップグレード前:

コマンドはインストール方法によって異なります。

macOS / Linux (インストールスクリプト): スクリプトを再実行。現バージョンを検出してその場で置き換えます。curl -fsSL https://opencode.ai/install | bash
Homebrew: brew upgrade anomalyco/tap/opencode (公式 formula の場合は opencode をアップグレード)
npm / pnpm / yarn: npm i -g opencode-ai@latest (各パッケージマネージャに合わせて)
Scoop / Chocolatey: scoop update opencode または choco upgrade opencode
Docker: 新イメージを取得してコンテナを再起動。サポート対象タグは Docker ガイドを参照。
Desktop アプリ: アプリ内アップデータ (Help → Check for Updates) を使用、またはダウンロードページから再インストール。

アップグレード後:

アップグレード後に重要なワークフローが壊れた場合:

毎回アップグレードする必要はありません。以下のような場合はスキップして構いません: