# OpenCode: agent lập trình mã nguồn mở chạy 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, giúp bạn đọc, hỏi đáp và sửa code ngay trên máy. Repo có sẵn hai agent là build (toàn quyền) và plan (chỉ đọc), và có cả bản desktop (beta). Cài không khó: chạy một dòng lệnh hoặc dùng trình quản lý gói quen thuộc.

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

OpenCode là một agent lập trình AI mã nguồn mở. Bạn mô tả việc cần làm bằng ngôn ngữ thường, agent đọc dự án, đề xuất và sửa code giúp bạn. Dự án do nhóm anomalyco phát triển, viết bằng TypeScript, dùng giấy phép MIT và có trang chủ riêng là opencode.ai.

Repo này hợp với lập trình viên mới muốn có một "người phụ" biết đọc code. Nó cũng hợp với người làm kinh doanh, văn phòng có chút nền tảng kỹ thuật, cần hiểu một dự án lạ mà không phải đọc từng file. Hiện repo có khoảng 226.506 sao và 30.658 fork, và vẫn được cập nhật trong 3 tháng gần đây.

Điểm đáng giá nhất là cách chia quyền rất rõ. Agent **build** làm được mọi việc, còn agent **plan** chỉ đọc và phân tích, nên bạn có thể khám phá một dự án lạ mà không lo nó tự sửa file. Ngoài ra còn có bản ứng dụng desktop (beta) cho ai không thích gõ lệnh.

```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, cài bằng một dòng lệnh hoặc dùng bản ứng dụng desktop.
- stars | 227k
- lang | TypeScript
- license | MIT
```

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

Theo README, OpenCode có mấy phần chính sau.

### Hai agent chuyển nhanh bằng phím Tab

- **build** là agent mặc định, toàn quyền cho công việc phát triển. Bạn dùng nó khi muốn nó thực sự viết hoặc sửa code.
- **plan** là 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 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ập kế hoạch thay đổi trước khi động vào.

Bạn đổi qua lại giữa hai agent bằng phím `Tab`. Lợi ích thực tế là bạn tách bạch "nghĩ" và "làm", nên ít rủi ro hơn.

### Subagent general cho việc tìm kiếm phức tạp

Repo còn có subagent **general**, dùng cho các tìm kiếm phức tạp và việc nhiều bước. Chủ yếu nó đượ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.

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

Bạn có thể cài bằng script, npm, Homebrew, pacman, paru, mise hoặc Nix. Ngoài ra có ứng dụng desktop (đang beta) cho macOS, Windows và Linux. Nhờ vậy gần như hệ điều hành nào cũng có đường vào.

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

Giấy phép MIT cho phép bạn xem code và dùng khá thoải mái. Cách cấu hình chi tiết nằm ở trang tài liệu opencode.ai/docs, nên README chỉ giữ phần cài đặt và giới thiệu agent.

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

README ghi khá ít, nên mình chỉ nêu đúng những gì có:

- **Hệ điều hành:** bản desktop có cho macOS (Apple Silicon và Intel), Windows và Linux (`.deb`, `.rpm`, `.AppImage`). Các lệnh Homebrew dùng cho macOS và Linux, pacman và paru cho Arch Linux, mise cho "mọi hệ điều hành", Nix cho người dùng Nix.
- **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.
- **Phiên bản Node/Python, tài khoản, API key, phần cứng:** README **chưa nói** gì về các mục này. Vì vậy mình không đoán. Nếu cần biết agent kết nối với mô hình AI nào và phải khai báo key ra sao, bạn xem tài liệu tại opencode.ai/docs.

Có một điểm bạn nên biết: lệnh npm trong README dùng gói `@opencode/cli`, trong khi thông tin repo ghi tên gói npm là `opencode`. Hai thứ này khác nhau. Mình chép đúng lệnh trong README, nếu gặp lỗi bạn đối chiếu lại với trang tải về chính thức.

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

```steps
- Gỡ bản cũ | Xoá phiên bản trước 0.1.x nếu máy đang có
- Chọn cách cài | Script, npm, Homebrew hoặc trình quản lý gói của hệ điều hành
- Chạy lệnh cài | Mở terminal và dán đúng một lệnh trong README
- Hoặc tải bản desktop | Tải file đúng hệ điều hành ở trang tải về
- Mở lại terminal | Để máy nhận lệnh mới rồi thử khởi chạy
```

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

