# 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 (anomalyco/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ó có hai chế độ: build để làm việc đầy đủ và plan để chỉ đọc, phân tích. Cài khá dễ: chỉ cần 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-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-4

OpenCode là một agent lập trình AI mã nguồn mở: bạn mở nó trong thư mục dự án, trò chuyện bằng ngôn ngữ thường, và nó giúp bạn đọc code, giải thích, lên kế hoạch hoặc sửa code. Tác giả mô tả ngắn gọn repo là «The open source coding agent». Hiện repo có khoảng 226.506 sao và 30.658 fork, giấy phép MIT, và vẫn được cập nhật trong vài tháng gần đây.

Bạn nên xem qua OpenCode nếu bạn là lập trình viên mới, người làm kỹ thuật trong công ty, hoặc dân văn phòng hay nhận dự án nhỏ, muốn có một trợ lý AI ngồi cạnh khi làm việc với code. Bạn không cần là chuyên gia. Chỉ cần biết mở terminal và vào được thư mục dự án là đủ để bắt đầu.

Điểm đáng giá nhất là hai chế độ làm việc tách bạch. Chế độ build có toàn quyền để làm việc. Chế độ plan chỉ đọc, mặc định không cho sửa file, nên bạn có thể thoải mái cho AI xem một dự án lạ mà không lo nó tự ý thay đổi gì. Ngoài ra repo còn có bản desktop (đang BETA) cho ai không thích dùng dòng lệnh.

```repo
- repo | anomalyco/opencode
- kind | Agent
- desc | OpenCode là agent lập trình AI mã nguồn mở, có bản terminal và bản desktop, giúp đọc, giải thích, lên kế hoạch và sửa code ngay trong dự án của bạn.
- stars | 227k
- lang | TypeScript
- license | MIT
```

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

Dưới đây là những gì README của repo nói thẳng ra, kèm ý nghĩa thực tế cho bạn.

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

- **build** là agent mặc định, có đủ quyền cho công việc phát triển. Bạn dùng khi muốn nhờ nó viết hoặc sửa code thật.
- **plan** là 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. Rất hợp khi bạn vừa nhận một dự án lạ và muốn hiểu nó trước khi động vào.

Bạn chuyển qua lại giữa hai agent bằng phím `Tab`. Thói quen tốt cho người mới: bắt đầu bằng plan để hiểu và lên kế hoạch, hài lòng rồi mới chuyển sang build.

### Agent phụ general cho việc phức tạp

Ngoài hai agent chính còn có subagent **general**, dùng cho các tìm kiếm phức tạp và công việc nhiều bước. Hệ thống tự dùng nó ở bên trong. 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, nhiều hệ điều hành

README liệt kê cách cài qua script, npm, Homebrew, pacman, paru, mise và Nix. Bạn có thể chọn cách quen thuộc với máy mình thay vì phải học thêm công cụ mới.

### Có bản desktop

Ngoài bản dòng lệnh, OpenCode có ứng dụng desktop (BETA) cho macOS, Windows và Linux. Người không quen terminal có thể dùng bản này.

### Cấu hình theo tài liệu riêng

Phần cấu hình chi tiết nằm ở trang tài liệu của dự án (opencode.ai/docs). README chỉ trỏ sang đó chứ không chép hết, nên khi cần chỉnh sâu bạn sẽ phải đọc tài liệu này.

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

Tư liệu README nói khá ít về yêu cầu hệ thống, nên mình chỉ nêu những gì có thật:

- **Hệ điều hành:** README có hướng dẫn cho macOS, Linux (kể cả Arch Linux), và có bản desktop cho Windows. Cách `mise use -g opencode` được 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 trên máy. README ghi thêm là có thể dùng bun, pnpm hoặc yarn thay thế.
- **Nếu cài bằng Homebrew:** bạn cần có Homebrew (macOS hoặc Linux).
- **Nếu cài bằng Nix:** bạn cần có Nix.
- **Bản cũ:** README khuyê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 hay phần cứng (GPU, RAM): README **chưa ghi** gì. Muốn biết cách kết nối với mô hình AI nào, bạn xem trang tài liệu tại opencode.ai/docs.

```note
README chưa nói về API key hay chi phí. Khi bạn kết nối OpenCode với một dịch vụ AI nào đó, hãy tự kiểm tra cách tính phí của dịch vụ đó. Không dán key vào chỗ công khai như repo GitHub hay ảnh chụp màn hình gửi người khác.
```

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

