# 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 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 cài bằng một dòng lệnh hoặc qua trình quản lý gói như npm, Homebrew, rồi dùng để đọc, phân tích và sửa code. Cài đặt không khó, nhưng README chưa ghi rõ cách kết nối mô hình AI nên bạn cần xem thêm tài liệu trên trang chủ dự án.

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

OpenCode là một coding agent mã nguồn mở: một trợ lý AI giúp bạn đọc, hiểu và chỉnh sửa code ngay trong dự án của mình. Repo hiện có khoảng 226.506 sao và 30.658 fork, giấy phép MIT, viết chủ yếu bằng TypeScript, và vẫn được cập nhật trong vài tháng gần đây.

Vấn đề nó giải quyết khá quen thuộc. Bạn có một dự án, bạn muốn có ai đó đọc giúp, giải thích giúp, hoặc sửa giúp một đoạn code, nhưng không muốn copy qua copy lại giữa trình duyệt và editor. Agent như OpenCode làm việc ngay trong thư mục dự án, nên nó nhìn thấy cả bức tranh.

Điểm đáng giá nhất là hai chế độ làm việc tách bạch: **build** (được phép sửa file) và **plan** (chỉ đọc, không sửa). Nhờ vậy lập trình viên mới có thể cho AI đọc thử một codebase lạ mà không sợ nó lỡ tay thay đổi gì. Ngoài bản dòng lệnh còn có ứng dụng desktop (đang beta) cho ai không thích terminal.

```repo
- repo | anomalyco/opencode
- kind | Agent
- desc | OpenCode là agent lập trình AI mã nguồn mở, có hai chế độ build và plan, cài bằng một dòng lệnh hoặc dùng bản ứng dụng desktop (beta).
- stars | 227k
- lang | TypeScript
- license | MIT
```

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

Dưới đây là những điều README nói rõ. Mình không thêm tính năng nào ngoài tư liệu.

### Hai agent có sẵn: build và plan

OpenCode đi kèm hai agent, bạn chuyển qua lại bằng phím `Tab`.

- **build** là agent mặc định, có 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ó bắt tay vào làm.
- **plan** là 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ế: bạn có một «chế độ an toàn». Muốn hiểu một dự án thừa kế từ người khác, hay muốn lên kế hoạch trước khi sửa, cứ để ở plan. Khi kế hoạch ổ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ó một subagent tên **general**, dành cho các tìm kiếm phức tạp và việc nhiều bước. README cho biết nó chủ yếu được dùng nội bộ, nhưng bạn có thể gọi trực tiếp 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ần theo nhiều file mới trả lời được.

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

Bạn có thể cài bằng script một dòng, npm, Homebrew, pacman, paru, mise hoặc Nix. Nghĩa là dù dùng macOS, Linux hay Windows, thường sẽ có một cách hợp với máy bạn. Ngoài ra có bản ứng dụng desktop (BETA) cho macOS, Windows và Linux.

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

Giấy phép MIT cho phép dùng khá thoải mái, kể cả trong công việc kinh doanh. Bạn cũng đọc được code để biết nó làm gì với máy của mình.

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

Tư liệu README khá ngắn nên phần này cũng ngắn. Mình chỉ nêu những gì có trong đó.

- **Hệ điều hành:** README liệt kê cách cài cho macOS, Linux (kể cả Arch Linux), và bản desktop có file cho Windows. Script cài đặt dạng `curl ... | bash` và các lệnh brew dành cho macOS/Linux. Riêng mise được ghi là chạy trên «mọi hệ điều hành».
- **Một trong các công cụ cài đặt**, tuỳ cách bạn chọn: npm (hoặc bun, pnpm, yarn), Homebrew, pacman, paru, mise hoặc Nix.
- **Gỡ 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, phiên bản Node, phần cứng:** README chưa nói gì về các mục này. Muốn biết cần chuẩn bị mô hình AI hay khoá nào, bạn xem tài liệu cấu hình tại trang chủ dự án (opencode.ai/docs).

