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

OpenCode v2 không phải là một bản update kiểu brew upgrade rồi quên đi v1. Tính đến ngày 04/08/2026, docs chính thức vẫn gọi đây là beta của OpenCode 2.0. Binary mới là opencode2, còn OpenCode v1 vẫn chạy bằng opencode.

Điểm này rất quan trọng: v2 được thiết kế để chạy song song với v1. Bạn có thể cài thử, mở trong một repo nhỏ, kiểm tra provider/model/MCP/skills, rồi mới quyết định có dùng hằng ngày hay chưa.

---

Tóm tắt nhanh

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

• OpenCode v2 hiện là beta, chưa nên thay v1 ngay.
• V2 cài bằng package @opencode-ai/cli@next và chạy bằng lệnh opencode2.
• V2 đọc được config v1 và translate trong runtime, nên chưa cần rewrite opencode.json.
• Skills, commands, agents file-based nhìn chung vẫn tương thích.
• Rủi ro lớn nhất nằm ở plugin API, server API/client contract, TUI config, MCP và permission rules.
• Cách nâng cấp an toàn là cài song song, smoke test, rồi mới migrate config native v2 nếu cần.

Lệnh thử nhanh:

npm install -g @opencode-ai/cli@next
opencode2 --version
cd /path/to/your/project
opencode2

Trong TUI, dùng:

/connect
/models

---

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.

Nhưng vì đang beta, bài học thực tế là: đừ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. Nếu một thứ v1 đang chạy ổn mà v2 không chạy, docs xem đó là beta compatibility bug hơn là 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.

---

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 song song

npm install -g @opencode-ai/cli@next
opencode2 --version

Không alias opencode sang opencode2. Cứ để v1 và v2 tồn tại cạnh nhau.

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

cd /path/to/small-project
opencode2

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ế: nên thử, chưa nên ép thay v1.

Nếu bạn là cá nhân dùng OpenCode để code, đọc repo, sửa task nhỏ, v2 đáng thử vì cài song song khá an toàn. Nếu lỗi, quay lại opencode v1.

Nếu bạn đang dùng OpenCode trong môi trường team, có MCP nội bộ, permission phức tạp, plugin riêng, workflow production hoặc automation dựa vào server API, thì v2 nên được xem như môi trường pilot.

OpenCode v2 là bước chuyển tốt vì nó làm runtime rõ ràng hơn. Nhưng chính vì nó chạm vào runtime, nâng cấp đúng không phải là "install xong là xong". Nâng cấp đúng là:

cài song song -> smoke test -> kiểm tra workflow -> migrate có kiểm soát

---

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.

Điểm tốt là v2 không bắt người dùng v1 nhảy ngay. Bạn có thể giữ opencode, cài thêm opencode2, dùng config cũ, rồi kiểm từng phần.

Điểm cần tỉnh táo là beta vẫn là beta. Plugin API, server API, TUI config và một số field permission/MCP là những chỗ phải test thật, nhất là nếu bạn đã dùng OpenCode như một phần của hệ thống làm việc hằng ngày.

Gợi ý ngắn gọn: cài v2 để học và thử workflow mới, nhưng giữ v1 làm đường lui cho đến khi toàn bộ provider, skills, commands, MCP và plugin của bạn đã được verify.

---

Nguồn tham khảo

• OpenCode v2 Get started
• OpenCode v2 Migrate from V1
• OpenCode v2 Config