# 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ở, viết bằng TypeScript, giấy phép MIT. Nó giúp bạn khám phá mã nguồn, lên kế hoạch và sửa code bằng cách trò chuyện. Cài khá dễ: một dòng curl hoặc qua npm, Homebrew; ngoài ra có bản Desktop (beta) cho macOS, Windows, Linux.

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

opencode là một agent lập trình AI mã nguồn mở. Hiểu đơn giản: bạn mô tả việc cần làm bằng lời, nó đọc dự án, đề xuất và (nếu bạn cho phép) trực tiếp sửa file, chạy lệnh giúp bạn. Tác giả mô tả ngắn gọn repo là 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 kèm khi đọc một dự án lạ, và với người làm kinh doanh, văn phòng hay phải chỉnh vài đoạn code, script, trang web nhỏ mà không muốn mày mò một mình. Nếu bạn đã quen các trợ lý AI trong khung chat, opencode đưa trợ lý đó vào thẳng thư mục dự án của bạn.

Điểm đáng giá nhất: repo hiện có khoảng 226.500 sao và 30.600 fork, giấy phép MIT (dùng và sửa tự do), vẫn được cập nhật trong 3 tháng gần đây. Ngoài ra nó có hai chế độ rất thực tế: một chế độ được sửa file, một chế độ chỉ đọc để bạn yên tâm khám phá.

```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 (beta), giấy phép MIT.
- stars | 227k
- lang | TypeScript
- license | MIT
```

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

Dưới đây là những gì README nói rõ, kèm lợi ích thực tế.

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

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

Bạn đổi qua lại giữa hai agent bằng phím `Tab`. Thói quen tốt cho người mới: cứ vào chế độ plan để hỏi và hiểu trước, rồi 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ó subagent **general**, dùng cho các tìm kiếm phức tạp và nhiệm vụ nhiều bước. Theo README, nó chủ yếu được dùng nội bộ, nhưng bạn có thể gọi trực tiếp bằng `@general` trong tin nhắn.

### Có cả bản Desktop (beta)

Nếu không thích dùng dòng lệnh, bạn có thể tải ứng dụng Desktop cho macOS (Apple Silicon và Intel), Windows và Linux. Bản này đang ở giai đoạn BETA nên có thể còn lỗi vặt.

### Nhiều cách cài và nhiều ngôn ngữ tài liệu

Bạn có thể cài bằng script, npm, Homebrew, pacman, mise hoặc Nix. README cũng có bản dịch tiếng Việt (file README.vi.md trong repo), tiện nếu bạn muốn đọc thêm bằng tiếng mẹ đẻ.

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

Tư liệu README nói khá ít về điều kiện, nên mình chỉ nêu đúng những gì có:

- Hệ điều hành: README có đường cài cho macOS, Linux (kể cả Arch Linux) và bản Desktop cho Windows. Phần dòng lệnh dùng `curl ... | bash` nên hợp với macOS/Linux; trên Windows, cách chắc chắn nhất theo README là tải bản Desktop `opencode-desktop-win-x64.exe`.
- Nếu cài qua npm, bạn cần có Node.js và npm trên máy (README nhắc đến npm, bun, pnpm, yarn). README không ghi phiên bản Node tối thiểu.
- Nếu đã từng cài phiên bản rất cũ, README khuyên gỡ các bản cũ hơn 0.1.x trước khi cài.
- Tài khoản, API key, phần cứng (GPU): README **chưa ghi**. Phần cấu hình nằm trong tài liệu chính thức tại trang chủ dự án (opencode.ai/docs). Bạn nên xem ở đó trước khi dùng thật.

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

```steps
- Mở terminal | Mở terminal ở thư mục bạn muốn làm việc
- Chọn cách cài | Chạy script curl, hoặc npm, hoặc Homebrew tuỳ máy bạn
- Cài bản Desktop (tuỳ chọn) | Tải file cài từ trang tải về nếu không thích dùng dòng lệnh
- Xem tài liệu cấu hình | Đọc docs để biết cách thiết lập trước khi dùng
```

### Bước 1: Mở terminal đúng chỗ

