# 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 trợ lý lập trình AI (coding agent) mã nguồn mở, giấy phép MIT, viết bằng TypeScript. Nó giúp bạn khám phá, lên kế hoạch và sửa code bằng ngôn ngữ tự nhiên. Cài đặt khá dễ: chỉ một dòng lệnh, hoặc tải bản Desktop (BETA) cho macOS, Windows, Linux.

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

opencode là một **coding agent mã nguồn mở**: một trợ lý AI chuyên làm việc với code, bạn trò chuyện với nó và nó đọc, phân tích, đề xuất hoặc sửa code trong dự án của bạn. Tác giả mô tả ngắn gọn là "The open source coding agent". Repo hiện có khoảng 226.506 sao và 30.658 fork, viết chủ yếu bằng TypeScript, giấy phép MIT.

Bạn nên xem qua nếu bạn là lập trình viên mới, người làm văn phòng hay chủ doanh nghiệp nhỏ có một dự án code (website, file tự động hoá…) nhưng chưa quen đọc code. Thay vì tự mò từng dòng, bạn nhờ trợ lý giải thích hoặc đề xuất cách sửa. Dev lâu năm cũng dùng được khi cần khám phá nhanh một codebase lạ.

Điểm đáng giá nhất theo README là **hai chế độ làm việc**: `build` (đầy đủ quyền, để làm việc thật) và `plan` (chỉ đọc, mặc định không cho sửa file). Bạn đổi qua lại bằng phím `Tab`. Nhờ vậy bạn có thể cho AI "nhìn trước, nghĩ trước" mà không sợ nó đụng vào file của mình.

```repo
- repo | anomalyco/opencode
- kind | Agent
- desc | opencode là coding agent mã nguồn mở: đọc hiểu code, sửa file, chạy lệnh giúp bạn, có 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, đổi bằng phím Tab

- **build**: agent mặc định, có đầy đủ quyền cho công việc phát triển. Dùng khi bạn đã rõ muốn làm gì và muốn nó bắt tay vào làm.
- **plan**: 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 xin phép trước khi chạy lệnh bash. Rất hợp khi bạn mở một dự án lạ hoặc muốn lên kế hoạch thay đổi trước khi động vào.

Lợi ích thực tế: bạn bắt đầu bằng `plan` để hiểu, rồi bấm `Tab` sang `build` để thực hiện. Cách này an toàn hơn cho 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ùng cho tìm kiếm phức tạp và các tác vụ 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 `@general` trong tin nhắn.

### Có bản terminal và bản Desktop (BETA)

Bạn có thể dùng qua dòng lệnh, hoặc tải ứng dụng Desktop (đang ở mức BETA) cho macOS (Apple Silicon và Intel), Windows và Linux. Ai ngại terminal có thể bắt đầu từ bản Desktop.

### Nhiều cách cài, mã nguồn mở

README liệt kê nhiều cách cài: script, npm, Homebrew, Arch Linux, mise, Nix. Mã nguồn công khai theo giấy phép MIT nên bạn có thể xem, tự kiểm tra, thậm chí đóng góp. README cũng có bản dịch nhiều ngôn ngữ, trong đó có tiếng Việt (`README.vi.md`).

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

Tư liệu README chỉ nêu các điểm sau:

- **Hệ điều hành**: macOS, Linux (cài bằng script hoặc Homebrew), Windows (có file cài bản Desktop `opencode-desktop-win-x64.exe`). Cách `mise` được ghi là dùng được trên mọi hệ điều hành.
- **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.
- **Công cụ tuỳ cách cài**: nếu cài bằng npm thì cần có Node.js và npm; Homebrew thì cần Homebrew; v.v. Phiên bản Node cụ thể README không nêu.
- **Tài khoản / API key / phần cứng**: README chưa ghi yêu cầu nào về tài khoản, khóa API hay GPU. Muốn biết cách kết nối mô hình AI, bạn xem tài liệu tại opencode.ai/docs.

```note
Khi cấu hình mô hình AI, bạn có thể phải nhập khóa (API key) của một nhà cung cấp. Khóa này như mật khẩu: không dán lên nhóm chat, không đưa vào file code đẩy lên GitHub. Việc dùng mô hình AI có thể phát sinh chi phí tuỳ nhà cung cấp; README không nói rõ nên hãy kiểm tra ở tài liệu chính thức.
```

## 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
- Gỡ bản cũ | Xoá phiên bản cũ hơn 0.1.x nếu có
- Chạy lệnh cài | Dán lệnh phù hợp vào terminal
- Mở dự án | Vào thư mục code của bạn trong terminal
- Xem tài liệu cấu hình | Làm theo opencode.ai/docs để thiết lập
```

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

Nếu chưa quen terminal, tải bản Desktop (BETA) tại opencode.ai/download. Tên file theo README:

| Hệ điều hành | File |
| --- | --- |
| 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 có thể cài bản Desktop bằng Homebrew:

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

Nếu thích dùng terminal, đọc tiếp các bước dưới.

### Bước 2: 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 thì bỏ qua bước này.

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

README đưa ra danh sách sau. Bạn chỉ cần chọn **một** dòng phù hợp máy mình, khô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 nhanh:

- Dòng `curl ... | bash` tải script cài từ trang chủ và chạy luôn. README tự đặt tên là "YOLO" (tức là cài nhanh, không kiểm tra). Nếu bạn muốn an toàn hơn, hãy mở địa chỉ script trong trình duyệt để đọc trước.
- Dòng `npm i -g ...` cài toàn cục bằng npm; README ghi bạn cũng có thể dùng bun, pnpm hoặc yarn.
- Hai dòng `brew` dành cho macOS và Linux. README khuyên dùng dòng `anomalyco/tap/opencode-v2` vì luôn mới nhất; bản `brew install opencode` là bản 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.

Chỗ dễ vấp: tên gói trong các dòng lệnh không giống hệt nhau (ví dụ `@opencode/cli`, `opencode-v2`, `opencode`). Bạn cứ chép đúng dòng bạn chọn, đừng tự sửa tên.

Script cài đặt sẽ đặt opencode vào thư mục `$HOME/.opencode/bin`.

Trên Windows, README không ghi riêng một lệnh PowerShell. Bạn có thể dùng bản Desktop `.exe`, hoặc các cách có sẵn Node/npm hoặc `mise` nếu bạn đã có.

### Bước 4: Mở dự án của bạn

Mở terminal ngay trong thư mục dự án cần làm việc (trong Windows Explorer: nhấp chuột phải vào thư mục và chọn mở terminal). Với dự án trên GitHub, bạn tải về như sau:

```bash
git clone https://github.com/anomalyco/opencode.git
cd opencode
```

Đây chỉ là ví dụ tải chính repo opencode về xem. Dự án thật của bạn thì `cd` vào thư mục của bạn.

### Bước 5: Cấu hình theo tài liệu

README chưa ghi lệnh khởi chạy cụ thể và các bước cấu hình mô hình AI. Mọi hướng dẫn cấu hình nằm ở tài liệu chính thức: opencode.ai/docs. Phần về agent nằm ở opencode.ai/docs/agents. Bạn nên đọc trước khi dùng thật.

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

README không mô tả kết quả mong đợi sau khi cài. Cách kiểm tra hợp lý:

- Với bản Desktop: mở ứng dụng, nếu giao diện hiện lên là cài thành công.
- Với bản dòng lệnh: sau khi cài, đóng terminal cũ, mở terminal mới (để máy nhận đường dẫn mới), rồi làm theo phần khởi chạy trong opencode.ai/docs.
- Nếu dùng script, kiểm tra thư mục `$HOME/.opencode/bin` đã có file chưa.
- Khi giao diện lên, thử bấm `Tab`. README nói phím này đổi giữa hai agent `build` và `plan`; nếu bạn thấy chế độ đổi, tức là mọi thứ đang chạy.

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

Các tình huống dưới đây bám theo khả năng README nêu: chế độ `plan`, chế độ `build` và subagent `@general`. Câu lệnh mẫu chỉ là gợi ý, bạn viết bằng lời thường.

### Làm quen một dự án lạ (nhân viên mới, lập trình viên mới)

Bạn vừa nhận bàn giao một dự án website mà người cũ đã nghỉ. Bạn mở terminal ở thư mục dự án, để ở chế độ `plan` (chỉ đọc) và hỏi:

```
Dự án này làm gì? Các phần chính nằm ở đâu? Giải thích cho người mới.
```

Vì `plan` mặc định từ chối sửa file và hỏi xin phép trước khi chạy lệnh bash, bạn yên tâm không bị đổi gì. Kết quả: bạn có bản giải thích về cấu trúc dự án trong vài phút.

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

Bạn cần thêm một tính năng vào ứng dụng. Ở chế độ `plan`, bạn nhờ:

```
Tôi muốn thêm chức năng X. Cần sửa những file nào? Đề xuất các bước.
```

> Cho AI đọc và nghĩ trước, rồi mới cho nó động tay — đó là cách dùng trợ lý code an toàn nhất.
>
> — Ông T

Sau khi đồng ý kế hoạch, bạn bấm `Tab` sang `build` và nhờ nó làm. Kết quả: thay đổi có định hướng, bạn kiểm soát được từng bước.

### Nhờ tìm kiếm nhiều bước (chủ shop có website nhỏ)

Chủ shop có một website bán hàng, muốn biết chỗ nào đang hiển thị giá. Bạn gọi subagent trong tin nhắn:

```
@general Tìm tất cả nơi trong dự án có hiển thị giá sản phẩm và liệt kê cho tôi.
```

