# 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 hiểu dự án, lên kế hoạch và sửa code bằng ngôn ngữ tự nhiên. Cài 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-08-05 · 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-mwelrhsq

opencode là một **coding agent (trợ lý lập trình AI) mã nguồn mở**. Bạn giao việc bằng câu chữ bình thường, nó đọc dự án, đề xuất và sửa code 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 ai? Lập trình viên mới muốn có người "ngồi cạnh" giải thích code. Dev lâu năm muốn giao bớt việc lặt vặt. Cả người làm kinh doanh hay văn phòng có một dự án nhỏ (một trang web, một file xử lý số liệu) và muốn nhờ AI đọc hiểu giúp. Bạn không cần bị khóa vào một công cụ đóng, vì giấy phép là MIT.

Điểm đáng giá nhất là **hai chế độ làm việc rõ ràng**. Một chế độ cho phép sửa file. Một chế độ chỉ đọc để phân tích, an toàn khi bạn chưa muốn AI đụng vào gì. Repo hiện có khoảng 226 nghìn sao và hơn 30 nghìn fork, nên cộng đồng khá lớn. Repo vẫn được cập nhật trong 3 tháng gần đây.

```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 ứng dụng desktop (beta).
- stars | 227k
- lang | TypeScript
- license | MIT
```

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

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

opencode có hai agent dựng sẵn. Bạn chuyển qua lại bằng phím `Tab`.

- **build**: agent mặc định, được toàn quyền để làm 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. 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ở một dự án lạ và chỉ muốn hiểu nó, hoặc muốn có kế hoạch trước khi sửa.

Lợi ích thực tế: bạn có thể cho AI "xem thử" mà không lo nó làm hỏng gì.

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

Ngoài hai agent trên còn có subagent **general**, dành cho việc tìm kiếm phức tạp và nhiều bước. Hệ thống dùng nó nội bộ. Bạn cũng có thể gọi trực tiếp bằng `@general` trong tin nhắn. Khi câu hỏi kiểu "tìm giúp mình mọi chỗ đang xử lý đơn hàng" quá lớn, đây là chỗ để thử.

### Nhiều cách cài, có cả ứng dụng desktop

Bạn có thể cài bằng script một dòng, npm, Homebrew, Arch Linux, mise hoặc Nix. Nếu ngại terminal, có **ứng dụng desktop (đang BETA)** cho macOS, Windows và Linux.

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

Phần cấu hình chi tiết nằm ở trang tài liệu của dự án (opencode.ai/docs). README cũng có bản dịch nhiều ngôn ngữ, trong đó có tiếng Việt (file `README.vi.md` trong repo).

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

Tư liệu README **không liệt kê** yêu cầu về phiên bản Node, Python hay phần cứng. Những gì README có nói:

- Hệ điều hành: macOS, Linux và Windows đều có đường cài. Script cài và lệnh Homebrew dành cho macOS/Linux. Windows có bản desktop `opencode-desktop-win-x64.exe`.
- Nếu đã từng cài bản cũ: README dặn gỡ các phiên bản cũ hơn 0.1.x trước khi cài.
- Nếu chọn cài bằng npm, bạn cần có npm (hoặc bun, pnpm, yarn) trên máy.

Về tài khoản hay API key: README **chưa nói** cần gì để agent hoạt động. Phần kết nối với dịch vụ AI bạn nên xem ở trang tài liệu opencode.ai/docs. Bạn cũng không cần GPU theo những gì README cho biết, vì README không đề cập chạy mô hình cục bộ.

```note
Agent AI có thể chạy lệnh và sửa file trong thư mục bạn mở. Nếu dùng key của dịch vụ AI trả phí, chi phí do bạn chịu. Hãy thử trên thư mục dự án có sao lưu, và đừng dán key vào file rồi đưa lên GitHub công khai.
```

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

```steps
- Gỡ bản cũ | Nếu đã cài bản cũ hơn 0.1.x thì gỡ trước
- Chọn cách cài | Script một dòng, npm, Homebrew hoặc bản desktop
- Chạy lệnh cài | Mở terminal và dán đúng lệnh trong README
- Mở ứng dụng | Vào thư mục dự án và khởi động opencode
- Kết nối AI | Làm theo tài liệu để cấu hình, vì README chưa ghi
```

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

README ghi: hãy gỡ các phiên bản cũ hơn 0.1.x trước khi cài. Nếu bạn chưa từng cài opencode, bỏ qua bước này. README không ghi lệnh gỡ cụ thể, nên cách gỡ phụ thuộc vào việc bạn đã cài bằng cách nào (npm, brew...). Hãy gỡ bằng chính công cụ đã dùng để cài.

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

README đưa ra nhiều lựa chọn. Người mới nên chọn **một** cách thôi, đừng chạy hết:

