# opencode: agent lập trình mã nguồn mở chạy ngay 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. Nó giúp bạn đọc, hiểu và sửa code bằng ngôn ngữ tự nhiên, có chế độ chỉ đọc để xem trước khi cho sửa. Cài khá dễ: một dòng lệnh, một trình quản lý gói, hoặc tải bản desktop (beta).

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

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, nó đọc dự án, đề xuất và thực hiện thay đổi trong code. Tác giả mô tả ngắn gọn repo là «The open source coding agent». Dự án viết bằng TypeScript, dùng giấy phép MIT, hiện có khoảng 226.506 sao và 30.658 fork trên GitHub, và vẫn được cập nhật trong 3 tháng gần đây.

Bạn nên xem qua nếu là lập trình viên mới muốn có một trợ lý ngồi cạnh khi đọc code lạ, hoặc người làm kinh doanh, văn phòng có dự án nhỏ (một website, vài script xử lý file) mà muốn nhờ AI hỗ trợ. Bạn không phải đi qua một quy trình cài đặt phức tạp: README đưa ra nhiều đường cài, từ một dòng lệnh đến Homebrew, npm, Arch Linux, mise, Nix, và cả ứng dụng desktop (đang ở bản BETA).

Điểm đáng giá nhất là cách chia vai rõ ràng: một agent làm việc đầy đủ quyền để phát triển, và một agent chỉ đọc để khám phá, lập kế hoạch. Bạn đổi qua lại bằng phím `Tab`. Nhờ vậy bạn có thể xem AI hiểu dự án ra sao trước khi cho nó đụng vào file nào.

```repo
- repo | anomalyco/opencode
- kind | Agent
- desc | OpenCode là agent lập trình AI mã nguồn mở (MIT): có chế độ build để sửa code và chế độ plan chỉ đọc, kèm bản desktop beta.
- stars | 227k
- lang | TypeScript
- license | MIT
```

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

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

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

- **build**: agent mặc định, toàn quyền, dùng cho công việc phát triển thật sự: viết, sửa code.
- **plan**: 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.

Lợi ích thực tế: khi mở một dự án lạ, bạn bắt đầu ở chế độ plan để hỏi «dự án này làm gì, file nào quan trọng». Không lo AI lỡ tay sửa gì. Khi đã rõ hướng, bạn bấm `Tab` sang build để nó làm.

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

Ngoài hai agent trên còn có agent phụ **general**, dùng cho các tìm kiếm phức tạp và tác vụ nhiều bước. Theo README, 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.

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

Bạn dùng terminal thì cài bằng lệnh. Bạn không thích terminal thì tải ứng dụng desktop cho macOS, Windows hoặc Linux (README ghi là BETA).

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

Giấy phép MIT, bạn tự do dùng. Cách cấu hình chi tiết nằm ở trang tài liệu của dự án (opencode.ai/docs), không nằm trong README.

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

README không ghi yêu cầu phiên bản Node, Python hay cấu hình phần cứng. Những gì tư liệu nói rõ chỉ có:

- Nếu từng cài bản rất cũ, hãy gỡ các phiên bản cũ hơn 0.1.x trước khi cài.
- Chọn một đường cài hợp với máy bạn: macOS và Linux có Homebrew; Arch Linux có pacman hoặc paru; mọi hệ điều hành có mise; hoặc dùng npm/bun/pnpm/yarn; hoặc Nix.
- Windows: README chỉ liệt kê file cài cho bản desktop là `opencode-desktop-win-x64.exe`. Các lệnh cài khác README không nói riêng cho Windows.

README cũng chưa nói về tài khoản, API key hay mô hình AI nào cần dùng. Phần này bạn xem ở trang tài liệu opencode.ai/docs trước khi bắt đầu.

```note
README không đề cập chi phí hay key. Vì đây là agent AI, có thể bạn sẽ phải kết nối một dịch vụ mô hình nào đó. Hãy đọc tài liệu chính thức để biết chi tiết, và không dán key vào chỗ công khai hoặc gửi cho người khác.
```

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

```steps
- Chọn cách cài | Quyết định dùng lệnh một dòng, trình quản lý gói hay bản desktop
- Gỡ bản cũ | Nếu có bản cũ hơn 0.1.x thì gỡ trướ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 cho hệ điều hành của bạn từ trang tải về
- Đọc tài liệu cấu hình | Xem opencode.ai/docs để thiết lập tiếp
```

### Bước 1: Chọn cách cài

