# opencode: trợ lý lập trình AI mã nguồn mở — hướng dẫn cài đặt và dùng

> OpenCode là coding agent AI mã nguồn mở viết bằng TypeScript, giúp bạn khám phá code, lập kế hoạch và thực hiện công việc phát triển phần mềm. Repo có nhiều cách cài trên macOS, Linux và Nix; Windows có ứng dụng desktop beta nên người mới có thể bắt đầu khá dễ.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-06-30 · Cập nhật: 2026-11-14
- URL: https://ongt.vn/bai-viet/opencode-tro-ly-lap-trinh-ai-ma-nguon-mo-8

OpenCode là một coding agent AI mã nguồn mở, dùng để hỗ trợ bạn đọc hiểu và phát triển phần mềm. Thay vì chỉ trả lời từng câu hỏi, agent có thể làm việc trong bối cảnh của cả codebase, giúp tìm kiếm nhiều bước, phân tích cấu trúc và hỗ trợ thực hiện công việc phát triển.

Công cụ này phù hợp với lập trình viên mới muốn có trợ lý khi làm quen dự án, dev đã có kinh nghiệm cần tăng tốc công việc, hoặc nhóm kỹ thuật muốn thử một coding agent có mã nguồn mở. Điểm đáng chú ý là OpenCode có sẵn agent `build` để làm việc đầy đủ và agent `plan` chỉ đọc để khảo sát, lập kế hoạch an toàn hơn.

Repo hiện có khoảng 226580 sao và 30675 fork. Dự án dùng TypeScript, giấy phép MIT và vẫn còn được cập nhật. README cung cấp nhiều lựa chọn cài đặt, từ npm, Homebrew, Nix đến ứng dụng desktop beta.

```repo
- repo | anomalyco/opencode
- kind | Agent
- desc | OpenCode là coding agent AI mã nguồn mở, hỗ trợ đọc, phân tích và phát triển dự án ngay trong môi trường làm việc.
- stars | 227k
- lang | TypeScript
- license | MIT
```

## OpenCode làm được gì

### Hỗ trợ phát triển trong codebase

OpenCode được mô tả là một open source AI coding agent. Giá trị chính của nó nằm ở việc hỗ trợ các công việc gắn với dự án, thay vì chỉ tạo một đoạn mã rời rạc. Bạn có thể dùng agent để đọc các file liên quan, tìm phần cần sửa, phân tích cách dự án đang vận hành và trao đổi về hướng triển khai.

Điều này hữu ích khi bạn nhận một codebase chưa quen. Bạn có thể bắt đầu bằng việc hỏi agent giải thích cấu trúc hoặc tìm luồng xử lý của một tính năng, rồi mới quyết định có thay đổi gì hay không.

### Có agent build cho công việc phát triển

`build` là agent mặc định và có toàn quyền truy cập cho công việc phát triển theo README. Đây là lựa chọn phù hợp khi bạn muốn OpenCode hỗ trợ xử lý một nhiệm vụ cụ thể trong dự án.

Bạn vẫn nên xem lại đề xuất và thay đổi trước khi đưa vào sản phẩm. Quyền truy cập đầy đủ có thể giúp công việc nhanh hơn, nhưng cũng đòi hỏi bạn kiểm tra kỹ lệnh, file và phạm vi thay đổi.

### Có agent plan chỉ đọc

`plan` là agent chỉ đọc, được thiết kế cho phân tích và khám phá code. Agent này mặc định từ chối chỉnh sửa file và hỏi quyền trước khi chạy lệnh bash.

Đây là lựa chọn tốt cho lần đầu mở một dự án lạ. Bạn có thể dùng nó để hiểu cấu trúc, xác định nguyên nhân có thể gây lỗi hoặc lập kế hoạch sửa trước khi chuyển sang công việc triển khai.

### Có subagent general cho tìm kiếm phức tạp

OpenCode có thêm subagent `general` cho các tìm kiếm phức tạp và công việc nhiều bước. README cho biết có thể gọi subagent này trong tin nhắn bằng `@general`.

Trong thực tế, bạn có thể dùng cách này khi câu hỏi cần rà qua nhiều phần của codebase hoặc cần kết hợp nhiều bước tìm hiểu. README không mô tả chi tiết cú pháp hay giới hạn của subagent ngoài cách gọi trên.

