# 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 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 hiểu, lên kế hoạch và sửa code ngay trong dự án. Repo có nhiều cách cài: một dòng lệnh, npm, Homebrew, hoặc ứng dụng desktop bản BETA. Cài khá nhanh, nhưng phần cấu hình model và khoá truy cập README không nêu, bạn cần xem trang tài liệu của dự án.

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

OpenCode là một agent lập trình AI mã nguồn mở. Hiểu đơn giản: đây là trợ lý AI sống cạnh dự án của bạn, giúp bạn đọc code, hỏi đáp về code, lên kế hoạch sửa và (nếu bạn cho phép) trực tiếp sửa file. Tác giả mô tả ngắn gọn là "the open source coding agent".

Ai nên dùng? Lập trình viên mới muốn có một "người hướng dẫn" khi mở một dự án lạ. Dev có kinh nghiệm muốn một agent không bị khoá vào một hãng. Và cả người làm kinh doanh, văn phòng có chút kỹ thuật, muốn nhờ AI chỉnh một đoạn script hay một trang web nhỏ mà không phải tự mò từng dòng.

Điểm đáng giá nhất của OpenCode là cách chia vai rõ ràng. Có một agent "build" toàn quyền để làm việc, và một agent "plan" chỉ được đọc, mặc định không cho sửa file. Bạn có thể cho AI xem xét trước, rồi mới cho nó động tay. Repo hiện có khoảng 226.506 sao và 30.658 fork, giấy phép MIT, và 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ó chế độ build để làm và plan để chỉ đọc.
- stars | 227k
- lang | TypeScript
- license | MIT
```

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

Tư liệu README khá ngắn, nên mình chỉ nói những gì nó xác nhận.

**Hai agent dựng sẵn, đổi qua lại bằng phím Tab.** Agent **build** là mặc định, toàn quyền, dùng cho công việc phát triển thực sự. Agent **plan** chỉ đọc: mặc định từ chối sửa file, và hỏi bạn trước khi chạy lệnh bash. Lợi ích thực tế: khi bạn chưa chắc AI sẽ làm gì, cứ để nó ở plan để khám phá và đề xuất, không sợ nó lỡ tay đụng vào code.

**Subagent "general".** Đây là agent phụ dành cho việc tìm kiếm phức tạp và các tác vụ nhiều bước. README nói nó được dùng nội bộ, và bạn cũng có thể gọi thẳng bằng cách gõ `@general` trong tin nhắn. Hợp khi bạn muốn nhờ "đi tìm giúp mình chỗ nào trong dự án xử lý việc này".

**Nhiều cách cài.** Có script một dòng, npm, Homebrew, pacman, paru, mise và Nix. Bạn chọn cách quen tay nhất.

**Có ứng dụng desktop (BETA).** Nếu bạn ngại terminal, có bản cài dành cho macOS, Windows và Linux. Vì còn là bản BETA, có thể sẽ chưa mượt như bản dòng lệnh.

**Tài liệu và cộng đồng.** Cách cấu hình chi tiết nằm ở trang tài liệu của dự án (opencode.ai/docs), và có cộng đồng trên Discord, X.

## 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ì có trong tư liệu:

- **Hệ điều hành:** bản desktop có file cho macOS (Apple Silicon và Intel), Windows (x64) và Linux (`.deb`, `.rpm`, `.AppImage`). Các lệnh cài qua Homebrew, pacman... nêu rõ macOS, Linux hoặc Arch Linux. Riêng mise được ghi là chạy "Any OS".
- **Nếu cài bằng npm:** bạn cần có npm trên máy (README ghi thêm "hoặc bun/pnpm/yarn"). README không nói yêu cầu phiên bản Node cụ thể.
- **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 nói. Một agent AI thường cần kết nối tới một model, nhưng cách cấu hình thế nào bạn hãy xem trong trang tài liệu của dự án trước khi làm.

Và một việc nên làm trước khi bắt đầu: mở terminal ngay trong thư mục dự án mà bạn muốn AI làm việc cùng. Với người mới, đây là chỗ hay vấp nhất, vì mở sai thư mục thì AI nhìn sai dự án.

```note
Một agent có quyền chạy lệnh và sửa file là công cụ mạnh. Hãy thử trên một dự án có sao lưu hoặc có git trước. Chế độ plan hỏi quyền trước khi chạy bash, nên đừng vội bấm đồng ý nếu bạn chưa hiểu lệnh đó làm gì. Về chi phí và khoá truy cập, README không nói gì, nên hãy đọc kỹ trang tài liệu trước khi nhập bất kỳ key nào.
```

## 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ỡ trước
- Chọn cách cài | Một dòng lệnh, npm, Homebrew hoặc trình quản lý gói khác
- Chạy lệnh cài | Dán lệnh vào terminal và chờ cài xong
- Mở terminal trong thư mục dự án | Để agent làm việc đúng dự án của bạn
- Hoặc dùng bản desktop | Tải file cài đặt nếu không muốn dùng dòng lệnh
```