Người mới và muốn nhanh thì chọn lệnh một dòng hoặc bản desktop. Người đã quen trình quản lý gói thì dùng đúng trình đó cho đỡ rối máy. Mở terminal bằng cách nào tùy hệ điều hành: Terminal trên macOS, hoặc terminal của bản Linux bạn đang dùng.

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

README nhắc: 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.

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

README ghi các lựa chọn sau. Bạn chỉ chạy MỘT dòng phù hợp, không chạy tất cả:

```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 để bạn chọn:

- Dòng `curl ... | bash` (README gọi vui là «YOLO») tải script cài về rồi chạy ngay. Nhanh, nhưng bạn nên biết mình đang chạy một script từ internet.
- `npm i -g @opencode/cli@latest` cài toàn cục qua npm. README ghi bạn có thể thay bằng bun, pnpm hoặc yarn.
- Hai dòng `brew` dành cho macOS và Linux. README đề xuất dòng đầu (`anomalyco/tap/opencode-v2`) vì luôn mới nhất; dòng thứ hai là formula chính thức nhưng cập nhật chậm hơn.
- `pacman` và `paru` dành cho Arch Linux; `paru` lấy 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 ...` chạy thẳng bằng Nix.

Chỗ người mới hay vấp: lệnh bắt đầu bằng `npm`, `brew`, `mise` chỉ chạy được khi máy đã có sẵn công cụ đó. Dòng bắt đầu bằng `#` là chú thích, không cần gõ.

Nếu dùng script cài, README cho biết nó cài OpenCode vào thư mục `$HOME/.opencode/bin`.

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