- Dùng macOS/Linux và muốn nhanh: script một dòng (dòng ghi chữ YOLO trong README).
- Đã có Node: dùng npm.
- Dùng Homebrew: dùng brew.
- Dùng Windows hoặc không thích gõ lệnh: tải bản desktop ở bước 5.

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

Mở **terminal** (macOS: Terminal; Windows: PowerShell hoặc terminal bạn quen; Linux: terminal của hệ). Dán một trong các lệnh dưới đây, chép đúng từ 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 nhanh:

- `curl ... | bash` tải script cài về và chạy luôn. Gọn, nhưng bạn nên chắc mình tin nguồn đó trước khi chạy.
- `npm i -g` cài toàn cục để gọi được từ bất kỳ thư mục nào.
- README ghi hai công thức brew. Công thức `anomalyco/tap/opencode-v2` được gọi là khuyến nghị và luôn mới. Công thức `opencode` chính thức thì cập nhật chậm hơn.
- Với Arch Linux có bản ổn định (`pacman`) và bản mới nhất (`paru`).

Chỗ hay vấp: dòng có dấu `#` phía sau chỉ là ghi chú. Khi dán, bạn chỉ cần phần lệnh phía trước dấu `#`.

Script cài đặt đặt opencode vào thư mục `$HOME/.opencode/bin`. Nếu sau khi cài mà terminal không nhận lệnh, hãy kiểm tra thư mục này có nằm trong PATH chưa. Cách thêm PATH tùy hệ điều hành, README không hướng dẫn.

### Bước 4: Mở ứng dụng trong thư mục dự án

README **chưa ghi rõ lệnh khởi chạy** cho bản dòng lệnh. Tên gói là `opencode`, nên cách phổ biến là mở terminal ngay trong thư mục dự án rồi gõ tên lệnh. Bạn hãy đối chiếu ở trang tài liệu opencode.ai/docs để chắc chắn.

```bash
cd duong-dan-toi-du-an-cua-ban
opencode
```

Lưu ý: `duong-dan-toi-du-an-cua-ban` là chỗ bạn tự thay bằng thư mục thật. Nên mở đúng thư mục dự án để agent chỉ làm việc trong đó.

### Bước 5: Hoặc tải bản desktop (beta)

Nếu không muốn dùng terminal, vào opencode.ai/download và tải theo bảng sau:

| Hệ điều hành | Tệp 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ản desktop bằng Homebrew:

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

Bản này đang BETA, nên có thể còn lỗi vặt.

### Bước 6: Kết nối dịch vụ AI

README không nói cách đăng nhập hay nhập key. Phần này xem ở trang tài liệu opencode.ai/docs. Nếu bạn cần giúp đỡ thì cộng đồng có Discord (link nằm cuối README).

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

README không mô tả màn hình kết quả mong đợi, nên mình chỉ nêu những dấu hiệu hợp lý, bạn đối chiếu thêm với tài liệu:

- Terminal nhận lệnh `opencode` mà không báo kiểu "command not found" (không tìm thấy lệnh).
- Giao diện mở ra, và bạn bấm `Tab` thì chuyển được giữa agent **build** và **plan**. Đây là chi tiết có trong README.
- Với bản desktop: mở ứng dụng lên được và thấy giao diện làm việc.

Nếu terminal báo không tìm thấy lệnh, thử đóng terminal rồi mở lại. Với script cài, kiểm tra `$HOME/.opencode/bin` có nằm trong PATH không.

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

### Dev mới nhận dự án lạ: dùng plan để làm quen

Bạn vừa vào công ty và được giao một repo mà không ai kịp giải thích. Mở dự án, bấm `Tab` sang agent **plan**. Agent này chỉ đọc, từ chối sửa file mặc định, và hỏi trước khi chạy lệnh bash.

Câu lệnh mẫu:

```text
Dự án này làm gì? Liệt kê các thư mục chính và nói file nào là điểm bắt đầu.
```

Kết quả: bạn có bản tóm tắt cấu trúc dự án mà không lo nó lỡ tay sửa code.

> Muốn hiểu một dự án lạ, đừng sửa gì vội. Cứ cho AI đọc trước.
>
> — Ông T

### Chủ shop có một trang web nhỏ: nhờ sửa nội dung

Bạn có trang giới thiệu cửa hàng và muốn đổi giờ mở cửa ở nhiều chỗ. Chuyển về agent **build**, rồi nhờ:

```text
Tìm mọi chỗ ghi giờ mở cửa và đổi thành 8h-21h. Cho mình xem thay đổi trước khi lưu.
```

Kết quả: agent tìm các chỗ liên quan và sửa giúp bạn. Hãy sao lưu thư mục trước vì build có toàn quyền.

### Nhân viên văn phòng: tìm nhanh trong nhiều file bằng @general