### 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. 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 nếu bạn cần thì xem lại cách bạn đã cài bản cũ (npm, brew...) và gỡ bằng đúng công cụ đó.

### Chọn một cách cài

README đưa ra danh sách sau. Bạn chỉ chạy MỘT dòng phù hợp với 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
```

Gợi ý chọn nhanh:

- **macOS hoặc Linux, dùng Homebrew:** README ghi dòng `brew install anomalyco/tap/opencode-v2` là cách "recommended, always up to date". Dòng `brew install opencode` là bản chính thức của brew nhưng cập nhật chậm hơn.
- **Đã có npm:** dùng `npm i -g @opencode/cli@latest`. Cờ `-g` nghĩa là cài toàn máy để gõ lệnh ở đâu cũng được.
- **Arch Linux:** `sudo pacman -S opencode` cho bản ổn định, `paru -S opencode-beta` cho bản mới nhất từ AUR.
- **Muốn nhanh gọn:** dòng đầu tiên, script cài một lệnh. README tự gọi nó là "YOLO", nghĩa là bạn đang chạy một script tải từ mạng về. Nếu muốn cẩn thận, hãy mở địa chỉ script đó ra đọc trước rồi mới chạy.

Lưu ý cho người dùng Windows: lệnh `curl ... | bash` cần môi trường bash, ví dụ Git Bash. README không nói rõ cách cài bản dòng lệnh trên Windows thuần. Nếu bạn gặp khó, hãy dùng ứng dụng desktop ở bước sau hoặc xem trang tài liệu.

Nếu bạn dùng script cài, README cho biết OpenCode được cài vào thư mục `$HOME/.opencode/bin`. Nếu sau khi cài, gõ lệnh mà máy báo không tìm thấy, hãy kiểm tra xem thư mục này có nằm trong PATH chưa.

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

Sau khi cài, hãy mở terminal ở đúng thư mục dự án. Ví dụ bạn có repo trên GitHub và muốn thử:

```bash
git clone https://github.com/<tên-người-dùng>/<tên-repo>.git
cd <tên-repo>
```

Thay phần trong dấu `<>` bằng tên thật. Lệnh đầu tải dự án về máy, lệnh thứ hai đi vào thư mục đó. README chưa ghi lệnh khởi động chi tiết, nên bước chạy OpenCode lần đầu và nhập thông tin model, bạn xem trong trang tài liệu của dự án.

### Hoặc dùng ứng dụng desktop (BETA)

Nếu bạn không thích dòng lệnh, tải bản desktop tại trang tải xuống trên opencode.ai. README liệt kê các file:

| Nền tảng | 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ằng Homebrew:

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

Với Windows, chạy file `.exe` rồi làm theo màn hình cài đặt như phần mềm thông thường.

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

README không nêu một lệnh kiểm tra cụ thể, nên mình chỉ gợi ý các dấu hiệu hợp lý, không khẳng định:

- Lệnh cài chạy xong không báo lỗi đỏ.
- Nếu dùng script cài, thư mục `$HOME/.opencode/bin` đã được tạo.
- Với bản desktop, ứng dụng mở lên được sau khi cài.
- Khi vào được giao diện, bạn bấm phím `Tab` và thấy chuyển được giữa hai agent **build** và **plan**. Đây là dấu hiệu rõ nhất theo README rằng công cụ đang hoạt động.

Nếu chưa vào được giao diện, hãy xem phần lỗi thường gặp bên dưới, hoặc hỏi trên Discord của dự án.

## 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 build và plan, subagent general. Câu lệnh mẫu là câu bạn gõ cho AI bằng tiếng thường, không phải lệnh của repo.

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

Bối cảnh: bạn vừa vào công ty, được giao một repo hơn chục thư mục mà không ai có thời gian giải thích. Hãy để OpenCode ở agent **plan** (README ghi rõ nó hợp để khám phá code lạ). Bạn gõ:

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

Kết quả: bạn nhận một bản tóm tắt cấu trúc dự án mà không có file nào bị sửa, vì plan mặc định từ chối sửa file. Đọc xong bạn đã có bản đồ để hỏi tiếp.

> Cho AI xem trước, rồi mới cho nó động tay vào code.
>
> — Ông T

### Lên kế hoạch trước khi sửa một tính năng

Bối cảnh: chủ một cửa hàng nhỏ có nhân viên kỹ thuật làm cho shop một trang đặt hàng. Giờ cần thêm ô nhập mã giảm giá. Cứ để agent **plan** phân tích:

```text
Mình muốn thêm ô nhập mã giảm giá vào trang đặt hàng. Hãy chỉ ra những file cần sửa và các bước làm. Chưa sửa gì cả.
```

Kết quả: một danh sách file và các bước. Bạn đọc, chỉnh lại cho đúng ý, rồi nhấn `Tab` để chuyển sang **build** và bảo nó làm theo kế hoạch đã duyệt. Cách này giúp bạn kiểm soát được thứ AI định làm.

### Nhờ tìm giúp một đoạn code trong dự án lớn

Bối cảnh: bạn cần biết chỗ nào trong dự án đang tính phí vận chuyển, nhưng dự án có hàng trăm file. README nói subagent **general** dành cho tìm kiếm phức tạp và việc nhiều bước, và gọi được bằng `@general`:

```text
@general tìm giúp mình các chỗ trong dự án có tính phí vận chuyển và cho biết file nào chịu trách nhiệm chính.
```

Kết quả: một danh sách vị trí liên quan để bạn mở ra xem hoặc giao tiếp cho build sửa.

### Chỉnh một script nhỏ cho công việc văn phòng

Bối cảnh: nhân viên văn phòng có một script xử lý file báo cáo do đồng nghiệp để lại, giờ cần đổi tên cột đầu ra. Mở terminal trong thư mục chứa script, giữ agent **build** và gõ:

```text
Trong script này, đổi tên cột "Doanh thu" thành "Doanh thu (VND)" ở file kết quả. Giải thích bạn đã sửa gì.
```

Kết quả: AI sửa file và nói rõ đã đổi những dòng nào. Bạn nên sao lưu script gốc trước, rồi chạy thử để so sánh kết quả.

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

README không có mục xử lý lỗi, nên các mục dưới đây là những lỗi rất dễ xảy ra với loại công cụ này.

**Gõ lệnh báo "không tìm thấy lệnh".** Thường do thư mục cài chưa nằm trong PATH. Nếu bạn cài bằng script, README cho biết nó nằm ở `$HOME/.opencode/bin`; hãy thêm thư mục đó vào PATH rồi mở lại terminal. Nếu cài bằng npm với `-g`, hãy mở terminal mới để PATH được nạp lại.

**Cài xong nhưng vẫn ra phiên bản cũ.** README dặn gỡ các bản cũ hơn 0.1.x trước khi cài. Hãy gỡ bản cũ bằng đúng công cụ đã dùng để cài nó, rồi cài lại.

**Lệnh `curl ... | bash` không chạy trên Windows.** Script này viết cho môi trường bash. Hãy dùng Git Bash, hoặc tải ứng dụng desktop `opencode-desktop-win-x64.exe` thay thế.

**AI không sửa được file.** Nếu bạn đang ở agent **plan**, đó là chuyện bình thường: nó mặc định từ chối sửa file. Nhấn `Tab` để chuyển sang **build** nếu bạn thực sự muốn nó làm.

**Không biết điền key hay chọn model ở đâu.** README không hướng dẫn phần này. Hãy đọc trang tài liệu của dự án và đừng dán key vào chỗ công khai, chẳng hạn một repo GitHub công khai hay một tin nhắn chat.

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

**Điểm mạnh:**

- Mã nguồn mở, giấy phép MIT, dùng và xem code thoải mái.
- Có nhiều cách cài và cả bản desktop nên dễ tiếp cận.
- Chia agent build/plan rõ ràng, giúp bạn kiểm soát quyền của AI. Đây là điểm dễ chịu nhất với người mới.
- Dự án rất được quan tâm (hiện có khoảng 226.506 sao) và vẫn được cập nhật gần đây.

**Giới hạn:**

- README ngắn: không nêu yêu cầu phiên bản, cách cấu hình model, hay chi phí. Bạn phải tự đọc trang tài liệu.
- Bản desktop còn là BETA.
- Dòng lệnh cài có nhiều biến thể (ví dụ hai lệnh brew với mức độ cập nhật khác nhau), nên người mới có thể thấy rối. Cứ chọn đúng một cách rồi làm theo.
- Agent có quyền chạy lệnh và sửa file, nên cần dùng cẩn thận.

**Khi nào chọn cách khác?** Nếu bạn chỉ muốn hỏi đáp về lập trình mà không cần AI đụng vào dự án, một khung chat thông thường là đủ. Nếu công ty bạn có quy định chặt về việc gửi code ra ngoài, hãy tìm hiểu kỹ cách OpenCode kết nối model trước khi dùng cho dự án thật. Còn nếu bạn muốn một agent mã nguồn mở có thể thử nhanh trên máy mình, OpenCode là lựa chọn đáng cài 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 code tự do. README không nói gì về chi phí của model AI mà nó kết nối tới, nên phần này chưa có thông tin. Hãy xem trang tài liệu của dự án trước khi dùng.

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

README có file cài ứng dụng desktop (BETA) cho Windows là `opencode-desktop-win-x64.exe`. Với bản dòng lệnh, README không nói rõ cách cài trên Windows; lệnh `curl ... | bash` cần môi trường bash. Bạn có thể xem thêm trong tài liệu của dự án.

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

Build là agent mặc định, 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 chuyển qua lại giữa hai agent bằng phím Tab.

### 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 xác nhận. Hãy xem trang tài liệu của dự án nếu bạn lo về cấu hình máy.

### 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, nên chưa có thông tin để khẳng định. Vì agent có thể đọc, sửa file và chạy lệnh, bạn nên thử trên dự án có sao lưu và đọc kỹ tài liệu về cách kết nối model, nhất là với code có tính bảo mật.

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

Đó là một subagent dành cho các tìm kiếm phức tạp và công việc nhiều bước. README nói nó được dùng nội bộ và bạn cũng có thể gọi nó bằng cách gõ `@general` trong tin nhắn.

### Tìm hướng dẫn cấu hình chi tiết ở đâu?

README chỉ dẫn tới trang tài liệu chính thức tại opencode.ai/docs, trong đó có phần giải thích về agent và cách cấu hình. Ngoài ra có cộng đồng trên Discord và X.com của dự án.