### Chuyển agent bằng phím Tab

Hai agent tích hợp là `build` và `plan`, và bạn có thể chuyển qua lại bằng phím `Tab`. Cách này giúp bạn đổi từ khảo sát an toàn sang phát triển khi đã hiểu rõ nhiệm vụ.

Một quy trình dễ áp dụng là bắt đầu ở `plan`, yêu cầu agent mô tả các file liên quan và kế hoạch sửa, sau đó chuyển sang `build` khi bạn đã kiểm tra hướng đi.

### Nhiều cách cài đặt

README có lệnh cài qua script, npm, Bun, pnpm, Yarn, Homebrew, pacman, AUR, mise và Nix. Bạn không nhất thiết phải dùng cách phức tạp nhất; hãy chọn công cụ quản lý gói đã quen thuộc trên hệ điều hành của mình.

Ngoài CLI, OpenCode còn có ứng dụng desktop beta. README liệt kê bộ cài cho macOS Apple Silicon, macOS Intel, Windows và Linux.

## Cần chuẩn bị gì

Bạn cần một máy tính chạy hệ điều hành được README hỗ trợ qua một trong các cách cài đặt. Với CLI, README nêu các lựa chọn cho macOS, Linux, Arch Linux, Nix và “Any OS” khi dùng mise. Với Windows, README liệt kê ứng dụng desktop beta dạng `opencode-desktop-win-x64.exe`.

Bạn cần chọn phương thức cài phù hợp. Nếu dùng npm, Bun, pnpm hoặc Yarn thì máy cần có trình quản lý gói tương ứng. README chỉ ghi lệnh npm cụ thể và nói có thể dùng Bun, pnpm hoặc Yarn; tài liệu được cung cấp không nêu phiên bản Node.js bắt buộc.

Nếu dùng Homebrew, bạn cần có Homebrew. Nếu dùng pacman hoặc AUR, bạn cần môi trường Arch Linux và công cụ tương ứng. Nếu dùng Nix, bạn cần Nix. Nếu dùng mise, bạn cần mise.

README không nêu yêu cầu GPU, RAM, tài khoản bắt buộc, API key hay nhà cung cấp mô hình. Vì vậy, không nên tự suy đoán các yêu cầu này từ tài liệu hiện có. README cũng không mô tả chi tiết cách cấu hình mô hình sau khi cài; phần hướng dẫn cấu hình được chỉ tới khu vực tài liệu của dự án.

README ghi rằng script cài đặt đặt OpenCode vào `$HOME/.opencode/bin`. Bạn cần lưu ý đường dẫn này khi kiểm tra lệnh sau khi cài hoặc khi terminal chưa nhận diện được chương trình.

Nếu đang dùng bản OpenCode cũ hơn `0.1.x`, README khuyên xóa các phiên bản cũ trước khi cài. Tài liệu không cung cấp lệnh xóa cụ thể, nên bạn cần xử lý theo cách quản lý gói đã dùng trước đó.

## Cài đặt từng bước

```steps
- Chọn cách cài | Chọn CLI, trình quản lý gói hoặc desktop theo hệ điều hành
- Cài OpenCode | Chạy đúng lệnh tương ứng trong terminal
- Mở ứng dụng | Khởi động CLI hoặc bộ cài desktop đã tải
- Chọn agent | Dùng Tab để chuyển giữa build và plan
- Đọc tài liệu | Xem phần cấu hình và agent trong repo khi cần
```

### Chọn phương thức cài

Nếu bạn dùng macOS hoặc Linux và muốn cài CLI nhanh, README cung cấp script chính thức. Nếu máy đã có npm, bạn có thể cài gói toàn cục. Homebrew cũng có hai công thức: một công thức được README đánh dấu là luôn cập nhật và một công thức chính thức nhưng cập nhật chậm hơn.

Trên Windows, README cung cấp ứng dụng desktop beta dạng file `.exe`. Đây là lựa chọn trực tiếp nhất được tài liệu nêu cho Windows. README không đưa ra lệnh cài CLI riêng cho Windows.

### Cài bằng script trên macOS hoặc Linux

