# 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 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. 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 khá dễ nhờ một dòng lệnh hoặc trình quản lý gói, ngoài ra còn có bản Desktop (BETA).

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-06-21 · 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-mwek7fcr

opencode là một **trợ lý lập trình AI mã nguồn mở** (coding agent). Bạn mô tả việc cần làm bằng lời thường, nó đọc code, đề xuất và có thể tự sửa file hoặc chạy lệnh thay bạn. Repo viết bằng TypeScript, dùng giấy phép MIT, nên dùng cá nhân hay trong công ty đều thoải mái.

Repo này hợp với lập trình viên mới muốn có "người kèm cặp" khi đọc một dự án lạ. Nó cũng hợp với người làm kinh doanh, văn phòng có chút quen terminal và muốn nhờ AI sửa file, dọn thư mục, viết script nhỏ. Hiện repo có khoảng 226 nghìn sao và 30 nghìn fork, và vẫn được cập nhật trong 3 tháng gần đây.

Điểm đáng giá nhất là **hai chế độ làm việc tách bạch**. Chế độ `build` có toàn quyền để làm việc. Chế độ `plan` chỉ đọc, dùng để xem xét và lên kế hoạch mà không đụng vào file nào. Bạn bấm phím `Tab` là đổi qua lại, nên thử ý tưởng rất an tâm.

