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

> opencode là một agent lập trình AI mã nguồn mở (MIT), viết bằng TypeScript, giúp bạn đọc, hiểu và sửa code bằng ngôn ngữ tự nhiên. Repo có hai agent dựng sẵn là build (toàn quyền) và plan (chỉ đọc). Cài đặt khá dễ: một dòng curl hoặc qua npm, Homebrew và vài trình quản lý gói khác, ngoài ra còn có bản ứng dụng desktop đang ở dạng BETA.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-08-02 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/opencode-tro-ly-lap-trinh-ai-ma-nguon-mo-huong-dan-cai-dat-mwell4hk

opencode là một agent lập trình AI mã nguồn mở. Bạn mô tả việc cần làm bằng lời thường, nó đọc code trong thư mục dự án và giúp bạn phân tích hoặc chỉnh sửa. Tác giả giới thiệu ngắn gọn: "The open source coding agent". Repo hiện có khoảng 226.506 sao và 30.658 fork, dùng giấy phép MIT, viết chủ yếu bằng TypeScript.

Bạn nên xem bài này nếu là lập trình viên mới, người làm văn phòng hay chủ shop có một ít code (website bán hàng, file xử lý dữ liệu, bot nhỏ) và muốn có một trợ lý ngồi cạnh để hỏi: "file này làm gì?", "sửa giúp mình chỗ này". Bạn không cần hiểu hết code, nhưng cần biết mở terminal và gõ lệnh.

Điều đáng giá nhất của opencode là cách chia quyền rõ ràng. Có sẵn một agent toàn quyền để làm việc, và một agent chỉ đọc để xem xét dự án mà không sợ nó lỡ tay sửa file. Với người mới, đây là lớp an toàn rất dễ hiểu.

```repo
- repo | anomalyco/opencode
- kind | Agent
- desc | opencode là agent lập trình AI mã nguồn mở, giấy phép MIT, có chế độ build để sửa code và chế độ plan chỉ đọc để phân tích dự án an toàn.
- stars | 227k
- lang | TypeScript
- license | MIT
```

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

README của repo khá ngắn, nên mình chỉ nói những gì nó ghi rõ.

### Hai agent dựng sẵn, đổi qua lại bằng phím Tab

opencode có hai agent bạn đổi qua lại bằng phím `Tab`:

- **build**: agent mặc định, toàn quyền, dùng cho công việc phát triển thực sự như viết thêm tính năng hay sửa lỗi.
- **plan**: agent chỉ đọc, dùng để phân tích và khám phá code. Mặc định nó từ chối sửa file, và hỏi bạn trước khi chạy lệnh bash.

Lợi ích thực tế: khi mới nhận một dự án lạ, bạn bật plan để nó giải thích cấu trúc, đề xuất hướng sửa. Khi đã ưng kế hoạch, bạn chuyển sang build để thực hiện.

### Subagent general cho việc tìm kiếm phức tạp

Ngoài hai agent trên còn có **general**, một subagent dành cho tìm kiếm phức tạp và các việc nhiều bước. README cho biết nó chủ yếu được dùng nội bộ, và bạn có thể gọi trực tiếp bằng `@general` trong tin nhắn. Hữu ích khi bạn cần tìm một thứ nằm rải rác trong nhiều file.

### Nhiều cách cài, nhiều nền tảng

Bạn có thể cài bằng script, npm (hoặc bun, pnpm, yarn), Homebrew, pacman và paru trên Arch Linux, mise hoặc Nix. Ngoài ra còn có ứng dụng desktop (BETA) cho macOS, Windows và Linux, dành cho ai không thích dùng terminal.

### Mã nguồn mở, giấy phép MIT

Bạn xem được code, dùng và sửa theo giấy phép MIT. Tài liệu cấu hình chi tiết nằm trên trang riêng của dự án.

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

Tư liệu README nói rất ít về yêu cầu hệ thống, nên mình chỉ ghi những gì có:

- **Hệ điều hành**: script và các trình quản lý gói trong README hướng tới macOS và Linux (Homebrew, pacman, paru, Nix). Lệnh `mise use -g opencode` được ghi là dùng cho mọi hệ điều hành. Bản desktop có file cài cho Windows (`opencode-desktop-win-x64.exe`).
- **Công cụ cài đặt**: tuỳ cách bạn chọn, cần sẵn curl, npm (hoặc bun/pnpm/yarn), Homebrew, mise hoặc Nix.
- **Gỡ bản cũ**: README lưu ý nên gỡ các phiên bản cũ hơn 0.1.x trước khi cài.
- **Tài khoản, API key, phần cứng**: README chưa nói gì về các mục này. Vì là agent AI, bạn nhiều khả năng phải cấu hình nguồn mô hình AI, nhưng cách làm cụ thể bạn hãy xem ở trang tài liệu https://opencode.ai/docs.