Mở terminal. Bạn có thể mở terminal từ thư mục dự án nếu muốn dùng OpenCode ngay tại dự án đó, hoặc chạy script trước rồi mở thư mục sau.

```bash
# YOLO
curl -fsSL https://opencode.ai/v2/install | bash
```

Lệnh này tải script cài đặt từ địa chỉ được README cung cấp rồi chuyển cho `bash` thực thi. Sau khi cài, README cho biết file được đặt trong `$HOME/.opencode/bin`.

Cách cài bằng script thuận tiện nhưng bạn nên hiểu rằng nó thực thi nội dung tải từ Internet. Nếu môi trường công ty có quy định bảo mật, hãy kiểm tra chính sách trước khi dùng. Nếu terminal báo không tìm thấy lệnh sau cài, nguyên nhân thường là thư mục cài chưa có trong PATH; README chỉ xác nhận vị trí cài, chưa ghi lệnh thêm PATH cụ thể.

### Cài bằng npm hoặc trình quản lý gói

Nếu máy đã có npm, chạy lệnh sau trong terminal:

```bash
npm i -g @opencode/cli@latest
```

Lệnh này cài CLI OpenCode ở phạm vi toàn cục và chọn bản `latest`. README cũng ghi có thể dùng Bun, pnpm hoặc Yarn, nhưng không đưa lệnh đầy đủ cho từng công cụ. Vì vậy, không nên tự thêm tên gói hoặc cờ lệnh khác nếu chưa kiểm tra tài liệu tương ứng.

Nếu bạn muốn cài qua Homebrew trên macOS hoặc Linux, README cung cấp hai lệnh sau:

```bash
brew install anomalyco/tap/opencode-v2
brew install opencode
```

Lệnh đầu tiên được README đánh dấu là khuyến nghị và luôn cập nhật. Lệnh thứ hai là công thức brew chính thức nhưng được cập nhật ít thường xuyên hơn.

### Cài trên Arch Linux, mise hoặc Nix

Với Arch Linux, README đưa ra lựa chọn bản ổn định và bản mới từ AUR:

```bash
sudo pacman -S opencode
paru -S opencode-beta
```

Lệnh đầu dùng `pacman` để cài gói `opencode`. Lệnh thứ hai dùng `paru` để cài `opencode-beta`. Chỉ dùng lệnh `paru` nếu máy bạn đã có công cụ này và bạn hiểu chính sách của AUR.

README cũng hỗ trợ mise và Nix:

```bash
mise use -g opencode
nix run github:anomalyco/opencode
```

`mise use -g opencode` đặt OpenCode ở phạm vi toàn cục theo mise. `nix run github:anomalyco/opencode` chạy OpenCode thông qua Nix. README không mô tả sâu hơn về cách cập nhật hoặc ghim phiên bản cho hai phương thức này.

### Cài ứng dụng desktop beta

README cho biết OpenCode có ứng dụng desktop beta và cung cấp bộ cài theo nền tảng:

- macOS Apple Silicon: `opencode-desktop-mac-arm64.dmg`
- macOS Intel: `opencode-desktop-mac-x64.dmg`
- Windows: `opencode-desktop-win-x64.exe`
- Linux: `.deb`, `.rpm` hoặc `.AppImage`

Bạn tải đúng bộ cài cho kiến trúc và hệ điều hành của mình, sau đó mở bộ cài để thực hiện các bước cài đặt của hệ điều hành. README không ghi quy trình màn hình chi tiết cho từng nền tảng.

Trên macOS, README có thêm lệnh Homebrew:

```bash
brew install --cask opencode-desktop
```

Lệnh này cài ứng dụng desktop qua Homebrew Cask. Tài liệu được cung cấp không nói ứng dụng desktop beta có toàn bộ tính năng giống CLI hay yêu cầu cấu hình riêng nào.

### Chạy trong một dự án

Sau khi cài, mở terminal tại thư mục dự án mà bạn muốn khám phá hoặc phát triển rồi khởi động OpenCode theo cách cài đã chọn. README được cung cấp không có lệnh khởi động CLI riêng, cũng không có ví dụ phiên làm việc hoàn chỉnh.

