# OpenCode: trợ lý AI viết code 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 mã nguồn mở (giấy phép MIT): bạn giao việc bằng ngôn ngữ thường, nó đọc code, đề xuất và sửa giúp bạn. Có bản dòng lệnh và bản desktop (đang BETA). Cài khá dễ vì có sẵn một dòng lệnh cài nhanh và nhiều cách cài qua trình quản lý gói.

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

OpenCode là một coding agent mã nguồn mở: một trợ lý AI chuyên đọc, hiểu và hỗ trợ viết code cho bạn. Repo viết bằng TypeScript, dùng giấy phép MIT, và hiện có khoảng 226.506 sao cùng 30.658 fork trên GitHub. Con số này cho thấy cộng đồng quan tâm rất nhiều.

Nếu bạn từng thấy các trợ lý AI viết code nhưng lo chuyện bị khoá vào một hãng, OpenCode là một lựa chọn đáng thử. Mã nguồn mở nên bạn đọc được nó làm gì, và dự án có trang tài liệu riêng để tự cấu hình. Người nên dùng là lập trình viên mới muốn có "người kèm cặp" khi đọc code lạ, dev đang làm dự án muốn giao bớt việc lặt vặt, và cả người làm văn phòng biết chút kỹ thuật muốn thử tự động hoá bằng script.

Điểm đáng giá nhất theo README là hai chế độ làm việc chuyển nhanh bằng phím `Tab`. 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 sợ nó sửa nhầm file của bạn.

```repo
- repo | anomalyco/opencode
- kind | Agent
- desc | OpenCode là agent AI viết code mã nguồn mở, có bản dòng lệnh và bản desktop, có sẵn hai chế độ build (làm việc) và plan (chỉ đọc, phân tích).
- stars | 227k
- lang | TypeScript
- license | MIT
```

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

### Hai agent có sẵn, chuyển bằng phím Tab

- **build**: agent mặc định, có đầy đủ quyền cho công việc phát triển. Bạn dùng nó khi đã biết mình muốn gì và để nó bắt tay vào làm.
- **plan**: agent chỉ đọc, dùng để phân tích và khám phá code. Theo README, nó từ chối sửa file theo mặc định và hỏi quyề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 thay đổi trước khi động vào code.

Lợi ích thực tế: bạn có thể cho AI "nhìn" dự án trước, hiểu rồi mới cho phép sửa. Đây là thói quen an toàn, nhất là với người mới.

### Subagent general cho việc phức tạp

Ngoài hai agent trên còn có subagent **general**, dành cho các tìm kiếm phức tạp và công việc nhiều bước. Theo README, 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. Khi câu hỏi kiểu "tìm giúp mình mọi chỗ đang xử lý thanh toán" quá lớn, bạn có thể giao cho nó.

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

OpenCode có script cài một dòng, cài qua npm, Homebrew, Arch Linux (pacman, paru), mise và Nix. Ngoài ra còn có ứng dụng desktop (BETA) cho macOS, Windows và Linux. Ai không thích terminal có thể tải bản desktop về dùng.

### Tài liệu và cộng đồng

README được dịch ra rất nhiều ngôn ngữ, trong đó có tiếng Việt (file README.vi.md trong repo). Cấu hình chi tiết nằm ở trang docs của dự án, và có cộng đồng trên Discord và X.com.

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

Tư liệu README nói khá ít về yêu cầu hệ thống, nên mình chỉ nêu những gì có thật:

- **Hệ điều hành:** README cho thấy có bản desktop cho macOS (Apple Silicon và Intel), Windows và Linux. Các lệnh cài bằng Homebrew áp dụng cho macOS và Linux, mise dùng được trên mọi hệ điều hành.
- **Node/npm:** chỉ cần nếu bạn chọn cách cài bằng `npm`. README không ghi phiên bản Node cụ thể.
- **Gỡ bản cũ:** README nhắc 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 **chưa ghi** bạn cần tài khoản hay key của nhà cung cấp AI nào, cũng không nói yêu cầu GPU. Phần này bạn xem ở trang docs của dự án.

```note
Nhiều công cụ AI viết code cần key hoặc tài khoản của nhà cung cấp mô hình, và có thể phát sinh chi phí. README của OpenCode không nói rõ phần này. Trước khi dùng, bạn đọc docs để biết mình cần gì, và đừng dán key vào chỗ công khai hay commit lên GitHub.
```

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

```steps
- Chọn cách cài | Script một dòng, npm, Homebrew hoặc bản desktop
- Chạy lệnh cài | Dán lệnh vào terminal và đợi cài xong
- Kiểm tra vị trí cài | Script cài vào thư mục $HOME/.opencode/bin
- Mở dự án và chạy | Vào thư mục code của bạn rồi khởi động OpenCode
- Làm quen hai chế độ | Dùng Tab để chuyển giữa build và plan
```

### Bước 1: Chọn cách cài

README đưa nhiều cách. Nếu bạn là người mới và dùng macOS hoặc Linux, hãy chọn script một dòng hoặc Homebrew. Nếu bạn đã có Node và quen npm, dùng npm. Nếu bạn muốn giao diện cửa sổ, bỏ qua phần terminal và tải bản desktop (xem ở dưới).

