# 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ở, viết bằng TypeScript, giấy phép MIT. Bạn giao việc bằng ngôn ngữ thường, nó đọc mã, đề xuất và sửa theo yêu cầu. Cài khá dễ vì có nhiều cách (script, npm, brew, app desktop bản beta), nhưng README chưa ghi cách kết nối mô hình AI nên bạn cần xem thêm trang docs.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-05-21 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/opencode-tro-ly-lap-trinh-ai-ma-nguon-mo

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 lời thường, nó đọc mã trong dự án, đề xuất và thực hiện thay đổi. Tác giả tự giới thiệu 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, nghĩa là bạn dùng và xem mã nguồn thoải mái.

Repo này hợp với lập trình viên mới, người làm văn phòng hay chủ shop có một ít code (website, file xử lý dữ liệu, script nhỏ) và muốn có người "phụ việc" đọc hiểu mã giúp. Bạn không cần là chuyên gia, nhưng nên biết mở terminal và gõ vài lệnh cơ bản.

Điểm đáng giá nhất là sự rõ ràng về quyền hạn. opencode có hai chế độ có sẵn: **build** (toàn quyền làm việc) và **plan** (chỉ đọc, phân tích). Bạn có thể cho nó "xem trước, chưa sửa gì" rồi mới cho phép làm thật. Repo hiện 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.

```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 theo yêu cầu của bạn, có sẵn chế độ build và plan, giấy phép MIT.
- stars | 227k
- lang | TypeScript
- license | MIT
```

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

Tư liệu README của repo khá ngắn, nên mình chỉ nói những gì nó thực sự ghi.

### Hai agent có sẵn, đổi bằng phím Tab

opencode có hai agent dựng sẵn và bạn chuyển qua lại bằng phím `Tab`:

- **build**: agent mặc định, được toàn quyền để làm việc phát triển (đọc, sửa file, chạy lệnh).
- **plan**: agent chỉ đọc, dùng để phân tích và khám phá mã. Mặc định nó 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 mở một dự án lạ, bạn dùng plan để hỏi "dự án này làm gì, file nào quan trọng" mà không sợ nó lỡ tay sửa gì. Khi đã hiểu và muốn làm, bạn bấm Tab sang build.

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

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

### Nhiều cách cài, có cả app 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 bản BETA** cho macOS, Windows và Linux, hợp với người không thích dùng terminal.

### Mã nguồn mở, cấu hình qua tài liệu

Mọi tuỳ chỉnh chi tiết nằm ở trang tài liệu của dự án (opencode.ai/docs). Repo cũng có thư mục `sdks/`, `packages/` và `specs/` cho ai muốn tìm hiểu sâu hoặc đóng góp.

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

Theo README, bạn cần:

- **Hệ điều hành**: các lệnh cài đặt ghi cho macOS, Linux (kể cả Arch Linux) và Nix. Bản desktop có file cho macOS (Apple Silicon và Intel), Windows (`opencode-desktop-win-x64.exe`) và Linux (`.deb`, `.rpm`, `.AppImage`). Dòng lệnh `curl ... | bash` là lệnh bash nên hợp macOS/Linux; người dùng Windows có thể chọn app desktop hoặc cách cài qua npm nếu đã có Node.
- **Một công cụ cài đặt** tuỳ cách bạn chọn: `npm` (hoặc bun/pnpm/yarn), `brew`, `pacman`, `mise` hoặc `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.

Về tài khoản, API key, phiên bản Node hay phần cứng: **README chưa ghi**. Vì đây là agent AI, nhiều khả năng bạn sẽ cần kết nối một mô hình AI nào đó, nhưng cách làm cụ thể mình không có trong tư liệu, bạn xem tại opencode.ai/docs.

```note
README không nói về chi phí hay API key. Nếu sau này bạn nối một dịch vụ AI tính phí, hãy kiểm tra gói cước và đặt hạn mức chi tiêu trước. Không dán key vào chỗ công khai hay đẩy lên GitHub.
```

## 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 bạn từng cài
- Chọn cách cài | Script, npm, brew hoặc app desktop tuỳ máy
- Chạy lệnh cài | Dán đúng lệnh trong README vào terminal
- Mở lại terminal | Để máy nhận lệnh mới
- Xem docs để cấu hình | Làm theo trang tài liệu của dự án
```

### 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 đây là lần đầu bạn dùng opencode thì bỏ qua bước này. README không ghi lệnh gỡ cụ thể, bạn gỡ theo đúng cách bạn đã cài (ví dụ cài bằng brew thì gỡ bằng brew).

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

