# 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 (anomalyco/opencode) là một coding agent mã nguồn mở, giấy phép MIT, giúp bạn đọc hiểu, sửa và lập kế hoạch cho mã nguồn bằng AI. Bạn cài bằng một dòng lệnh, bằng trình quản lý gói như npm, brew, hoặc tải bản desktop (đang BETA). Cài không khó, nhưng README không ghi cách đăng nhập hay chọn mô hình AI, nên bạn cần xem thêm 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-28 · 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-mwekdzmc

opencode là một **agent lập trình AI mã nguồn mở**. Nói đơn giản: đây là một trợ lý AI chuyên đọc mã nguồn, trả lời câu hỏi về dự án và giúp bạn viết, sửa code. Tác giả mô tả ngắn gọn là “The open source coding agent”. Repo viết chủ yếu bằng TypeScript, dùng giấy phép MIT, và hiện có khoảng 226.506 sao cùng 30.658 fork trên GitHub.

Ai nên dùng? Lập trình viên muốn có trợ lý AI ngay trong quy trình làm việc là đối tượng rõ nhất. Nhưng người mới học code, hoặc nhân viên văn phòng phải đọc một dự án có sẵn mà không biết bắt đầu từ đâu, cũng dùng được. Bạn không cần viết hết mọi thứ từ đầu, chỉ cần hỏi và đọc câu trả lời.

Điểm đáng giá nhất theo README là **hai chế độ làm việc có sẵn**. Chế độ `build` có toàn quyền để làm việc phát triển. Chế độ `plan` chỉ đọc, mặc định không cho sửa file, nên bạn yên tâm để nó khám phá một dự án lạ. Bạn đổi qua lại giữa hai chế độ bằng phím `Tab`.

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

README giới thiệu khá gọn, nên mình chỉ nói những gì tư liệu có. Phần còn lại bạn tra thêm ở trang tài liệu chính thức của dự án.

### Hai agent có sẵn: build và plan

- **build** là agent mặc định, có đầy đủ quyền cho công việc phát triển. Bạn dùng nó khi đã biết mình muốn làm gì và muốn AI thực hiện luôn.
- **plan** là agent chỉ đọc, dành cho phân tích và khám phá mã nguồn. Mặc định nó từ chối sửa file. Nó cũng hỏi xin phép bạn trước khi chạy lệnh bash. Lợi ích thực tế: bạn có thể để AI đọc dự án và đề xuất hướng làm mà không sợ nó đụng vào file nào.

Bạn chuyển giữa hai agent bằng phím `Tab`. Một thói quen tốt là bắt đầu bằng `plan` để hiểu và lên kế hoạch, rồi mới chuyển sang `build` khi đã yên tâm.

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

Ngoài hai agent trên còn có subagent **general**. Nó dùng cho các lần tìm kiếm phức tạp và công việc nhiều bước. Theo README, opencode tự dùng nó ở bên trong. Bạn cũng có thể chủ động gọi bằng cách gõ `@general` trong tin nhắn.

### Mã nguồn mở, giấy phép MIT

Bạn xem được code, tự kiểm tra nó làm gì, và dùng theo giấy phép MIT. Với người làm kinh doanh, ý nghĩa thực tế là không bị khóa vào một nhà cung cấp công cụ duy nhất. Nhưng chi phí dùng mô hình AI phía sau thì README không nói, mình sẽ nhắc lại ở phần cuối.

### 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. Ai ngại terminal có thể thử bản này trước.

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

Mình chỉ nêu những gì README ghi rõ:

- **Hệ điều hành:** README liệt kê cách cài cho macOS, Linux (kể cả Arch Linux), và bản desktop có file cho Windows. Script cài đặt `curl ... | bash` là lệnh kiểu Linux/macOS.
- **Công cụ cài:** tùy cách bạn chọn. Có thể là npm (hoặc bun, pnpm, yarn), Homebrew, pacman, paru, mise hoặc nix. Bạn chỉ cần một trong số đó.
- **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, phiên bản Node:** README **chưa nói** gì về các mục này. Nếu cần đăng nhập hoặc chọn mô hình AI, bạn xem trang tài liệu tại opencode.ai/docs.