Trước khi cài, nhớ gỡ các phiên bản cũ hơn 0.1.x nếu máy bạn từng cài OpenCode.

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

Mở terminal (trên macOS là app Terminal, trên Windows là PowerShell hoặc Windows Terminal) rồi chạy MỘT dòng trong danh sách dưới đây. Đây là các lệnh nguyên văn trong README, bạn chỉ chọn 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:

- Dòng `curl ... | bash` tải script cài về và chạy luôn. README gọi nó là "YOLO" (làm liều), vì bạn chạy script mà không đọc trước. Nếu muốn an toàn hơn, hãy mở địa chỉ script trong trình duyệt để xem nội dung trước.
- `npm i -g @opencode/cli@latest` cài toàn cục bằng npm. README ghi bạn cũng có thể dùng bun, pnpm hoặc yarn.
- Có hai công thức Homebrew. README khuyên dùng `anomalyco/tap/opencode-v2` vì luôn mới nhất. Công thức chính thức `opencode` cập nhật chậm hơn.
- Các dòng `pacman`, `paru`, `mise`, `nix` dành cho người đã dùng các công cụ đó.

Chỗ người mới hay vấp: lệnh `sudo pacman` chỉ dành cho Arch Linux. Nếu bạn dùng Windows hay macOS, đừng chạy dòng đó.

### Bước 3: Kiểm tra nơi cài (nếu dùng script)

Theo README, script cài đặt OpenCode vào thư mục `$HOME/.opencode/bin`. Nếu sau khi cài, terminal báo không tìm thấy lệnh, hãy kiểm tra thư mục này có file chưa. README không nói script có tự thêm đường dẫn vào PATH hay không, nên nếu cần bạn xem thêm ở trang docs.

### Bước 4: Cài bản desktop (nếu bạn không thích terminal)

