# 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 agent lập trình AI mã nguồn mở (giấy phép MIT), viết bằng TypeScript, có bản dòng lệnh và bản desktop (BETA). Bạn dùng nó để hỏi đáp, khám phá và chỉnh sửa code trong dự án. Cài đặt khá dễ: một dòng lệnh, hoặc qua npm, Homebrew và vài trình quản lý gói khác.

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

opencode là một **agent lập trình AI mã nguồn mở**: bạn mở nó trong thư mục dự án, nói bằng ngôn ngữ thường cái bạn muốn, và nó giúp đọc, phân tích, rồi sửa code. 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 trên GitHub, giấy phép MIT, và vẫn được cập nhật trong vài tháng gần đây.

Bài này dành cho ba nhóm người. Thứ nhất là lập trình viên mới, muốn có một "người bạn" biết đọc cả dự án mà mình chưa hiểu. Thứ hai là dân văn phòng hay chủ doanh nghiệp nhỏ có chút code (website, file tự động hoá) và muốn nhờ AI sửa hộ. Thứ ba là dev lâu năm muốn một công cụ mã nguồn mở thay vì phụ thuộc hoàn toàn vào một hãng.

Điểm đáng giá nhất theo README là cách chia hai chế độ rõ ràng: một chế độ được phép sửa file để làm việc, một chế độ chỉ đọc để khám phá và lên kế hoạch. Bạn đổi qua lại bằng phím `Tab`. Nhờ vậy bạn có thể cho AI xem dự án mà không lo nó tự ý sửa gì.

```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, giúp đọc hiểu, sửa và lên kế hoạch cho code ngay trong dự án của bạn.
- stars | 227k
- lang | TypeScript
- license | MIT
```

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

Tư liệu của repo nói về một số điểm chính. Mình giải thích theo hướng "có lợi gì cho bạn".

**Hai agent dựng sẵn, đổi bằng phím Tab.**
- **build** là agent mặc định, có đầy đủ quyền để làm việc phát triển. Dùng khi bạn đã biết mình muốn gì và muốn AI bắt tay vào 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 việc sửa file, và sẽ hỏi bạ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.

**Subagent general.** Đây là agent phụ dành cho các việc tìm kiếm phức tạp hoặ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 của bạn cần lục nhiều chỗ trong dự án.

**Có cả bản desktop (BETA).** Nếu bạn không quen terminal, repo có ứng dụng desktop cho macOS, Windows và Linux. Bạn tải về như một phần mềm bình thường.

**Nhiều cách cài.** Từ một dòng `curl`, npm, Homebrew, pacman, mise cho tới Nix. Bạn chọn cách quen tay nhất.

**Mã nguồn mở, MIT.** Bạn đọc được mã, dùng được, và không bị khoá vào một dịch vụ đóng.

README cũng có nhiều bản dịch ngôn ngữ, trong đó có tiếng Việt (`README.vi.md` trong repo). Nếu muốn đọc bản gốc bằng tiếng Việt, bạn mở file đó.

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

README ghi rất ít về yêu cầu, nên mình chỉ nêu những gì có thật:

- **Hệ điều hành:** bản dòng lệnh có cách cài cho macOS, Linux (Arch Linux có lệnh riêng), và mise dùng được trên mọi hệ điều hành. Bản desktop có file cho macOS (Apple Silicon và Intel), Windows (`opencode-desktop-win-x64.exe`) và Linux (`.deb`, `.rpm`, `.AppImage`).
- **Công cụ cài:** tuỳ cách bạn chọn, cần có `curl`, hoặc npm/bun/pnpm/yarn, hoặc Homebrew, hoặc Nix. Chọn một cách là đủ.
- **Gỡ bản cũ:** README dặ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** gì về việc này (ví dụ cần key của nhà cung cấp mô hình AI nào, cần GPU hay không). Phần cấu hình nằm ở trang tài liệu https://opencode.ai/docs. Bạn nên xem trang đó trước khi dùng thật.

```note
README không nói chi phí. Một agent lập trình AI thường kết nối tới mô hình AI bên ngoài, và việc đó có thể tốn tiền theo cách bạn cấu hình. Hãy xem trang tài liệu chính thức để biết bạn đang dùng mô hình nào và tính phí ra sao trước khi giao việc lớn.
```

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