```steps
- Mở terminal | Mở terminal (PowerShell, Terminal…) trên máy của bạn
- Chọn một cách cài | Chạy script cài nhanh hoặc dùng npm, Homebrew, mise… theo README
- Gỡ bản cũ nếu có | Gỡ các phiên bản cũ hơn 0.1.x trước khi cài
- Hoặc tải bản desktop | Tải file cài đặt từ opencode.ai/download nếu không thích terminal
- Xem tài liệu cấu hình | Đọc opencode.ai/docs để kết nối và cấu hình
```

### Mở terminal đúng chỗ

Terminal là cửa sổ để bạn gõ lệnh. Trên Windows bạn có thể mở PowerShell hoặc Windows Terminal. Trên macOS là ứng dụng Terminal. Trên Linux là terminal của bản phân phối bạn dùng. Các lệnh trong README được viết kiểu bash, nên dùng chúng trên macOS hoặc Linux là chắc ăn nhất. Nếu bạn dùng Windows và thấy lệnh không chạy, hãy dùng bản desktop hoặc xem phần tài liệu của dự án.

### Gỡ bản cũ (nếu có)

README có một lưu ý: 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.

### Cách 1: script cài nhanh

README gọi cách này là «YOLO», nghĩa là gọn nhưng bạn chạy script tải từ mạng mà không xem trước. Nếu bạn muốn chắc chắn hơn, hãy chọn các cách dùng trình quản lý gói ở bên dưới.

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

Lệnh này tải script cài đặt từ trang của dự án rồi chạy nó. Theo README, script sẽ cài OpenCode vào thư mục `$HOME/.opencode/bin`. Chỗ người mới hay vấp: sau khi cài, nếu terminal không nhận ra lệnh, hãy đóng và mở lại cửa sổ terminal.

### Cách 2: dùng trình quản lý gói

README liệt kê các lệnh sau. Bạn chỉ chạy **một** dòng phù hợp với máy mình, đừng chạy hết cả danh sách.

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

Cách chọn nhanh:

- Dùng npm: dòng `npm i -g @opencode/cli@latest`. Phần sau dấu # chỉ là ghi chú, nghĩa là bạn cũng có thể thay npm bằng bun, pnpm hoặc yarn.
- Dùng macOS hoặc Linux có Homebrew: README ghi dòng `brew install anomalyco/tap/opencode-v2` là cách được khuyến nghị và luôn mới nhất. Dòng `brew install opencode` là công thức brew chính thức nhưng cập nhật chậm hơn.
- Dùng Arch Linux: `sudo pacman -S opencode` cho bản ổn định, hoặc `paru -S opencode-beta` cho bản mới nhất từ AUR.
- Dùng mise: `mise use -g opencode`, chạy được trên mọi hệ điều hành.
- Dùng Nix: `nix run github:anomalyco/opencode`.

Một điểm bạn nên biết: tên gói npm ghi trong thông tin repo là `opencode`, còn dòng lệnh trong README lại ghi `@opencode/cli@latest`. Mình chép đúng theo README. Nếu lệnh npm báo không tìm thấy gói, hãy xem lại README và trang tài liệu của dự án để lấy tên gói mới nhất.

### Cách 3: bản desktop (BETA)

Nếu bạn không thích gõ lệnh, tải ứng dụng ở opencode.ai/download. README ghi các file cho từng nền tảng:

- macOS chip Apple Silicon: `opencode-desktop-mac-arm64.dmg`
- macOS chip 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ản desktop bằng Homebrew:

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

Lệnh này cài ứng dụng desktop thay cho bản dòng lệnh. Vì là bản BETA, bạn có thể gặp những chỗ chưa hoàn thiện.

### Muốn xem mã nguồn hoặc tự tìm hiểu

Bạn có thể tải mã nguồn về máy để đọc. Đây không phải cách cài được README khuyến nghị:

```bash
git clone https://github.com/anomalyco/opencode.git
cd opencode
```

README **chưa ghi** cách build từ mã nguồn. Nếu muốn làm việc đó, hãy xem file `CONTRIBUTING.md` và `package.json` trong repo.

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

README không ghi một lệnh kiểm tra hay màn hình kết quả cụ thể. Bạn có thể tự kiểm tra theo cách an toàn như sau:

- **Bản desktop:** mở ứng dụng lên, nếu giao diện hiện ra là ổn.
- **Bản dòng lệnh:** đóng rồi mở lại terminal, sau đó thử gọi chương trình. README chưa ghi tên lệnh khởi động. Với gói tên `opencode` thì thông thường lệnh sẽ là `opencode`, nhưng bạn nên đối chiếu trong trang tài liệu opencode.ai/docs cho chắc.
- **Nếu cài bằng script:** kiểm tra xem thư mục `$HOME/.opencode/bin` có tồn tại không, vì README nói script cài vào đó.
- **Thử phím Tab:** khi đã vào giao diện của OpenCode, bấm `Tab` để đổi giữa build và plan. Nếu thấy hai chế độ đổi qua lại, bạn đã dùng được tính năng cốt lõi.

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

README không đưa ví dụ lệnh cụ thể. Các tình huống dưới đây bám đúng những gì repo nói là nó làm được (hai agent build và plan, subagent general), còn câu lệnh mẫu là gợi ý của mình để bạn bắt đầu.

### Nhận một dự án lạ và cần hiểu nhanh

Bạn là lập trình viên mới vào công ty, được giao một dự án chưa từng thấy. Hãy mở terminal ở thư mục dự án, khởi động OpenCode, rồi bảo đảm bạn đang ở chế độ plan (bấm `Tab` để chuyển nếu cần). Sau đó hỏi:

```text
Hãy đọc dự án này và cho mình biết: nó làm gì, các thư mục chính là gì, và file nào mình nên đọc trước.
```

Vì 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 yên tâm là nó không tự ý thay đổi gì. Kết quả là một bản tóm tắt giúp bạn bớt mất hàng giờ mò mẫm.

> Cứ để AI đọc trước, hiểu rồi mới cho nó sửa — an toàn hơn nhiều so với giao việc ngay từ đầu.
>
> — Ông T

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

Bạn là chủ một shop nhỏ có website do bạn tự quản lý và muốn thêm một thay đổi, ví dụ đổi cách hiển thị giá. Đừng nhờ sửa ngay. Ở chế độ plan, bạn mô tả việc cần làm và hỏi:

```text
Mình muốn đổi cách hiển thị giá sản phẩm. Hãy chỉ ra những file nào liên quan và đề xuất các bước làm, chưa sửa gì cả.
```

Bạn đọc kế hoạch, chỉnh lại cho đúng ý, rồi bấm `Tab` sang build và nhờ nó thực hiện. Nhờ vậy bạn kiểm soát được những gì sẽ bị thay đổi.

### Giao việc nhiều bước cho agent phụ

Khi cần tìm một đoạn logic nằm rải rác nhiều file, hoặc một việc phải làm qua nhiều bước, bạn có thể gọi subagent general bằng `@general`. README mô tả nó dành cho tìm kiếm phức tạp và công việc nhiều bước. Ví dụ:

```text
@general tìm tất cả chỗ trong dự án có xử lý đơn hàng và liệt kê giúp mình theo từng file.
```

Kết quả bạn nhận được là một danh sách đã gom sẵn, thay vì phải tự mở từng file để tìm.

### Dùng bản desktop cho người ít quen dòng lệnh

Bạn là nhân viên văn phòng thỉnh thoảng phải chỉnh một dự án nhỏ do đồng nghiệp để lại. Hãy cài bản desktop từ opencode.ai/download, mở thư mục dự án và hỏi bằng tiếng Việt như khi nhắn tin. Bắt đầu bằng việc nhờ giải thích, đừng nhờ sửa ngay. Khi quen rồi mới thử các việc lớn hơn. Nhớ rằng bản desktop vẫn là BETA.

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

README không có mục xử lý lỗi, nên các lỗi 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.

### Terminal báo không nhận ra lệnh sau khi cài

Nguyên nhân thường gặp là terminal chưa cập nhật đường dẫn. Hãy đóng hẳn cửa sổ terminal rồi mở lại. Nếu bạn cài bằng script, README nói nó cài vào `$HOME/.opencode/bin`, nên hãy kiểm tra thư mục này có tồn tại không. Việc thêm thư mục này vào PATH, nếu cần, bạn nên xem hướng dẫn trong tài liệu của dự án.

### Lệnh npm không tìm thấy gói hoặc báo lỗi quyền

