# 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 coding agent (trợ lý lập trình AI) mã nguồn mở, giấy phép MIT, viết bằng TypeScript. Bạn dùng nó để nhờ AI đọc hiểu dự án, lên kế hoạch và sửa code. Cài khá dễ: có một dòng lệnh cài nhanh, nhiều trình quản lý gói và cả bản ứng dụng desktop (beta).

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

OpenCode là một trợ lý lập trình AI mã nguồn mở (người ta gọi là coding agent). Bạn mở nó trong thư mục dự án, ra yêu cầu bằng tiếng người, và nó giúp bạn đọc, tìm hiểu và sửa code. Tác giả mô tả ngắn gọn: «The open source coding agent».

Repo này hợp với lập trình viên mới muốn có người «ngồi cạnh» giải thích code, và hợp với người làm kinh doanh, văn phòng có chút nền tảng kỹ thuật, ví dụ người tự chỉnh một website nhỏ hay một đoạn script. Bạn không phải dựng gì phức tạp. Cài xong là dùng được.

Điều đáng giá nhất là hai chế độ làm việc rất rõ ràng. Chế độ **build** có toàn quyền để làm việc. Chế độ **plan** chỉ đọc, dùng để khám phá và lên kế hoạch mà không đụng vào file của bạn. Repo hiện có khoảng 226.506 sao và 30.658 fork, giấy phép MIT, và vẫn được cập nhật trong 3 tháng gần đây.

```repo
- repo | anomalyco/opencode
- kind | Agent
- desc | OpenCode là coding agent mã nguồn mở: đọc, sửa code và chạy lệnh giúp bạn, có chế độ build để làm việc và chế độ plan chỉ đọc để phân tích.
- stars | 227k
- lang | TypeScript
- license | MIT
```

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

Theo README, OpenCode có các điểm chính sau.

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

- **build** là agent mặc định, có đầy đủ quyền cho việc phát triển. Bạn dùng nó khi muốn AI thật sự viết và sửa code.
- **plan** là agent chỉ đọc, dùng để phân tích và khám phá code. Mặc định nó từ chối việc 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 để AI giải thích cấu trúc mà không lo nó lỡ tay sửa hỏng thứ gì. Hiểu xong rồi bạn mới chuyển sang build.

### 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 chuyên cho các tìm kiếm phức tạp và công việc nhiều bước. Hệ thống dùng nó nội bộ, và bạn cũng gọi được bằng cách gõ `@general` trong tin nhắn. Nó hợp với kiểu việc như «tìm giúp mình mọi chỗ trong dự án đang xử lý đơn hàng».

### Nhiều cách cài, có cả bản desktop

Bạn cài bằng một dòng lệnh, bằng npm, Homebrew, Arch Linux, mise hoặc Nix. Có thêm ứng dụng desktop (đang BETA) cho macOS, Windows và Linux, nên người ngại gõ lệnh vẫn có lối vào.

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

Bạn đọc được code, tự kiểm tra nó làm gì, và dùng theo giấy phép MIT. Với công cụ có quyền chạy lệnh trên máy bạn, điều này đáng quý.

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

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

- **Hệ điều hành:** bản desktop có file cho macOS (Apple Silicon và Intel), Windows (`.exe`) và Linux (`.deb`, `.rpm`, `.AppImage`). Các cách cài bằng dòng lệnh được ghi cho macOS, Linux và cả «Any OS» (qua mise).
- **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, pacman, paru, mise hoặc Nix.
- **Dọn bản cũ:** README khuyến cáo xoá các phiên bản cũ hơn 0.1.x trước khi cài.
- **Tài khoản, API key, GPU, phiên bản Node:** README không nêu. Đây là công cụ cần một mô hình AI phía sau, nhưng cách kết nối mô hình nào thì README chưa ghi. Bạn xem phần cấu hình trong tài liệu chính thức tại opencode.ai/docs.

```note
README không nói OpenCode tính phí thế nào hay cần key của nhà cung cấp AI nào. Trước khi dùng cho việc quan trọng, bạn đọc tài liệu chính thức để biết chi phí và cách cấp quyền. Không dán key vào chỗ công khai.
```

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

