# 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 bằng TypeScript. Bạn dùng nó để hỏi đáp về code, khám phá dự án lạ, lên kế hoạch và nhờ AI sửa code. Cài khá đơn giản: một dòng lệnh, một trình quản lý gói, hoặc tải bản desktop (BETA).

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

opencode là một agent lập trình AI mã nguồn mở. Hiểu đơn giản: đây là một "trợ lý code" bạn cài lên máy, rồi giao việc cho nó ngay trong thư mục dự án của mình. Mô tả của tác giả chỉ có một câu: "The open source coding agent". 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.

Bạn nên xem qua nếu là lập trình viên mới, người làm kinh doanh có vài dự án nhỏ cần chỉnh sửa, hoặc dân văn phòng hay đụng đến script, file cấu hình. Thay vì tự mò từng dòng, bạn nhờ AI đọc giúp, giải thích giúp, và sửa giúp.

Điểm đáng giá nhất của opencode là nó có hai chế độ rất rõ ràng: một chế độ được phép sửa file, một chế độ chỉ đọc để phân tích. Bạn chuyển qua lại bằng phím Tab. Nhờ vậy bạn có thể cho AI "xem thử" dự án mà không lo nó tự ý thay đổi gì.

```repo
- repo | anomalyco/opencode
- kind | Agent
- desc | opencode là agent lập trình AI mã nguồn mở, giúp đọc, sửa và lên kế hoạch cho code ngay trong dự án của bạn, có cả bản desktop.
- stars | 227k
- lang | TypeScript
- license | MIT
```

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

Tư liệu repo mô tả ngắn gọn, nên mình chỉ nói những gì có trong đó.

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

- **build**: agent mặc định, có đầy đủ quyền để làm việc phát triển. Dùng khi bạn muốn AI thật sự viết hoặc sửa code.
- **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ở một dự án lạ, bạn cứ dùng **plan** để hỏi "dự án này chia thư mục thế nào", "hàm này gọi ở đâu". Hiểu xong, bạn mới chuyển sang **build** để làm.

### 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 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 có thể gọi trực tiếp bằng cách gõ `@general` trong tin nhắn.

### Nhiều cách cài, nhiều hệ điều hành

Bạn có thể cài bằng một dòng lệnh, bằng npm/bun/pnpm/yarn, Homebrew, pacman (Arch Linux), mise hoặc Nix. Ngoài ra có ứng dụng desktop (BETA) cho macOS, Windows và Linux. Ai ngại terminal có thể bắt đầu từ bản desktop.

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

Giấy phép MIT cho phép bạn xem code, dùng và sửa khá thoải mái. Với người làm doanh nghiệp, đây là điểm cộng khi cần đánh giá một công cụ trước khi đưa vào quy trình.

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

README không liệt kê yêu cầu hệ thống chi tiết. Những gì có thể rút ra từ tư liệu:

- **Hệ điều hành**: bản dòng lệnh có hướng dẫn cho macOS, Linux (Homebrew, pacman, AUR) và mọi hệ điều hành qua mise. Bản desktop có file cài cho macOS (Apple Silicon và Intel), Windows (`.exe`) và Linux (`.deb`, `.rpm`, `.AppImage`).
- **Công cụ cài đặt**: tuỳ cách bạn chọn. Dùng npm thì cần có npm; dùng Homebrew thì cần có Homebrew; dùng script thì cần `curl` và `bash`.
- **Phiên bản cũ**: README dặ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 không nói gì. Cách kết nối với mô hình AI và các yêu cầu khác bạn xem trong tài liệu chính thức tại opencode.ai/docs.

```note
README không nêu chuyện API key hay chi phí. Nếu sau này bạn kết nối opencode với một dịch vụ AI có tính phí, hãy đọc kỹ tài liệu của dịch vụ đó, đặt giới hạn chi tiêu nếu có, và không dán key vào file mà bạn chia sẻ hay đưa lên GitHub.
```

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