README dặn: gỡ các phiên bản cũ hơn 0.1.x trước khi cài. README không nói cách gỡ. Nếu bạn từng cài OpenCode bằng cách nào, hãy gỡ bằng chính cách đó (ví dụ cài bằng Homebrew thì gỡ bằng Homebrew). Chưa từng cài thì bỏ qua bước này.

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

Trong README, các lệnh nằm chung một khối. Bạn chỉ cần chọn **một** dòng phù hợp, đừ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
```

Gợi ý chọn nhanh:

- **Dùng macOS hoặc Linux, muốn bản mới nhất:** dùng `brew install anomalyco/tap/opencode-v2` (README ghi là cách được khuyên dùng).
- **Đã có npm (hoặc bun/pnpm/yarn):** dùng `npm i -g @opencode/cli@latest`.
- **Dùng Arch Linux:** `sudo pacman -S opencode` cho bản ổn định, hoặc `paru -S opencode-beta` cho bản mới nhất từ AUR.
- **Muốn một cách chung cho mọi hệ điều hành:** `mise use -g opencode`.
- **Dùng Nix:** `nix run github:anomalyco/opencode`.
- **Thích nhanh gọn:** dòng `curl ... | bash` đứng đầu. README gọi nó đùa là "YOLO". Lệnh này tải một script từ mạng về chạy luôn, nên chỉ dùng khi bạn tin nguồn đó.

Chỗ người mới hay vấp: dòng bắt đầu bằng `#` là chú thích, không cần gõ. Phần chữ sau `#` ở cuối dòng cũng chỉ là ghi chú. Mở terminal ở đâu cũng được, vì đây là cài toàn máy (cờ `-g` của npm có nghĩa đó). Trên Windows, README không viết riêng lệnh cài cho dòng lệnh, nên cách an toàn nhất là dùng bản desktop ở bước sau.

### Bước 3: Biết script cài vào đâu

Nếu bạn dùng script cài đặt, README cho biết nó cài OpenCode vào thư mục `$HOME/.opencode/bin`. Nếu sau khi cài mà terminal báo không tìm thấy lệnh, đây là chỗ đầu tiên cần xem. README không nói gì thêm về việc thêm thư mục này vào PATH, nên bạn cần xem tài liệu nếu gặp tình huống đó.

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

