# 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 bằng ngôn ngữ tự nhiên. Có hai chế độ chính là build (toàn quyền) và plan (chỉ đọc), đổi qua lại bằng phím Tab. Cài khá dễ: một dòng curl hoặc qua npm, Homebrew, pacman, mise, Nix; ngoài ra có bản desktop (BETA).

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

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 dự án, đề xuất và sửa code giúp bạn. Tác giả giới thiệu ngắn gọn là "the open source coding agent". Repo viết 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 mới muốn có "người trợ giúp" ngay trong dự án. Dân kinh doanh, văn phòng có thuê dev hoặc tự mày mò làm công cụ nhỏ cũng có thể thử, miễn là không ngại mở terminal. Nếu bạn từng nhìn một dự án lạ mà không biết bắt đầu từ đâu, đây là loại công cụ sinh ra để giúp việc đó.

Điểm đáng giá nhất theo README: có hai chế độ rõ ràng. Chế độ **build** toàn quyền để làm việc, còn chế độ **plan** chỉ đọc, mặc định không cho sửa file, nên bạn khám phá dự án mà không sợ lỡ tay làm hỏng. Bài này hướng dẫn cài và dùng dựa trên đúng những gì README ghi.

```repo
- repo | anomalyco/opencode
- kind | Agent
- desc | opencode là agent lập trình AI mã nguồn mở, có chế độ build để sửa code và chế độ plan chỉ đọc để khám phá dự án, cài bằng một dòng lệnh.
- stars | 227k
- lang | TypeScript
- license | MIT
```

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

Theo README, opencode xoay quanh mấy ý sau.

- **Agent build (mặc định).** Đây là agent toàn quyền cho công việc phát triển. Bạn giao việc, nó có thể thao tác trực tiếp trên dự án. Hợp khi bạn đã biết mình muốn gì.
- **Agent plan (chỉ đọc).** Mặc định từ chối việc sửa file, và hỏi bạn trước khi chạy lệnh bash. README ghi nó "lý tưởng" để khám phá codebase lạ hoặc lên kế hoạch thay đổi. Lợi ích thực tế: bạn hiểu dự án trước, sửa sau.
- **Đổi agent bằng phím Tab.** Không cần cấu hình gì, bấm Tab để chuyển giữa build và plan.
- **Subagent general.** Dùng cho việc tìm kiếm phức tạp và nhiều bước. Hệ thống dùng nó nội bộ, và 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.** Từ script một dòng, npm, Homebrew, Arch Linux, mise đến Nix. Bạn chọn cách quen tay nhất.
- **Có bản desktop (BETA).** Nếu không thích terminal, bạn tải ứng dụng cho macOS, Windows hoặc Linux.
- **Mã nguồn mở, giấy phép MIT.** Bạn xem được code, tự kiểm tra nó làm gì.

Repo còn có tài liệu cấu hình riêng trên trang dự án, và README được dịch ra nhiều thứ tiếng, trong đó có tiếng Việt (file README.vi.md).

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

README khá ngắn, nên phần "yêu cầu" cũng ít. Những gì tư liệu nói rõ:

- **Hệ điều hành:** bản desktop có cho macOS (Apple Silicon và Intel), Windows (x64) và Linux (`.deb`, `.rpm`, `.AppImage`). Các cách cài bằng Homebrew ghi là cho macOS và Linux; mise ghi là dùng được trên mọi hệ điều hành.
- **Nếu cài bằng npm:** bạn cần có npm (README cũng nhắc bun, pnpm, yarn đều dùng được).
- **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 nói** gì về các mục này. Vì đây là agent AI, rất có thể bạn sẽ cần cấu hình một nguồn mô hình AI nào đó, nhưng cách làm cụ thể bạn cần xem ở tài liệu trên trang opencode.ai/docs, đừng đoán.

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

