---
title: "OpenCode 2.0 大改版：三項刻意的不兼容變更與遷移路徑"
url: https://sammy.hk/opencode-2-0-%e5%a4%a7%e6%94%b9%e7%89%88%ef%bc%9a%e4%b8%89%e9%a0%85%e5%88%bb%e6%84%8f%e7%9a%84%e4%b8%8d%e5%85%bc%e5%ae%b9%e8%ae%8a%e6%9b%b4%e8%88%87%e9%81%b7%e7%a7%bb%e8%b7%af%e5%be%91/
author: Ethan
published: 2026-10-13T10:41:00+08:00
modified: 2026-10-13T10:31:22+08:00
description: "開源 AI 編程工具 OpenCode 發布 2.0 版本。官方在遷移文件中指出，OpenCode 1 與 OpenCode 2 同樣使用 opencode 指令，但預設不再並存安裝；若以套件管理器安裝過 V1，需先移除，因為 V2 的 curl 安裝程式會取代 V1 的執行檔。[1] 三項刁意的不兼容變更 官方列出 …"
categories: [AI, "開放源碼"]
tags: ["AI 編程", OpenCode, "插件 API", "遷移", "開源工具"]
source: https://sammy.hk
---
![OpenCode 2.0 major release with three breaking changes and migration guide](https://sammy.hk/wp-content/uploads/2026/10/openrouter_google_gemini-3_1-flash-lite-image_20261013_103038_3801c85b.jpg)開源 AI 編程工具 OpenCode 發布 2.0 版本。官方在遷移文件中指出，OpenCode 1 與 OpenCode 2 同樣使用 `opencode` 指令，但預設不再並存安裝；若以套件管理器安裝過 V1，需先移除，因為 **V2 的 curl 安裝程式會取代 V1 的執行檔**。\[1\]

## 三項刁意的不兼容變更

官方列出 V2 的三項刁意不兼容變更：\[1\]

- **插件**：使用新的插件 API
- **伺服器 API 與客戶端**：採用新的契約
- **終端客戶端設定**：由分層的 `tui.json(c)` 檔案，改為單一的全局 `cli.json` 檔案（會自動遷移）

官方指出，上述範圍以外受支援的 V1 功能，預期仍與 V1 兼容；一些 V1 架構接收、但在 V2 沒有對應的位置會被刁意忽略，並已在文件中列出。已有受支援的伺服器設定位置、代理定義、指令定義、技能，以及 `.opencode/` 下的其他檔案，繼可繼續運作而毋需改動；官方強調，若文件所謂受支援的行為在 V2 失效，視之為兼容性錯誤，而非預期的遷移要求。\[1\]

## 官方建議的遷移步驟

官方表示，使用者需在開始使用 V2 前重覽所有內容，實務上的遷移順序為：\[1\]

1. 保留現有設定與檔案定義
2. 啟動 V2，並核對模型、認證、代理、權限與 MCP 伺服器
3. 移植插件，因為 V1 的插件無法在 V2 執行
4. 移植呼叫伺服器 API 的整合
5. 準備好時才把設定轉為原生 V2 格式（此步驟可選）

官方提醒，驗證遷移期鋒保留 V1 設定的副本；由於 V1 與 V2 使用相同的設定位置，不要把 V1 指向已轉為原生 V2 專用格式的檔案。\[1\]

## 設定與插件格式

官方指出，V2 會從與 V1 相同的位置讀取全局與專案設定（`~/.config/opencode/opencode.json(c)`、專案根目錄的 `opencode.json(c)`、以及 `/.opencode/opencode.json(c)`），並在記憶體中把受支援的 V1 位置與原生 V2 位置正規化，而不改來源檔案；V1 設定格式仍受支援。\[1\]

插件方面，設定鍵由 `plugin` 改名為 `plugins`，原本的「套件+選項」元組改為物件形式；V2 會同時從 `.opencode/plugin/` 與 `.opencode/plugins/` 發現本機插件，官方建議 V2 檔案放在後者。\[1\]

## 伺服器 API

官方指出，V2 有修訂後、更易用的伺服器 API 與一組新客戶端；呼叫 V1 伺服器 API 的整合必須遷移至 V2 API，並可使用 `@opencode/client` 套件存取已發布的 V2 API。\[1\]\[2\]

## 參考資料

\[1\] [OpenCode 官方文件 — Migrate from V1](https://opencode.ai/v2/docs/migrate-v1/)
\[2\] [OpenCode 官方 — 更新記錄 (Changelog)](https://opencode.ai/changelog)

### 相關文章：

1. [阿里巴巴開源 AI 程式碼評審工具 OpenCodeReview](https://sammy.hk/%e9%98%bf%e9%87%8c%e5%b7%b4%e5%b7%b4%e9%96%8b%e6%ba%90-ai-%e7%a8%8b%e5%bc%8f%e7%a2%bc%e8%a9%95%e5%af%a9%e5%b7%a5%e5%85%b7-opencodereview/ "阿里巴巴開源 AI 程式碼評審工具 OpenCodeReview")
2. [GitHub 用開源 AI 安全代理找出 24 個 Android 漏洞：方法與自身限制](https://sammy.hk/github-%e7%94%a8%e9%96%8b%e6%ba%90-ai-%e5%ae%89%e5%85%a8%e4%bb%a3%e7%90%86%e6%89%be%e5%87%ba-24-%e5%80%8b-android-%e6%bc%8f%e6%b4%9e%ef%bc%9a%e6%96%b9%e6%b3%95%e8%88%87%e8%87%aa%e8%ba%ab%e9%99%90/ "GitHub 用開源 AI 安全代理找出 24 個 Android 漏洞：方法與自身限制")
3. [Docker 開源 Docker Agent：以 YAML 定義、可推到 OCI 註冊庫的 AI 代理](https://sammy.hk/docker-%e9%96%8b%e6%ba%90-docker-agent%ef%bc%9a%e4%bb%a5-yaml-%e5%ae%9a%e7%be%a9%e3%80%81%e5%8f%af%e6%8e%a8%e5%88%b0-oci-%e8%a8%bb%e5%86%8a%e5%ba%ab%e7%9a%84-ai-%e4%bb%a3%e7%90%86/ "Docker 開源 Docker Agent：以 YAML 定義、可推到 OCI 註冊庫的 AI 代理")
4. [GitHub 用 AI 代理把 Copilot 執行時重寫為 Rust：832,378 行與 96% 提示快取命中](https://sammy.hk/github-%e7%94%a8-ai-%e4%bb%a3%e7%90%86%e6%8a%8a-copilot-%e5%9f%b7%e8%a1%8c%e6%99%82%e9%87%8d%e5%af%ab%e7%82%ba-rust%ef%bc%9a832378-%e8%a1%8c%e8%88%87-96-%e6%8f%90%e7%a4%ba%e5%bf%ab%e5%8f%96%e5%91%bd/ "GitHub 用 AI 代理把 Copilot 執行時重寫為 Rust：832,378 行與 96% 提示快取命中")