# 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 (anomalyco/opencode) là một coding agent mã nguồn mở, giấy phép MIT, viết bằng TypeScript. Nó giúp bạn đọc, hỏi đáp và sửa code bằng ngôn ngữ tự nhiên. Cài đặt khá dễ: 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-05-25 · 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-7

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 thường, nó đọc code trong thư mục dự án rồi giúp bạn phân tích hoặc sửa. Tác giả giới thiệu ngắn gọn là "The open source coding agent". Repo hiện có khoảng 226.506 sao và 30.658 fork trên GitHub, viết chủ yếu bằng TypeScript, 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 muốn có "người kèm" khi đọc một dự án lạ, hoặc người làm văn phòng, chủ shop đang nhờ dev hay tự chỉnh vài đoạn code (website, file tự động hoá) và muốn có công cụ hỏi đáp trực tiếp trên code đó. Bạn không cần là chuyên gia, nhưng cần biết mở terminal và gõ lệnh.

Điểm đáng giá nhất của opencode là cách chia vai rõ ràng: một chế độ **build** có toàn quyền để làm việc, và một chế độ **plan** chỉ đọc, mặc định không sửa file. Bạn bấm phím `Tab` để chuyển qua lại. Nhờ vậy bạn có thể "nhìn" trước, an tâm rồi mới cho nó động vào code.

```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.
- stars | 227k
- lang | TypeScript
- license | MIT
```

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

Theo README, opencode có những phần chính sau.

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

- **build** là agent mặc định, có toàn quyền cho công việc phát triển. Bạn dùng khi đã biết mình muốn gì và để nó bắt tay 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 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 thay đổi trước.

Bạn chuyển giữa hai agent bằng phím `Tab`. Lợi ích thực tế: bạn kiểm soát được mức "quyền" của AI ngay trong lúc làm việc, không phải đổi cấu hình.

### 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 hoặc việc nhiều bước. README nói nó được dùng nội bộ, và 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 kiểu "chỗ nào trong dự án xử lý việc này?" cần lần qua nhiều file.

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

Bạn có thể cài qua script, npm, Homebrew, pacman, mise hoặc Nix. Ngoài ra có **ứng dụng desktop (BETA)** cho macOS, Windows và Linux, hợp với ai chưa quen terminal.

### Mã nguồn mở, có tài liệu riêng

Giấy phép MIT, nên bạn xem được code và dùng tự do theo giấy phép. Phần cấu hình chi tiết nằm ở trang tài liệu của dự án (opencode.ai/docs), README không chép lại.

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

README chỉ nói những điều sau:

- Một máy macOS, Linux hoặc Windows. Bản desktop có file cho macOS (Apple Silicon và Intel), Windows (`opencode-desktop-win-x64.exe`) và Linux (`.deb`, `.rpm`, `.AppImage`).
- Nếu dùng cách cài bằng npm thì cần có npm (README ghi "or bun/pnpm/yarn" nên các công cụ này cũng được).
- Nếu trước đây bạn đã cài phiên bản cũ hơn 0.1.x, README dặn gỡ đi trước khi cài.

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

```note
README không nói về chi phí hay key. Khi tài liệu hướng dẫn bạn điền khoá của một dịch vụ AI, hãy giữ kín khoá đó, đừng dán vào chat công khai hay đẩy lên GitHub. Hãy đọc kỹ bảng giá của dịch vụ bạn chọn trước khi cho AI chạy nhiều việc liên tục.
```

