# opencode: trợ lý lập trình AI mã nguồn mở chạy 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ở (giấy phép MIT), viết chủ yếu bằng TypeScript. Nó giúp bạn khám phá, hiểu và sửa code bằng cách trò chuyện, có bản dòng lệnh và bản ứng dụng desktop (BETA). Cài đặt chỉ cần một dòng lệnh hoặc tải file cài, không khó nếu bạn đã quen mở terminal.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-06-15 · 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-18

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, nó đọc code trong dự án, đề xuất và thực hiện thay đổi, thậm chí chạy lệnh giúp bạn. Tác giả giới thiệu ngắn gọn: "The open source coding agent". Repo viết chủ yếu bằng TypeScript, dùng giấy phép MIT, nghĩa là bạn dùng miễn phí và xem được toàn bộ mã nguồn.

Vấn đề nó giải quyết rất đời thường. Bạn có một dự án code nhưng không rành, hoặc rành mà muốn làm nhanh hơn. Thay vì tự lục từng file, bạn nhờ agent đọc hộ, giải thích hộ, rồi sửa hộ. Người nên thử là lập trình viên mới, người làm kinh doanh hay văn phòng có vài đoạn script nội bộ cần chỉnh, và dev có kinh nghiệm muốn một công cụ chạy ngay trong terminal.

Điểm đáng giá nhất là **hai chế độ làm việc rõ ràng**. Chế độ `build` được toàn quyền để làm việc. Chế độ `plan` chỉ đọc, mặc định từ chối sửa file, nên bạn có thể yên tâm cho nó đi xem một dự án lạ mà không sợ nó làm hỏng gì. Repo hiện có khoảng 226.506 sao và 30.658 fork, và vẫn được cập nhật trong 3 tháng gần đây.

```repo
- repo | anomalyco/opencode
- kind | Agent
- desc | opencode là agent lập trình AI mã nguồn mở: đọc code, sửa file, chạy lệnh giúp bạn, có bản terminal và bản desktop, giấy phép MIT.
- stars | 227k
- lang | TypeScript
- license | MIT
```

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

Dưới đây là những gì tư liệu repo cho biết. Mình chỉ nói đúng những điều có thật, không thêm tính năng ngoài README.

### Hai agent có sẵn, đổi bằng phím Tab

- **build**: agent mặc định, toàn quyền cho công việc phát triển. Dùng khi bạn đã biết mình muốn gì và để nó tự tay làm.
- **plan**: agent chỉ đọc, dùng để phân tích và khám phá code. Nó từ chối sửa file theo mặc định và hỏi lại bạn trước khi chạy lệnh bash. Rất hợp khi bạn mở một dự án chưa quen hoặc muốn lên kế hoạch trước khi sửa.

Bạn đổi qua lại giữa hai agent bằng phím `Tab`. Lợi ích thực tế: bắt đầu bằng `plan` để hiểu và chốt hướng đi, rồi mới chuyển sang `build` để làm.

### Subagent general cho việc phức tạp

Ngoài hai agent trên còn có subagent **general**, dùng cho tìm kiếm phức tạp và các tác vụ nhiều bước. README cho biết nó chủ yếu được dùng nội bộ, nhưng bạn cũng gọi được bằng cách gõ `@general` trong tin nhắn. Hữu ích khi câu hỏi của bạn cần lục nhiều nơi trong dự án.

### Có bản terminal và bản desktop

Bạn dùng được qua dòng lệnh, hoặc cài ứng dụng desktop (đang ở dạng BETA) cho macOS, Windows và Linux. Ai ngại terminal có thể bắt đầu bằng bản desktop.

### Nhiều cách cài

Repo hỗ trợ cài bằng script, npm/bun/pnpm/yarn, Homebrew, pacman và paru (Arch Linux), mise, Nix. Bạn chọn cách quen tay nhất.

### Tài liệu nhiều ngôn ngữ

README có nhiều bản dịch, trong đó có tiếng Việt (file `README.vi.md` trong repo). Phần cấu hình chi tiết nằm ở trang tài liệu của dự án (opencode.ai/docs).

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

Theo README, bạn cần:

- **Hệ điều hành**: macOS, Linux (cài bằng lệnh hoặc gói) hoặc Windows (có file cài `opencode-desktop-win-x64.exe` cho bản desktop). Riêng `mise` được ghi là dùng được trên mọi hệ điều hành.
- **Một terminal** nếu bạn dùng cách cài bằng lệnh. Trên Windows, dòng `curl ... | bash` cần môi trường bash (ví dụ Git Bash). README không hướng dẫn riêng cho Windows, nên nếu thấy rối, hãy dùng bản desktop.
- **npm hoặc một trình quản lý gói** nếu bạn chọn cách cài bằng `npm i -g`. README không nêu phiên bản Node tối thiểu.
- **Dọn bản cũ**: README ghi rõ nên gỡ các phiên bản cũ hơn 0.1.x trước khi cài.

Về tài khoản, API key hay phần cứng (GPU, RAM): **README chưa nói gì**. Để biết cách kết nối mô hình AI và cấu hình, bạn xem trang tài liệu tại opencode.ai/docs.

```note
README không nói cách cấu hình khoá truy cập cho mô hình AI. Khi bạn tự điền bất kỳ khoá (API key) nào, hãy giữ kín, không dán vào chat công khai, không đưa vào file code rồi đẩy lên GitHub. Dịch vụ AI bên thứ ba có thể tính phí theo lượng dùng, hãy xem bảng giá của nhà cung cấp trước.
```

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

```steps
- Gỡ bản cũ | Xoá các phiên bản cũ hơn 0.1.x nếu máy bạn từng cài
- Chọn cách cài | Script, npm, Homebrew, pacman, mise hoặc Nix tuỳ máy bạn
- Chạy lệnh cài | Mở terminal và dán đúng một lệnh ở bước chọn
- Hoặc cài bản desktop | Tải file cài từ trang tải về nếu không muốn dùng terminal
- Xem tài liệu cấu hình | Làm theo opencode.ai/docs để kết nối mô hình AI
```

### Gỡ bản cũ nếu có

README dặn: xoá các phiên bản cũ hơn 0.1.x trước khi cài. Nếu đây là lần đầu bạn cài, bỏ qua bước này. README không ghi cách gỡ cụ thể, nên bạn gỡ theo đúng cách bạn đã cài trước đó (ví dụ dùng chính trình quản lý gói đã cài nó).

### Cài bằng script (cách nhanh nhất)

Mở terminal (macOS: ứng dụng Terminal; Linux: cửa sổ terminal; Windows: Git Bash) rồi dán lệnh sau. README gọi cách này là "YOLO" vì nó tải script về và chạy luôn.

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

Script sẽ cài opencode vào thư mục `$HOME/.opencode/bin`. Chỗ người mới hay vấp: sau khi cài, hãy đóng và mở lại terminal để máy nhận lệnh mới. Nếu vẫn không thấy lệnh, kiểm tra thư mục `$HOME/.opencode/bin` có nằm trong PATH của bạn không.

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

Bạn chỉ cần chạy **một** dòng phù hợp với máy mình. Đây là các dòng có trong README:

```bash
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
```

Gợi ý chọn nhanh:

- Có Homebrew trên macOS hoặc Linux: dùng dòng `brew install anomalyco/tap/opencode-v2`, README ghi là cách được khuyên dùng và luôn mới nhất. Dòng `brew install opencode` là bản brew chính thức nhưng cập nhật chậm hơn.
- Có npm: dùng dòng `npm i -g @opencode/cli@latest`. Có thể thay npm bằng bun, pnpm hoặc yarn.
- Dùng Arch Linux: `sudo pacman -S opencode` cho bản ổn định, `paru -S opencode-beta` cho bản mới nhất từ AUR.
- Muốn một cách cho mọi hệ điều hành: `mise use -g opencode`.
- Dùng Nix: `nix run github:anomalyco/opencode`.

Lưu ý: tên gói npm trong README là `@opencode/cli`. Nếu bạn thấy tên khác ở nơi khác, hãy làm theo README và trang tài liệu chính thức.

### Hoặc cài bản desktop (BETA)

Nếu bạn không thích terminal, tải ứng dụng từ trang opencode.ai/download. Các file theo từng hệ điều hành:

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

Trên macOS có Homebrew, bạn cũng cài bản desktop bằng lệnh:

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

Bản desktop đang ở dạng BETA, nên có thể còn lỗi vặt.

### Lấy cách cấu hình mô hình AI