Tên gói ghi trong README (`@opencode/cli`) và tên gói trong thông tin repo (`opencode`) khác nhau. Hãy chép chính xác lệnh trong README và đối chiếu với trang tài liệu. Nếu gặp lỗi quyền khi cài toàn cục, đừng vội dùng quyền quản trị cho mọi thứ. Thử một cách cài khác như Homebrew hoặc mise sẽ an toàn hơn.

### Cài chồng lên bản cũ gây lỗi

README khuyên gỡ các phiên bản cũ hơn 0.1.x trước khi cài. Nếu bạn từng cài OpenCode từ lâu rồi cài lại mà thấy hoạt động lạ, hãy gỡ bản cũ theo cách bạn đã cài (npm, brew…) rồi cài lại từ đầu.

### Gõ lệnh bash trên Windows không chạy

Các lệnh như `curl ... | bash` được viết cho môi trường kiểu bash. Trên Windows bạn dùng bản desktop (file `.exe`) cho đơn giản, thay vì cố chạy các lệnh đó trong PowerShell.

### Nhờ sửa code nhưng kết quả không như ý

Đây không hẳn là lỗi cài đặt mà là đặc điểm chung của AI viết code. Hãy giao việc nhỏ, rõ ràng, dùng plan để xem kế hoạch trước, và luôn đọc lại thay đổi trước khi dùng thật. Nếu dự án quan trọng, hãy sao lưu hoặc dùng quản lý phiên bản như git để có thể quay lại.

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

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

- Mã nguồn mở, giấy phép MIT, nên bạn xem được nó làm gì và dùng tự do.
- Có hai chế độ rõ ràng: build làm việc và plan chỉ đọc. Phù hợp với người mới vì có thể xem xét trước khi cho AI sửa.
- Nhiều cách cài, có cả bản desktop cho người không thích terminal.
- Cộng đồng lớn: hiện có khoảng 226.506 sao và 30.658 fork, repo vẫn được cập nhật gần đây.

**Giới hạn:**

- README khá ngắn, chưa hướng dẫn kết nối mô hình AI, chưa nói về chi phí hay yêu cầu phần cứng. Bạn phải đọc thêm tài liệu trên opencode.ai/docs.
- Tên gói npm trong README và trong thông tin repo không khớp nhau, dễ làm người mới bối rối.
- Bản desktop vẫn là BETA.
- Các lệnh trong README thiên về macOS và Linux. Người dùng Windows nên ưu tiên bản desktop.

**Khi nào nên chọn cách khác:** nếu bạn hoàn toàn không đụng đến code và chỉ cần một ứng dụng chat AI thông thường để viết văn bản hay trả lời câu hỏi, một công cụ chat đơn giản sẽ hợp hơn. OpenCode đáng thử khi bạn muốn một trợ lý làm việc ngay trong thư mục dự án, và muốn có chế độ chỉ đọc để phân tích trước khi sửa.

Lưu ý cuối: nếu bạn làm dự án có tên chứa «opencode» (như «opencode-dashboard»), README yêu cầu ghi rõ là dự án đó không do đội OpenCode làm và không liên kết với họ.

## 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ở dưới giấy phép MIT nên bạn dùng tự do. README không nói gì về chi phí của dịch vụ AI mà bạn kết nối vào. Phần này chưa có thông tin, bạn cần xem tài liệu tại opencode.ai/docs.

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

Có bản desktop cho Windows với file opencode-desktop-win-x64.exe (đang BETA). Các lệnh cài kiểu bash trong README thiên về macOS và Linux. README cũng ghi mise chạy được trên mọi hệ điều hà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 nên xem trang tài liệu của dự án trước khi cài.

### Chế độ build và plan khác nhau thế nào?

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 qua lại bằng phím Tab.

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

README không có phần nào nói về việc dữ liệu được xử lý hay gửi đi đâu. Repo có file SECURITY.md, bạn nên đọc nó và tài liệu của dự án trước khi dùng với code nhạy cảm.

### Tôi không quen dòng lệnh thì dùng thế nào?

Bạn tải bản desktop (BETA) từ opencode.ai/download cho macOS, Windows hoặc Linux. Trên macOS còn có lệnh brew install --cask opencode-desktop.

### OpenCode cài vào đâu khi dùng script?

Theo README, script cài đặt đưa OpenCode vào thư mục $HOME/.opencode/bin. Bạn cũng nên gỡ các bản cũ hơn 0.1.x trước khi cài.