Trên macOS/Linux, mở ứng dụng Terminal. Trên Windows, nếu bạn muốn dùng dòng lệnh, mở PowerShell; còn nếu thấy rườm rà, bỏ qua và sang phần bản Desktop. Người mới hay vấp ở chỗ gõ lệnh sai thư mục, nên nếu bạn định để opencode làm việc trên một dự án, hãy mở terminal ngay trong thư mục dự án đó (hoặc dùng lệnh cd để vào).

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

README liệt kê nhiều cách. Bạn chỉ cần chọn MỘT cách phù hợp với máy mình. Danh sách nguyên văn 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 ngắn từng nhóm:

- Dòng `curl ... | bash` (README đặt nhãn YOLO) tải script cài về và chạy ngay. Tiện nhưng bạn đang chạy một script từ mạng mà chưa đọc nó. Nếu cẩn thận, hãy mở địa chỉ script bằng trình duyệt để xem trước.
- Dòng `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.
- Hai dòng `brew` dành cho macOS và Linux có Homebrew. README khuyến nghị dòng `anomalyco/tap/opencode-v2` vì luôn mới nhất; dòng `brew install opencode` là công thức chính thức nhưng cập nhật chậm hơn.
- `pacman` và `paru` dành cho Arch Linux; `mise` dùng được trên mọi hệ điều hành; `nix run` dành cho người dùng Nix.

Lưu ý: các dòng trong README có tên gói hơi khác nhau (ví dụ `@opencode/cli` và `opencode`). Bạn cứ chép đúng dòng của cách mình chọn, đừng trộn lẫn. Nếu có lỗi không tìm thấy gói, xem lại trang cài đặt trong docs.

Nếu dùng script curl, README cho biết nó cài opencode vào thư mục sau:

```bash
$HOME/.opencode/bin
```

Đây là đường dẫn chương trình nằm sau khi cài. Nếu gõ tên lệnh mà máy báo không tìm thấy, có thể thư mục này chưa nằm trong PATH; README chưa hướng dẫn chỗ này nên bạn xem thêm trong docs.

```note
Lệnh curl ... | bash chạy thẳng một script từ internet. Chỉ chạy khi bạn tin nguồn, và nên đọc script trước nếu có thể. Nếu ngại, hãy chọn Homebrew, npm hoặc bản Desktop.
```

### Bước 3: Cài bản Desktop (tuỳ chọn)

Nếu không muốn dùng dòng lệnh, tải bản Desktop từ trang tải về của dự án (opencode.ai/download). Tên file theo từng nền tảng:

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

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

Với Windows, chỉ cần tải file `.exe`, bấm đúp và làm theo hướng dẫn. Đây là cách đơn giản nhất cho người không quen terminal.

### Bước 4: Xem tài liệu để cấu hình

README chưa ghi chi tiết cách khởi động lần đầu, cách kết nối mô hình AI hay điền khoá truy cập. Tất cả nằm ở tài liệu chính thức: opencode.ai/docs. Đây là bước không nên bỏ qua. Nếu cần thông tin thêm, bạn cũng có thể xem file AGENTS.md và CONTRIBUTING.md trong repo.

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

README không nêu một lệnh kiểm tra cụ thể hay kết quả mong đợi, nên mình không bịa ra. Có vài dấu hiệu hợp lý để bạn tự kiểm tra:

- Với bản Desktop: mở ứng dụng lên và thấy giao diện của opencode hiện ra là xong.
- Với bản dòng lệnh: sau khi cài, mở một cửa sổ terminal mới và thử gọi chương trình theo cách docs hướng dẫn. Nếu terminal báo không tìm thấy lệnh, xem lại phần PATH ở trên.
- Khi giao diện hiện ra, thử bấm `Tab` để xem có chuyển được giữa hai agent build và plan hay không. Đây là tính năng README nói rõ.

Bạn đối chiếu thêm với hướng dẫn bắt đầu trong docs để chắc chắn mình làm đúng trình tự.

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

Phần này là các tình huống mình thấy hợp với những gì README mô tả (agent build, agent plan, subagent general). Câu lệnh mẫu chỉ là lời bạn nói với AI, không phải lệnh cài đặt.

### Tình huống 1: Lập trình viên mới nhận một dự án lạ

Bạn vừa vào công ty và được giao một dự án mà không ai ghi chú gì. Mở opencode trong thư mục dự án, chuyển sang agent **plan** bằng phím `Tab`. Vì agent này chỉ đọc, bạn không sợ lỡ tay làm hỏng gì.

Prompt mẫu:

```text
Hãy đọc cấu trúc dự án này và giải thích cho mình: dự án làm gì, file nào là điểm bắt đầu, và mình nên đọc theo thứ tự nào.
```

Kết quả: bạn có một bản tóm tắt để đọc dần, thay vì mở từng file đoán mò.

### Tình huống 2: Chủ shop muốn sửa một chỗ nhỏ trên trang web

Bạn có một trang bán hàng nhỏ do người khác dựng, giờ muốn đổi chữ hoặc chỉnh một đoạn mã nhỏ. Hãy bắt đầu với agent plan: nhờ nó chỉ ra chính xác chỗ cần sửa và kế hoạch sửa. Đọc kế hoạch xong, nếu thấy ổn mới chuyển sang agent **build** để nó áp dụng.

Prompt mẫu:

```text
Mình muốn đổi dòng khuyến mãi trên trang chủ. Hãy chỉ cho mình file nào chứa dòng đó và đề xuất cách sửa, chưa cần sửa ngay.
```

Kết quả: bạn kiểm soát được từng bước và biết nó định đụng vào file nào trước khi cho phép.

> Cứ để agent plan đọc và lên kế hoạch trước, bạn gật đầu rồi mới cho build ra tay: vậy là bạn vẫn cầm lái.
>
> — Ông T

### Tình huống 3: Tìm một đoạn code nằm đâu đó trong dự án lớn

Dự án có hàng trăm file và bạn cần biết chỗ nào đang xử lý việc tính tiền hoặc gửi email. README nói subagent **general** dùng cho các tìm kiếm phức tạp và nhiệm vụ nhiều bước, và bạn có thể gọi nó bằng `@general` trong tin nhắn.

Prompt mẫu:

```text
@general tìm giúp mình tất cả chỗ trong dự án có xử lý việc tính tổng đơn hàng và liệt kê tên file.
```

Kết quả: một danh sách các vị trí liên quan để bạn mở ra xem hoặc nhờ agent build sửa tiếp.

### Tình huống 4: Nhân viên văn phòng viết script tự động nhỏ

Bạn hay phải đổi tên hàng loạt file hoặc gom số liệu từ nhiều file thành một. Mở opencode trong thư mục chứa các file, dùng agent build và mô tả việc cần làm bằng lời thường. Vì agent build có toàn quyền, hãy làm việc trên bản sao dữ liệu quan trọng, không làm trực tiếp trên bản gốc duy nhất.

Prompt mẫu:

```text
Viết giúp mình một script gom các file trong thư mục này thành một danh sách, và giải thích từng bước script làm gì.
```

Kết quả: một script bạn có thể đọc, chạy thử và chỉnh dần. README không nói rõ giới hạn loại file nào, nên hãy thử trên dữ liệu nhỏ trước.

## 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ễ xảy ra với loại công cụ này.

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

Thường do thư mục cài chưa nằm trong PATH, hoặc bạn chưa mở terminal mới sau khi cài. Hãy đóng terminal, mở lại rồi thử. Với script curl, chương trình nằm ở `$HOME/.opencode/bin`, bạn có thể kiểm tra xem thư mục đó có tồn tại không. Nếu vẫn lỗi, xem hướng dẫn trong docs.

### Cài nhầm hoặc cài chồng nhiều cách

README có nhiều dòng lệnh cho nhiều cách cài, và các tên gói khác nhau. Nếu bạn chạy lẫn lộn, dễ sinh ra nhiều bản cùng lúc. Hãy chọn một cách duy nhất, và nếu từng cài bản rất cũ (trước 0.1.x), README khuyên gỡ nó đi trước.

### Không dùng được vì chưa cấu hình mô hình AI hoặc khoá truy cập

Repo chỉ là agent; README không ghi nó dùng mô hình nào hay cần khoá nào. Nếu mở lên mà không trả lời, rất có thể bạn chưa cấu hình phần này. Đọc tài liệu cấu hình tại opencode.ai/docs và làm theo. Không dán khoá truy cập vào chỗ công khai như tin nhắn, ảnh chụp màn hình hay kho code.

### Agent sửa nhầm file

Agent build có toàn quyền nên có thể sửa nhiều file hơn bạn nghĩ. Cách phòng: dùng agent plan để xem kế hoạch trước, làm việc trong thư mục có quản lý phiên bản (như git) hoặc có bản sao lưu, và đọc kỹ những gì nó định làm trước khi đồng ý.

### Bản Desktop lỗi vặt

Bản Desktop đang ở giai đoạn beta nên có thể có lỗi. Thử đóng mở lại, tải lại bản mới từ trang tải về chính thức, hoặc chuyển sang dùng bản dòng lệnh. Có thể hỏi thêm ở cộng đồng Discord của dự án.

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

**Điểm mạnh**

- Mã nguồn mở, giấy phép MIT, cộng đồng rất lớn (khoảng 226.500 sao) và vẫn được cập nhật.
- Có sẵn chế độ chỉ đọc (plan) nên rất hợp cho người mới, khám phá dự án mà không sợ làm hỏng.
- Nhiều cách cài, có cả bản Desktop cho Windows, macOS, Linux.

**Giới hạn**

- README ngắn, chưa hướng dẫn rõ cách khởi động lần đầu, cấu hình mô hình hay chi phí. Bạn phải đọc thêm docs.
- Bản Desktop vẫn là beta.
- Agent có thể chạy lệnh và sửa file, nên bạn vẫn cần xem lại kết quả. Chưa có thông tin trong tư liệu về chuyện dữ liệu của bạn được xử lý thế nào khi gửi cho mô hình AI; hãy kiểm tra trong docs trước khi cho nó đọc dữ liệu nhạy cảm.

**Khi nào chọn cách khác**: nếu bạn chỉ cần hỏi đáp một đoạn code ngắn, khung chat thông thường là đủ. Nếu công ty bạn có quy định chặt về dữ liệu, hãy hỏi bộ phận kỹ thuật trước. Còn nếu bạn muốn một trợ lý nằm ngay trong thư mục dự án, đọc, lập kế hoạch và sửa code theo từng bước có kiểm soát, opencode là một lựa chọn đáng thử.

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

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

Bản thân repo là mã nguồn mở với giấy phép MIT, bạn tải và dùng tự do. Tư liệu README không nói gì về chi phí khi kết nối mô hình AI bên ngoài, nên chưa có thông tin. Bạn xem thêm trong tài liệu chính thức.

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

Có bản Desktop cho Windows: file opencode-desktop-win-x64.exe tải từ trang tải về của dự án (đang ở dạng BETA). Về bản dòng lệnh trên Windows, README chưa ghi rõ, nên bạn xem thêm trong docs.

### 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, kể cả GPU. Chưa có thông tin chính thức về việc này trong tư liệu.

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

Build là agent mặc định, toàn quyền cho 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ài bằng cách nào nhanh nhất?

README có lệnh curl -fsSL https://opencode.ai/v2/install | bash, ngoài ra còn npm, Homebrew, pacman, mise, Nix. Nếu không muốn dùng terminal, bạn có thể tải bản Desktop. Hãy chọn một cách duy nhất.

### 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 quyền riêng tư. Với dữ liệu nhạy cảm, bạn nên đọc tài liệu chính thức và hỏi bộ phận kỹ thuật trước. Chế độ plan giúp hạn chế việc agent sửa file ngoài ý muốn.

### Tôi hỏi và xem tài liệu ở đâu?

README dẫn đến tài liệu cấu hình tại opencode.ai/docs, kèm cộng đồng Discord và X của dự án. Repo còn có bản README tiếng Việt (README.vi.md).