Bạn có thư mục chứa nhiều tập lệnh xử lý báo cáo và cần biết đoạn nào tính doanh thu. Gọi subagent bằng `@general` trong tin nhắn:

```text
@general Tìm các file có tính doanh thu theo tháng và tóm tắt mỗi file làm gì.
```

Kết quả: bạn nhận danh sách file kèm mô tả ngắn, đỡ phải mở từng file.

### Lên kế hoạch trước khi sửa lớn

Trước khi đổi một chức năng, hãy ở agent **plan** và hỏi cách làm. Khi đã vừa ý với kế hoạch, bấm `Tab` sang **build** và nhờ nó thực hiện. Cách chia hai bước này giúp bạn kiểm soát được mọi thay đổi.

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

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

Thường do thư mục cài chưa nằm trong PATH, hoặc terminal cũ chưa nạp lại. Đóng và mở lại terminal. Nếu cài bằng script, kiểm tra `$HOME/.opencode/bin`. Nếu vẫn không được, thử cài bằng cách khác (ví dụ Homebrew hoặc bản desktop).

### Xung đột giữa bản cũ và bản mới

README dặn gỡ các bản cũ hơn 0.1.x trước khi cài. Nếu bạn thấy phiên bản không như mong đợi, hãy gỡ bản cũ bằng đúng công cụ đã dùng để cài rồi cài lại một cách duy nhất.

### Cài nhầm bản brew không phải bản mới nhất

README ghi công thức `opencode` chính thức cập nhật chậm hơn công thức `anomalyco/tap/opencode-v2`. Nếu muốn bản mới, dùng công thức thứ hai.

### Agent chưa chạy vì chưa cấu hình AI

README không nói chi tiết bước kết nối dịch vụ AI. Nếu agent không trả lời, xem phần cấu hình ở opencode.ai/docs trước. Đừng tải script lạ về để "sửa" giúp.

### Agent sửa nhầm file

Đây là rủi ro chung của agent có toàn quyền. Phòng bằng cách dùng **plan** trước, sao lưu dự án, và nếu dùng Git thì commit trước khi cho **build** làm việc, để có thể quay lại.

## 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 nghìn sao).
- Có sẵn hai chế độ build và plan, dễ kiểm soát.
- Nhiều cách cài, kể cả ứng dụng desktop cho Windows, macOS, Linux.
- Có README nhiều ngôn ngữ, trong đó có tiếng Việt.

**Giới hạn:**

- README ngắn, không ghi rõ lệnh khởi chạy, cách nhập key hay yêu cầu phiên bản. Bạn phải đọc thêm ở trang tài liệu.
- Bản desktop vẫn đang beta.
- README liệt kê nhiều lệnh cài khác nhau (kể cả hai tên gói npm và brew khác nhau), nên người mới dễ rối. Hãy chọn một cách thôi.
- Script cài bằng `curl | bash` cần bạn tin nguồn.

**Khi nào nên chọn cách khác:** nếu bạn chỉ cần một ứng dụng chat hỏi đáp, không đụng vào dự án thì không cần agent này. Nếu bạn không có dự án để thử, hoặc không thoải mái với terminal, hãy bắt đầu bằng bản desktop.

Tóm lại, opencode đáng thử nếu bạn muốn một trợ lý lập trình mở và linh hoạt. Hãy bắt đầu ở chế độ plan, quen rồi mới cho build sửa code.

## 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ở theo giấy phép MIT. README không nói gì về chi phí của dịch vụ AI mà agent kết nối tới. Bạn nên xem ở trang tài liệu opencode.ai/docs để biết phần đó.

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

Có bản desktop cho Windows là tệp opencode-desktop-win-x64.exe (đang beta), tải ở opencode.ai/download. Script cài một dòng và lệnh Homebrew trong README dành cho macOS/Linux. README không hướng dẫn riêng cách cài bản dòng lệnh trên Windows.

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

README không nêu yêu cầu phần cứng nào, cũng không nhắc tới việc chạy mô hình trên máy bạn. Vì vậy chưa có thông tin chính thức về GPU.

### Chế độ build và plan khác nhau thế nào?

Build là agent mặc định với toàn quyền để làm 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 đổi qua lại bằng phím Tab.

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

README không nói về cách xử lý dữ liệu. Agent có thể đọc và sửa file trong thư mục bạn mở, nên hãy sao lưu và dùng plan khi chỉ muốn xem. Về quyền riêng tư, bạn nên đọc thêm tài liệu và file SECURITY.md trong repo.

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

Đây là subagent 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ó thể gọi trực tiếp bằng @general trong tin nhắn.

### Nếu dự án tên có chữ opencode thì có cần ghi chú gì không?

Có. Nếu bạn làm dự án liên quan và dùng chữ opencode trong tên, ví dụ opencode-dashboard, README yêu cầu ghi chú rõ rằng dự án đó không do nhóm OpenCode làm và không liên kết với họ.