## 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
- Chạy lệnh cài | Dán lệnh tương ứng vào terminal
- Gỡ bản cũ nếu có | Xoá phiên bản cũ hơn 0.1.x trước khi cài
- Mở dự án | cd vào thư mục code bạn muốn làm việc
- Xem tài liệu cấu hình | Làm theo opencode.ai/docs để kết nối mô hình AI
```

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

README liệt kê nhiều cách. Nếu chưa quen, bạn chọn một cái thôi, không cần chạy hết. Người dùng macOS hoặc Linux thường chọn script hoặc Homebrew. Ai ngại terminal có thể nhảy sang phần bản desktop ở cuối mục này.

### Cài bằng script một dòng

Đây là cách README gọi vui là "YOLO" (chạy một phát cho xong). Mở terminal rồi dán:

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

Lệnh này tải script cài đặt từ trang chủ rồi chạy luôn. Theo README, script cài opencode vào thư mục `$HOME/.opencode/bin`. Lệnh này dùng `bash`, nên với Windows bạn nên cân nhắc một trong các cách khác bên dưới (npm, mise) hoặc bản desktop, vì README không nói rõ script chạy được trên Windows thuần hay không.

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

Tất cả các dòng dưới đây chép nguyên từ README. Chọn **một** dòng phù hợp hệ thống của bạn:

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

Ghi chú nhanh:

- `npm i -g` là cài toàn cục bằng npm, cần máy đã có Node và npm.
- Hai dòng `brew` dành cho macOS và Linux. README khuyên dòng đầu (`anomalyco/tap/opencode-v2`) vì luôn mới; dòng sau là bản chính thức của Homebrew nhưng cập nhật chậm hơn.
- `pacman` và `paru` dành cho Arch Linux.
- `mise use -g opencode` dùng được trên mọi hệ điều hành nếu bạn đã có mise.
- `nix run` chạy thẳng từ GitHub nếu bạn dùng Nix.
- Chỗ người mới hay vấp: tên gói trong README có chỗ là `opencode`, có chỗ là `@opencode/cli`. Cứ chép đúng dòng của cách bạn chọn, đừng tự sửa.

### Cài bản desktop (BETA)

Vào opencode.ai/download và tải file đúng hệ điều hành:

| 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ì đây là bản BETA, có thể còn lỗi vặt. Nếu gặp sự cố, thử bản terminal.

### Mở dự án và bắt đầu

README chưa ghi lệnh khởi động cụ thể. Bạn xem hướng dẫn trong tài liệu tại opencode.ai/docs. Khi làm việc, hãy đứng trong thư mục dự án của bạn. Ví dụ với một dự án tải từ GitHub (thay `<tên>/<repo>` bằng dự án của bạn):

```bash
git clone https://github.com/<tên>/<repo>.git
cd <repo>
```

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

README không nêu lệnh kiểm tra hay màn hình kết quả mong đợi. Cách an toàn để biết cài thành công:

- Mở **một cửa sổ terminal mới** (để máy nạp lại đường dẫn), rồi thử gọi lệnh `opencode`. Nếu terminal báo không tìm thấy lệnh, xem phần lỗi thường gặp bên dưới.
- Nếu cài bằng script, kiểm tra thư mục `$HOME/.opencode/bin` có tồn tại không, vì README nói script cài vào đó.
- Nếu dùng bản desktop, mở ứng dụng lên và thấy giao diện là xong bước cài.
- Khi vào được giao diện, thử bấm `Tab`: README nói phím này chuyển giữa agent build và plan. Thấy chế độ đổi là bạn đã chạy đúng.

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

README chỉ mô tả các agent chứ không đưa ví dụ cụ thể. Các tình huống dưới đây là cách mình gợi ý áp dụng, bám đúng khả năng đó.

### Nhân viên mới đọc một dự án code chưa từng thấy

Bạn vừa nhận bàn giao một website nội bộ, mở ra thấy hàng chục thư mục. Hãy để opencode ở chế độ **plan** (chỉ đọc, không sửa). Gõ câu hỏi bằng tiếng Việt:

```text
Dự án này làm gì? Hãy tóm tắt các thư mục chính và nói file nào xử lý đăng nhập.
```

Kết quả: bạn nhận được bản giải thích bằng lời, và vì đang ở plan nên không có file nào bị đổi. Nếu nó xin chạy lệnh bash, nó sẽ hỏi bạn trước.

> Cứ để AI đọc trước, sửa sau. Chế độ chỉ đọc là cách rẻ nhất để biết mình đang làm việc với cái gì.
>
> — Ông T

### Chủ shop muốn sửa nhỏ trên trang bán hàng

Bạn có một trang giới thiệu sản phẩm bằng code đơn giản và muốn đổi số hotline, thêm một dòng chính sách đổi trả. Trước tiên, ở chế độ plan, hỏi nó sẽ sửa ở đâu. Khi đã thấy hợp lý, bấm `Tab` sang **build** rồi ra lệnh:

```text
Đổi số hotline thành số mới ở mọi nơi trong dự án, và thêm dòng "Đổi trả trong 7 ngày" dưới phần mô tả sản phẩm.
```

Kết quả: các file được sửa theo yêu cầu. Bạn nên mở lại trang để xem bằng mắt, hoặc nhờ dev xác nhận, trước khi đưa lên chạy thật.

### Tìm nhanh trong dự án lớn bằng @general

Dev mới thường mất nhiều thời gian để tìm "chỗ tính phí vận chuyển nằm ở đâu". Dùng subagent general để tìm:

```text
@general Tìm tất cả chỗ trong dự án có tính phí vận chuyển và liệt kê tên file kèm giải thích ngắn.
```

Kết quả: một danh sách file liên quan thay vì bạn tự lần từng thư mục.

### Lên kế hoạch trước khi đổi lớn

Bạn định đổi cách lưu đơn hàng và sợ làm hỏng mọi thứ. Ở chế độ plan, nhờ nó phân tích:

```text
Nếu mình muốn đổi cách lưu đơn hàng, những file nào bị ảnh hưởng? Hãy đề xuất các bước làm theo thứ tự, chưa sửa gì cả.
```

Kết quả: một kế hoạch từng bước để bạn đọc, chỉnh, rồi mới chuyển sang build khi thấy yên tâm.

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

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

Thường do terminal chưa nạp lại đường dẫn sau khi cài. Hãy đóng và mở terminal mới. Nếu cài bằng script, README nói file nằm ở `$HOME/.opencode/bin`; kiểm tra xem thư mục này có tồn tại không và đã nằm trong biến PATH của máy chưa. README chưa ghi cách thêm PATH, nên bạn xem hướng dẫn trong tài liệu dự án.

### Lệnh `curl ... | bash` không chạy trên Windows

Lệnh dùng `bash`, môi trường Windows thường không có sẵn. Thay vì cố sửa, hãy dùng cách khác trong README: `mise use -g opencode` (README ghi "Any OS"), `npm i -g` nếu bạn đã có npm, hoặc tải file `opencode-desktop-win-x64.exe`.

### Cài xong nhưng bản chạy là phiên bản cũ hoặc 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 đó đi rồi cài lại để tránh hai bản chồng nhau.

### Nhầm tên gói khi cài bằng npm hoặc brew

Trong README, tên gói khác nhau tuỳ cách cài (`@opencode/cli`, `opencode`, `opencode-v2`...). Hãy chép đúng nguyên dòng lệnh, không tự đổi tên. Với brew, README nói rõ dòng nào là bản mới nhất, dòng nào cập nhật chậm.

### AI sửa code không như ý

Ngay cả agent tốt cũng có lúc hiểu sai. Cách xử lý an toàn: để nó phân tích ở chế độ plan trước, chỉ chuyển sang build khi đã đồng ý với hướng làm, và luôn giữ bản sao lưu hoặc quản lý code bằng git để quay lại được.

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

**Điểm mạnh.** Mã nguồn mở với giấy phép MIT, cộng đồng lớn (khoảng 226.506 sao). Có nhiều cách cài, kể cả bản desktop cho người ngại terminal. Cặp agent build/plan cho bạn kiểm soát mức quyền một cách rõ ràng: xem trước, rồi mới làm.

**Giới hạn.** README khá ngắn: chưa nói rõ lệnh 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 opencode.ai/docs. Bản desktop vẫn là BETA. Cách đặt tên gói trong README chưa thật nhất quán, người mới dễ rối. Dữ liệu code của bạn đi đâu còn phụ thuộc vào mô hình AI bạn chọn, mà tư liệu ở đây chưa nói.

**Khi nào chọn cách khác.** Nếu bạn không đụng đến code và chỉ cần trò chuyện hỏi đáp thông thường, một ứng dụng chat là đủ. Nếu công ty bạn có quy định nghiêm về dữ liệu, hãy hỏi bộ phận IT và đọc kỹ tài liệu trước khi cho AI đọc mã nguồn nội bộ.

Với người muốn thử một coding agent mở, dễ cài và có sẵn chế độ chỉ đọc để học dần, opencode là lựa chọn đáng bỏ ít phút thử.

## 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 dùng không mất tiền mua phần mềm. Tuy nhiên README không nói gì về chi phí của mô hình AI mà bạn kết nối. Bạn cần xem tài liệu tại opencode.ai/docs để biết chi tiết.

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

Có bản desktop cho Windows (file opencode-desktop-win-x64.exe, đang ở dạng BETA). README cũng ghi mise dùng được trên mọi hệ điều hành và có lệnh cài bằng npm. Riêng script curl dùng bash nên README chưa nói rõ có chạy trên Windows thuần hay không.

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

README không nhắc đến yêu cầu GPU hay cấu hình phần cứng. Chưa có thông tin về việc này trong tư liệu, bạn nên xem thêm tại opencode.ai/docs.

### 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 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. README nói nó được dùng 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.

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

README không mô tả chi tiết về xử lý dữ liệu. Chế độ plan giúp hạn chế việc sửa file ngoài ý muốn, nhưng việc code được gửi đến đâu còn phụ thuộc cấu hình bạn chọn. Chưa có thông tin cụ thể trong tư liệu, hãy đọc tài liệu và chính sách bảo mật của dự án (có file SECURITY.md trong repo).

### Tài liệu hướng dẫn cấu hình nằm ở đâu?

README trỏ tới trang tài liệu của dự án tại opencode.ai/docs, trong đó có phần về agent và cấu hình. Dự án cũng có cộng đồng trên Discord và X.com.