```steps
- Chọn cách cài | Một dòng lệnh, trình quản lý gói, hoặc bản desktop
- Dọn bản cũ | Gỡ phiên bản cũ hơn 0.1.x nếu có
- Chạy lệnh cài | Dán lệnh phù hợp vào terminal
- Tìm nơi cài | Biết file nằm ở đâu để khỏi lạc
- Mở thử | Vào thư mục dự án và khởi động
```

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

README đưa ra nhiều lựa chọn. Nếu bạn không rành kỹ thuật, bản desktop (beta) là lối nhẹ nhất. Nếu quen terminal, dùng dòng lệnh. Chọn **một** cách thôi, đừng cài chồng nhiều cách lên nhau.

### Bước 2: Dọn bản cũ

README ghi: hãy 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. Còn nếu bạn từng thử một bản rất cũ, hãy gỡ đi để tránh xung đột.

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

Mở terminal (macOS/Linux: ứng dụng Terminal; Windows: PowerShell hoặc Terminal), rồi dán **một** dòng trong danh sách dưới đây. Đây là các lệnh có trong 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 chọn đúng:

- Dòng `curl ... | bash` là cách nhanh nhất. README tự gọi nó là «YOLO» vì nó tải script về và chạy luôn. Nếu bạn muốn chắc ăn, hãy đọc nội dung script trước khi chạy.
- `npm i -g ...` cài toàn cục qua npm. README ghi bạn có thể thay bằng bun, pnpm hoặc yarn.
- Có hai công thức Homebrew. README ghi `anomalyco/tap/opencode-v2` là bản khuyến nghị, luôn mới nhất. Công thức `opencode` chính thức thì cập nhật chậm hơn.
- `pacman` và `paru` dành cho Arch Linux. `mise` chạy trên mọi hệ điều hành. `nix run` chạy thử thẳng từ GitHub.

Chỗ người mới hay vấp: bạn **không** dán cả khối này vào cùng lúc. Chỉ chọn một dòng. Các dòng bắt đầu bằng `#` là chú thích, không phải lệnh.

Nếu muốn lấy mã nguồn về xem, bạn dùng lệnh git thông thường:

```bash
git clone https://github.com/anomalyco/opencode.git
cd opencode
```

### Bước 4: Hoặc cài bản desktop

Tải từ trang opencode.ai/download. README liệt kê các file:

| Nền tảng | File tải |
| --- | --- |
| 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` |

Trên macOS bạn cũng có thể cài qua Homebrew:

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

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

### Bước 5: Biết file được cài ở đâu

README cho biết script cài đặt đặt OpenCode vào thư mục `$HOME/.opencode/bin`. Nếu sau khi cài mà terminal báo không tìm thấy lệnh, thư mục này là chỗ đầu tiên đáng kiểm tra. README không nói cách mở sau khi cài, nên bạn xem mục bắt đầu trong tài liệu chính thức tại opencode.ai/docs để biết lệnh khởi động chính xác.

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

README không mô tả kết quả cụ thể của một lệnh kiểm tra. Vì vậy mình chỉ gợi ý những dấu hiệu hợp lý, bạn đối chiếu với tài liệu chính thức:

1. Với bản desktop: ứng dụng mở lên được và bạn thấy giao diện làm việc.
2. Với bản dòng lệnh: sau khi cài, mở một cửa sổ terminal **mới** (để máy nhận đường dẫn mới) và thử khởi động theo hướng dẫn trong tài liệu.
3. Khi đã vào được giao diện, thử bấm phím `Tab`. README nói phím này chuyển qua lại giữa agent **build** và **plan**. Nếu bạn thấy chế độ đổi, tức là công cụ đang chạy bình thường.

Nếu không thấy gì, nhảy xuống phần lỗi thường gặp bên dưới.

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

Các tình huống dưới đây bám vào những gì README mô tả: hai agent, subagent `@general` và cách đổi bằng Tab. Câu lệnh mẫu chỉ là gợi ý cách bạn nhờ AI, không phải lệnh của công cụ.

### Làm quen một dự án lạ trước khi sửa

Bối cảnh: bạn là lập trình viên mới, vừa nhận một dự án web từ đồng nghiệp đã nghỉ. Bạn chưa biết file nào làm gì.

Cách làm: mở OpenCode trong thư mục dự án, bấm `Tab` để sang agent **plan** (chỉ đọc). Rồi hỏi:

```text
Giải thích giúp mình cấu trúc thư mục này. File nào xử lý đăng nhập? Luồng dữ liệu đi từ đâu tới đâu?
```

Kết quả: bạn nhận được bản giải thích mà không có file nào bị sửa. README ghi rõ plan từ chối sửa file mặc định và hỏi trước khi chạy lệnh bash, nên rất yên tâm cho lần đọc đầu tiên.

### Lên kế hoạch rồi mới cho AI làm

Bối cảnh: chủ một shop nhỏ có website bán hàng và muốn thêm trường «ghi chú đơn hàng». Bạn không chắc phải đụng vào những file nào.

Cách làm: ở chế độ plan, nhờ nó đề xuất các bước:

```text
Mình muốn thêm ô ghi chú vào form đặt hàng. Liệt kê các file cần sửa và thứ tự làm, chưa sửa gì cả.
```

Đọc kế hoạch xong, bạn bấm `Tab` sang **build** và yêu cầu nó làm theo từng bước.

> Cho AI đọc trước, sửa sau: plan để hiểu, build để làm.
>
> — Ông T

Kết quả: thay đổi nhỏ, có kế hoạch, dễ kiểm tra lại. Nếu kết quả không ưng, bạn hủy thay đổi bằng công cụ quản lý phiên bản như git.

### Tìm thứ gì đó trong dự án lớn

Bối cảnh: nhân viên kỹ thuật ở công ty cần tìm mọi chỗ trong code có nhắc tới một khái niệm, ví dụ «mã giảm giá».

Cách làm: gọi subagent chuyên tìm kiếm bằng `@general` ngay trong tin nhắn:

```text
@general tìm mọi chỗ trong dự án xử lý mã giảm giá và tóm tắt mỗi chỗ làm gì
```

Kết quả: một bản tóm tắt gọn các vị trí liên quan, tiết kiệm công mở từng file thủ công. README nói general dành cho tìm kiếm phức tạp và công việc nhiều bước.

### Giao việc sửa lỗi nhỏ ở chế độ build

Bối cảnh: dev tự làm một công cụ nội bộ, thấy nút «Xuất báo cáo» bị lỗi.

Cách làm: ở agent **build**, mô tả lỗi và mong muốn:

```text
Nút Xuất báo cáo bị lỗi khi danh sách trống. Tìm nguyên nhân và sửa, rồi cho mình xem những gì đã đổi.
```

Kết quả: AI đọc code, đề xuất và áp dụng chỉnh sửa. Bạn vẫn nên đọc lại thay đổi và chạy thử trước khi dùng thật, vì agent có toàn quyền ở chế độ này.

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

README không có mục xử lý sự cố. Các lỗi dưới đây là những tình huống rất dễ xảy ra với loại công cụ dòng lệnh này. Cách xử lý mang tính an toàn chung.

### Báo không tìm thấy lệnh sau khi cài

Thường do terminal chưa nhận đường dẫn mới. Hãy đóng terminal, mở cửa sổ mới rồi thử lại. README cho biết script cài vào `$HOME/.opencode/bin`, nên bạn kiểm tra xem thư mục đó có tồn tại và có nằm trong PATH không.

### Cài chồng nhiều cách và gặp xung đột

Bạn dùng cả `curl`, `npm` lẫn Homebrew nên máy có nhiều bản khác nhau. Hãy chọn một cách, gỡ các bản còn lại. README cũng khuyên xoá phiên bản cũ hơn 0.1.x trước khi cài.

### Lệnh cài nhầm công thức hay gói

README có nhiều tên gần giống nhau (`opencode`, `opencode-v2`, `opencode-beta`, `opencode-desktop`) và còn ghi rõ công thức Homebrew `opencode` cập nhật chậm hơn bản `anomalyco/tap/opencode-v2`. Nếu chạy ra bản cũ, hãy thử đổi sang cách README gọi là khuyến nghị.

### Công cụ chạy nhưng không có phản hồi từ AI

Đây là dấu hiệu chưa kết nối mô hình AI hoặc chưa cấp quyền. README không nói cách cấu hình, nên bạn xem tài liệu cấu hình tại opencode.ai/docs, hoặc hỏi trong cộng đồng Discord/X của dự án.

### AI sửa nhầm file quan trọng

Ở chế độ build, agent có toàn quyền. Hãy làm việc trong thư mục đã có git, hoặc sao lưu trước. Nếu chưa chắc, đổi sang plan để chỉ đọc và hỏi trước.

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

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

- Mã nguồn mở, giấy phép MIT, đọc code được.
- Có chế độ plan chỉ đọc, an toàn khi khám phá dự án lạ.
- Nhiều cách cài, có cả bản desktop và hỗ trợ nhiều hệ điều hành.
- Cộng đồng lớn: hiện có khoảng 226.506 sao, và repo còn được cập nhật đều.

**Giới hạn:**

- README ngắn, chủ yếu nói về cài đặt và hai agent. Phần cấu hình, mô hình AI, chi phí nằm ở tài liệu riêng.
- README liệt kê nhiều tên gói gần giống nhau, người mới dễ lẫn.
- Bản desktop còn BETA.
- Đây là công cụ cho việc lập trình. Nếu bạn chỉ cần soạn văn bản hay làm bảng tính, nó không phải lựa chọn đúng.

**Khi nào nên chọn cách khác:** nếu bạn hoàn toàn không đụng tới code, hoặc không muốn mở terminal, một ứng dụng chat AI thông thường sẽ dễ hơn. Còn nếu bạn muốn một trợ lý đọc và sửa code ngay trong dự án, lại kiểm soát được mã nguồn của công cụ, OpenCode đáng để thử. Hãy bắt đầu bằng chế độ plan trên một dự án nhỏ trước.

## 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. README không nói về chi phí của mô hình AI mà công cụ sử dụng, nên mục này chưa có thông tin. Bạn xem tài liệu chính thức tại opencode.ai/docs.

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

Có bản desktop cho Windows: file `opencode-desktop-win-x64.exe` (đang BETA). README không ghi rõ các lệnh cài bằng dòng lệnh có chạy trên Windows hay không, nên nếu muốn dùng terminal bạn nên xem thêm tài liệu chính thức.

### Mình có cần GPU hay máy mạnh không?

README không nêu yêu cầu phần cứng nào, nên chưa có thông tin chính thức. Cần có tài khoản hay API key nào hay không cũng chưa được README nói đến.

### Hai chế độ build và plan khác nhau thế nào?

Build là agent mặc định, có toàn quyền cho công việc phát triển. Plan là agent chỉ đọc, từ chối sửa file mặc định và hỏi trước khi chạy lệnh bash. Bạn bấm phím Tab để chuyển qua lại.

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

General là subagent cho các tìm kiếm phức tạp và công việc nhiều bước. Hệ thống dùng nó nội bộ, và bạn có thể gọi bằng cách gõ `@general` trong tin nhắn.

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

README không có phần nói về bảo mật dữ liệu hay nơi code được gửi đi. Repo có file SECURITY.md ở thư mục gốc, bạn nên đọc trước khi dùng với code nhạy cảm. Mã nguồn mở cũng cho phép bạn tự kiểm tra cách công cụ hoạt động.

### Cài ở đâu và gỡ bản cũ thế nào?

Script cài đặt đặt OpenCode vào `$HOME/.opencode/bin`. README khuyến cáo xoá các phiên bản cũ hơn 0.1.x trước khi cài, nhưng không hướng dẫn chi tiết cách gỡ.