Nếu bạn làm việc từ source code của repo, cấu trúc gốc có `package.json`, `bun.lock`, `bunfig.toml`, `turbo.json` và các thư mục `packages/`, `script/`, `sdks/`, `services/`, `specs/`. Tuy nhiên, nội dung `package.json` không được cung cấp trong tư liệu này. README cũng không ghi cách build từ source, nên chưa thể đưa ra lệnh build cụ thể mà không bịa thêm thông tin.

### Chọn agent đầu tiên

Khi OpenCode đã mở, dùng phím `Tab` để chuyển giữa hai agent tích hợp. Chọn `plan` nếu bạn đang đọc code hoặc muốn lập kế hoạch. Chọn `build` khi muốn làm công việc phát triển với quyền truy cập đầy đủ.

Bạn có thể gọi subagent tìm kiếm bằng cú pháp sau trong tin nhắn:

```text
@general
```

README chỉ xác nhận đây là cách gọi `general`; nó không cung cấp prompt mẫu hay danh sách tham số bổ sung.

## Kiểm tra đã chạy được chưa

Cách kiểm tra cơ bản là mở OpenCode thành công từ phương thức bạn đã cài. Với desktop, bạn cần thấy ứng dụng khởi động trên nền tảng tương ứng. Với CLI, bạn cần mở được phiên làm việc trong thư mục dự án.

Trong phiên làm việc, hãy thử nhấn `Tab`. Nếu có thể chuyển giữa `build` và `plan`, phần agent tích hợp đang hoạt động theo mô tả README. Chọn `plan` để xác nhận agent đọc và phân tích có thể được sử dụng.

Nếu cài bằng script, kiểm tra vị trí cài là `$HOME/.opencode/bin`, vì README ghi rõ đây là thư mục đích. Nếu terminal không nhận lệnh, hãy kiểm tra PATH và phiên terminal hiện tại. README không cung cấp câu lệnh kiểm tra phiên bản hoặc output mẫu cụ thể.

Bạn cũng có thể kiểm tra cấu trúc repo khi làm việc với source. Các file như `AGENTS.md`, `package.json`, `CHANGELOG.md` và `README.md` có trong cấu trúc gốc. Tuy nhiên, sự tồn tại của các file này không thay thế cho việc xác nhận CLI hoặc desktop đã chạy được.

## Dùng vào việc thật

### Lập trình viên mới nhận một dự án lạ

Bạn vừa được giao một codebase TypeScript nhưng chưa biết điểm bắt đầu. Mở dự án trong OpenCode, chọn `plan` bằng phím `Tab`, rồi yêu cầu agent giải thích cấu trúc thư mục, luồng chạy chính và các file cần đọc trước.

Một câu hỏi thực tế có thể là: “Hãy khám phá codebase này và lập kế hoạch để tôi hiểu luồng xử lý của tính năng đăng nhập. Chỉ đọc file, chưa chỉnh sửa.” Agent `plan` phù hợp vì README nói agent này dành cho phân tích, khám phá code và mặc định từ chối chỉnh sửa file.

Kết quả mong đợi là một hướng dẫn khảo sát dựa trên các file trong dự án. Bạn dùng kết quả đó để quyết định bước tiếp theo thay vì sửa code khi chưa hiểu bối cảnh.

### Dev cần tìm nguyên nhân một lỗi qua nhiều file

Một lỗi xảy ra ở giao diện nhưng nguyên nhân có thể nằm trong API, service hoặc phần cấu hình. Bạn có thể dùng `plan` để yêu cầu tìm toàn bộ luồng liên quan, hoặc gọi `@general` khi nhiệm vụ cần tìm kiếm phức tạp và nhiều bước.

Ví dụ: “@general hãy tìm các phần xử lý dữ liệu đơn hàng từ lúc nhận request đến lúc hiển thị kết quả, chỉ ra các file liên quan và điểm có thể gây lỗi.” README xác nhận `general` dùng cho các tìm kiếm phức tạp và công việc nhiều bước.

Kết quả hữu ích là danh sách file, mối liên hệ và giả thuyết cần kiểm tra. Vì README không cung cấp mẫu output, bạn nên xem đây là cách giao việc phù hợp với khả năng được mô tả, không phải một kết quả cố định.

### Dev đã có kế hoạch và muốn bắt đầu triển khai