```steps
- Gỡ bản cũ | Xoá phiên bản opencode cũ hơn 0.1.x nếu có
- Chọn cách cài | Script một dòng, trình quản lý gói, hoặc bản desktop
- Chạy lệnh cài | Dán lệnh vào terminal và chờ cài xong
- Mở dự án | Vào thư mục code của bạn rồi khởi chạy opencode
- Đọc tài liệu | Xem opencode.ai/docs để cấu hình thêm
```

### Bước 1: Gỡ bản cũ nếu có

README ghi: "Remove versions older than 0.1.x before installing." Nghĩa là nếu máy bạn từng cài opencode rất cũ, hãy gỡ đi trước. README không nêu lệnh gỡ cụ thể, nên cách gỡ phụ thuộc bạn đã cài bằng gì (npm, Homebrew…). Nếu bạn chưa từng cài, bỏ qua bước này.

### Bước 2: Chọn một cách cài

Bạn chỉ cần chọn MỘT cách dưới đây. Mở terminal (macOS/Linux: ứng dụng Terminal; Windows: PowerShell hoặc một terminal hỗ trợ bash) rồi dán lệnh.

Cách nhanh nhất là script một dòng. README gọi nó là "YOLO" vì bạn chạy thẳng một script tải từ mạng về:

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

Lệnh này tải script cài đặt từ opencode.ai và chạy bằng bash. Script sẽ cài opencode vào `$HOME/.opencode/bin`. Nếu muốn an toàn hơn, bạn có thể mở địa chỉ đó bằng trình duyệt để đọc script trước khi chạy.

Nếu quen trình quản lý gói, README liệt kê các lựa chọn sau:

```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 nhanh để bạn chọn đúng:

- `npm i -g ...` cài toàn cục bằng npm (có thể thay bằng bun, pnpm hoặc yarn). Phù hợp nếu bạn đã có Node.
- `brew install anomalyco/tap/opencode-v2` là cách README đánh dấu "recommended, always up to date" cho macOS và Linux. Còn `brew install opencode` là công thức brew chính thức nhưng cập nhật chậm hơn.
- `pacman` và `paru` dành cho người dùng Arch Linux (bản ổn định và bản mới nhất từ AUR).
- `mise use -g opencode` dùng được trên mọi hệ điều hành nếu bạn đã có mise.
- `nix run github:anomalyco/opencode` chạy trực tiếp bằng Nix.

Chỗ dễ vấp: đừng chạy hết cả danh sách. Các dòng đó là các lựa chọn thay thế nhau, và dòng có dấu `#` là chú thích.

### Bước 2b: Hoặc dùng bản desktop (BETA)

Nếu bạn không thích terminal, tải ứng dụng desktop tại opencode.ai/download. Tên file theo README:

- 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 bằng Homebrew:

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

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

### Bước 3: Mở dự án và khởi chạy

README chưa ghi rõ lệnh khởi chạy sau khi cài. Cách thường gặp với công cụ dòng lệnh là mở terminal trong thư mục dự án rồi gõ tên lệnh `opencode`. Bạn nên đối chiếu lại trong trang tài liệu chính thức. Ví dụ để vào thư mục dự án:

```bash
cd ten-thu-muc-du-an
```

Thay `ten-thu-muc-du-an` bằng tên thư mục thật của bạn. Nhiều người mới quên bước này và chạy ở thư mục sai, khiến AI nhìn không thấy code cần xem.

### Bước 4: Đọc tài liệu cấu hình

README chỉ hướng dẫn cài và giới thiệu agent. Phần cấu hình (kết nối mô hình AI, tuỳ chỉnh agent…) nằm ở opencode.ai/docs và opencode.ai/docs/agents.

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

README không mô tả kết quả mong đợi, nên mình đưa ra cách kiểm tra hợp lý:

1. Cài xong, **mở terminal mới** (để máy nhận đường dẫn mới) và thử khởi chạy opencode trong một thư mục dự án.
2. Nếu bạn cài bằng script, file nằm ở `$HOME/.opencode/bin`. Bạn có thể vào thư mục này xem có file chương trình không.
3. Khi giao diện mở lên, thử bấm phím `Tab`. README nói phím này chuyển giữa hai agent **build** và **plan**. Nếu chuyển được, bạn đã chạy đúng.
4. Với bản desktop, mở ứng dụng sau khi cài. Nếu cửa sổ hiện lên là thành công.

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

Các tình huống dưới đây bám theo khả năng mà README mô tả: hai agent build và plan, cùng `@general`. Câu lệnh mẫu là gợi ý của mình, bạn tự điều chỉnh theo dự án.

### Tình huống 1: Nhận một dự án lạ từ đồng nghiệp

Bạn là lập trình viên mới, vừa được giao repo của người đã nghỉ việc. Mở opencode trong thư mục repo, bấm `Tab` để chuyển sang agent **plan**. Vì plan chỉ đọc, bạn yên tâm là nó không sửa gì.

Prompt mẫu:

```text
Hãy đọc dự án này và giải thích cấu trúc thư mục. File nào là điểm bắt đầu của chương trình?
```

Kết quả: bạn có bản tóm tắt cấu trúc dự án, đủ để biết nên đọc file nào trước. README nói plan ở chế độ này rất hợp để khám phá codebase lạ.

### Tình huống 2: Lên kế hoạch trước khi sửa

Chủ shop nhỏ có một website bán hàng và muốn thêm trường "ghi chú đơn hàng". Thay vì để AI sửa ngay, bạn dùng **plan** để nhờ nó liệt kê những chỗ cần đổi.

```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ả.
```

Kết quả: một danh sách việc cần làm. Bạn đọc, thấy hợp lý rồi mới bấm `Tab` sang **build** để thực hiện. Plan hỏi quyền trước khi chạy lệnh bash, nên bạn kiểm soát được từng bước.

> Cho AI đọc trước, sửa sau: chỉ riêng thói quen này đã tránh được nửa số rắc rối.
>
> — Ông T

### Tình huống 3: Tìm kiếm nhiều bước bằng @general

Bạn đang làm việc trong dự án lớn và cần tìm "mọi nơi đang xử lý việc tính phí vận chuyển". Việc này phải tìm qua nhiều file. README nói subagent **general** dành cho tìm kiếm phức tạp và việc nhiều bước, và bạn gọi bằng `@general`.

```text
@general tìm tất cả chỗ trong dự án có tính phí vận chuyển và cho mình biết mỗi chỗ làm gì
```

Kết quả: danh sách các vị trí liên quan để bạn xem tiếp, thay vì tự bấm tìm từng file.

### Tình huống 4: Nhờ agent build viết hoặc sửa một đoạn code nhỏ

Nhân viên văn phòng có một script xử lý file báo cáo bị lỗi. Ở agent **build** (mặc định), bạn dán mô tả lỗi và nhờ sửa:

```text
Script xu_ly_bao_cao nay bao loi khi file co dong trong. Hay doc va sua giup minh.
```

Kết quả: AI đề xuất và áp dụng thay đổi vào file. Bạn nên sao lưu file gốc hoặc dùng git trước, và đọc lại thay đổi rồi mới dùng cho dữ liệu thật.

## 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 tình huống rất dễ gặp với loại công cụ này.

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

Thường do terminal chưa nhận đường dẫn mới sau khi cài. Hãy đóng terminal rồi mở lại. Nếu cài bằng script, chương trình nằm trong `$HOME/.opencode/bin`, bạn kiểm tra xem thư mục này có nằm trong PATH của máy chưa.

### Cài xong nhưng chạy ra bản cũ hoặc lỗi lạ