```steps
- Mở terminal | Dùng terminal của máy (PowerShell, Terminal hoặc shell Linux)
- Chọn cách cài | Script một dòng, npm, hoặc trình quản lý gói bạn quen
- Chạy lệnh cài | Dán đúng lệnh trong README
- Hoặc tải bản desktop | Tải file cài đặt theo hệ điều hành
- Mở thử | Chạy opencode và xem tài liệu để cấu hình
```

### Mở terminal đúng chỗ

Terminal là cửa sổ gõ lệnh. Trên macOS và Linux bạn mở ứng dụng Terminal. Trên Windows bạn mở PowerShell hoặc Windows Terminal. Lệnh cài đặt dưới đây chạy ở đâu cũng được, không cần vào thư mục dự án. Chỉ khi bắt đầu dùng, bạn mới nên đứng trong thư mục dự án cần làm việc.

Nếu máy bạn từng cài opencode bản rất cũ (trước 0.1.x), README dặn gỡ đi trước.

### Cách nhanh nhất: script cài một dòng

README ghi chú đùa là "YOLO" cho cách này, nghĩa là tải script về và chạy luôn mà không xem trước:

```bash
curl -fsSL https://opencode.ai/v2/install | bash
```

Lệnh dùng `curl` tải script từ trang chủ rồi đưa thẳng cho `bash` chạy. Vì chạy ngay không xem, bạn nên chắc là đang gõ đúng địa chỉ opencode.ai. Theo README, script cài opencode vào thư mục `$HOME/.opencode/bin`. Lệnh này cần môi trường bash, nên người dùng Windows thuần PowerShell nên chọn cách npm hoặc bản desktop bên dưới.

### Cài bằng trình quản lý gói

Bạn chỉ cần chọn **một** dòng hợp với máy mình. README liệt kê:

```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 ngắn:

- `npm i -g @opencode/cli@latest` cài toàn cục bằng npm (đổi `npm` thành bun, pnpm hoặc yarn nếu bạn dùng các công cụ đó).
- `brew install anomalyco/tap/opencode-v2` là cách README **khuyên dùng** cho macOS và Linux vì luôn mới nhất. Dòng `brew install opencode` là công thức chính thức của Homebrew nhưng cập nhật chậm hơn.
- Hai dòng pacman và paru dành cho Arch Linux: bản ổn định và bản mới nhất từ AUR.
- `mise use -g opencode` dùng được trên mọi hệ điều hành nếu bạn đã có mise.
- `nix run github:anomalyco/opencode` chạy bằng Nix.

Chỗ người mới hay vấp: đừng dán cả khối vào terminal cùng lúc. Các dòng là lựa chọn thay thế nhau, không phải chuỗi lệnh phải chạy hết.

### Hoặc dùng bản desktop (BETA)

Nếu ngại dòng lệnh, tải bản ứng dụng từ trang opencode.ai/download. README liệt kê tên file theo nền tảng:

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

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

Bản desktop đang ở mức BETA, nên có thể còn lỗi vặt.

### Bước cuối: mở và cấu hình

README **chưa ghi** lệnh khởi động cụ thể, cũng chưa ghi cách kết nối nguồn mô hình AI. Cái tên gói và thư mục cài (`.opencode/bin`) cho thấy lệnh thường là `opencode`, nhưng bạn nên xác nhận trong tài liệu chính thức tại opencode.ai/docs. Thư mục `packages/` và `specs/` trong repo cũng chứa thêm thông tin nếu bạn thích tự đọc.

```note
Agent AI có thể chạy lệnh và sửa file trên máy bạn. Lần đầu hãy thử trong một thư mục dự án nhỏ hoặc bản sao lưu, và bắt đầu bằng chế độ plan. Chi phí và cách dùng key của nguồn mô hình AI phụ thuộc vào nhà cung cấp bạn chọn; README chưa nói về việc này.
```

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

README không mô tả màn hình kết quả mong đợi, nên mình chỉ nêu cách kiểm tra chung, chắc chắn đúng:

- **Với bản desktop:** mở ứng dụng lên và thấy giao diện hiện ra là cài xong.
- **Với bản dòng lệnh:** mở một cửa sổ terminal **mới** (để máy nhận đường dẫn mới), rồi thử gõ tên lệnh. Nếu terminal báo không tìm thấy lệnh, hãy xem phần lỗi bên dưới.
- **Thử tính năng đặc trưng:** khi đã vào giao diện, bấm phím `Tab`. README nói phím này chuyển giữa agent build và plan. Nếu bạn thấy chế độ đổi qua lại thì nó đang hoạt động đúng.

Còn câu hỏi mô hình AI nào đang được dùng và đã kết nối chưa, bạn cần đối chiếu với tài liệu trên opencode.ai/docs.

## 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: chế độ plan, chế độ build và `@general`. Câu lệnh mẫu chỉ là gợi ý cách bạn viết yêu cầu, không phải cú pháp bắt buộc.

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

Bạn vừa vào công ty, được giao một dự án mà chưa ai kịp hướng dẫn. Hãy vào thư mục dự án, mở opencode ở chế độ **plan** (chỉ đọc), rồi hỏi:

```
Dự án này làm gì? Thư mục nào quan trọng nhất? Nếu mình muốn thêm trang đăng nhập thì nên bắt đầu từ file nào?
```

Vì plan mặc định không sửa file và hỏi trước khi chạy lệnh bash, bạn đọc 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 và gợi ý chỗ bắt đầu, tiết kiệm cả buổi tự mò.

> Cứ để AI đọc và vạch kế hoạch trước, khi nào hiểu rồi mới cho nó động vào file.
>
> — Ông T

### Chủ shop nhờ làm thêm một chức năng nhỏ

Giả sử bạn có một trang web bán hàng nhỏ và muốn đổi dòng thông báo khuyến mãi ở đầu trang. Bạn dùng plan để hỏi "dòng thông báo này nằm ở file nào, sửa thế nào là an toàn". Khi đã rõ, bấm Tab sang **build** và ra lệnh:

```
Đổi dòng thông báo đầu trang thành: Miễn phí vận chuyển cho đơn từ 500.000đ. Chỉ sửa đúng chỗ đó.
```

Câu "chỉ sửa đúng chỗ đó" giúp giới hạn phạm vi. Kết quả là file được sửa, bạn mở trang lên xem lại. Với thay đổi quan trọng, bạn nên nhờ người biết code xem qua.

### Tìm thứ gì đó trong dự án lớn

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

```
@general Tìm tất cả chỗ trong dự án có tính phí vận chuyển và liệt kê tên file giúp mình.
```

Kết quả mong đợi: một danh sách chỗ liên quan để bạn đi tiếp. Đây là cách nhanh hơn nhiều so với tự tìm từng thư mục.

### Nhân viên văn phòng cần hiểu tệp công cụ nội bộ

Công ty có một thư mục script do người khác để lại, bạn cần biết nó làm gì trước khi dùng. Mở opencode trong thư mục đó ở chế độ plan và hỏi:

```
Giải thích bằng tiếng Việt đơn giản từng script trong thư mục này làm gì, script nào có thể xoá hoặc ghi đè dữ liệu.
```

Bạn nhận được phần giải thích dễ hiểu, và quan trọng hơn là cảnh báo về script nguy hiểm trước khi bạn lỡ chạy. Bạn vẫn nên kiểm chứng lại các nhận định quan trọng, vì AI có thể hiểu sai.

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

README không có mục xử lý sự cố, nên các lỗi dưới đây là những tình huống rất dễ gặp với loại công cụ này. Cách khắc phục đều theo hướng an toàn.

**1. Gõ lệnh báo "không tìm thấy lệnh" sau khi cài.**
Terminal đang mở chưa nhận đường dẫn mới. Hãy đóng và mở lại cửa sổ terminal. Nếu cài bằng script, README nói file nằm ở `$HOME/.opencode/bin`, bạn có thể kiểm tra thư mục này có tồn tại không và đường dẫn đã nằm trong PATH chưa.

**2. Lệnh curl không chạy trên Windows.**
Lệnh một dòng dùng `bash`, vốn không có sẵn trong PowerShell thuần. Hãy chọn cách `npm i -g @opencode/cli@latest` hoặc tải file `opencode-desktop-win-x64.exe`.

**3. Cài xong nhưng vẫn ra phiên bản cũ hoặc xung đột.**
README dặn gỡ các bản cũ hơn 0.1.x trước khi cài. Nếu từng cài bằng cách khác (ví dụ vừa brew vừa npm), hãy gỡ bản cũ rồi cài lại bằng đúng một cách.

**4. Công cụ không phản hồi hoặc báo thiếu cấu hình mô hình AI.**
README chưa nói rõ phần này. Hãy đọc trang tài liệu trên opencode.ai/docs để làm theo đúng cách kết nối. Không dán key vào chỗ công khai như tin nhắn nhóm chat hay file bạn sẽ đẩy lên GitHub.

**5. AI sửa file không như ý.**
Quay lại các thao tác an toàn: làm việc trong thư mục có sao lưu hoặc có quản lý phiên bản, bắt đầu bằng chế độ plan, và chỉ chuyển sang build khi yêu cầu đã rõ và giới hạn phạm vi. Chỗ nào AI xin phép chạy lệnh, hãy đọc kỹ rồi hẵng đồng ý.

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

**Điểm mạnh.** Mã nguồn mở với giấy phép MIT, được cập nhật trong vài tháng gần đây, cộng đồng lớn (hiện có khoảng 226 nghìn sao). Cặp agent build và plan rất dễ hiểu và là cách làm an toàn: đọc trước, sửa sau. Nhiều cách cài, có cả bản desktop cho người ngại terminal.

**Giới hạn.** README rất ngắn, phần cấu hình và kết nối mô hình AI phải đọc ở tài liệu riêng. Bản desktop vẫn là BETA. Công cụ này làm việc trên code, nên nếu bạn chỉ cần soạn văn bản hay xử lý bảng tính thông thường thì chưa chắc phù hợp. Và như mọi agent AI, kết quả cần được người kiểm tra lại.

**Khi nào chọn cách khác.** Nếu bạn không đụng đến code và muốn một ứng dụng chat đơn giản, hãy dùng công cụ chat thông thường. Nếu bạn cần một sản phẩm có hỗ trợ chính thức, cam kết dịch vụ, hãy so sánh kỹ các lựa chọn thương mại. README không nêu so sánh trực tiếp với công cụ nào, nên mình không kết luận hơn kém.

Tóm lại: nếu bạn muốn thử một trợ lý lập trình AI mã nguồn mở, cài nhẹ và có cơ chế chỉ đọc để yên tâm, opencode đáng để bạn dành một buổi chiều thử 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 opencode là mã nguồn mở với 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 nguồn mô hình AI mà công cụ sử dụng, vì vậy phần đó chưa có thông tin; bạn xem tài liệu trên opencode.ai/docs.

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

Có bản desktop cho Windows (file opencode-desktop-win-x64.exe, đang BETA). Với dòng lệnh, bạn có thể dùng cách cài bằng npm. Lệnh curl một dòng dùng bash nên không hợp với PowerShell thuần.

### 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ề GPU hay cấu hình tối thiểu, bạn xem tài liệu chính thức nếu cần chắc chắn.

### Khác nhau giữa chế độ build và plan là gì?

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

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

Với macOS và Linux, README khuyên dùng brew install anomalyco/tap/opencode-v2 vì luôn mới nhất. Cách nhanh nhất là chạy script curl một dòng. Nếu ngại terminal, hãy tải bản desktop từ opencode.ai/download.

### @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. Hệ thống dùng nó nội bộ, và bạn cũng có thể gọi trực tiếp bằng cách gõ @general trong tin nhắn.

### 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. Repo có file SECURITY.md và code mở để bạn tự kiểm tra, nhưng cách dữ liệu được gửi đi còn phụ thuộc nguồn mô hình AI bạn chọn, phần này chưa có thông tin trong tư liệu. Hãy thử trước trên dự án không nhạy cảm.