Nếu không muốn dùng terminal, hãy tải bản ứng dụng ở trang 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` |

Người dùng macOS có Homebrew cũng cài được bằng lệnh sau:

```bash
# macOS (Homebrew)
brew install --cask opencode-desktop
```

Chọn đúng chip: máy Mac đời mới (chip M1 trở lên) dùng bản arm64, máy Mac cũ dùng chip Intel thì chọn bản x64. Bản desktop vẫn đang beta nên có thể còn lỗi vặt.

### Bước 5: Mở lại terminal

Sau khi cài, hãy đóng và mở lại cửa sổ terminal để máy nhận lệnh mới. README chưa ghi rõ lệnh khởi chạy. Tên gói là `opencode`, nên bạn thử gõ tên đó. Nếu khác, hãy xem hướng dẫn ở opencode.ai/docs.

```note
README không nói về việc khai báo tài khoản hay API key. Nếu tài liệu yêu cầu điền key của một nhà cung cấp AI, hãy giữ key riêng tư, đừng dán vào chỗ công khai và đừng gửi cho người khác. Dịch vụ AI tính phí theo mức dùng thường có thể tốn tiền, nên hãy theo dõi chi phí ngay từ đầu.
```

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

README không đưa ra lệnh kiểm tra phiên bản hay kết quả mẫu, nên mình không bịa ra. Cách kiểm tra thực tế, dựa trên những gì tư liệu có:

1. **Terminal nhận lệnh:** mở một terminal mới, thử khởi chạy bằng tên `opencode`. Nếu giao diện agent hiện lên thì cài thành công.
2. **Thử phím Tab:** theo README, `Tab` chuyển giữa agent **build** và **plan**. Nếu bạn thấy chuyển được, tức là bạn đang dùng đúng OpenCode.
3. **Với bản desktop:** mở ứng dụng lên là thấy giao diện. Nếu file tải về không mở được, kiểm tra lại bạn đã chọn đúng hệ điều hành và chip chưa.

Nếu máy báo không tìm thấy lệnh, xem lại thư mục `$HOME/.opencode/bin` (nếu cài bằng script) hoặc mục lỗi bên dưới.

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

README không đưa ví dụ lệnh cụ thể, nên các tình huống dưới đây bám vào đúng khả năng đã nêu: hai agent build/plan, subagent `@general`, và việc đọc, sửa code. Câu lệnh mẫu chỉ là cách bạn nhập nội dung trong khung chat của OpenCode.

> Đừng để AI sửa code khi bạn chưa hiểu dự án. Cứ cho nó đọc trước, rồi mới cho nó viết.
>
> — Ông T

### Tình huống 1: Nhận một dự án lạ và muốn hiểu nó

Bạn là lập trình viên mới, vừa được giao một thư mục code của người khác. Thay vì mò từng file, bạn mở OpenCode trong thư mục đó và đổi sang agent **plan** bằng phím `Tab`. Vì plan chỉ đọc, bạn yên tâm nó không đụng đến file nào.

Bạn hỏi bằng tiếng Việt, ví dụ:

```text
Dự án này làm gì? Liệt kê các thư mục chính và cho mình biết nên đọc file nào trước.
```

Kết quả bạn nhận được là một bản tóm tắt cấu trúc dự án và gợi ý thứ tự đọc. Plan còn hỏi quyền trước khi chạy lệnh bash, nên bạn vẫn kiểm soát được.

### Tình huống 2: Lập kế hoạch trước khi sửa

Bạn làm chủ một website bán hàng nhỏ do thuê người viết, và muốn thêm một tính năng. Đừng cho sửa ngay. Ở chế độ **plan**, bạn mô tả việc cần làm:

```text
Mình muốn thêm trường ghi chú đơn hàng. Hãy cho mình biết sẽ phải sửa những file nào và các bước làm theo thứ tự.
```

Bạn nhận được một danh sách bước và các file liên quan. Bạn có thể đưa danh sách này cho người viết code gốc xem, hoặc tự chuyển sang agent **build** để thực hiện.

### Tình huống 3: Giao agent build làm việc nhỏ có giới hạn

Bạn là dev đã hiểu dự án và có một việc rõ ràng như sửa lỗi chính tả trong thông báo, đổi tên một hàm, hay thêm một đoạn kiểm tra đầu vào. Bấm `Tab` sang **build**, rồi mô tả đúng một việc:

```text
Trong file xử lý đăng nhập, thêm kiểm tra email rỗng và trả về thông báo lỗi bằng tiếng Việt.
```

Build có toàn quyền nên nó sẽ chỉnh file trực tiếp. Hãy xem lại phần thay đổi trước khi dùng. Nếu bạn dùng Git để quản lý code thì càng dễ so sánh và quay lại.

### Tình huống 4: Tìm kiếm phức tạp bằng @general

Dự án lớn, bạn cần tìm mọi chỗ gọi một chức năng và xem chúng liên quan thế nào. Bạn nhắc subagent trong tin nhắn:

```text
@general tìm tất cả nơi dùng chức năng gửi email và tóm tắt luồng chạy.
```

README mô tả `@general` dành cho các tìm kiếm phức tạp và việc nhiều bước. Kết quả là bản tổng hợp mà bạn khó có được nếu chỉ tìm chữ thủ công.

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

### Báo không tìm thấy lệnh sau khi cài

Đây là lỗi rất hay gặp với công cụ dòng lệnh. Trước hết đóng hẳn terminal và mở lại. Nếu cài bằng script, nhớ README cho biết file nằm ở `$HOME/.opencode/bin`. Kiểm tra thư mục đó có tồn tại không. Nếu cần thêm vào PATH, bạn xem tài liệu ở opencode.ai/docs vì README chưa hướng dẫn.

### Cài lệnh npm nhưng gói không đúng

README dùng `@opencode/cli`, trong khi thông tin repo ghi tên gói là `opencode`. Nếu lệnh npm báo lỗi hoặc cài ra thứ không đúng, đừng thử bừa nhiều gói. Hãy quay về cách cài khác (Homebrew, script) hoặc kiểm tra tên chính xác ở trang tải về chính thức. Cũng cẩn thận với các dự án có chữ "opencode" trong tên: README nhắc rằng một số dự án như "opencode-dashboard" hay "opencode-mobile" không do nhóm OpenCode làm và không liên kết với họ.

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

README dặn gỡ các bản cũ hơn 0.1.x trước khi cài. Nếu máy chạy ra giao diện lạ hoặc lệnh không như mô tả, rất có thể bạn đang chạy bản cũ. Hãy gỡ bản cũ bằng đúng cách đã cài, rồi cài lại.

### Chọn nhầm file desktop

Trên Mac, file `arm64` chỉ chạy trên chip Apple Silicon, còn `x64` dành cho chip Intel. Mở không được thì thường là chọn sai. Vào menu Apple, chọn "Giới thiệu về máy Mac này" để xem chip, rồi tải lại bản đúng.

### Agent đã sửa code theo cách bạn không muốn

Đây là rủi ro tự nhiên với agent có toàn quyền như **build**. Cách phòng: dùng **plan** để xem trước, giao từng việc nhỏ, và giữ code trong Git hoặc có bản sao lưu để quay lại. Đừng giao nó cả dự án quan trọng khi chưa có bản sao.

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

**Điểm mạnh.** OpenCode miễn phí để dùng phần mềm và mã nguồn mở theo giấy phép MIT, nên bạn xem được nó làm gì. Việc chia rõ hai chế độ build và plan rất thực dụng cho người mới. Nhiều cách cài, có cả bản desktop, và dự án đang được cập nhật đều. Cộng đồng lớn (hàng trăm nghìn sao) cũng là một tín hiệu tốt, và README có nhiều bản dịch, trong đó có tiếng Việt.

**Giới hạn.** README rất ngắn. Nó chưa nói về yêu cầu phiên bản, cách khai báo key hay lệnh khởi chạy, nên bạn phải đọc thêm tài liệu trên trang chủ. Bản desktop còn là beta. Các lệnh cài khá nhiều và có chỗ không thống nhất về tên gói, nên người mới dễ bối rối. Chi phí dùng mô hình AI (nếu có) tuỳ bạn chọn nhà cung cấp nào, và tư liệu chưa nói về điều đó.

**Khi nào nên chọn cách khác.** Nếu bạn hoàn toàn không đụng đến code mà chỉ cần trò chuyện với AI, một ứng dụng chat thông thường sẽ đơn giản hơn. Nếu công ty bạn có quy định nghiêm ngặt về dữ liệu, hãy hỏi bộ phận kỹ thuật trước khi cho bất kỳ agent nào đọc code, vì tư liệu chưa nói rõ dữ liệu được xử lý ra sao. Còn nếu bạn muốn một agent lập trình mã nguồn mở, cài nhanh và có chế độ chỉ đọc để làm quen an toàn 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à phần mềm mã nguồn mở theo giấy phép MIT. Tư liệu chưa nói gì về chi phí của mô hình AI hay dịch vụ đi kèm, nên bạn xem tài liệu ở opencode.ai/docs để biết cần tài khoản hoặc key nào.

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

Có bản ứng dụng desktop (beta) cho Windows là file opencode-desktop-win-x64.exe. README chưa ghi lệnh cài riêng cho dòng lệnh trên Windows, ngoài các lệnh chung như npm và mise (mise được ghi là dùng cho mọi hệ điều hành).

### Cài OpenCode bằng cách nào nhanh nhất?

README có một dòng curl chạy script cài đặt, ghi là cài vào $HOME/.opencode/bin. Người dùng macOS và Linux còn có lệnh Homebrew, được README khuyên dùng vì luôn mới. Bạn chỉ cần chọn một cách, không phải chạy hết.

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

Build là agent mặc định, toàn quyền cho công việc phát triển. Plan chỉ đọc: mặc định từ chối sửa file và hỏi trước khi chạy lệnh bash. Bạn đổi qua lại bằng phím Tab.

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

Tư liệu chưa có thông tin về yêu cầu phần cứng hay GPU. Bạn nên xem tài liệu ở opencode.ai/docs trước khi cài.

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

Tư liệu README không nói về cách xử lý dữ liệu. Vì repo mã nguồn mở nên bạn có thể tự xem code, và repo có file SECURITY.md. Với code nhạy cảm, hãy hỏi bộ phận kỹ thuật và đọc tài liệu trước khi dùng.

### Các dự án có chữ "opencode" trong tên có phải của nhóm này không?

Chưa chắc. README dặn các dự án liên quan dùng chữ opencode trong tên (như opencode-dashboard, opencode-mobile) phải ghi rõ là không do nhóm OpenCode làm và không liên kết với họ.