```note
README không nói opencode có thu phí hay không, cũng không nói chi phí gọi mô hình AI. Nếu sau này bạn nhập API key của một dịch vụ AI, hãy đặt hạn mức chi tiêu trên trang của dịch vụ đó và đừng dán key vào file bạn định đưa lên GitHub.
```

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

```steps
- Chọn cách cài | Script một dòng, npm hoặc trình quản lý gói bạn quen
- Gỡ bản cũ | Xoá phiên bản cũ hơn 0.1.x nếu có
- Chạy lệnh cài | Dán lệnh vào terminal và chờ hoàn tất
- Mở lại terminal | Để máy nhận lệnh mới
- Xem tài liệu | Cấu hình thêm theo trang docs của dự án
```

### Bước 1: Chọn cách cài phù hợp

README đưa ra nhiều cách. Người mới nên chọn đúng một cách, đừng chạy hết. Nếu dùng macOS hoặc Linux và đã có Homebrew thì chọn brew. Nếu đã quen Node thì dùng npm. Nếu muốn nhanh nhất thì dùng script.

### Bước 2: Gỡ bản cũ (nếu có)

README ghi: gỡ các phiên bản cũ hơn 0.1.x trước khi cài. Nếu bạn chưa từng cài opencode thì bỏ qua bước này.

### Bước 3: Chạy lệnh cài

Mở terminal (trên macOS là Terminal, trên Linux là cửa sổ terminal, trên Windows là PowerShell hoặc Windows Terminal), rồi dán một trong các lệnh sau. Đây là nguyên văn từ README:

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