README liệt kê các cách sau. **Chỉ chọn một**, đừ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
```

Giải thích cho người mới:

- Dòng đầu (gọi "YOLO") tải script cài đặt rồi chạy luôn. Nhanh, nhưng bạn đang chạy thẳng một script từ mạng. Nếu muốn chắc ăn, hãy chọn cách qua trình quản lý gói.
- `npm i -g ...` cài toàn cục, cần máy đã có Node và npm. Dấu `-g` nghĩa là dùng được ở mọi thư mục.
- Với macOS/Linux, README ghi dòng `brew install anomalyco/tap/opencode-v2` là cách "recommended, always up to date", còn `brew install opencode` là công thức chính thức nhưng cập nhật chậm hơn.
- Hai dòng `pacman` và `paru` dành cho Arch Linux. `mise` dùng được trên mọi hệ điều hành. `nix run` dành cho người dùng Nix.
- Chữ sau dấu `#` chỉ là ghi chú, không phải lệnh.

Một chỗ bạn cần để ý: tên gói trong README không thống nhất hoàn toàn (có chỗ ghi `@opencode/cli`, có chỗ ghi `opencode`). Bạn cứ chép đúng một dòng lệnh ở trên. Nếu lệnh báo không tìm thấy gói, hãy xem lại bản hướng dẫn mới nhất ở opencode.ai.

### Hoặc dùng app desktop (BETA)

Nếu không thích terminal, tải app ở trang opencode.ai/download. README liệt kê các file:

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

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

Lệnh này cài bản desktop (cask) thay vì bản terminal. Vì là BETA nên có thể còn lỗi vặt.

### Biết nó cài vào đâu

README cho biết script cài đặt đưa opencode vào thư mục `$HOME/.opencode/bin`. Nếu sau khi cài mà terminal báo không nhận lệnh, hãy thử **đóng terminal rồi mở lại**. README không nói gì thêm về việc thêm thư mục này vào PATH, nên nếu vẫn lỗi bạn xem tài liệu của dự án.

### Cấu hình lần đầu

README chỉ dẫn sang trang tài liệu cho phần cấu hình. Bạn mở opencode.ai/docs và làm theo phần thiết lập ban đầu. Mình không đưa lệnh cụ thể ở đây vì không có trong tư liệu.

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

README **chưa ghi** lệnh kiểm tra hay kết quả mong đợi. Cách an toàn để tự kiểm:

- Với app desktop: mở app lên, nếu cửa sổ làm việc hiện ra là cài thành công.
- Với bản terminal: mở một cửa sổ terminal mới, thử gọi tên lệnh theo hướng dẫn trong trang docs. Nếu máy báo "không tìm thấy lệnh", quay lại mục Lỗi hay gặp bên dưới.
- Khi giao diện đã mở, thử bấm `Tab`. Theo README, bạn sẽ chuyển giữa agent **build** và **plan**. Đây là dấu hiệu tốt cho thấy bạn đang dùng đúng opencode.

## 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 mô tả: hai agent, phím Tab và `@general`. Câu lệnh mẫu là gợi ý để bạn gõ bằng lời thường.

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

Bạn vừa được giao một thư mục code của người khác và không biết bắt đầu từ đâu. Hãy mở thư mục đó, để ở chế độ **plan** (chỉ đọc) và hỏi:

```text
Dự án này làm gì? Các file chính nằm ở đâu? Giải thích cho người mới.
```

Vì plan mặc định từ chối sửa file và hỏi trước khi chạy bash, bạn khám phá thoải mái mà không lo hỏng gì. Kết quả: một bản tóm tắt cấu trúc dự án để bạn đọc tiếp có định hướng.

### Chủ shop có website nhỏ, cần sửa một chỗ nhỏ

Bạn có trang bán hàng đơn giản và muốn đổi chữ trên nút hay chỉnh lại một đoạn mô tả. Trước hết ở chế độ plan, bạn nhờ nó chỉ ra file cần sửa và nói sẽ sửa thế nào. Khi thấy hợp lý, bấm `Tab` sang **build** và nhờ nó làm:

```text
Đổi chữ nút "Mua ngay" thành "Đặt hàng" ở trang chủ.
```

Cách làm hai bước này giúp bạn xem kế hoạch trước, rồi mới cho phép thay đổi thật. Kết quả: file được sửa theo đúng yêu cầu, bạn kiểm lại bằng cách mở trang.

> Cho AI xem trước, chưa cho sửa, rồi mới bấm Tab để nó làm thật — thói quen này tiết kiệm rất nhiều rắc rối.
>
> — Ông T

### Nhân viên văn phòng tìm thứ gì đó trong đống file

Bạn có một thư mục nhiều file script và dữ liệu, cần biết "đoạn nào đang tính tổng doanh thu". Việc tìm kiếm nhiều bước kiểu này đúng là thứ subagent **general** sinh ra để làm. Bạn gọi nó trực tiếp:

```text
@general tìm giúp mình đoạn code tính tổng doanh thu và cho biết nằm ở file nào
```

Kết quả: bạn nhận lại danh sách vị trí liên quan, đỡ phải mở từng file.

### Dev lên kế hoạch sửa lỗi trước khi động vào code