```note
README không nói opencode dùng mô hình AI nào hay tính phí ra sao. Nếu sau này bạn nhập API key, hãy giữ kín như mật khẩu, không dán vào chat công khai, không đưa vào file mà bạn đẩy lên GitHub. Hãy kiểm tra chi phí ở nhà cung cấp mô hình trước khi dùng nhiều.
```

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

```steps
- Chọn cách cài | Script một dòng, trình quản lý gói, hoặc bản desktop
- Gỡ bản cũ | Xóa phiên bản cũ hơn 0.1.x nếu có
- Chạy lệnh cài | Dán đúng lệnh của cách bạn chọn vào terminal
- Hoặc tải bản desktop | Tải file đúng với máy tại opencode.ai/download
- Đọc tài liệu | Xem opencode.ai/docs để cấu hình
```

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

README đưa ra nhiều lựa chọn. Nếu bạn dùng macOS hoặc Linux và muốn nhanh nhất, chọn script. Nếu đã quen npm hoặc Homebrew, dùng luôn công cụ đó. Nếu bạn dùng Windows và không quen terminal, bản desktop ở Bước 4 là lối dễ nhất.

### Bước 2: Gỡ phiên bản cũ

README ghi: gỡ các phiên bản cũ hơn 0.1.x trước khi cài. Cách gỡ phụ thuộc vào việc bạn đã cài bằng gì trước đây. README không hướng dẫn riêng phần này, nên hãy dùng chính công cụ đã cài nó (ví dụ npm hay brew) để gỡ.

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