# Package managers
npm i -g @opencode/cli@latest      # or bun/pnpm/yarn
brew install anomalyco/tap/opencode-v2 # macOS and Linux (recommended, always up to date)
brew install opencode              # macOS and Linux (official brew formula, updated less)
sudo pacman -S opencode            # Arch Linux (Stable)
paru -S opencode-beta              # Arch Linux (Latest from AUR)
mise use -g opencode               # Any OS
nix run github:anomalyco/opencode  # Nix
```

Giải thích để bạn khỏi vấp:

- Dòng `curl ... | bash` tải script cài về rồi chạy luôn. README tự gọi nó là kiểu "YOLO", nghĩa là nhanh nhưng bạn không xem trước script. Nếu cẩn thận, hãy chọn một cách cài qua trình quản lý gói.
- Dòng `npm i -g @opencode/cli@latest` cài toàn cục bằng npm. Chữ "or bun/pnpm/yarn" nghĩa là bạn thay `npm i -g` bằng lệnh tương đương của bun, pnpm hoặc yarn. Lưu ý: tên gói trong lệnh này là `@opencode/cli`, trong khi tư liệu về repo ghi tên gói là `opencode`. Nếu lệnh npm báo không tìm thấy gói, bạn hãy đối chiếu lại với trang cài đặt trên https://opencode.ai.
- Hai dòng `brew`: dòng đầu (`anomalyco/tap/opencode-v2`) được README khuyên dùng vì luôn mới nhất. Dòng sau là bản chính thức của Homebrew nhưng cập nhật ít hơn.
- Hai dòng Arch Linux: `pacman` cho bản ổn định, `paru` cho bản mới nhất từ AUR.
- Dòng `mise` dùng được trên mọi hệ điều hành nếu bạn đã có mise.
- Dòng `nix run` chạy trực tiếp mà không cài cố định, dành cho người dùng Nix.

Khi dùng script cài, README cho biết opencode được cài vào thư mục `$HOME/.opencode/bin`.

### Bước 4: Mở lại terminal

Sau khi cài xong, hãy đóng và mở lại cửa sổ terminal. README không viết bước này, nhưng đây là thói quen chung để máy nhận lệnh mới. Nếu cài bằng script, bạn có thể phải thêm thư mục `$HOME/.opencode/bin` vào PATH. README chưa nói script có tự làm việc này không, nên hãy xem hướng dẫn trên trang cài đặt của dự án.

### Bước 5: Dùng bản desktop (tuỳ chọn)

Nếu ngại terminal, bạn tải bản desktop (BETA) tại opencode.ai/download. README liệt kê các file: `opencode-desktop-mac-arm64.dmg` cho Mac chip Apple, `opencode-desktop-mac-x64.dmg` cho Mac Intel, `opencode-desktop-win-x64.exe` cho Windows, và `.deb`, `.rpm` hoặc `.AppImage` cho Linux. Trên macOS bạn cũng có thể cài bằng Homebrew:

```bash
# macOS (Homebrew)
brew install --cask opencode-desktop
```

Vì đang là BETA, bạn có thể gặp lỗi lặt vặt hơn so với bản terminal.

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

README không ghi lệnh kiểm tra hay màn hình kết quả mong đợi. Vì vậy mình chỉ gợi ý cách kiểm tra chung, bạn nhớ đối chiếu với tài liệu chính thức:

1. Mở terminal mới, vào một thư mục dự án thử nghiệm (không phải dự án quan trọng).
2. Gõ tên lệnh `opencode`, là tên gói trong tư liệu. Nếu máy không nhận ra lệnh, kiểm tra lại PATH như ở bước 4.
3. Nếu giao diện mở ra, thử nhấn `Tab`. README nói phím này đổi giữa hai agent build và plan, nên bạn sẽ thấy tên agent đang dùng thay đổi.

Với bản desktop, bạn chỉ cần mở ứng dụng lên. Bạn mở được cửa sổ chính là cài thành công.

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

Các tình huống dưới đây bám vào hai chế độ build, plan và subagent general mà README mô tả. Câu lệnh mẫu chỉ là lời nhắn bằng tiếng thường, không phải cú pháp riêng của công cụ.

### Tình huống 1: Nhận một dự án lạ và cần hiểu nhanh

Bạn là lập trình viên mới, vừa được giao một thư mục code của người đi trước để lại. Mở terminal ở thư mục đó, chạy opencode, nhấn `Tab` để chuyển sang agent **plan** (chỉ đọc). Sau đó nhắn:

```text
Hãy giải thích dự án này làm gì, các thư mục chính có vai trò gì, và file nào là điểm bắt đầu.
```

Kết quả: bạn nhận được bản tóm tắt cấu trúc mà không lo nó sửa nhầm file nào. README nói rõ plan mặc định từ chối sửa file và hỏi trước khi chạy lệnh bash.

> Muốn hiểu một dự án lạ, hãy để agent chỉ đọc đi trước, rồi mới cho agent toàn quyền vào làm.
>
> — Ông T

### Tình huống 2: Lập kế hoạch trước khi sửa website bán hàng

Bạn là chủ shop có website nhỏ do thuê người làm, muốn thêm một nút hoặc đổi cách hiển thị giá. Ở chế độ plan, bạn nhắn:

```text
Mình muốn đổi cách hiển thị giá sản phẩm. Hãy chỉ ra những file cần sửa và đề xuất các bước, chưa sửa gì cả.
```

Kết quả: một danh sách file và bước làm. Bạn đọc, thấy hợp lý thì nhấn `Tab` sang **build** và nhắn "làm theo kế hoạch trên". Nếu không chắc, bạn có thể đưa kế hoạch cho người làm web của mình xem trước.

### Tình huống 3: Tìm một đoạn code nằm rải rác

Nhân viên văn phòng có một bộ script xử lý báo cáo Excel, không nhớ chỗ nào đang tính tổng doanh thu. Bạn gọi subagent bằng cách nhắn:

```text
@general tìm giúp mình tất cả chỗ trong dự án có tính tổng doanh thu và cho biết nằm ở file nào.
```

README mô tả general dùng cho tìm kiếm phức tạp và việc nhiều bước. Kết quả mong đợi là danh sách vị trí tìm được để bạn đi thẳng tới đúng file.

### Tình huống 4: Sửa một lỗi nhỏ ở chế độ build

Bạn có một script bị lỗi khi đọc file khách hàng. Ở chế độ **build** (mặc định, toàn quyền), bạn nhắn mô tả lỗi và dán thông báo lỗi vào. Agent đọc code, đề xuất và áp dụng chỉnh sửa. Hãy làm việc này trên bản sao hoặc trong thư mục đã có sao lưu, vì build có toàn quyền chỉnh sửa. Sau khi sửa, bạn tự chạy lại script để kiểm tra.

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

README không có mục xử lý sự cố, nên các lỗi dưới đây là những chuyện rất dễ xảy ra với loại công cụ này.

### Gõ opencode báo không tìm thấy lệnh

Thường do terminal chưa nhận lệnh mới hoặc thư mục cài chưa nằm trong PATH. Hãy đóng và mở lại terminal. Nếu cài bằng script, thư mục cài là `$HOME/.opencode/bin`, bạn kiểm tra xem thư mục này đã được thêm vào PATH chưa.

### Lệnh npm báo không tìm thấy gói

README ghi `@opencode/cli@latest`, còn tên gói trong tư liệu repo là `opencode`. Nếu có lệnh nào báo lỗi, hãy thử cách cài khác trong danh sách (brew hoặc script), hoặc xem lại trang cài đặt chính thức.

### Cài chồng lên bản cũ gây lỗi lạ

README dặn gỡ các bản cũ hơn 0.1.x trước khi cài. Nếu opencode chạy không ổn sau khi cài, hãy gỡ bản cũ rồi cài lại bằng đúng một cách.

### Agent sửa nhầm file

Đây là rủi ro của chế độ build, vì nó toàn quyền. Cách phòng: dùng plan để lên kế hoạch trước, làm việc trên dự án có sao lưu hoặc có Git, và đọc lại những gì nó đã thay đổi trước khi dùng thật.

### Không biết nhập API key hay chọn mô hình AI ở đâu

README chưa hướng dẫn phần này. Hãy đọc trang tài liệu cấu hình tại https://opencode.ai/docs, hoặc hỏi ở cộng đồng Discord của dự án (liên kết có trong README).

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

**Điểm mạnh:**

- Mã nguồn mở, giấy phép MIT, cộng đồng lớn (khoảng 226 nghìn sao) và repo còn được cập nhật trong 3 tháng gần đây.
- Hai chế độ build và plan giúp tách việc đọc, lập kế hoạch khỏi việc sửa. Rất hợp với người mới.
- Nhiều cách cài, có cả bản desktop và README có bản tiếng Việt.

**Giới hạn:**

- README chính rất ngắn. Phần cấu hình, kết nối mô hình AI và chi phí đều phải đọc thêm ở trang docs.
- Bản desktop đang ở BETA.
- Danh sách lệnh cài có vài chỗ cần đối chiếu (như tên gói npm), nên người mới cần cẩn thận.
- Vì là agent có quyền sửa file và chạy lệnh, bạn vẫn phải tự đọc lại kết quả. Đừng giao nguyên dự án quan trọng mà không sao lưu.

**Khi nào nên chọn cách khác:** nếu bạn chỉ cần hỏi đáp vài câu về lập trình, một khung chat AI thông thường đã đủ. Nếu bạn không muốn đụng vào terminal, hãy thử bản desktop trước, hoặc dùng công cụ có giao diện đồ hoạ quen thuộc hơn. Còn nếu bạn muốn một agent mã nguồn mở, tự kiểm soát được quyền truy cập ngay trên máy, opencode là lựa chọn đáng thử.

Lưu ý từ README: nếu bạn làm dự án có chữ "opencode" trong tên (ví dụ opencode-dashboard), hãy ghi rõ dự án đó không do đội ngũ opencode tạo ra và không liên kết với họ.

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

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

Bản thân opencode là mã nguồn mở theo giấy phép MIT, nên bạn xem và dùng code tự do. README không nói gì về chi phí gọi mô hình AI phía sau. Phần này chưa có thông tin trong tư liệu, bạn nên xem trang docs của dự án.

### opencode chạy được trên Windows không?

Có bản ứng dụng desktop (BETA) cho Windows là file opencode-desktop-win-x64.exe. Với bản dòng lệnh, README ghi lệnh mise là dùng được trên mọi hệ điều hành, còn các cách khác chủ yếu nhắm macOS và Linux. Bạn nên xem trang cài đặt chính thức để biết cách cài trên Windows.

### Cài opencode có khó không?

Không khó. Bạn chỉ cần dán một dòng lệnh vào terminal, ví dụ lệnh curl hoặc brew trong README. Nếu ngại terminal, bạn có thể tải bản desktop và cài như một ứng dụng thông thường.

### Agent build và plan khác nhau thế nào?

Build là agent mặc định, toàn quyền, dùng để làm việc phát triển. Plan là agent chỉ đọc, mặc định từ chối sửa file và hỏi trước khi chạy lệnh bash, hợp để khám phá code lạ hoặc lên kế hoạch. Bạn đổi giữa hai agent bằng phím Tab.

### opencode có cần GPU hay máy cấu hình mạnh không?

README không nêu yêu cầu phần cứng nào. Vì vậy mình chưa có thông tin để khẳng định. Bạn nên xem trang tài liệu của dự án.

### Dữ liệu và code của mình có an toàn không?

README không có mục nói về quyền riêng tư hay nơi dữ liệu được gửi đến. Điều có thể khẳng định là agent plan mặc định không sửa file và hỏi trước khi chạy bash. Repo có file SECURITY.md để bạn tham khảo chính sách bảo mật.

### @general dùng để làm gì?

Đây là subagent dành cho tìm kiếm phức tạp và các việc nhiều bước. README cho biết nó chủ yếu được dùng nội bộ, và bạn có thể gọi trực tiếp bằng cách gõ @general trong tin nhắn.