README chưa ghi cách kết nối mô hình AI hay lệnh khởi động. Bạn xem mục tài liệu ở opencode.ai/docs để làm theo. Phần này mình không đoán mò để tránh chỉ sai lệnh.

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

README không có mục kiểm tra cài đặt riêng, nên mình nói theo cách an toàn:

- **Với bản desktop**: mở ứng dụng lên. Nếu cửa sổ chính hiện ra, bạn đã cài xong.
- **Với bản dòng lệnh**: mở terminal **mới**, gọi chương trình theo hướng dẫn khởi động trong tài liệu opencode.ai/docs. Nếu máy báo "command not found", nghĩa là terminal chưa nhận lệnh (xem phần lỗi bên dưới).
- **Thử phím Tab**: khi giao diện đã mở, bấm `Tab` để đổi giữa agent `build` và `plan`. Thấy tên agent đổi là bạn đang dùng đúng bản opencode.

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

Các tình huống dưới đây dựa trên khả năng README mô tả: hai agent `build` và `plan`, và subagent `@general`. Câu lệnh mẫu chỉ là cách mình diễn đạt yêu cầu bằng lời, không phải cú pháp riêng của công cụ.

### Dev mới nhận một dự án lạ

Bạn vừa vào công ty và được giao một kho code chưa từng thấy. Hãy mở dự án, để ở agent `plan` (chỉ đọc, từ chối sửa file) và hỏi bằng lời tự nhiên:

```text
Hãy giải thích dự án này làm gì, các thư mục chính nằm ở đâu và nên bắt đầu đọc từ file nào.
```

Kết quả: bạn có bản tóm tắt cấu trúc dự án mà không lo agent lỡ tay sửa gì. README mô tả đúng đây là trường hợp lý tưởng của `plan`: khám phá code lạ và lên kế hoạch thay đổi.

> Cứ để agent đọc trước, sửa sau. Hiểu xong mới cho phép nó đụng vào code.
>
> — Ông T

### Lập kế hoạch trước khi sửa một tính năng

Giả sử bạn là chủ shop có một website bán hàng nhỏ do freelancer làm, giờ muốn thêm ô nhập mã giảm giá. Bạn vẫn ở `plan` và nhờ:

```text
Tôi muốn thêm ô nhập mã giảm giá ở trang thanh toán. Hãy chỉ ra những file cần sửa và các bước làm, chưa sửa gì cả.
```

Kết quả: một danh sách file và các bước. Bạn có thể đưa danh sách này cho freelancer, hoặc bấm `Tab` sang `build` để agent tự làm. Chỉ nên chuyển sang `build` khi bạn đã đọc kế hoạch và đồng ý.

### Tìm thứ khó tìm bằng @general

Dự án có hàng trăm file và bạn cần biết hàm tính phí vận chuyển được gọi ở những đâu. Đây là việc tìm kiếm nhiều bước, đúng sở trường của subagent `general`. Trong tin nhắn, gõ:

```text
@general Tìm mọi nơi trong dự án có tính phí vận chuyển và liệt kê theo file.
```

Kết quả: danh sách các vị trí liên quan, giúp bạn khỏi phải tự tìm từng file. README cho biết `@general` dùng cho tìm kiếm phức tạp và tác vụ nhiều bước.

### Nhờ agent làm việc thật với build

Nhân viên văn phòng có một script nhỏ gộp báo cáo từ nhiều file, nhưng cột ngày đang sai định dạng. Chuyển sang `build` và mô tả lỗi rõ ràng:

```text
Script gộp báo cáo đang in ngày dạng tháng/ngày/năm. Hãy sửa để in ngày/tháng/năm.
```

Kết quả: agent sửa file trong dự án giúp bạn. Vì `build` có toàn quyền, hãy làm trên bản sao hoặc dự án đã được lưu bằng Git để có thể quay lại nếu kết quả không như ý.

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

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

### Gõ lệnh báo "command not found"

Thường do terminal chưa nhận lệnh mới cài. Đóng hẳn terminal, mở lại cửa sổ mới rồi thử lại. Nếu bạn cài bằng script, kiểm tra thư mục `$HOME/.opencode/bin` có nằm trong PATH không.

### Cài bằng script bị lỗi trên Windows

Dòng `curl ... | bash` cần có bash. Trên Windows, hãy chạy trong Git Bash, hoặc đổi sang cài bản desktop với file `opencode-desktop-win-x64.exe`, hoặc dùng `npm i -g @opencode/cli@latest` nếu bạn đã có npm.