Sau khi dùng `plan` để hiểu vấn đề, chuyển sang `build` bằng phím `Tab`. Bạn có thể đưa yêu cầu cụ thể như: “Thực hiện kế hoạch đã thống nhất cho tính năng này, chỉ thay đổi các file liên quan và giải thích các thay đổi.”

`build` là agent mặc định, có toàn quyền truy cập cho công việc phát triển theo README. Do đó, bạn nên nêu rõ phạm vi file, tiêu chí hoàn thành và yêu cầu xem lại thay đổi. Sau khi agent làm xong, hãy đọc diff và tự chạy kiểm thử của dự án nếu dự án có hướng dẫn riêng.

### Nhân viên văn phòng phối hợp với dev để mô tả yêu cầu

Nếu bạn không trực tiếp viết code nhưng cần trao đổi với đội kỹ thuật, có thể dùng OpenCode để hỏi về cấu trúc và khả năng của một dự án. Ví dụ, mở codebase và yêu cầu `plan` trả lời: “Tính năng này hiện được xử lý ở những phần nào? Nếu muốn thêm trường thông tin khách hàng, nhóm dev có thể cần thay đổi những khu vực nào?”

Cách dùng này giúp bạn biến một yêu cầu nghiệp vụ thành danh sách phần kỹ thuật cần thảo luận. Agent chỉ đọc sẽ phù hợp khi bạn chưa muốn tạo thay đổi trong repo.

> Hãy bắt đầu bằng việc hiểu code, rồi mới trao quyền thay đổi cho agent.
>
> — Ông T

### Người quản lý muốn thử coding agent mã nguồn mở

Nếu nhóm đang đánh giá một coding agent, hãy cài OpenCode trên máy thử nghiệm, mở một repo không chứa dữ liệu nhạy cảm và bắt đầu bằng `plan`. So sánh chất lượng phần giải thích code, khả năng tìm kiếm và kế hoạch xử lý trước khi cho agent `build` làm việc trên dự án thật.

README cho biết dự án có giấy phép MIT và vẫn được cập nhật. Tuy vậy, tài liệu được cung cấp không mô tả chính sách lưu trữ dữ liệu, mô hình AI, chi phí sử dụng hoặc cơ chế bảo vệ thông tin của từng cấu hình. Vì thế, nhóm cần tự kiểm tra các tài liệu cấu hình và chính sách liên quan trước khi đưa code nội bộ vào sử dụng.

## Lỗi hay gặp và cách xử lý

### Terminal không nhận diện được OpenCode sau khi cài

Script cài đặt đặt chương trình vào `$HOME/.opencode/bin`. Nếu terminal báo không tìm thấy lệnh, hãy kiểm tra thư mục này và PATH của phiên terminal hiện tại. Đóng rồi mở lại terminal có thể giúp nạp lại PATH, nhưng README không cung cấp lệnh sửa PATH cụ thể nên không nên tự thêm một cấu hình chưa kiểm tra.

### Cài nhầm phiên bản cũ

README khuyên xóa các phiên bản cũ hơn `0.1.x` trước khi cài. Lỗi thường xảy ra khi máy đã có bản cũ từ một phương thức khác như npm, Homebrew hoặc một bộ cài trước đó. Hãy xác định phương thức đã dùng để cài bản cũ rồi gỡ theo đúng công cụ đó; README không đưa lệnh gỡ chung.

### Chọn sai bộ cài desktop

macOS Apple Silicon và macOS Intel có file khác nhau. Windows dùng file `.exe`, còn Linux có `.deb`, `.rpm` hoặc `.AppImage`. Nếu ứng dụng không mở, hãy kiểm tra lại hệ điều hành và kiến trúc trước khi tải lại bộ cài phù hợp.

### Dùng agent build khi chỉ muốn khảo sát

`build` là agent mặc định và có toàn quyền truy cập cho công việc phát triển. Nếu bạn chỉ muốn đọc code, hãy chuyển sang `plan` bằng phím `Tab`. Agent này được thiết kế cho phân tích, mặc định từ chối chỉnh sửa và hỏi quyền trước khi chạy lệnh bash.

### Không biết cách build từ source

