OpenCode v2 khác gì v1? Cách hiểu đúng trước khi nâng cấp

V2 không phải một bản update kiểu brew upgrade rồi quên đi v1. Nó là bản viết lại: runtime mới (Node), server API mới, desktop app mới (Electron). Nhưng nó cũng không bắt bạn phải migrate config ngay — v2 đọc config v1 và translate trong memory.

Điểm cần nắm trước khi nâng cấp: sau GA, installer v2 thay binary v1 chứ không chạy song song mặc định. Muốn giữ đường lui thì phải chủ động backup hoặc cài v2 vào một đường dẫn riêng (phần cuối bài có cách làm thật).

---

Tóm tắt nhanh

Nếu bạn chỉ cần câu trả lời ngắn:

• OpenCode v2 đã GA ngày 11/09/2026, tính đến giữa tháng 09 đã tới 2.0.x với patch dày.
• Cài bằng curl -fsSL https://opencode.ai/v2/install | bash hoặc npm @opencode/cli (không còn là @opencode-ai/cli@next như thời beta).
• Cả hai thế hệ dùng chung lệnh opencode; installer v2 thay binary v1 — không side-by-side mặc định như thời beta.
• V2 đọc được config v1 và translate trong runtime, chưa cần rewrite opencode.json.
• Skills, commands, agents file-based nhìn chung tương thích (test thật: hub 400+ skills load bình thường).
• Rủi ro thật sự nằm ở plugin API (plugin v1 không chạy trên v2), server API/client contract, TUI config và một số field MCP/permission.
• v1 không chết ngay: kênh GitHub vẫn phát hành bản 1.18.x sau ngày GA của v2.

Lệnh thử nhanh:

curl -fsSL https://opencode.ai/v2/install | bash
opencode --version   # -> opencode v2.0.x
cd /path/to/your/project
opencode

Timeline ra mắt

---

Vì sao v2 đáng chú ý?

OpenCode v1 đã mạnh ở đúng thứ developer thích: CLI-first, open source, nhiều provider, có agents, skills, commands, MCP, permissions, custom workflows. Nhưng càng dùng sâu thì config càng thành một lớp vận hành thật sự, không còn là vài dòng setting.

V2 đang cố làm lớp này rõ ràng hơn.

Thay vì nhiều field cũ có ý nghĩa hơi ngầm, v2 đẩy config sang hướng explicit hơn: providers, agents, permissions, mcp.servers, share, media, snapshots. Đây không chỉ là đổi tên field. Nó cho thấy OpenCode đang trưởng thành từ một CLI tool thành một runtime cho AI coding workflow.

Đã hết thời beta, nhưng bài học vẫn nguyên: đừng nâng cấp bằng niềm tin, hãy nâng cấp bằng checklist.

---

Bảng so sánh OpenCode v1 và v2

---

Điểm dễ hiểu nhầm nhất: v2 không bắt bạn migrate config ngay

Nhiều người nghe "v2 có config format mới" sẽ nghĩ việc đầu tiên là mở opencode.json và sửa hàng loạt field.

Không nên.

Docs v2 nói rõ OpenCode 2 vẫn đọc config global/project ở các vị trí quen thuộc:

~/.config/opencode/opencode.json(c)
<project>/opencode.json(c)
<project>/.opencode/opencode.json(c)

Nếu file đang theo shape v1, v2 sẽ detect và translate trong memory, không rewrite file gốc. Nghĩa là bạn có thể thử v2 mà không động vào config đang chạy ổn cho v1.

Đây là design khá hợp lý. Với AI coding tool, config không chỉ là preference. Nó chứa provider, model routing, permission, MCP server, skills, commands, agent behavior. Migrate nhầm một field permission hoặc MCP là đủ làm workflow lệch ngay.

---

Breaking changes thật sự nằm ở đâu?

Theo docs migration, v2 có ba nhóm breaking change có chủ đích:

1. Plugin API mới.
2. Server API và client contracts mới.
3. TUI config chuyển từ layered tui.json(c) sang một file global cli.json.

Phần còn lại được kỳ vọng tương thích với v1, đặc biệt là file-based definitions trong .opencode/: agents, commands, skills và server config. Docs v2 nói thẳng: nếu một thứ v1 đang chạy ổn mà v2 không chạy, hãy coi đó là compatibility bug để báo issue, không phải yêu cầu migration bình thường.