Bạn gặp một lỗi trong dự án và muốn có kế hoạch trước. Ở chế độ plan, mô tả lỗi và nhờ nó phân tích nguyên nhân khả dĩ cùng các bước sửa. Đọc kỹ kế hoạch, chỉnh lại nếu chưa ổn, rồi mới chuyển sang build. Kết quả: bạn kiểm soát được phạm vi thay đổi thay vì để agent tự ý sửa nhiều chỗ.

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

Các mục 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. README không liệt kê lỗi cụ thể.

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

Nguyên nhân hay gặp là terminal chưa nhận lệnh mới hoặc thư mục cài chưa nằm trong PATH. Hãy đóng hẳn terminal, mở lại rồi thử. README cho biết script cài vào `$HOME/.opencode/bin`, bạn có thể kiểm tra xem thư mục đó đã tồn tại chưa. Nếu vẫn lỗi, xem trang docs.

### Cài bằng npm thất bại hoặc không thấy gói

Kiểm tra máy đã có Node và npm chưa. Tên gói trong README có chỗ không thống nhất, nên hãy chép chính xác dòng lệnh `npm i -g @opencode/cli@latest` và đối chiếu với trang opencode.ai nếu báo lỗi. Đừng tự đoán tên gói khác.

### Lẫn lộn giữa hai bản cài

README có hai công thức brew (`opencode-v2` và `opencode`), và còn dặn gỡ các bản cũ hơn 0.1.x. Nếu bạn từng cài trước đây và giờ chạy ra phiên bản lạ, hãy gỡ bản cũ rồi chỉ giữ một cách cài.

### Sợ agent sửa nhầm file

Đây không hẳn là lỗi mà là rủi ro tự nhiên của mọi agent AI. Hãy bắt đầu ở chế độ **plan**, và chỉ chuyển sang **build** khi bạn đã hài lòng. Với dự án quan trọng, hãy sao lưu thư mục hoặc dùng quản lý phiên bản như git trước khi cho nó sửa.

### Chưa biết kết nối mô hình AI ở đâu

README không giải thích phần này. Hãy đọc tài liệu tại opencode.ai/docs, và hỏi trong cộng đồng Discord của dự án nếu bị kẹt.

## 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 (khoảng 226.506 sao) và còn được cập nhật.
- Có hai chế độ rõ ràng: build để làm việc và plan để chỉ đọc. Mặc định plan còn hỏi trước khi chạy lệnh, giúp người mới an tâm hơn.
- Nhiều cách cài và có cả app desktop, hợp cả người thích terminal lẫn người không thích.
- README có bản tiếng Việt, tiện cho bạn đọc thêm.

**Giới hạn**

- README rất ngắn: chưa nói rõ yêu cầu hệ thống, cách kết nối mô hình AI, chi phí, hay lệnh kiểm tra. Bạn phải đọc thêm tài liệu trên trang chính thức.
- App desktop vẫn là BETA, có thể chưa ổn định.
- Tên gói trong README chưa hoàn toàn thống nhất, người mới dễ phân vân.
- Tư liệu không nói gì về quyền riêng tư của dữ liệu khi gửi mã đến mô hình AI. Với mã nguồn nhạy cảm, hãy tìm hiểu kỹ trước.

**Khi nào chọn cách khác**: nếu bạn hoàn toàn không đụng đến code và chỉ cần trợ lý hỏi đáp thông thường, một ứng dụng chat AI sẽ đơn giản hơn. Còn nếu bạn có code cần đọc hiểu, sửa nhỏ hoặc lập kế hoạch thay đổi, opencode đáng thử, nhất là khi bạn muốn một công cụ mở và kiểm soát được quyền của agent.

## Câu hỏi thường gặp

### opencode có miễn phí không?

Bản thân repo dùng giấy phép MIT và là mã nguồn mở. Tư liệu chưa nói gì về chi phí khi kết nối với các mô hình AI, nên bạn cần xem trang tài liệu của dự án trước khi dùng thường xuyên.

### opencode có chạy trên Windows không?

README có file cài app desktop cho Windows là opencode-desktop-win-x64.exe (bản BETA). Lệnh curl ... | bash ghi cho môi trường bash nên hợp macOS/Linux hơn. README chưa ghi riêng hướng dẫn terminal cho Windows.

### Cài opencode có khó không?

Không khó: bạn chỉ cần chọn một lệnh trong README (script, npm, brew...) hoặc tải app desktop. Phần cấu hình sau khi cài thì README chuyển sang trang tài liệu chính thức.

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

Build là agent mặc định, toàn quyền cho 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, hợp để khám phá mã lạ hoặc lên kế hoạch. Bạn đổi qua lại bằng phím Tab.

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

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

### Có cần GPU hay máy 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 trang tài liệu của dự án để biết chính xác.

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

Tư liệu không nói về cách dữ liệu được xử lý hay gửi đi. Vì vậy với mã nhạy cảm, bạn nên đọc kỹ tài liệu, chính sách bảo mật của dự án và của dịch vụ AI bạn dùng trước khi cho agent truy cập.