```note
Một agent lập trình có thể sửa file và chạy lệnh trên máy bạn. Lần đầu thử, hãy dùng thư mục dự án thử nghiệm hoặc dự án đã có bản sao lưu, và để ở chế độ plan cho tới khi bạn quen. Nếu sau này bạn điền API key của dịch vụ AI nào đó, đừng dán key vào nơi công khai và hãy để ý chi phí sử dụng của dịch vụ đó.
```

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

```steps
- Chọn cách cài | Script một dòng, trình quản lý gói, hoặc bản desktop
- Mở terminal | Windows PowerShell hoặc terminal trên macOS/Linux
- Chạy lệnh cài | Chép đúng một dòng lệnh trong README
- Mở thư mục dự án | cd vào dự án của bạn để agent làm việc ở đó
- Chạy OpenCode | Khởi động, rồi xem docs để cấu hình mô hình AI
```

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

README đưa ra nhiều lựa chọn, bạn chỉ cần chọn **một**. Gợi ý cho người mới:

- Dùng macOS/Linux và đã có Homebrew: chọn dòng `brew`.
- Đã có Node/npm: chọn dòng `npm`.
- Không muốn gõ lệnh: dùng bản desktop ở bước riêng bên dưới.

### Bước 2: Mở terminal

Trên macOS mở ứng dụng Terminal. Trên Linux mở terminal của bản phân phối bạn dùng. Trên Windows mở PowerShell. Lưu ý quan trọng: các lệnh `curl ... | bash` trong README là cú pháp cho macOS/Linux; trên Windows, bạn nên chọn npm hoặc bản desktop cho đỡ vấp.

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

Đây là toàn bộ khối lệnh cài trong README, chép nguyên văn. Bạn chỉ chạy **một dòng** hợp với máy mình, đừng chạy hết:

```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` tải script cài đặt rồi chạy luôn. README tự gọi nó là «YOLO» vì bạn chạy script mà chưa kịp đọc. Nếu muốn chắc ăn, hãy mở địa chỉ script trong trình duyệt để đọc trước khi chạy.
- Dòng `npm i -g ...` cài toàn cục qua npm. Chú thích «or bun/pnpm/yarn» nghĩa là bạn có thể dùng các công cụ tương tự thay cho npm.
- Hai dòng `brew`: README ghi dòng `anomalyco/tap/opencode-v2` là khuyến nghị và luôn mới; dòng `brew install opencode` là bản chính thức nhưng cập nhật chậm hơn.
- Các dòng `pacman`, `paru` dành riêng cho Arch Linux; `mise` dùng được trên mọi hệ điều hành; `nix run` chạy trực tiếp qua Nix.

Nếu dùng script cài, README cho biết nó đặt OpenCode vào `$HOME/.opencode/bin`. Nếu sau khi cài, máy không nhận lệnh, hãy kiểm tra thư mục này có nằm trong PATH không.

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

Bản ứng dụng desktop đang ở trạng thái BETA. Bạn tải từ trang opencode.ai/download. Các file theo README:

- 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òn có thể cài bằng Homebrew:

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

Lệnh này cài bản ứng dụng (cask) thay vì bản dòng lệnh.

### Bước 5: Vào thư mục dự án và khởi động

README chưa ghi lệnh khởi động cụ thể. Tên gói npm trong tư liệu là `opencode`, nên thông thường bạn mở terminal tại thư mục dự án rồi gõ tên lệnh đó; nếu không chạy, hãy xem phần hướng dẫn bắt đầu tại opencode.ai/docs. Việc `cd` vào đúng thư mục dự án là quan trọng, vì agent sẽ làm việc trong thư mục bạn đang đứng:

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

Còn việc chọn mô hình AI và nhập khoá (nếu cần), README chưa ghi. Hãy làm theo phần cấu hình trong tài liệu chính thức.

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

README không nêu lệnh kiểm tra riêng, nên mình chỉ gợi ý những dấu hiệu hợp lý:

1. Sau khi cài, mở **một cửa sổ terminal mới** và chạy lệnh của OpenCode. Nếu terminal không báo kiểu «command not found», tức là lệnh đã được nhận.
2. Khi khởi động, bạn nên thấy giao diện làm việc của agent. Thử nhấn `Tab`: README nói phím này chuyển giữa agent **build** và **plan**. Nếu thấy chế độ đổi, bạn đã chạy đúng.
3. Với bản desktop, chỉ cần mở ứng dụng lên được là đạt bước này.

Nếu cài bằng script, thử kiểm tra thư mục `$HOME/.opencode/bin` có tồn tại không, vì đó là nơi README nói script cài vào.

## 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 build/plan, subagent general và phím `Tab`. Câu lệnh mẫu chỉ là cách bạn diễn đạt yêu cầu bằng lời bình thường.

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

Bạn vừa vào công ty, được giao một codebase mà người cũ đã nghỉ. Bạn mở terminal tại thư mục dự án, bật OpenCode và để ở chế độ **plan** (chỉ đọc). Rồi hỏi:

```text
Dự án này gồm những phần chính nào? Luồng xử lý một yêu cầu đi qua những file nào?
```

Vì plan từ chối sửa file theo mặc định và hỏi trước khi chạy bash, bạn khám phá thoải mái mà không sợ làm hỏng gì. Kết quả: một bức tranh tổng quan để bắt đầu, thay vì mở từng file đoán mò cả buổi.

> Cứ để AI đọc trước, hiểu rồi mới cho nó sửa. Chế độ chỉ đọc sinh ra để làm việc đó.
>
> — Ông T

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

Bạn là freelancer, khách muốn thêm một tính năng nhỏ vào website. Trước khi động tay, bạn ở chế độ **plan** và nhờ:

```text
Mình muốn thêm tính năng X. Hãy chỉ ra cần sửa những file nào và nên làm theo thứ tự nào.
```

Bạn nhận được danh sách việc cần làm có cơ sở từ chính code hiện có. Đọc kỹ, đồng ý rồi nhấn `Tab` sang **build** và nhờ nó thực hiện từng bước. Tách «nghĩ» và «làm» như vậy giúp bạn kiểm soát hơn nhiều.

### Tìm một đoạn logic nằm rải rác nhiều file

Bạn cần biết «giá giảm cho khách quen được tính ở đâu». Đoạn này có thể nằm ở nhiều chỗ. Bạn gọi subagent bằng `@general` trong tin nhắn:

```text
@general tìm giúp mình nơi tính giá giảm cho khách quen và liệt kê các file liên quan
```

README mô tả general dành cho tìm kiếm phức tạp và việc nhiều bước, nên đây là đúng chỗ dùng nó. Kết quả là danh sách vị trí cần xem, bạn khỏi phải tự tìm từng file.

### Chủ shop nhỏ có người làm web giúp

Bạn không code, nhưng người làm website cho bạn hay vắng mặt. Bạn có thể dùng chế độ plan để nhờ AI giải thích một đoạn code «đang làm gì» bằng ngôn ngữ dễ hiểu, giúp bạn nói chuyện với thợ web chính xác hơn. Mình khuyên chỉ dùng plan, và để người có chuyên môn xem lại trước khi sửa bất kỳ thứ gì trên website đang bán hàng. README không nói về trường hợp này, đây chỉ là cách ứng dụng hợp lý từ chế độ chỉ đọc.

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

### Gõ lệnh báo không tìm thấy (command not found)

Thường do terminal chưa nhận đường dẫn mới sau khi cài. Hãy đóng terminal, mở cửa sổ mới rồi thử lại. Nếu cài bằng script, kiểm tra xem `$HOME/.opencode/bin` đã nằm trong PATH chưa. Nếu vẫn không được, thử cài lại bằng một cách khác trong README (ví dụ npm hoặc brew).

### Lệnh curl chạy không được trên Windows

Dòng `curl ... | bash` viết cho macOS/Linux. Trên Windows PowerShell, bạn nên chọn `npm i -g @opencode/cli@latest` nếu đã có Node, hoặc tải file `opencode-desktop-win-x64.exe` từ trang tải về.

