# 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 coding agent (trợ lý AI lập trình) mã nguồn mở, giấy phép MIT, viết bằng TypeScript. Nó giúp bạn khám phá, lên kế hoạch và sửa code bằng ngôn ngữ thường. Cài khá dễ: một dòng lệnh, hoặc qua npm/brew, hoặc tải app desktop bản beta.

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

opencode là một "coding agent" mã nguồn mở: một trợ lý AI đọc code trong dự án của bạn, trả lời câu hỏi, đề xuất và thực hiện thay đổi theo yêu cầu bằng ngôn ngữ thường. Repo do nhóm anomalyco phát triển, viết chủ yếu bằng TypeScript, giấy phép MIT, hiện có khoảng 226.506 sao và 30.658 fork trên GitHub.

Bạn nên đọc bài này nếu là lập trình viên mới, người làm văn phòng hay chủ shop đang tự dựng website, file tự động hoá, và muốn có "người phụ" biết đọc cả thư mục code thay vì phải dán từng đoạn vào khung chat. Dự án còn được cập nhật trong 3 tháng gần đây, nên không phải repo bỏ hoang.

Điểm đáng giá nhất là hai chế độ làm việc có thể đổi nhanh bằng phím Tab. Chế độ **build** được toàn quyền để làm việc thật. Chế độ **plan** chỉ đọc, mặc định từ chối sửa file, rất hợp để khám phá code lạ mà không sợ hỏng gì. Ngoài ra, opencode còn có bản app desktop (đang BETA) cho người không thích terminal.

```repo
- repo | anomalyco/opencode
- kind | Agent
- desc | opencode là coding agent 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ỉ xem.
- 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ì có trong đó.

- **Hai agent có sẵn, đổi bằng phím Tab.** `build` là agent mặc định, toàn quyền cho công việc phát triển. `plan` là agent chỉ đọc, dùng để phân tích và khám phá code. Lợi ích thực tế: bạn có một "chế độ an toàn" để hỏi han trước, rồi mới chuyển sang chế độ được làm.
- **Plan hỏi trước khi chạy lệnh.** Ở chế độ plan, các thay đổi file bị từ chối mặc định và nó hỏi xin phép trước khi chạy lệnh bash. Người mới vì vậy đỡ lo bị sửa nhầm hay chạy nhầm.
- **Subagent `general`.** Đây là trợ lý phụ dành cho tìm kiếm phức tạp và việc nhiều bước. Nó được dùng nội bộ, và bạn cũng có thể gọi trực tiếp bằng `@general` trong tin nhắn.
- **Nhiều cách cài.** Có script một dòng, npm, Homebrew, Arch Linux (pacman và AUR), mise, Nix. Bạn chọn cách quen tay nhất.
- **Có app desktop (BETA).** Có bản cho macOS (Apple Silicon và Intel), Windows và Linux (.deb, .rpm, .AppImage).
- **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 thoải mái theo giấy phép.

Những thứ như đổi model, cấu hình chi tiết thì README không nêu, mà trỏ sang tài liệu chính thức ở trang chủ opencode.ai (mục docs).

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

README không liệt kê yêu cầu hệ thống chi tiết. Đây là những gì tư liệu cho biết:

- **Hệ điều hành:** có tuỳ chọn cho macOS, Linux và Windows (qua app desktop). Cách cài bằng Homebrew ghi rõ cho macOS và Linux. mise ghi là dùng được trên mọi hệ điều hành.
- **Công cụ cài đặt:** tuỳ cách bạn chọn. Dùng npm thì cần có Node/npm (README ghi thêm "hoặc bun/pnpm/yarn"). Dùng Homebrew thì cần có brew. Dùng script thì cần có `curl` và `bash`.
- **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 ghi** gì về việc này. Một coding agent thường cần kết nối tới một model AI nào đó, nhưng cách kết nối cụ thể bạn hãy xem trong tài liệu ở trang opencode.ai/docs.

```note
Khi dán API key hay đăng nhập dịch vụ AI nào, hãy làm theo hướng dẫn trong tài liệu chính thức. Đừng gửi key qua chat hay chụp màn hình công khai. Dịch vụ AI bên ngoài có thể tính phí theo lượng dùng, nên hãy kiểm tra bảng giá trước khi cho agent làm việc dài.
```

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

```steps
- Chọn cách cài | Script một dòng, npm, brew hoặc cách khác phù hợp máy bạn
- Chạy lệnh cài | Mở terminal và dán đúng một lệnh trong README
- Kiểm tra thư mục cài | Script cài vào $HOME/.opencode/bin
- Hoặc tải app desktop | Dành cho người không thích terminal (BETA)
- Đọc tài liệu cấu hình | Xem opencode.ai/docs để kết nối model
```

### Chọn cách cài phù hợp

README đưa ra khá nhiều lựa chọn. Bạn chỉ cần chọn **một** cách, đừng chạy tất cả. Gợi ý nhanh cho người mới:

- Đã có Node/npm: dùng dòng npm.
- Dùng macOS hoặc Linux và có Homebrew: dùng brew.
- Muốn nhanh nhất: dùng script một dòng (README gọi vui là "YOLO", nghĩa là chạy thẳng script từ mạng, bạn nên cân nhắc).
- Không thích dòng lệnh: tải app desktop (xem bước sau).

Nếu máy bạn từng cài opencode bản cũ hơn 0.1.x, hãy gỡ nó trước.

### Chạy lệnh cài

Mở terminal (macOS/Linux: ứng dụng Terminal; Windows: PowerShell hoặc Windows Terminal). Rồi dán một trong các lệnh dưới đây, đúng như README ghi:

```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 ngắn từng dòng:

- Dòng `curl ... | bash` tải script cài đặt rồi chạy luôn. Nó tiện, nhưng vì chạy thẳng script từ mạng, bạn chỉ nên dùng khi tin nguồn.
- Dòng `npm i -g @opencode/cli@latest` cài toàn cục qua npm. Phần `# or bun/pnpm/yarn` là ghi chú: bạn có thể dùng trình quản lý gói khác thay npm.
- Hai dòng `brew` đều dành cho macOS và Linux. README ghi dòng đầu (`anomalyco/tap/opencode-v2`) là bản khuyến nghị, luôn mới. Dòng thứ hai là bản chính thức của Homebrew, cập nhật chậm hơn.
- `pacman` và `paru` dành cho Arch Linux. `mise` dùng được trên mọi hệ điều hành. `nix run` chạy thẳng từ GitHub bằng Nix.

Chỗ dễ vấp: dấu `#` và phần chữ phía sau chỉ là ghi chú. Khi dán lệnh, bạn có thể bỏ phần ghi chú đi cho gọn.

Một điểm mình thấy README chưa thật nhất quán: tên gói npm của repo là `opencode`, trong khi lệnh npm trong README lại dùng `@opencode/cli`. Nếu một lệnh báo lỗi, bạn hãy xem lại README và trang opencode.ai để chắc chắn lệnh nào đang đúng.

### Biết nó được cài ở đâu

Nếu cài bằng script, README cho biết opencode được đặt tại thư mục sau:

```bash
$HOME/.opencode/bin
```

Đây là thư mục tên `.opencode/bin` nằm trong thư mục cá nhân của bạn (thư mục bắt đầu bằng dấu chấm thường bị ẩn). Nếu sau khi cài mà terminal không nhận lệnh, hãy kiểm tra xem thư mục này có nằm trong PATH không. README chưa hướng dẫn việc này.

### Hoặc tải app desktop (BETA)

Từ trang opencode.ai/download, bạn tải file theo hệ điều hành:

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

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

Lưu ý đây là bản BETA, nên có thể còn lỗi vặt.

### Đọc tài liệu để cấu hình

README chỉ nói chung: muốn biết cấu hình opencode thế nào, hãy xem tài liệu tại opencode.ai/docs. Phần agent có trang riêng tại opencode.ai/docs/agents. Việc kết nối model AI, README **chưa ghi** chi tiết, nên bạn đọc ở đó.

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

README không có mục "kiểm tra sau khi cài" hay lệnh mẫu để thử. Vì vậy mình chỉ gợi ý những cách an toàn:

1. Mở một cửa sổ terminal **mới** (để PATH được nạp lại) và thử gọi lệnh `opencode`. Tên gói npm là `opencode`, nhiều khả năng đây cũng là tên lệnh, nhưng README không ghi rõ nên bạn đối chiếu với tài liệu ở trang chủ.
2. Nếu cài bằng script, kiểm tra xem thư mục `$HOME/.opencode/bin` đã được tạo chưa.
3. Nếu dùng app desktop, mở app lên và xem có vào được giao diện không.
4. Nếu chạy được, thử bấm `Tab` để đổi giữa hai agent `build` và `plan`. Đó là dấu hiệu rõ nhất theo README.

## 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 build/plan, subagent general, và việc chạy trong dự án của bạn. Câu mẫu là gợi ý của mình, bạn tự điều chỉnh cho dự án của mình.

### Hiểu một dự án lạ trước khi đụng vào

Bạn là lập trình viên mới vào công ty, được giao một thư mục code mà không ai giải thích. Hãy mở terminal ngay trong thư mục đó, chạy opencode và chuyển sang agent **plan** (phím Tab). Rồi hỏi bằng tiếng thường, ví dụ:

```
Dự án này làm gì? Các thư mục chính có vai trò gì? Muốn thêm trang đăng nhập thì nên sửa ở đâu?
```

Vì plan là chế độ chỉ đọc, mặc định từ chối sửa file và hỏi trước khi chạy lệnh bash, bạn yên tâm khám phá. Kết quả là một bản tóm tắt cấu trúc dự án và gợi ý nơi cần sửa, trước khi bạn viết dòng code nào.

> Hỏi trước bằng chế độ chỉ đọc, đồng ý rồi mới cho phép sửa. Đó là cách dùng AI không phải hối hận.
>
> — Ông T

### Lên kế hoạch thay đổi rồi mới làm

Bạn là chủ shop nhỏ, có website bán hàng do người khác dựng, giờ muốn đổi cách hiển thị giá. Ở chế độ **plan**, bạn mô tả:

```
Mình muốn hiển thị giá theo định dạng 1.000.000đ thay vì 1000000. Hãy chỉ ra những file cần sửa và đề xuất cách làm, chưa sửa gì.
```

Bạn đọc kế hoạch, thấy ổn thì bấm Tab sang **build** và nói: "Làm theo kế hoạch trên". Kết quả là thay đổi được thực hiện theo từng bước bạn đã duyệt, thay vì để AI tự quyết hết.

### Nhờ trợ lý phụ tìm kiếm việc nhiều bước

Dự án lớn, bạn cần tìm mọi chỗ dùng một chức năng cũ để thay thế. README cho biết subagent **general** phục vụ tìm kiếm phức tạp và công việc nhiều bước, và bạn gọi được bằng `@general` trong tin nhắn:

```
@general Tìm tất cả những chỗ đang gọi hàm tính phí vận chuyển và liệt kê theo file.
```

Bạn nhận về danh sách các vị trí liên quan, rồi dùng chính danh sách đó để sửa từng chỗ ở chế độ build.

### Làm việc không cần gõ lệnh với app desktop

Nếu bạn làm văn phòng, ngại terminal, hãy thử app desktop (BETA) tải từ trang opencode.ai/download. Bạn dùng cùng ý tưởng: hỏi để hiểu, rồi nhờ sửa. README không mô tả giao diện app chi tiết, nên bạn cứ mở lên và làm quen, đồng thời xem tài liệu nếu bí.

## 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ụ cài qua dòng lệnh. Cách xử lý đều theo hướng an toàn.

**1. Gõ lệnh báo "không tìm thấy lệnh" (command not found).**
Thường do terminal chưa nạp lại PATH, hoặc thư mục cài chưa nằm trong PATH. Hãy đóng terminal rồi mở cửa sổ mới. Nếu cài bằng script, kiểm tra thư mục `$HOME/.opencode/bin` có tồn tại không. Chưa rõ thì xem tài liệu ở trang chủ.