Mở terminal (Terminal trên macOS/Linux). Rồi chọn **một** dòng dưới đây. Đây là nguyên văn từ 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
```

Đừng chạy hết cả khối. Mỗi dòng là một cách cài độc lập. Vài điểm dễ vấp:

- Dòng đầu (`curl ... | bash`) tải script về và chạy luôn. README gọi đùa là “YOLO”, nghĩa là bạn chạy mà chưa xem script. Nếu muốn an tâm, hãy mở địa chỉ script trong trình duyệt đọc trước.
- Với npm, README ghi `npm i -g @opencode/cli@latest`. Lưu ý tên gói trong lệnh này khác với tên gói `opencode` ghi trong repo. Mình khuyên bạn chép đúng lệnh README, và nếu báo lỗi không tìm thấy gói thì xem lại trang cài đặt tại opencode.ai.
- Với Homebrew, README ghi hai công thức. Bản `anomalyco/tap/opencode-v2` được README đánh dấu là khuyến nghị và luôn mới. Bản `opencode` chính thức thì cập nhật ít hơn.
- Script cài đặt đưa OpenCode vào thư mục `$HOME/.opencode/bin`. Nếu gõ tên lệnh mà máy báo không tìm thấy, hãy kiểm tra thư mục này đã nằm trong biến PATH của bạn chưa. Cách thêm PATH tùy hệ điều hành và README không hướng dẫn.

Nếu bạn dùng Windows: README **chưa ghi** lệnh cài dành riêng cho Windows ở phần terminal. Cách chắc chắn nhất theo README là dùng bản desktop, ở bước kế tiếp.

### Bước 4: Hoặc tải bản ứng dụng desktop (BETA)

Vào opencode.ai/download và tải file đúng với máy:

| 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, nếu dùng Homebrew, bạn có thể cài bản desktop bằng lệnh:

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

Bản desktop đang ở giai đoạn BETA, nghĩa là có thể còn lỗi vặt. Nếu gặp trục trặc, hãy thử cách cài qua terminal.

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

README chỉ gói gọn phần cài đặt và giới thiệu agent. Mọi thứ về cấu hình (đăng nhập, chọn mô hình, tùy chỉnh agent) nằm ở trang tài liệu: opencode.ai/docs, và riêng phần agent ở opencode.ai/docs/agents. Hãy đọc trước khi dùng nghiêm túc.

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

README **không ghi** lệnh kiểm tra hay kết quả mong đợi cụ thể, nên mình không bịa ra một lệnh. Bạn có thể tự đánh giá bằng các dấu hiệu hợp lý sau:

- Lệnh cài chạy xong mà terminal không báo lỗi.
- Nếu cài bằng script, thư mục `$HOME/.opencode/bin` đã được tạo trên máy.
- Nếu cài bản desktop, ứng dụng mở được sau khi cài.
- Khi vào giao diện, bấm `Tab` thấy chuyển giữa hai agent `build` và `plan`. Đây là hành vi README mô tả, nên nếu thấy được thì bạn biết công cụ hoạt động đúng.

Cách khởi động và đăng nhập cụ thể, hãy làm theo trang tài liệu chính thức.

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

Các tình huống dưới đây bám vào những gì README nói: hai agent, subagent general, và bản desktop. Câu lệnh mẫu là cách bạn có thể nhập bằng ngôn ngữ thường vào hộp chat của công cụ, không phải lệnh terminal.

### Nhân viên mới tiếp nhận một dự án lạ

Bối cảnh: bạn vừa vào công ty, được giao một dự án web mà người cũ đã nghỉ. Thư mục có rất nhiều file và bạn không biết file nào làm gì.

Cách làm: mở thư mục dự án rồi để ở chế độ **plan**. README ghi chế độ này mặc định từ chối sửa file và rất hợp để khám phá mã nguồn lạ. Bạn thử hỏi:

```text
Hãy đọc dự án này và giải thích ngắn gọn: nó làm gì, các thư mục chính là gì, file nào là điểm bắt đầu.
```

Kết quả: bạn nhận được bản tóm tắt cấu trúc dự án bằng tiếng Việt dễ đọc, mà không có file nào bị thay đổi. Nếu opencode định chạy lệnh bash, nó sẽ hỏi bạn trước. Bạn chỉ cần đọc kỹ rồi đồng ý hoặc từ chối.

> Cứ để AI đọc trước, sửa sau. Chế độ chỉ đọc cho bạn thời gian hiểu mà không phải lo hỏng gì.
>
> — Ông T

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

Bối cảnh: chủ một cửa hàng online thuê freelancer làm website, nay muốn thêm ô nhập mã giảm giá ở trang thanh toán. Bạn chưa biết việc này lớn hay nhỏ.

Cách làm: ở chế độ **plan**, mô tả việc cần làm và hỏi xem phải đụng tới những đâu:

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

Kết quả: bạn có một danh sách file và các bước dự kiến. Bạn đưa danh sách này cho người làm web để báo giá và ước lượng thời gian sát hơn. Đây là cách dùng AI để hỏi cho đúng, không cần tự viết code.

### Lập trình viên nhờ agent sửa code thật

Bối cảnh: bạn là lập trình viên mới, đã hiểu dự án và muốn AI giúp làm một việc nhỏ, ví dụ đổi tên một hàm ở nhiều nơi.

Cách làm: nhấn `Tab` để chuyển sang agent **build** (agent mặc định, có toàn quyền cho việc phát triển). Rồi nhập yêu cầu cụ thể:

```text
Đổi tên hàm tinhTongTien thành tinhTongDonHang ở mọi nơi nó được dùng.
```

Kết quả: agent thực hiện thay đổi trực tiếp trong dự án. Vì build có toàn quyền, hãy dùng Git (hoặc ít nhất sao lưu thư mục) trước khi giao việc, để xem lại và hoàn tác nếu cần.

### Tìm kiếm nhiều bước bằng @general

Bối cảnh: dự án có hàng trăm file và bạn muốn biết mọi chỗ xử lý lỗi thanh toán, dù chúng nằm rải rác.

Cách làm: README nói subagent `general` dành cho tìm kiếm phức tạp và việc nhiều bước, và bạn gọi nó bằng `@general` trong tin nhắn:

```text
@general tìm giúp mình tất cả các chỗ trong dự án có xử lý lỗi khi thanh toán thất bại, và liệt kê theo file.
```

Kết quả: một danh sách các vị trí liên quan, giúp bạn không phải tự mở từng file. Mức độ chính xác phụ thuộc vào mô hình AI bạn dùng, nên hãy mở file ra kiểm tra trước khi tin hoàn toàn.

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

README không có mục xử lý sự cố. Dưới đây là các tình huống rất dễ xảy ra với loại công cụ này, kèm cách xử lý an toàn.

### Gõ lệnh mà terminal báo không tìm thấy

Thường là do thư mục cài chưa nằm trong PATH. Script cài vào `$HOME/.opencode/bin`, nên hãy kiểm tra thư mục đó có trong PATH không. Sau khi sửa, đóng terminal rồi mở lại. Nếu vẫn lỗi, thử cài bằng cách khác như Homebrew hoặc npm.

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

README ghi `npm i -g @opencode/cli@latest`, còn repo khai báo tên gói là `opencode`. Hai tên này khác nhau và bạn có thể gặp lỗi. Cách an toàn: xem lại hướng dẫn mới nhất tại opencode.ai, hoặc chuyển sang cách cài khác trong danh sách như Homebrew.

### Cài chồng lên bản cũ gây xung đột

README khuyên gỡ phiên bản cũ hơn 0.1.x trước khi cài. Nếu bạn thấy công cụ chạy lạ sau khi cài, hãy gỡ bản cũ bằng đúng công cụ đã cài nó, rồi cài lại từ đầu.

### Agent sửa nhầm file

Chế độ `build` có toàn quyền nên có thể sửa những chỗ bạn không muốn. Hãy dùng Git để xem phần thay đổi và hoàn tác. Với dự án quan trọng, bắt đầu bằng `plan` để xem kế hoạch rồi mới chuyển sang `build`.

### Không đăng nhập hay không chọn được mô hình AI

Phần này README chưa nói. Đừng đoán biến môi trường hay lệnh. Hãy đọc trang cấu hình tại opencode.ai/docs, hoặc hỏi ở cộng đồng Discord của dự án.

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

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

- Mã nguồn mở, giấy phép MIT, repo được cập nhật trong vài tháng gần đây.
- Có sẵn chế độ `plan` chỉ đọc rất phù hợp cho người mới và khi xử lý dự án lạ.
- Nhiều cách cài, kể cả bản desktop cho Windows, macOS và Linux.
- Cộng đồng lớn (hiện có khoảng 226.506 sao), nên dễ tìm người hỏi.

**Giới hạn:**

- README ngắn, thiếu hướng dẫn đăng nhập, chọn mô hình và chi phí. Bạn phải đọc thêm trang tài liệu.
- Bản desktop còn BETA.
- Chưa có hướng dẫn riêng cho terminal trên Windows trong README, và tên gói npm trong README khác với tên khai báo trong repo.
- Với chế độ `build`, bạn vẫn phải tự kiểm tra kết quả. AI có thể sai.

**Khi nên chọn cách khác:** nếu bạn không đụng tới code và chỉ cần AI viết văn bản hay làm bảng tính, một công cụ chat thông thường sẽ đơn giản hơn. Nếu công ty có quy định nghiêm về dữ liệu, hãy tìm hiểu kỹ trước khi cho bất kỳ agent nào đọc mã nguồn nội bộ.

Tóm lại: nếu bạn muốn một trợ lý lập trình mã nguồn mở, bắt đầu nhẹ nhàng bằng chế độ `plan`, 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. README không nói gì về chi phí của mô hình AI mà nó kết nối tới. Bạn nên xem trang tài liệu tại opencode.ai/docs để biết rõ.

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

README có liệt kê bản desktop cho Windows (file opencode-desktop-win-x64.exe, đang BETA). README chưa ghi lệnh cài riêng cho terminal Windows, nên cách chắc chắn nhất là dùng bản desktop.

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

README không nêu yêu cầu phần cứng nào. Chưa có thông tin về việc có cần GPU hay không.

### Khác gì giữa agent build và plan?

build là agent mặc định, có toàn quyền cho công việc phát triển. plan là agent 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 giữa hai agent bằng phím Tab.

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

general là subagent dành cho các tìm kiếm phức tạp và công việc nhiều bước. opencode dùng nó ở bên trong, và bạn cũng có thể gọi trực tiếp bằng cách gõ @general trong tin nhắn.

### Cài bằng cách nào là dễ nhất?

Trên macOS hoặc Linux, một dòng curl là nhanh nhất, còn Homebrew được README khuyến nghị vì luôn mới. Ai không quen terminal có thể tải bản desktop tại opencode.ai/download. Mỗi cách cài là độc lập, bạn chỉ cần chọn một.

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

README chưa có thông tin về việc dữ liệu được xử lý hay gửi đi đâu. Hãy đọc tài liệu chính thức và tệp SECURITY.md trong repo trước khi dùng với mã nguồn nhạy cảm.