### Cài nhầm nhiều bản hoặc bản cũ gây xung đột

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 OpenCode bằng cách khác, hãy gỡ bản cũ bằng đúng công cụ đã dùng để cài, rồi cài lại một bản duy nhất. Lưu ý README có hai dòng brew khác nhau (một bản khuyến nghị và một bản chính thức cập nhật chậm hơn); chỉ chọn một.

### Mở lên nhưng AI không trả lời

Vì README không ghi cách kết nối mô hình AI, rất có thể bạn chưa cấu hình xong. Hãy làm theo hướng dẫn cấu hình tại opencode.ai/docs. Khi nhập khoá nào đó, kiểm tra không dán thừa khoảng trắng và không chia sẻ khoá ra ngoài.

### Agent sửa file ngoài ý muốn

Đây là rủi ro tự nhiên của agent có toàn quyền. Cách phòng: dùng chế độ **plan** khi chưa chắc, làm việc trên thư mục có sao lưu hoặc có quản lý phiên bản (git), và đọc lại thay đổi trước khi dùng thật.

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

**Điểm mạnh.** Mã nguồn mở, giấy phép MIT; có hai chế độ build/plan rất dễ hiểu; nhiều cách cài đặt; có cả bản desktop cho ai ngại terminal; cộng đồng lớn (hiện có khoảng 226.506 sao) và dự án vẫn được cập nhật đều.

**Giới hạn.** README rất ngắn, chưa nói rõ về cách khởi động, cách kết nối mô hình AI, yêu cầu phiên bản hay chi phí, bạn phải đọc thêm tài liệu trên trang chủ. Bản desktop đang BETA nên có thể chưa ổn định bằng. Phần cài đặt trong README có nhiều biến thể (hai tên gói npm/brew khác nhau xuất hiện), nên người mới dễ phân vân; hãy bám theo một cách và xem docs nếu có lỗi.

**Khi nào chọn cách khác.** Nếu bạn hoàn toàn không đụng vào code và chỉ cần một trợ lý hỏi đáp, một ứng dụng chat thông thường sẽ đơn giản hơn. Nếu công ty bạn có quy định nghiêm về việc đưa mã nguồn cho dịch vụ AI bên ngoài, hãy hỏi bộ phận phụ trách trước, vì tư liệu chưa nói dữ liệu của bạn được xử lý thế nào.

Nếu bạn là lập trình viên mới hoặc người làm kỹ thuật muốn có một trợ lý ngay trong thư mục dự án, OpenCode đáng để thử, miễn là bạn bắt đầu bằng chế độ plan và đọc kỹ tài liệu cấu hình.

## 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, nên bạn tải và dùng được. README không nói gì về chi phí của mô hình AI mà bạn kết nối. Phần này chưa có thông tin trong tư liệu, bạn nên xem tài liệu tại opencode.ai/docs.

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

README có file cài cho bản desktop trên Windows là opencode-desktop-win-x64.exe (đang BETA). Cũng có lệnh cài qua npm, và mise được ghi là dùng được trên mọi hệ điều hành. Dòng curl ... | bash là cú pháp cho macOS/Linux.

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

build là agent mặc định, có 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 quyền trước khi chạy lệnh bash. Bạn chuyển giữa hai agent bằng phím Tab.

### OpenCode có cần GPU không?

README không đề cập yêu cầu phần cứng hay GPU. Chưa có thông tin trong tư liệu về việc này.

### 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. Repo có file SECURITY.md ở thư mục gốc để bạn tham khảo chính sách bảo mật. Hãy thận trọng khi dùng với code nhạy cảm và bắt đầu với chế độ plan chỉ đọc.

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

Nếu đã có npm, dùng npm i -g @opencode/cli@latest. Nếu dùng macOS hoặc Linux có Homebrew, README khuyến nghị brew install anomalyco/tap/opencode-v2. Nếu không thích gõ lệnh, bạn có thể tải bản desktop (BETA) từ opencode.ai/download.

### Script cài đặt đặt OpenCode ở đâu?

Theo README, script cài đặt đặt OpenCode vào $HOME/.opencode/bin. README cũng dặn gỡ các phiên bản cũ hơn 0.1.x trước khi cài.