Với người dùng phổ thông, điều này nghĩa là:

• Nếu bạn chỉ dùng CLI, provider API key, skills, commands cơ bản: v2 đáng để thử.
• Nếu bạn có plugin tự viết, integration gọi server API, MCP production, permission rules phức tạp: phải test kỹ hơn.
• Nếu bạn đang vận hành OpenCode như một phần của team workflow, chưa nên thay binary mặc định.

---

Ví dụ khác biệt config

Sharing

V1:

{
  "autoshare": true
}

V2:

{
  "share": "auto"
}

V2 rõ ràng hơn vì không chỉ có boolean. Bạn có thể chọn manual, auto, hoặc disabled.

Permissions

V1:

{
  "permission": {
    "bash": {
      "git push *": "ask"
    },
    "edit": "allow"
  },
  "tools": {
    "websearch": false
  }
}

V2:

{
  "permissions": [
    { "action": "shell", "resource": "git push *", "effect": "ask" },
    { "action": "edit", "resource": "*", "effect": "allow" },
    { "action": "websearch", "resource": "*", "effect": "deny" }
  ]
}

V2 verbose hơn, nhưng đổi lại rule order và exception dễ audit hơn. Với team có nhiều repo, đây là hướng tốt hơn vì permission là một lớp bảo mật, không phải cosmetic config.

MCP server

V1:

{
  "mcp": {
    "playwright": {
      "type": "local",
      "command": ["npx", "@playwright/mcp"],
      "enabled": true,
      "timeout": 30000
    }
  }
}

V2:

{
  "mcp": {
    "servers": {
      "playwright": {
        "type": "local",
        "command": ["npx", "@playwright/mcp"],
        "disabled": false,
        "timeout": {
          "catalog": 30000,
          "execution": 30000
        }
      }
    }
  }
}

Đây là chỗ cần cẩn thận vì enabled: true ở v1 thành disabled: false ở v2. Nếu migrate máy móc rất dễ đảo nghĩa.

---

Cài thử trên macOS thật (18/09/2026)

Không nói lý thuyết suông — dưới đây là kết quả cài v2.0.6 lên một máy đang chạy OpenCode v1 hằng ngày, config tương đối nặng (provider custom qua gateway riêng, hub vài trăm skills, MCP, plugin local):

• Auth migrate sạch: toàn bộ credential (API key + OAuth của vài provider) được v2 nhận diện ngay, không cần login lại.
• Provider custom vẫn chạy: cấu hình provider dạng v1 (dùng field npm) được translate trong memory; model mặc định qua gateway riêng trả lời bình thường. Lưu ý nhỏ: provider custom không hiện trong opencode models (lệnh này chỉ list provider catalog) — đừng tưởng gãy, cứ opencode run thử.
• Skills hub load nguyên vẹn: agent tự báo thấy cả vài trăm skill trong context.
• Tự update hoạt động: cài 2.0.6 buổi sáng, chiều đã tự lên 2.0.7 — field autoupdate của v1 được normalize thành update: "auto" và chạy thật.
• Gotcha PATH: installer đặt binary vào ~/.opencode/bin/ nhưng không tự thêm vào PATH — mở terminal gõ opencode sẽ "command not found" nếu thư mục đó chưa có trong PATH. Cách xử lý đơn giản:

ln -sf ~/.opencode/bin/opencode ~/.local/bin/opencode

(nếu ~/.local/bin đã có trong PATH, cách đa số máy macOS dùng qua ~/.zprofile).

• Desktop app v1 trong /Applications không bị đụng — CLI v2 cài song song độc lập với app. Muốn bản desktop v2 (Electron) phải tải .dmg riêng.

Điều chưa verify trong buổi thử: 2 plugin v1 local được opencode plugin list liệt kê nhưng chưa test chạy thật — docs nói rõ plugin API v1 phải port. TUI tương tác cần bạn tự mở terminal trải nghiệm.

---

Lộ trình nâng cấp an toàn

Đây là cách mình khuyên dùng cho developer đã có OpenCode v1 chạy ổn.

Bước 1: Cài v2 — và biết rõ nó thay cái gì

curl -fsSL https://opencode.ai/v2/install | bash
opencode --version

Khác thời beta: giờ installer thay binary v1, không còn side-by-side mặc định. Muốn giữ đường lui:

• nếu v1 cài bằng package manager (brew/npm): giữ lại công thức cũ để rollback (brew install lại bản v1 khi cần);
• nếu muốn hai bản cạnh nhau: cài v2 rồi symlink thủ công như phần trên (~/.local/bin/opencode), giữ binary v1 ở đường dẫn khác và điều khiển thứ tự PATH.

Bước 2: Mở trong repo ít rủi ro

cd /path/to/small-project
opencode

Test các workflow cơ bản:

• hỏi về codebase;
• sửa một file nhỏ;
• dùng /undo;
• kiểm tra diff;
• chạy command không nguy hiểm;
• kiểm tra provider và model bằng /connect, /models.

Bước 3: Kiểm tra skills, commands, agents

Nếu bạn dùng .opencode/skills, .opencode/commands, hoặc custom agents, hãy chạy từng nhóm nhỏ.

Không cần rewrite skill body chỉ vì v2. Quan trọng là kiểm tra discovery và behavior:

• skill có hiện đúng không;
• agent có đọc đúng system prompt không;
• command có giữ đúng template/model không;
• permission có chặn đúng hành động cần chặn không.

Bước 4: Kiểm tra MCP và plugin riêng

Đây là vùng không nên làm qua loa.

Với MCP, kiểm tra:

• server có load catalog không;
• tool có chạy được không;
• timeout có đủ không;
• server production/write-capable có bị disable mặc định đúng như policy không.

Với plugin, coi như phải migrate theo API mới. Đừng giả định plugin v1 chạy trực tiếp trên v2.

Bước 5: Chỉ migrate native v2 khi đã có lý do

Bạn chỉ nên convert opencode.json sang native v2 khi:

• v2 đã chạy ổn với workflow hằng ngày;
• bạn muốn config explicit hơn để team audit;
• bạn cần dùng tính năng native v2 không tiện giữ ở shape v1;
• bạn đã có backup hoặc git-tracked config.

Prompt migration được docs gợi ý có thể viết kiểu:

Migrate my OpenCode configuration, including file-based definitions, from the V1 format to the native V2 format.
Preserve its behavior and all unrelated settings.

Điểm quan trọng là không mix field v1 và v2 thủ công trong một file nếu bạn không chắc.

---

Nên dùng v2 ngay chưa?

Câu trả lời thực tế sau GA: cá nhân thì chuyển dần được, team thì vẫn nên chạy pilot.

Nếu bạn là cá nhân dùng OpenCode để code, đọc repo, sửa task nhỏ: v2 đã ổn để dùng hằng ngày — config cũ chạy được, skills load, auth migrate. V1 vẫn được maintain nên không có áp lực nhảy ngay.

Nếu bạn đang dùng OpenCode trong môi trường team, có plugin tự viết, integration gọi server API, MCP production, permission phức tạp: v2 nên được xem như môi trường pilot cho tới khi port xong plugin và integration. Đây là hai thứ không có đường tắt — API mới là breaking thật.

Nâng cấp đúng vẫn là:

backup đường lui -> cài v2 -> smoke test -> port plugin/integration -> migrate config native (tuỳ chọn)

---

Kết luận

OpenCode v2 không chỉ là đổi số phiên bản. Nó là dấu hiệu OpenCode đang chuẩn hóa lớp vận hành phía sau AI coding: provider routing, permissions, agents, skills, MCP, commands, media, sharing và server API — viết lại trên runtime Node, kèm desktop app Electron và terminal builtin.

Điểm tốt là v2 không bắt người dùng v1 nhảy ngay: config cũ được đọc và translate trong memory, skills/commands/agents file-based tương thích, v1 vẫn nhận bản vá.

Điểm cần tỉnh táo: plugin API và server API là breaking change thật — chúng là thứ quyết định bạn chuyển được hay chưa, không phải số phiên bản. Và sau GA, installer thay binary v1, nên "giữ đường lui" là việc bạn phải chủ động làm, không còn mặc định như thời beta.

Gợi ý ngắn gọn: cài v2, chạy thử workflow hằng ngày trong một tuần; song song đó port plugin và integration. Khi cả hai xong, chuyển hẳn — v1 chỉ còn là bản vá chờ hết thời.

---

Nguồn tham khảo

• OpenCode v2 Get started
• OpenCode v2 Migrate from V1
• OpenCode v2 Config
• npm @opencode/cli — mốc publish các bản 2.0.x
• Bản phát hành v1 (sst/opencode)