### Lệnh npm báo thiếu quyền (permission)

Đây là lỗi thường gặp khi cài gói toàn cục. Đừng vội dùng quyền quản trị cho mọi thứ. Hãy thử cách cài khác trong README (ví dụ Homebrew, mise hoặc bản desktop), hoặc xem lại cách cấu hình npm trên máy bạn.

### Nhầm với phiên bản cũ

README dặn xoá các bản cũ hơn 0.1.x trước khi cài. Nếu sau khi cài vẫn thấy hành vi lạ hoặc số phiên bản cũ, hãy gỡ bản cũ rồi cài lại.

### Agent sửa nhiều hơn bạn muốn

Vì `build` có toàn quyền, nó có thể sửa nhiều file. Cách phòng: luôn bắt đầu bằng `plan`, dùng Git để lưu lại trạng thái trước khi cho `build` làm, và đọc kỹ thay đổi sau đó.

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

**Điểm mạnh**

- Miễn phí, mã nguồn mở, giấy phép MIT.
- Hai chế độ rõ ràng: `build` để làm việc, `plan` chỉ đọc để khám phá an toàn.
- Có cả bản terminal và bản desktop, nhiều cách cài cho nhiều hệ điều hành.
- Cộng đồng lớn (khoảng 226.506 sao, 30.658 fork) và vẫn được cập nhật gần đây.

**Giới hạn**

- README ngắn, không nói cách cấu hình mô hình AI hay lệnh khởi động. Bạn phải đọc thêm tài liệu ở opencode.ai/docs.
- Bản desktop vẫn là BETA.
- Chi phí và quyền riêng tư phụ thuộc vào mô hình AI bạn kết nối. README chưa có thông tin về việc này, nên bạn tự kiểm tra trước khi đưa code nhạy cảm vào.
- Có vài dòng cài khác nhau trong README, bạn cần chọn đúng một cách phù hợp với máy mình.

**Khi nào nên chọn cách khác**: nếu bạn hoàn toàn không muốn đụng tới terminal hay cấu hình, hãy cân nhắc bản desktop trước. Nếu bạn cần một công cụ có hướng dẫn từng bước thật chi tiết ngay trong README, hãy đọc kỹ tài liệu chính thức trước khi quyết định.

## 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ở, dùng giấy phép MIT nên bạn dùng miễn phí. Tuy nhiên README không nói gì về chi phí của mô hình AI bạn kết nối, nên chưa có thông tin về việc đó. Bạn nên xem tài liệu và bảng giá của nhà cung cấp mô hình trước khi dùng nhiều.

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

Có bản desktop cho Windows, file `opencode-desktop-win-x64.exe`. Dòng cài bằng script dùng `bash`, nên trên Windows bạn cần môi trường bash, hoặc dùng cách cài khác trong README như `npm i -g @opencode/cli@latest` nếu máy đã có npm.

### 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, kể cả GPU. Chưa có thông tin cụ thể về cấu hình tối thiểu. Bạn xem thêm tại trang tài liệu opencode.ai/docs.

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

`build` là agent mặc định, toàn quyền cho công việc phát triển. `plan` chỉ đọc: mặc định từ chối sửa file và hỏi quyền trước khi chạy lệnh bash. Bạn đổi giữa hai agent bằng phím `Tab`.

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

README không nói về cách xử lý dữ liệu hay việc nó gửi code đến đâu. Chưa có thông tin cụ thể. Repo có file SECURITY.md để bạn tham khảo, và bạn nên kiểm tra kỹ mô hình AI mình kết nối trước khi đưa code nhạy cảm vào.

### Tôi nên cài bằng cách nào cho dễ nhất?

Nếu quen terminal, cách nhanh nhất là dòng script `curl -fsSL https://opencode.ai/v2/install | bash`. Nếu dùng macOS hoặc Linux có Homebrew, README khuyên dùng `brew install anomalyco/tap/opencode-v2`. Nếu ngại dòng lệnh, hãy tải bản desktop (BETA) ở opencode.ai/download.

### Tôi đã cài bản cũ, có cần làm gì không?

Có. README dặn xoá các phiên bản cũ hơn 0.1.x trước khi cài. README không nêu cách gỡ cụ thể, nên bạn gỡ theo đúng cách đã cài bản cũ.