```steps
- Chọn cách cài | Dùng một dòng curl, hoặc npm, Homebrew, mise… tuỳ máy bạn
- Chạy lệnh cài | Dán lệnh vào terminal và chờ cài xong
- Mở thư mục dự án | Dùng terminal, cd vào thư mục code của bạn
- Cấu hình theo tài liệu | Xem opencode.ai/docs để thiết lập
- Thử hai chế độ | Dùng Tab để đổi giữa build và plan
```

### Chọn cách cài phù hợp

README đưa ra khá nhiều cách. Bạn chỉ cần chọn **một**:

- Muốn nhanh nhất, không cần nghĩ: dòng `curl` (README đặt nhãn vui là "YOLO", nghĩa là chạy thẳng script từ mạng).
- Đã có Node/npm: dùng `npm`.
- Dùng macOS hoặc Linux có Homebrew: dùng `brew`. README ghi bản `anomalyco/tap/opencode-v2` là bản khuyến nghị và luôn mới nhất, còn bản `opencode` chính thức của brew thì cập nhật chậm hơn.
- Dùng Arch Linux, mise hay Nix: có dòng lệnh riêng bên dưới.
- Không thích terminal: xem phần bản desktop ở cuối mục này.

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

### Chạy lệnh cài

Mở terminal (macOS/Linux: ứng dụng Terminal; Windows: PowerShell hoặc terminal bạn quen), rồi dán đúng **một** dòng dưới đây. Đây là toàn bộ danh sách trong 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
```

Một vài lưu ý cho người mới:

- Đừng dán cả khối, chỉ chọn **một dòng** phù hợp với máy bạn. Chạy hết sẽ cài lặp nhiều lần.
- Dòng bắt đầu bằng `#` là ghi chú, không phải lệnh.
- `curl ... | bash` tải một script từ mạng rồi chạy ngay. Nếu bạn muốn chắc chắn, hãy mở địa chỉ script trong trình duyệt để đọc trước khi chạy.
- Lệnh `npm i -g` cài toàn cục, nên cần máy đã có npm. Dòng này ghi `@opencode/cli@latest`. Lưu ý tên gói trong README khác với tên gói `opencode` ghi trong thông tin repo. Bạn cứ làm theo README, và nếu gặp lỗi không tìm thấy gói thì xem lại trang tài liệu.
- `sudo pacman` sẽ hỏi mật khẩu quản trị, bình thường.
- Với cách `curl`, README cho biết script cài opencode vào `$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 của bạn không. README chưa hướng dẫn chi tiết bước này, nên hãy xem thêm ở trang tài liệu.

### Hoặc dùng bản desktop

Bản desktop đang ở trạng thái **BETA**, tải ở opencode.ai/download. Các file theo từng nền tảng:

| 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 có thể cài bằng Homebrew:

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

Người dùng Windows muốn cách đơn giản nhất thì tải file `.exe` ở trên. README chưa ghi lệnh cài riêng cho PowerShell ngoài npm và mise.

### Mở thư mục dự án

Bạn dùng agent trong ngữ cảnh một dự án cụ thể, nên hãy đứng đúng thư mục. Với dự án đã có trên GitHub, bạn có thể lấy về bằng lệnh phổ thông:

```bash
git clone https://github.com/<ten-ban>/<ten-du-an>.git
cd <ten-du-an>
```

Thay `<ten-ban>/<ten-du-an>` bằng dự án của bạn. Nếu code đã nằm trên máy, chỉ cần `cd` vào thư mục đó.

### Cấu hình theo tài liệu

README không liệt kê các bước cấu hình, chỉ chỉ bạn tới trang https://opencode.ai/docs. Đây là chỗ bạn tìm cách chọn mô hình AI, điền key nếu cần, và tuỳ chỉnh agent (xem thêm https://opencode.ai/docs/agents). Mình không đoán tên biến môi trường hay file cấu hình ở đây để tránh hướng dẫn sai.

### Thử đổi giữa hai chế độ

Sau khi mở giao diện, bạn nhấn phím `Tab` để chuyển giữa **build** và **plan**. Mới làm quen thì nên bắt đầu ở **plan** cho an toàn.

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

README không nêu một lệnh kiểm tra cụ thể hay màn hình kết quả mẫu. Vì vậy mình chỉ gợi ý những dấu hiệu hợp lý dựa trên những gì README mô tả:

1. Lệnh cài chạy xong mà không báo lỗi đỏ.
2. Nếu cài bằng `curl`, thư mục `$HOME/.opencode/bin` đã xuất hiện trên máy. Bạn có thể kiểm tra nhanh bằng cách liệt kê thư mục này.
3. Mở được giao diện của opencode (bản desktop thì mở ứng dụng lên), và khi nhấn `Tab` thì chế độ đổi giữa **build** và **plan**.
4. Ở chế độ **plan**, thử nhờ nó giải thích một file. Nếu nó trả lời được mà không sửa gì, nghĩa là mọi thứ đang chạy đúng.

README chưa ghi chính xác tên lệnh để khởi động bản dòng lệnh. Bạn xem trang tài liệu chính thức để biết lệnh mở giao diện.

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

Các tình huống dưới đây bám vào khả năng README mô tả: đọc và khám phá code, lên kế hoạch, và làm việc phát triển. Câu lệnh mẫu chỉ là cách bạn nói chuyện với agent, không phải cú pháp của công cụ.

### Dev mới nhận một dự án lạ

Bạn vừa vào công ty và được giao một repo chưa từng đọc. Hãy mở opencode trong thư mục dự án, để ở chế độ **plan**, rồi hỏi:

```text
Giải thích cấu trúc thư mục của dự án này. Phần nào xử lý đăng nhập? Chỉ cho mình file nào nên đọc trước.
```

Vì **plan** là chế độ chỉ đọc, nó sẽ khám phá và trả lời mà không sửa file. Kết quả là một bản "bản đồ" dự án để bạn đỡ mất cả buổi lần mò. README nói rõ trường hợp này là điểm mạnh của plan: khám phá codebase lạ.

> Cho AI xem dự án ở chế độ chỉ đọc trước, tin tưởng rồi mới cho nó sửa.
>
> — Ông T

### Chủ shop muốn sửa nhỏ trên website

Bạn có một website bán hàng do người khác dựng, giờ muốn đổi dòng chữ khuyến mãi ở trang chủ. Bạn mở thư mục website, để **plan** trước và hỏi:

```text
Dòng chữ khuyến mãi ở trang chủ nằm ở file nào? Nếu muốn đổi sang nội dung mới thì cần sửa chỗ nào?
```

Khi đã thấy kế hoạch hợp lý, bạn nhấn `Tab` sang **build** và nhờ nó thực hiện. Kết quả: thay đổi nhỏ được áp dụng ngay trong file, bạn xem lại trước khi đưa lên mạng. Nhớ sao lưu hoặc dùng git trước khi cho phép sửa.

### Nhân viên văn phòng tìm trong nhiều file

Bạn có một thư mục chứa nhiều script tự động hoá (xử lý báo cáo, đổi tên file…), và quên mất đoạn nào gửi email. Bạn gọi subagent:

```text
@general tìm trong dự án mọi chỗ có gửi email và liệt kê file cùng mô tả ngắn.
```

README mô tả `@general` dành cho các tìm kiếm phức tạp và việc nhiều bước. Bạn nhận về một danh sách các chỗ liên quan để tự quyết định sửa gì.

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

Bạn định đổi cách lưu dữ liệu của ứng dụng và sợ làm hỏng nhiều chỗ. Ở **plan**, bạn nhờ:

```text
Mình muốn đổi cách lưu cấu hình người dùng. Liệt kê các file bị ảnh hưởng và đề xuất thứ tự thay đổi.
```

Vì plan hỏi quyền trước khi chạy lệnh bash, bạn kiểm soát được từng bước. Có kế hoạch rồi, bạn mới chuyển sang **build** để làm từng phần nhỏ.

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

README không có mục xử lý lỗi, nên dưới đây là những tình huống rất dễ xảy ra với loại công cụ này. Mình nói rõ đây là gợi ý chung, không phải thông báo lỗi chính thức của repo.

**Terminal báo không tìm thấy lệnh sau khi cài.** Terminal đang mở có thể chưa nhận lệnh mới. Hãy đóng và mở lại terminal. Nếu cài bằng `curl`, kiểm tra thư mục `$HOME/.opencode/bin` đã có trong PATH chưa.

**Lệnh `npm i -g` báo lỗi quyền hoặc không tìm thấy gói.** Lỗi quyền thường gặp khi cài toàn cục trên máy có cấu hình npm chặt. Đừng vội dùng quyền quản trị cho mọi thứ. Thử một cách cài khác trong README (ví dụ Homebrew hoặc mise). Nếu báo không tìm thấy gói, đối chiếu lại tên gói với trang tài liệu chính thức.

**Bản cài cũ gây xung đột.** README dặn gỡ các bản cũ hơn 0.1.x trước khi cài. Nếu bạn từng cài opencode từ lâu, hãy gỡ bản cũ rồi cài lại.

**Agent không chịu sửa file.** Có thể bạn đang ở chế độ **plan**, vốn mặc định từ chối sửa file. Nhấn `Tab` để sang **build** nếu bạn thực sự muốn nó sửa.

**Agent sửa sai hoặc sửa quá tay.** Với mọi agent lập trình, hãy làm việc trong thư mục có git hoặc đã sao lưu, để quay lại được khi cần. Giao việc nhỏ, từng bước, và đọc lại thay đổi trước khi dùng thật.

**Nhầm với dự án có tên gần giống.** README lưu ý các dự án dùng chữ "opencode" trong tên (như opencode-dashboard hay opencode-mobile) có thể không do đội opencode làm. Hãy kiểm tra nguồn trước khi cài thứ gì có tên tương tự.

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

**Điểm mạnh:**
- Mã nguồn mở, giấy phép MIT, repo rất đông người quan tâm và vẫn được cập nhật.
- Chia chế độ rõ: **build** để làm, **plan** chỉ đọc để khám phá. Giúp người mới an tâm hơn.
- Nhiều đường cài, có cả bản desktop (BETA) cho người ngại terminal.
- Có subagent `@general` cho việc tìm kiếm nhiều bước.

**Giới hạn:**
- README khá ngắn: chưa có hướng dẫn khởi động, cấu hình mô hình AI hay xử lý lỗi. Bạn sẽ phải đọc thêm trang tài liệu chính thức.
- Bản desktop còn ở BETA, nên có thể chưa ổn định bằng.
- Tên gói npm trong README và trong thông tin repo không trùng nhau, dễ làm người mới bối rối.
- Chưa có thông tin về chi phí hay yêu cầu phần cứng trong tư liệu.

**Khi nào chọn cách khác?** Nếu bạn hoàn toàn không đụng tới code và chỉ cần AI viết văn bản, một ứng dụng chat thông thường sẽ đơn giản hơn. Nếu bạn cần cam kết hỗ trợ chính thức cho doanh nghiệp, hãy tìm hiểu kỹ chính sách của dự án trước. Còn nếu bạn muốn một agent mở, đọc hiểu dự án, lên kế hoạch và sửa code ngay trong terminal, opencode là một lựa chọn đáng thử. Hãy bắt đầu ở chế độ **plan** trên một dự án nhỏ.

## 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ở, giấy phép MIT, nên bạn dùng mà không phải trả tiền cho phần mềm. README không nói gì về chi phí của mô hình AI hay dịch vụ đi kèm. Bạn nên xem trang tài liệu chính thức để biết chi tiết.

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

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

### Cần GPU hay máy mạnh không?

README không nêu yêu cầu phần cứng nào, nên chưa có thông tin để khẳng định. Bạn xem thêm trang tài liệu chính thức nếu muốn chắc chắn.

### Hai chế độ 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 quyền trước khi chạy lệnh bash, hợp để khám phá code hoặc lên kế hoạch. Bạn đổi qua lại bằng phím Tab.

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

README không mô tả chi tiết về xử lý dữ liệu. Có thông tin là chế độ plan không sửa file và hỏi trước khi chạy lệnh bash. Còn việc code được gửi đi đâu phụ thuộc cách bạn cấu hình, nên hãy xem tài liệu chính thức. Luôn sao lưu hoặc dùng git trước khi cho agent sửa code.

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

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

### Tôi không quen terminal thì dùng thế nào?

Bạn có thể dùng bản desktop (BETA), tải ở opencode.ai/download, với file cho macOS, Windows và Linux. Trên macOS còn có lệnh brew install --cask opencode-desktop. Phần cấu hình vẫn nên xem trong tài liệu chính thức.