README mô tả `general` dùng cho tìm kiếm phức tạp và tác vụ nhiều bước. Kết quả: danh sách vị trí để bạn (hoặc thợ web của bạn) sửa đúng chỗ.

### Sửa lỗi nhỏ khi đã hiểu rõ (build)

Bạn biết chính xác một dòng chữ sai trên trang. Ở chế độ `build`, bạn nhờ: "Đổi chữ A thành chữ B trên trang giới thiệu". Agent có đầy đủ quyền nên sẽ sửa trực tiếp. Hãy kiểm tra lại kết quả trước khi đưa lên máy chủ thật.

## 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. Đóng terminal, mở lại. Nếu cài bằng script, thư mục là `$HOME/.opencode/bin`; hãy kiểm tra xem file có ở đó không. Nếu vẫn lỗi, xem hướng dẫn ở opencode.ai/docs.

### Đã cài nhưng chạy lệnh ra bản cũ hoặc lỗi lạ

README nhắc gỡ phiên bản cũ hơn 0.1.x trước khi cài. Gỡ bản cũ rồi cài lại. Cũng tránh cài cùng lúc bằng nhiều cách (npm, brew, script) vì dễ chồng chéo.

### Nhầm tên gói khi cài

Tên gói khác nhau giữa các cách (`@opencode/cli`, `opencode-v2`, `opencode`). Hãy chép nguyên dòng lệnh của đúng cách bạn chọn, không trộn lẫn. Nếu báo không tìm thấy gói, thử cách khác trong danh sách hoặc xem tài liệu chính thức.

### Agent chưa kết nối được mô hình AI

Vì cần có mô hình AI để trả lời, bạn có thể gặp thông báo thiếu cấu hình hoặc thiếu khóa. README không ghi chi tiết; hãy làm theo opencode.ai/docs. Tuyệt đối không dán khóa vào chỗ công khai.

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

Ở chế độ `build` agent có đầy đủ quyền. Hãy làm việc trên dự án đã được lưu bằng git hoặc đã sao lưu, để quay lại được nếu cần. Khi chưa chắc, dùng `plan` trước.

## 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 (hiện có khoảng 226.506 sao).
- Chế độ `plan` chỉ đọc giúp người mới khám phá code an toàn.
- Nhiều cách cài, có cả bản Desktop (BETA) cho Windows, macOS, Linux.
- Có tài liệu riêng và README nhiều ngôn ngữ, gồm tiếng Việt.

**Giới hạn**

- README chưa nêu rõ cách khởi chạy, kết nối mô hình AI, chi phí. Bạn phải đọc thêm tài liệu chính thức.
- Bản Desktop đang ở mức BETA, có thể chưa ổn định.
- Tên gói giữa các cách cài không đồng nhất, dễ gây rối cho người mới.
- Là công cụ cho việc lập trình; nếu bạn chỉ cần chatbot hỏi đáp thông thường thì không cần đến nó.

**Khi nào chọn cách khác**: nếu bạn không có dự án code, hoặc không muốn làm việc trong terminal lẫn cài đặt, một ứng dụng chat AI thông thường có thể phù hợp hơn. Còn nếu bạn muốn một trợ lý code mã nguồn mở, kiểm soát được quyền (đọc hay sửa), thì opencode đáng 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 bạn dùng và xem mã miễn phí. Tuy nhiên README không nói về chi phí của mô hình AI mà nó kết nối tới; phần này chưa có thông tin trong tư liệu, bạn xem ở opencode.ai/docs.

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

Có bản Desktop (BETA) cho Windows với file `opencode-desktop-win-x64.exe`. README cũng ghi cách cài `mise` dùng được trên mọi hệ điều hành và cách cài qua npm. README không có lệnh PowerShell riêng.

### Cài opencode có khó không?

Không khó. Cách nhanh nhất là chạy một dòng `curl -fsSL https://opencode.ai/v2/install | bash`, hoặc tải bản Desktop rồi cài như phần mềm thường. Chỗ dễ vấp là chọn đúng một cách cài và gỡ bản cũ hơn 0.1.x trước.

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

`build` là agent mặc định, có đầy đủ 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 xin phép trước khi chạy lệnh bash. Bạn đổi giữa hai chế độ bằng phím `Tab`.

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

Đó là subagent dùng cho tìm kiếm phức tạp và các tác vụ 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 `@general` trong tin nhắn.

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

README không nêu yêu cầu phần cứng hay GPU. Chưa có thông tin về vấn đề này trong tư liệu, bạn xem thêm tài liệu chính thức.

### 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. Có điều chế độ `plan` mặc định không cho sửa file và hỏi trước khi chạy lệnh bash, nên rất hợp để thử. Mã nguồn công khai nên bạn có thể tự kiểm tra, còn chi tiết về dữ liệu gửi đi thì chưa có thông tin trong tư liệu.