**2. Lệnh npm báo lỗi hoặc không tìm thấy gói.**
Tên gói trong README có chỗ chưa thống nhất (gói npm ghi là `opencode`, lệnh lại dùng `@opencode/cli`). Hãy kiểm tra Node/npm đã cài chưa, đọc kỹ thông báo lỗi, và thử một cách cài khác như brew hoặc script. Đừng dùng `sudo` cho npm chỉ để "cho qua" lỗi nếu bạn chưa hiểu nó.

**3. Nhầm lẫn giữa nhiều phiên bản.**
README dặn gỡ các bản cũ hơn 0.1.x trước khi cài. Ngoài ra có hai công thức brew khác nhau (`opencode-v2` và `opencode`). Chỉ giữ **một** cách cài, và nếu thấy lạ thì gỡ bản cũ rồi cài lại.

**4. Agent không sửa được file.**
Có thể bạn đang ở chế độ **plan**, nơi mặc định từ chối sửa file. Bấm Tab để chuyển sang **build** khi thực sự muốn nó làm thay đổi.

**5. Lo ngại khi chạy script từ mạng.**
Lệnh `curl ... | bash` chạy thẳng script tải về. Nếu bạn không yên tâm, hãy chọn cách cài khác như npm hoặc brew, hoặc đọc kỹ nội dung script trước khi chạy. README cũng gọi cách này là "YOLO".

## 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 (hiện có khoảng 226.506 sao) và vẫn được cập nhật.
- Có cách cài cho nhiều hệ điều hành, cộng thêm app desktop cho người ngại terminal.
- Hai chế độ build/plan giúp bạn kiểm soát: khám phá trước, sửa sau.
- Có trợ lý phụ `@general` cho việc tìm kiếm và nhiều bước.

**Giới hạn cần biết:**

- README ngắn, thiếu nhiều thông tin người mới cần: cách kết nối model AI, lệnh khởi chạy, cách kiểm tra sau cài. Bạn sẽ phải đọc thêm tài liệu ở opencode.ai/docs.
- App desktop còn ở bản BETA.
- README có chỗ chưa thống nhất về tên gói/lệnh cài npm, nên bạn cần đối chiếu khi cài.
- Tư liệu không nói gì về chi phí, yêu cầu phần cứng hay chính sách dữ liệu, nên mình không thể khẳng định.

**Khi nào nên chọn cách khác:** nếu bạn hoàn toàn không đụng tới code và chỉ cần chat hỏi đáp thông thường, một ứng dụng chat AI là đủ. Nếu công ty có quy định nghiêm về việc đưa mã nguồn cho dịch vụ bên ngoài, hãy hỏi bộ phận IT hoặc bảo mật trước khi dùng bất kỳ coding agent nào.

Tóm lại: opencode đáng thử nếu bạn muốn một trợ lý lập trình mã nguồn mở có chế độ "chỉ xem" an toàn. Hãy bắt đầu ở chế độ plan trên một dự án nhỏ, quen tay rồi mới cho nó sửa thật.

## 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. Tư liệu không nói gì về chi phí của các dịch vụ AI mà nó có thể kết nối tới, nên mình chưa có thông tin. Bạn xem tài liệu ở opencode.ai/docs và bảng giá của nhà cung cấp model bạn chọn.

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

README có file app desktop cho Windows (opencode-desktop-win-x64.exe), hiện ở bản BETA. Cách cài bằng dòng lệnh thì README ghi rõ macOS, Linux và mise dùng được trên mọi hệ điều hành. README không nói thêm về Windows ở phần dòng lệnh.

### Có 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 chính thức. Bạn xem thêm trong tài liệu ở opencode.ai/docs.

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

build là agent mặc định, 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.

### Dữ liệu và code của mình có an toàn không?

Tư liệu README không nói về cách xử lý dữ liệu. Repo có file SECURITY.md, bạn nên đọc để biết chính sách bảo mật. Với code nhạy cảm, hãy kiểm tra kỹ dịch vụ AI bạn kết nối và hỏi bộ phận IT nếu làm cho công ty.

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

Nhanh nhất là script một dòng `curl -fsSL https://opencode.ai/v2/install | bash`, hoặc dùng npm/brew nếu bạn đã quen. Người không thích terminal có thể tải app desktop (BETA) từ trang opencode.ai/download.

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

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