Bản desktop đang ở giai đoạn BETA, tải ở trang tải về của dự án (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 bằng Homebrew:

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

### Bước 5: Khởi động và làm quen

README **chưa ghi lệnh khởi động** cụ thể cho bản dòng lệnh. Nhiều khả năng lệnh trùng với tên gói là `opencode`, nhưng bạn nên xác nhận ở trang docs (opencode.ai/docs) trước khi tin. Cách dùng đúng theo README: chạy OpenCode trong thư mục dự án của bạn, rồi nhấn `Tab` để đổi giữa agent **build** và **plan**.

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

README không mô tả màn hình hay kết quả mong đợi sau khi cài. Vì vậy bạn có thể tự kiểm tra theo các dấu hiệu hợp lý sau:

1. Lệnh cài kết thúc không báo lỗi.
2. Nếu cài bằng script, thư mục `$HOME/.opencode/bin` có file bên trong.
3. Khi mở OpenCode, bạn nhấn `Tab` và thấy chuyển được giữa hai agent **build** và **plan**. Đây là hành vi README mô tả.
4. Với bản desktop, ứng dụng mở được sau khi cài.

Nếu một trong các bước trên không đạt, xem 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 theo khả năng README mô tả (hai chế độ, subagent general). Câu lệnh mẫu là gợi ý để bạn gõ vào hộp chat của OpenCode, không phải lệnh terminal.

### Dev mới nhận dự án lạ: đọc hiểu trước khi sửa

Bạn vừa vào công ty và được giao một dự án vài chục thư mục. Mở OpenCode trong thư mục dự án, nhấn `Tab` để sang chế độ **plan**. Chế độ này chỉ đọc, từ chối sửa file mặc định và hỏi quyền trước khi chạy lệnh bash, nên bạn yên tâm khám phá.

Bạn có thể hỏi:

```text
Giải thích cho mình cấu trúc dự án này. Phần nào xử lý đăng nhập?
```

Kết quả: bạn nhận bản giải thích bằng lời, đỡ mất cả buổi tự lần mò.

> Cho AI đọc trước, sửa sau: chế độ chỉ đọc là cách rẻ nhất để không phá code đang chạy.
>
> — Ông T

### Lên kế hoạch trước khi đổi một tính năng

Bạn muốn thêm trường "mã giảm giá" vào form đặt hàng của một web nhỏ. Hãy ở chế độ **plan** và hỏi:

```text
Mình muốn thêm trường mã giảm giá vào form đặt hàng. Cần sửa những file nào? Liệt kê theo thứ tự làm.
```

Kết quả: bạn có danh sách file và thứ tự thực hiện. Đọc xong thấy hợp lý, bạn nhấn `Tab` sang **build** và nhờ nó làm theo kế hoạch.

### Giao việc tìm kiếm nhiều bước cho @general

Bạn là dev đang dọn code cũ và cần biết một hàm đang được gọi ở những chỗ nào. Việc này nhiều bước, hợp để gọi subagent general bằng `@general`:

```text
@general tìm mọi nơi dùng hàm tinhPhiVanChuyen và cho mình biết file nào phụ thuộc vào nó
```

Kết quả: bạn nhận danh sách các chỗ liên quan để quyết định có sửa hay xoá an toàn không. Tên hàm ở trên chỉ là ví dụ, bạn thay bằng tên trong dự án của mình.

### Người làm văn phòng thử tự động hoá nhỏ

Bạn làm kế toán hoặc điều phối đơn, biết chút kỹ thuật và có một thư mục script nhỏ. Mở OpenCode trong thư mục đó ở chế độ **build** để nhờ viết hoặc chỉnh một script ngắn, ví dụ:

```text
Viết giúp mình script đổi tên các file trong thư mục này theo dạng ngày_tên-khách.
```

Kết quả: bạn nhận script để chạy thử. README không nói OpenCode chạy được tới đâu với từng ngôn ngữ, nên hãy đọc kỹ code nó viết và thử trên thư mục sao lưu trước.

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

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

Thường do terminal chưa nhận đường dẫn cài. Với script, README nói file nằm ở `$HOME/.opencode/bin`, bạn kiểm tra thư mục đó có file không. Thử mở một cửa sổ terminal mới, vì cửa sổ cũ thường chưa nạp lại cấu hình. Nếu vẫn không được, xem hướng dẫn cài trong docs.

### Cài trùng nhiều cách, chạy nhầm bản cũ

README nhắc 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 cách khác (ví dụ npm rồi lại Homebrew), máy có thể có hai bản. Gỡ bản không dùng bằng đúng công cụ đã cài nó.

### Chạy dòng `sudo pacman` hoặc `paru` trên máy không phải Arch

Đây là lỗi hay gặp khi chép nguyên khối lệnh. Các dòng trong khối là lựa chọn thay thế, không phải chuỗi lệnh chạy lần lượt. Chỉ chạy một dòng hợp với hệ điều hành của bạn.

### Không biết cần key hay tài khoản gì để AI trả lời

README không nêu phần này. Nếu OpenCode mở lên nhưng không trả lời được, hãy xem phần cấu hình trong docs để biết cách kết nối nhà cung cấp mô hình. Giữ key kín: đừng dán lên chat công khai hay đưa vào file được đẩy lên GitHub.

### Ở chế độ build nó sửa file ngoài ý muốn

Chế độ **build** có toàn quyền cho việc phát triển. Hãy dùng Git hoặc sao lưu thư mục trước khi giao việc lớn, và dùng **plan** để duyệt hướng đi trước. Sau mỗi thay đổi, đọc lại phần nó sửa thay vì tin hoàn toàn.

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

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

- Mã nguồn mở, giấy phép MIT, repo còn được cập nhật trong vài tháng gần đây.
- Hai chế độ build và plan giúp bạn kiểm soát mức độ AI được phép làm.
- Nhiều cách cài, có cả bản desktop nếu bạn không thích terminal.
- README có bản tiếng Việt, và có cộng đồng trên Discord, X.com.

**Giới hạn:**

- README ngắn, chưa nói rõ lệnh khởi động, yêu cầu phiên bản Node hay cần key của nhà cung cấp nào. Bạn phải đọc thêm docs.
- Bản desktop vẫn đang BETA, nên có thể chưa ổn định bằng bản dòng lệnh.
- README không nói rõ người dùng Windows có cài được bản dòng lệnh theo cách nào ngoài npm và bản desktop hay không.
- Với người không đụng tới code hay terminal, đây có thể là công cụ hơi "kỹ thuật".

**Khi nào nên chọn cách khác:** nếu bạn chỉ cần hỏi đáp thông thường, một ứng dụng chat AI là đủ. Nếu công ty bạn có quy định chặt về dữ liệu, hãy xem kỹ docs và chính sách bảo mật của dự án (repo có file SECURITY.md) trước khi cho nó đọc code thật.

Tóm lại, nếu bạn là dev hoặc người học lập trình muốn một trợ lý AI mã nguồn mở có chế độ chỉ-đọc an toàn, OpenCode đáng để thử trong 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 phần mềm là mã nguồn mở với giấy phép MIT. README không nói về chi phí của các mô hình AI mà nó kết nối tới, nên mình chưa có thông tin về việc có phát sinh phí hay không. Bạn xem trang docs của dự án để biết rõ.

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

README có bản desktop cho Windows (file opencode-desktop-win-x64.exe, đang BETA) và cách cài bằng npm. Các dòng như Homebrew áp dụng cho macOS và Linux. README không nói thêm về bản dòng lệnh trên Windows, bạn xem docs để chắc chắn.

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

README không nhắc đến yêu cầu GPU hay phần cứng. Chưa có thông tin về việc này trong tư liệu, bạn kiểm tra thêm ở trang docs.

### 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 theo mặc định 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à 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.

### 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. Repo có file SECURITY.md để bạn tham khảo chính sách bảo mật. Với code nhạy cảm, hãy đọc docs kỹ và dùng chế độ plan để hạn chế quyền sửa file.

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

Với macOS hoặc Linux, README gợi ý Homebrew (anomalyco/tap/opencode-v2) vì luôn mới nhất, hoặc script cài một dòng. Nếu bạn quen npm thì dùng npm i -g @opencode/cli@latest. Nếu không thích terminal, tải bản desktop (BETA).