README dặn gỡ các phiên bản cũ hơn 0.1.x trước khi cài. Nếu bạn từng cài bằng nhiều cách khác nhau (vừa npm vừa brew chẳng hạn), có thể máy đang chạy nhầm bản. Hãy giữ lại một cách cài duy nhất.

### Nhầm tên gói npm

Trong README, lệnh npm dùng gói `@opencode/cli@latest`, trong khi tư liệu repo ghi tên gói npm là `opencode`. Hai tên này khác nhau. Nếu lệnh npm của bạn báo lỗi, hãy thử cách cài khác trong danh sách (script hoặc Homebrew), hoặc kiểm tra lại hướng dẫn mới nhất tại opencode.ai.

### Script cài đặt bị chặn hoặc lỗi trên Windows

Lệnh `curl ... | bash` cần có bash. Trên Windows thường không có sẵn trong PowerShell thuần. Hãy dùng bản desktop `.exe` mà README cung cấp, hoặc cài qua trình quản lý gói bạn đã có (như npm hoặc mise).

### AI không chịu sửa file

Bạn có thể đang ở agent **plan**, vốn từ chối sửa file theo mặc định. Bấm `Tab` để chuyển sang **build**. Ngược lại, nếu chỉ muốn xem xét mà lỡ để ở build, hãy chuyển sang plan cho an toàn.

## 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.506 sao) và còn được cập nhật.
- Hai chế độ build/plan tách bạch, giúp bạn kiểm soát việc AI được làm gì.
- Nhiều cách cài, có cả bản desktop cho người ngại dòng lệnh.
- README có nhiều bản dịch, trong đó có tiếng Việt (README.vi.md).

**Giới hạn**

- README ngắn, chưa nói rõ yêu cầu hệ thống, cách kết nối mô hình AI hay chi phí. Bạn phải đọc thêm tài liệu chính thức.
- Bản desktop còn ở giai đoạn BETA.
- Có vài chỗ trong README có thể gây nhầm (tên gói npm, nhiều bản brew), nên cần đối chiếu khi cài.
- Dữ liệu dự án của bạn đi đâu còn phụ thuộc mô hình AI bạn chọn. Tư liệu chưa có thông tin về việc này.

**Khi nào nên chọn cách khác**: nếu bạn không đụng đến code hay file kỹ thuật, hoặc cần một công cụ có hỗ trợ và hướng dẫn tiếng Việt đầy đủ từng bước, hãy cân nhắc công cụ khác. Còn nếu bạn muốn thử một trợ lý code mở, linh hoạt và dễ kiểm soát, opencode là lựa chọn đáng bỏ vài phút cài thử. Hãy bắt đầu ở chế độ plan trên một dự án không quan trọng.

## 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 mã nguồn được. Tư liệu chưa nói về chi phí của mô hình AI mà bạn kết nối vào, nên bạn cần xem tài liệu tại opencode.ai/docs.

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

Có bản desktop (BETA) cho Windows với file opencode-desktop-win-x64.exe. Bản dòng lệnh thì README liệt kê macOS, Linux và mise cho mọi hệ điều hành. Riêng script curl cần có bash.

### Cài opencode bằng cách nào dễ nhất?

Script một dòng `curl -fsSL https://opencode.ai/v2/install | bash` là nhanh nhất, nó cài vào $HOME/.opencode/bin. Nếu ngại terminal, hãy tải bản desktop tại opencode.ai/download.

### Khác nhau giữa agent build và plan là gì?

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

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

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

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

Tư liệu không nêu yêu cầu về GPU hay phần cứng. Vì vậy mình không thể khẳng định. Bạn nên xem thêm trong tài liệu chính thức.

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

Tư liệu repo chưa có thông tin chi tiết về cách xử lý dữ liệu. Repo có file SECURITY.md để bạn tham khảo. Mức an toàn thực tế còn phụ thuộc vào mô hình AI và cấu hình bạn chọn.