Repo có `package.json` và nhiều file phục vụ phát triển, nhưng README được cung cấp không ghi quy trình build từ source. Không nên tự đoán lệnh dựa trên tên file. Hãy xem `package.json`, `CONTRIBUTING.md` và các hướng dẫn trong repo để tìm quy trình chính thức.

```note
Agent có thể làm việc với file và lệnh trong dự án. Trước khi mở repo nội bộ hoặc cho agent build quyền truy cập đầy đủ, hãy kiểm tra dữ liệu nhạy cảm, quyền truy cập và chính sách của nhóm. Tư liệu hiện có chưa nêu chi tiết về API key, chi phí hoặc cách dữ liệu được xử lý.
```

## Có nên dùng không

Bạn nên thử OpenCode nếu muốn một coding agent mã nguồn mở, có nhiều lựa chọn cài đặt và có hai chế độ rõ ràng cho khảo sát và phát triển. Agent `plan` giúp giảm rủi ro khi bắt đầu với codebase lạ, còn `build` phù hợp khi bạn đã xác định nhiệm vụ. Việc có ứng dụng desktop beta cũng giúp người dùng Windows có một đường vào dễ hơn.

Repo có quy mô cộng đồng lớn, giấy phép MIT và vẫn được cập nhật. README cũng có nhiều bản ngôn ngữ và chỉ rõ các phương thức cài phổ biến. Đây là những điểm thuận lợi cho cá nhân, nhóm dev và người mới muốn thử coding agent.

Giới hạn lớn nhất của tư liệu hiện có là README không nêu chi tiết mô hình AI, API key, chi phí, yêu cầu phần cứng, lệnh khởi động CLI, quy trình build từ source hay chính sách dữ liệu. Ứng dụng desktop vẫn được đánh dấu beta. Nếu công ty yêu cầu kiểm soát chặt dữ liệu, quyền truy cập hoặc triển khai nội bộ, bạn nên đọc thêm tài liệu cấu hình và chính sách của dự án trước.

Nếu bạn chỉ cần một trình soạn thảo mã đơn giản, trợ lý hỏi đáp không truy cập codebase, hoặc công cụ đã có quy trình doanh nghiệp rõ ràng, OpenCode có thể chưa phải lựa chọn phù hợp nhất. Còn nếu mục tiêu là thử một coding agent mã nguồn mở có thể khám phá và hỗ trợ phát triển dự án, đây là repo đáng để cài thử bắt đầu từ agent `plan`.

## Câu hỏi thường gặp

### OpenCode có miễn phí không?

Repo có giấy phép MIT. Tuy nhiên, tư liệu được cung cấp không nói rõ chi phí của mô hình AI, API hoặc dịch vụ phía sau, nên chưa thể khẳng định toàn bộ quá trình sử dụng không phát sinh phí.

### Windows có chạy được OpenCode không?

README liệt kê ứng dụng desktop beta cho Windows với file `opencode-desktop-win-x64.exe`. README không cung cấp lệnh cài CLI riêng cho Windows.

### Có cần GPU không?

Tư liệu được cung cấp không nêu yêu cầu GPU. Không nên tự kết luận về phần cứng cần thiết nếu chưa xem thêm tài liệu cấu hình của dự án.

### Có cần API key không?

README được cung cấp không đề cập API key hoặc cách cấu hình nhà cung cấp mô hình. Bạn cần xem thêm tài liệu cấu hình trong dự án để biết yêu cầu cụ thể.

### OpenCode khác gì một chatbot viết code?

OpenCode được mô tả là coding agent, có thể hỗ trợ khám phá codebase và công việc phát triển. Repo có agent `plan` chỉ đọc, agent `build` cho phát triển và subagent `general` cho tìm kiếm phức tạp.

### Tôi nên dùng agent nào khi mới mở một dự án?

Nên bắt đầu với `plan` nếu bạn muốn đọc, phân tích và lập kế hoạch mà chưa sửa file. Khi đã hiểu nhiệm vụ và muốn triển khai, bạn có thể chuyển sang `build` bằng phím `Tab`.

### Có thể build OpenCode từ source không?

Repo có `package.json` cùng nhiều file phục vụ phát triển, nhưng README được cung cấp chưa ghi quy trình build từ source. Hãy xem `package.json` và `CONTRIBUTING.md` trong repo để tìm hướng dẫn chính thức.