Tải từ 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` |

Trên macOS bạn cũng có thể cài bằng Homebrew:

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

Vì đây là bản BETA, bạn có thể gặp lỗi vặt. Nếu cần ổn định hơn, cân nhắc bản dòng lệnh.

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

README không hướng dẫn cách khởi động hay thiết lập mô hình AI. Phần này mình chưa thể chép lệnh vì tư liệu chưa ghi. Bạn xem tại opencode.ai/docs, và mục agents tại opencode.ai/docs/agents.

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

README không ghi lệnh kiểm tra phiên bản hay màn hình mong đợi. Mình gợi ý cách kiểm tra an toàn, không bịa lệnh:

- Nếu cài bản desktop: mở ứng dụng lên, thấy giao diện hiện ra là xong bước cài.
- Nếu cài bằng script: kiểm tra thư mục `$HOME/.opencode/bin` đã được tạo và có file bên trong chưa.
- Nếu cài bằng trình quản lý gói: kiểm tra trình đó báo cài thành công, không có lỗi đỏ.
- Khi đã vào được giao diện, thử bấm `Tab` để đổi giữa hai agent build và plan, đúng như README mô tả.

Cách khởi động chính xác, bạn xem ở 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 mô tả: hai chế độ agent, subagent `@general` và việc làm trên code. Câu lệnh mẫu là gợi ý của mình để bạn viết yêu cầu, không phải cú pháp bắt buộc.

### Dev mới tìm hiểu một dự án lạ

Bạn vừa nhận một dự án của công ty, mở ra thấy hàng chục thư mục. Hãy ở chế độ **plan**, agent chỉ đọc, mặc định từ chối sửa file. Bạn hỏi thử:

```text
Dự án này làm gì? Liệt kê các thư mục chính và file nên đọc đầu tiên.
```

Kết quả: bạn có bản tóm tắt cấu trúc để định hướng, trong khi code không bị đụng đến.

> Cho AI đọc trước, sửa sau: ở chế độ plan, nó xem được hết mà không sửa được gì.
>
> — Ông T

### Chủ shop nhờ sửa một script nhỏ

Bạn có một script xuất danh sách đơn hàng, nhờ người quen viết từ lâu. Giờ cần thêm một cột. Bạn lên kế hoạch ở chế độ plan trước, hỏi cần sửa file nào. Khi thấy hợp lý, bấm `Tab` sang **build** và yêu cầu:

```text
Thêm cột ghi chú vào file xuất đơn hàng, giữ nguyên các cột cũ.
```

Kết quả: agent thực hiện thay đổi. Bạn nên xem lại từng thay đổi trước khi dùng cho đơn hàng thật.

### Tìm nhanh nơi code xử lý một tính năng

Trong dự án lớn, bạn cần biết đoạn nào tính phí vận chuyển. README nói subagent **general** dùng cho tìm kiếm phức tạp và việc nhiều bước, gọi được bằng `@general`:

```text
@general tìm giúp mình các chỗ trong code có tính phí vận chuyển và tóm tắt cách tính.
```

Kết quả: một danh sách vị trí cần xem, đỡ mất công tự mở từng file.

### Lên kế hoạch trước khi thay đổi lớn

Bạn muốn đổi cách lưu dữ liệu nhưng sợ hỏng. Ở chế độ plan, bạn nhờ liệt kê những file bị ảnh hưởng và các bước làm. README ghi rõ plan hỏi quyền trước khi chạy lệnh bash, nên bạn kiểm soát được từng bước. Kết quả là một kế hoạch bạn đọc, chỉnh, rồi mới cho build thực hiện.

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

### Lệnh cài báo không tìm thấy npm, brew hay mise

Nghĩa là máy chưa có công cụ đó. Hãy cài công cụ trước, hoặc chuyển sang cách khác trong danh sách: lệnh `curl` một dòng hoặc bản desktop.

### Cài xong nhưng gõ lệnh không nhận

Script cài đặt vào `$HOME/.opencode/bin`. Nếu terminal không nhận lệnh, rất có thể thư mục này chưa nằm trong đường dẫn tìm kiếm của máy. Hãy đóng và mở lại terminal, rồi kiểm tra thư mục đó. README chưa ghi cách chỉnh đường dẫn, xem thêm ở opencode.ai/docs.

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

README dặn gỡ các phiên bản cũ hơn 0.1.x trước khi cài. Nếu cài xong mà chạy lạ, hãy kiểm tra xem còn bản cũ nào trên máy không.

### AI sửa file ngoài ý muốn

Agent build có toàn quyền. Hãy làm việc trên bản sao hoặc dự án có quản lý phiên bản, và xem lại thay đổi trước khi dùng. Khi chưa chắc, quay về chế độ plan bằng `Tab`.

### Bản desktop gặp lỗi

Bản desktop đang ở BETA, nên lỗi là điều có thể xảy ra. Thử tải bản mới nhất từ opencode.ai/download hoặc chuyển sang bản dòng lệnh.

## 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.
- Chia agent rõ ràng: build để làm, plan để đọc. Dễ kiểm soát rủi ro khi thử trên dự án thật.
- Nhiều đường cài, có cả ứng dụng desktop cho người ngại terminal.

**Giới hạn**

- README ngắn, không ghi yêu cầu hệ thống, cách khởi động hay cách kết nối mô hình AI. Bạn phải đọc thêm tài liệu chính thức.
- Bản desktop còn là BETA.
- Cách cài khá nhiều nên người mới dễ rối; hãy chọn một cách và bám theo.
- README không nói gì về chi phí hay chuyện dữ liệu đi đâu, nên hãy kiểm tra kỹ trước khi dùng với code nhạy cảm.

Nếu bạn muốn một agent lập trình AI mã nguồn mở, có chế độ chỉ đọc để an tâm khám phá code, OpenCode đáng thử. Nếu bạn chỉ cần một công cụ không phải đọc tài liệu cấu hình, hoặc cần cam kết rõ ràng về dữ liệu và chi phí ngay từ README, hãy cân nhắc công cụ khác cho đến khi bạn đọc xong tài liệu của dự án.

## 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 được dùng tự do. README không nói gì về chi phí của mô hình AI hay dịch vụ đi kèm, nên phần này chưa có thông tin. Bạn xem thêm ở opencode.ai/docs.

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

README có liệt kê file cài bản desktop cho Windows là opencode-desktop-win-x64.exe, ghi chú là BETA. Các lệnh cài khác README không nói riêng về Windows, bạn nên xem tài liệu chính thức.

### Cần GPU hay máy mạnh không?

README không ghi 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 trong tư liệu.

### OpenCode khác gì giữa hai chế độ build và plan?

Build là agent mặc định, toàn quyền cho 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 đổi giữa hai chế độ bằng phím Tab.

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

Người mới có thể dùng lệnh một dòng curl của README hoặc tải bản desktop (BETA) từ opencode.ai/download. Nếu đã quen Homebrew hay npm thì dùng các lệnh tương ứng README đã liệt kê. Nhớ gỡ bản cũ hơn 0.1.x trước khi cài.

### 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 hay quyền riêng tư. Bạn nên đọc tài liệu và chính sách bảo mật của dự án trước khi dùng với code nhạy cảm. Repo có file SECURITY.md để bạn tham khảo.

### Tôi gọi subagent general bằng cách nào?

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