```repo
- repo | anomalyco/opencode
- kind | Agent
- desc | opencode là agent lập trình AI mã nguồn mở: đọc code, sửa file và 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ì

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

### Agent `build`: làm việc thật

Đây là agent mặc định, có toàn quyền cho công việc phát triển. Bạn nhờ nó viết thêm tính năng, sửa lỗi hay chỉnh file, nó sẽ làm trực tiếp trong thư mục dự án. Lợi ích: bạn đỡ phải copy qua dán lại giữa khung chat và trình soạn thảo.

### Agent `plan`: chỉ đọc, rất an toàn

Chế độ này mặc định từ chối việc sửa file. Trước khi chạy lệnh bash, nó hỏi xin phép bạn. Dùng khi bạn mới nhận một dự án lạ và muốn hiểu cấu trúc, hoặc muốn có kế hoạch thay đổi trước khi cho AI động tay vào.

### Subagent `general`: xử lý việc nhiều bước

Đây là agent phụ dành cho tìm kiếm phức tạp và các tác vụ nhiều bước. Hệ thống dùng nó nội bộ, và bạn cũng có thể gọi bằng cách gõ `@general` trong tin nhắn. Hợp khi câu hỏi cần lục nhiều file rồi 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, npm, Homebrew, pacman, mise hoặc Nix. Ngoài ra có ứng dụng Desktop (BETA) cho macOS, Windows và Linux, dành cho ai ngại terminal.

### Mã nguồn mở, có tài liệu và cộng đồng

Có trang tài liệu riêng ở opencode.ai/docs, README được dịch ra nhiều thứ tiếng (có cả tiếng Việt), và có Discord để hỏi đáp.

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

README không liệt kê yêu cầu hệ thống chi tiết. Những gì tư liệu nói rõ:

- **Hệ điều hành:** các lệnh brew cho macOS và Linux; pacman/paru cho Arch Linux; mise dùng được trên mọi hệ điều hành; Nix cũng có. Bản Desktop có file cho macOS (chip Apple Silicon và Intel), Windows (`.exe`) và Linux (`.deb`, `.rpm`, `.AppImage`).
- **Node/npm:** chỉ cần nếu bạn chọn cài bằng `npm`. README ghi thêm là có thể dùng bun, pnpm hoặc yarn thay thế.
- **Gỡ bản cũ:** README khuyê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, phần cứng:** README **chưa ghi** các mục này. Bạn xem tại docs của dự án (opencode.ai/docs) để biết cách kết nối với mô hình AI.

```note
Một agent AI có thể sửa file và chạy lệnh trên máy bạn. Lần đầu hãy thử trong một thư mục sao lưu hoặc dự án không quan trọng, và ưu tiên chế độ plan khi chưa hiểu rõ nó sẽ làm gì. README chưa nói về chi phí mô hình AI, nên bạn đọc docs để biết bạn dùng dịch vụ nào và tính phí ra sao.
```

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

```steps
- Gỡ bản cũ | Nếu từng cài phiên bản cũ hơn 0.1.x thì gỡ đi trước
- Chọn cách cài | Chọn một lệnh trong README hợp với máy bạn (script, npm, brew…)
- Chạy lệnh cài | Mở terminal và dán lệnh đã chọn
- Hoặc dùng bản Desktop | Tải file cài đặt từ opencode.ai/download nếu ngại terminal
- Xem docs | Đọc tài liệu để cấu hình, vì README chưa ghi phần này
```

### 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 thì bỏ qua bước này. README không nói cách gỡ, nên bạn dùng đúng cách bạn đã cài để gỡ (ví dụ cài bằng npm thì gỡ bằng npm).

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

README đưa ra nhiều lựa chọn. **Chỉ cần chọn MỘT dòng** hợp với máy bạn, không chạy hết cả danh sách.

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

Gợi ý cho từng nhóm người dùng:

- **macOS/Linux, người mới:** dùng `brew install anomalyco/tap/opencode-v2`. README ghi dòng này là khuyên dùng và luôn cập nhật mới nhất. Dòng `brew install opencode` là bản chính thức nhưng cập nhật chậm hơn.
- **Đã có Node:** dùng lệnh `npm i -g @opencode/cli@latest`. Cờ `-g` là cài toàn cục để gọi được từ mọi thư mục.
- **Dùng script:** lệnh đầu tiên (chú thích là "YOLO") tải script từ opencode.ai về và chạy luôn bằng bash. Tiện nhưng bạn đang chạy một script mà không đọc trước. Nếu ngại, hãy chọn cách cài bằng trình quản lý gói.
- **Arch Linux:** dùng pacman (bản ổn định) hoặc paru (bản mới nhất từ AUR).

Một chỗ dễ nhầm: tên gói npm trong tư liệu là `opencode`, nhưng lệnh npm trong README lại ghi `@opencode/cli`. Mình chép đúng theo README. Nếu lệnh npm báo lỗi, bạn quay lại trang docs để xem tên gói hiện hành.

Nếu dùng script cài, README cho biết nó cài opencode vào thư mục `$HOME/.opencode/bin`.

### Bước 3: Hoặc dùng bản Desktop (BETA)

Nếu không muốn dùng terminal, hãy tải ứng dụng ở opencode.ai/download. Các file theo README:

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

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

Bản Desktop đang ở giai đoạn BETA, nên có thể còn lỗi vặt.

### Bước 4: Cài trên Windows thì sao?

README không có lệnh riêng cho Windows ngoài file `.exe` của bản Desktop. Các lệnh `curl ... | bash` cần môi trường bash. Với người dùng Windows, cách chắc chắn nhất theo tư liệu là bản Desktop `.exe`. Nếu muốn dùng bản terminal, bạn xem trang docs của dự án để biết cách được hỗ trợ.

### Bước 5: Đọc docs để cấu hình

README chỉ nói rằng cách cấu hình nằm ở trang tài liệu opencode.ai/docs. Cách khai báo mô hình AI hay API key **README chưa ghi**, nên bạn làm theo trang đó và đừng đoán mò.

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

README không có mục kiểm tra cài đặt, nên mình chỉ nêu những dấu hiệu hợp lý, không phải kết quả chính thức:

- Nếu cài bằng script, kiểm tra xem thư mục `$HOME/.opencode/bin` đã được tạo chưa.
- Nếu cài bằng bản Desktop, mở ứng dụng và xem có vào được giao diện không.
- Khi đã chạy được, bạn sẽ thấy hai agent là `build` và `plan`. Bấm phím `Tab` để chuyển qua lại. Thấy được việc đổi này nghĩa là bạn đã vào đúng giao diện của opencode.

Lệnh khởi chạy trong terminal README chưa ghi rõ. Bạn xem mục bắt đầu trong docs. Nếu lệnh báo không tìm thấy, hãy đóng terminal mở lại, vì đôi khi máy chưa nhận đường dẫn mới sau khi cà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 nêu: hai agent, subagent `general` và việc đổi chế độ bằng `Tab`. Câu lệnh mẫu chỉ là gợi ý cách nhờ, không phải cú pháp bắt buộc.

### Lập trình viên mới nhận dự án lạ

**Bối cảnh:** bạn vừa vào công ty, được giao một dự án mà không ai có thời gian giải thích.

Bạn mở opencode ở thư mục dự án và đảm bảo đang ở chế độ `plan` (bấm `Tab` để đổi). Sau đó hỏi:

```text
Dự án này chia thành những phần nào? Phần xử lý đơn hàng nằm ở đâu?
```

**Kết quả:** vì `plan` chỉ đọc và từ chối sửa file mặc định, bạn khám phá thoải mái mà không sợ lỡ tay làm hỏng gì. Bạn nắm được bản đồ dự án trong vài phút thay vì mở từng file.

> Nên cho AI đọc trước, rồi mới cho nó sửa. Chế độ chỉ đọc là chỗ an toàn để bắt đầu.
>
> — Ông T

### Chủ shop nhờ sửa một file nhỏ

**Bối cảnh:** bạn có website bán hàng nhỏ do người khác dựng, cần đổi đoạn chữ khuyến mãi trong một file.

Chuyển qua `plan` trước và hỏi: "File nào đang chứa dòng khuyến mãi trên trang chủ?". Khi đã biết đúng file, đổi sang `build` và nhờ:

```text
Đổi dòng khuyến mãi trong file đó thành: Giảm 10% cho đơn đầu tiên.
```

**Kết quả:** file được sửa trực tiếp. Bạn nên sao lưu thư mục trước và kiểm tra lại kết quả trên trang web.

### Nhân viên văn phòng dọn việc lặp lại

**Bối cảnh:** mỗi tuần bạn phải đổi tên hàng chục file báo cáo theo cùng một quy tắc.

Trong chế độ `build`, bạn mô tả quy tắc đổi tên và nhờ agent viết một script nhỏ làm việc đó. Vì `plan` hỏi quyền trước khi chạy lệnh bash, bạn có thể dùng chế độ này để xem agent định chạy lệnh gì rồi mới cho phép.

**Kết quả:** việc thủ công lặp lại được thay bằng một script. Hãy thử trên vài file mẫu trước khi chạy trên toàn bộ thư mục.

### Dev tìm một chỗ trong code lớn

**Bối cảnh:** bạn cần biết hàm tính phí vận chuyển được gọi ở những đâu, mà dự án có hàng trăm file.

Bạn nhờ trong tin nhắn:

```text
@general tìm tất cả chỗ gọi hàm tính phí vận chuyển và tóm tắt lại
```

**Kết quả:** theo README, subagent `general` dành cho tìm kiếm phức tạp và tác vụ nhiều bước, nên nó hợp với kiểu câu hỏi này. Bạn nhận một bản tóm tắt thay vì tự lục từng file.

## 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. Đóng terminal, mở lại rồi thử lại. Nếu cài bằng script, bạn kiểm tra thư mục `$HOME/.opencode/bin` có tồn tại không. Nếu chưa, chạy lại bước cài.

### Lệnh npm báo lỗi hoặc không tìm thấy gói

Tên gói trong tư liệu và trong README lệch nhau (`opencode` và `@opencode/cli`). Hãy thử đúng dòng README ghi. Nếu vẫn lỗi, xem trang docs hoặc chọn cách cài khác như Homebrew hay bản Desktop.

### Xung đột với bản cũ

README khuyên gỡ các phiên bản cũ hơn 0.1.x trước khi cài. Nếu bạn gặp hành vi lạ sau khi cài mới, hãy kiểm tra xem máy còn bản cũ nào không, gỡ đi rồi cài lại.

### Agent chạy không có mô hình AI để trả lời

opencode là agent, cần kết nối tới một mô hình AI để làm việc. README chưa ghi cách kết nối, nên bạn làm theo trang cấu hình ở docs. Tuyệt đối không dán API key vào nơi công khai hoặc vào file bạn sẽ đưa lên GitHub.

### Agent sửa nhầm file

Trong chế độ `build`, agent có toàn quyền. Cách an toàn: sao lưu hoặc dùng quản lý phiên bản như git trước khi nhờ sửa. Với việc chưa chắc, hãy chuyển sang `plan` để xem kế hoạch 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 nghìn sao).
- Hai agent rõ ràng: `build` để làm, `plan` để xem mà không sửa. Điều này giúp người mới yên tâm hơn.
- Nhiều cách cài, có bản Desktop cho ai ngại terminal.
- README có cả bản tiếng Việt, và có Discord để hỏi.

**Giới hạn:**

- README rất ngắn: không nói về yêu cầu phần cứng, API key, chi phí hay lệnh khởi chạy. Bạn phải đọc thêm docs.
- Bản Desktop vẫn là BETA.
- Các lệnh cài viết cho môi trường kiểu Unix. Người dùng Windows nên ưu tiên bản `.exe`.
- Tên gói npm trong README có dấu hiệu chưa thống nhất với tên gói liệt kê trong tư liệu, nên có thể phải kiểm tra lại.

**Khi nào chọn cách khác:** nếu bạn không muốn đụng vào terminal hay cấu hình nào và chỉ cần một khung chat để hỏi đáp, dùng một ứng dụng chat AI thông thường sẽ đơn giản hơn. Nếu bạn cần một agent làm việc trực tiếp trên mã nguồn trong máy mình, và muốn kiểm soát bằng chế độ chỉ đọc, opencode là lựa chọn đáng thử.

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

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

README có file Desktop (BETA) cho Windows là opencode-desktop-win-x64.exe. Các lệnh cài bằng script dùng bash, và README không có hướng dẫn riêng cho Windows ngoài bản Desktop. Cách chắc chắn nhất theo tư liệu là dùng bản Desktop.

### 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, nên chưa có thông tin. Xem trang docs của dự án để biết chi tiết.

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

`build` là agent mặc định, có toàn quyền để 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.

### Có cần API key không và dữ liệu có an toàn không?

README không nói về API key hay cách xử lý dữ liệu, nên chưa có thông tin chắc chắn. Bạn đọc docs, và nên tránh để key trong thư mục sẽ đưa lên mạng. Vì agent có thể sửa file và chạy lệnh, hãy sao lưu trước khi dùng chế độ build.

### Có nên chạy lệnh curl ... | bash không?

Đó là cách cài nhanh nhất trong README, nhưng nó chạy một script tải từ mạng mà bạn không đọc trước. Nếu ngại, bạn chọn cách cài bằng trình quản lý gói như brew hoặc npm, hoặc dùng bản Desktop.

### Tôi hỏi ở đâu khi gặp vấn đề?

README chỉ tới trang tài liệu opencode.ai/docs, cộng đồng Discord và tài khoản X của dự án. README cũng có bản tiếng Việt để bạn đọc thêm.
