# anomalyco/opencode: AI coding agent mã nguồn mở — hướng dẫn cài đặt và dùng

> anomalyco/opencode là coding agent AI mã nguồn mở dành cho công việc phát triển phần mềm. Công cụ có agent build để làm việc với toàn quyền, agent plan để phân tích chỉ đọc và một subagent general cho các tìm kiếm phức tạp. Cài CLI khá đơn giản trên hệ điều hành được hỗ trợ; Windows có ứng dụng desktop beta.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-07-02 · Cập nhật: 2026-11-14
- URL: https://ongt.vn/bai-viet/anomalyco-opencode-ai-coding-agent

OpenCode là coding agent AI mã nguồn mở, giúp bạn làm việc với mã nguồn bằng hội thoại ngay trong terminal hoặc ứng dụng desktop. Bạn có thể dùng nó để khám phá một codebase, lập kế hoạch thay đổi, thực hiện công việc phát triển và xử lý các yêu cầu tìm kiếm nhiều bước.

Repo này phù hợp với lập trình viên mới muốn có trợ lý trong lúc học, dev cần hiểu nhanh một dự án lạ, hoặc nhóm muốn thử một coding agent có mã nguồn mở. Điểm đáng giá nhất là OpenCode có hai agent tích hợp với vai trò rõ ràng: `build` để làm việc phát triển và `plan` để phân tích, khám phá code theo chế độ chỉ đọc. Repo hiện có khoảng 226580 sao và 30675 fork, dùng giấy phép MIT, ngôn ngữ chính là TypeScript.

```repo
- repo | anomalyco/opencode
- kind | Agent
- desc | OpenCode là coding agent AI mã nguồn mở giúp phân tích, sửa và phát triển dự án ngay trong terminal hoặc ứng dụng desktop.
- stars | 227k
- lang | TypeScript
- license | MIT
```

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

- **Hỗ trợ công việc phát triển bằng agent build:** Đây là agent mặc định và có toàn quyền cho công việc phát triển. Bạn có thể dùng nó khi muốn trợ lý AI tham gia trực tiếp vào quy trình làm việc với dự án.

- **Phân tích code an toàn hơn bằng agent plan:** Agent `plan` được thiết kế cho việc phân tích và khám phá code. Agent này mặc định từ chối chỉnh sửa tệp và hỏi quyền trước khi chạy lệnh bash, phù hợp khi bạn chưa quen một codebase hoặc muốn hiểu vấn đề trước khi thay đổi.

- **Chuyển agent bằng phím Tab:** Bạn có thể đổi giữa `build` và `plan` bằng phím `Tab`. Cách này giúp chuyển từ giai đoạn tìm hiểu sang thực hiện mà không cần dùng hai công cụ riêng.

- **Tìm kiếm phức tạp với subagent general:** OpenCode có sẵn subagent `general` cho các lượt tìm kiếm phức tạp và nhiều bước. Bạn có thể gọi subagent này trong tin nhắn bằng `@general`.

- **Chạy trong terminal:** OpenCode có thể được cài bằng script hoặc nhiều trình quản lý gói. Đây là lựa chọn phù hợp nếu bạn quen làm việc trong terminal và muốn giữ quy trình phát triển gần với thư mục dự án.

- **Có ứng dụng desktop beta:** Ngoài CLI, dự án còn có ứng dụng desktop beta cho macOS, Windows và Linux. Người dùng không muốn bắt đầu từ terminal có thể dùng bản desktop, tùy nền tảng.

- **Mã nguồn mở và có thể đóng góp:** Repo dùng giấy phép MIT và có sẵn các tệp hướng dẫn đóng góp. Điều này phù hợp với người muốn đọc mã nguồn, nghiên cứu cách một coding agent được tổ chức hoặc tham gia phát triển dự án.

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

- **Một hệ điều hành phù hợp với cách cài bạn chọn:** README ghi các lựa chọn CLI gồm script cài đặt, npm, bun, pnpm, yarn, Homebrew, Arch Linux, AUR, mise và Nix. Homebrew được ghi cho macOS và Linux. Ứng dụng desktop có bản cho macOS Apple Silicon, macOS Intel, Windows và Linux.

- **Công cụ quản lý gói tương ứng nếu dùng cách cài đó:** Bạn cần có npm nếu dùng lệnh npm, Homebrew nếu dùng brew, pacman hoặc paru nếu dùng Arch/AUR, mise nếu dùng mise, hoặc Nix nếu dùng Nix. README không nêu phiên bản cụ thể của Node.js, npm, Bun hay các công cụ khác.

- **Quyền chạy lệnh cài đặt:** Cách cài bằng script cần chạy lệnh shell. Cách cài Arch Linux trong README dùng `sudo`, nên tài khoản cần có quyền phù hợp trên máy đó.

- **Một thư mục dự án nếu muốn dùng OpenCode cho code thật:** README mô tả OpenCode là coding agent và có agent cho phát triển, phân tích code. Tư liệu được cung cấp không nêu một API key, tài khoản dịch vụ hay cấu hình nhà cung cấp mô hình bắt buộc nào.

- **Không cần tự chuẩn bị GPU theo tư liệu hiện có:** README không yêu cầu GPU hoặc phần cứng đặc biệt. Vì vậy mình không nên khẳng định công cụ chạy hoàn toàn cục bộ hay không phát sinh chi phí mô hình; phần này chưa được README cung cấp.

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

```steps
- Chọn cách cài | Chọn script, npm, brew, Arch, mise hoặc Nix phù hợp với máy
- Cài OpenCode | Chạy đúng lệnh trong README cho phương án đã chọn
- Kiểm tra bản cũ | Gỡ các phiên bản cũ hơn 0.1.x trước khi cài nếu đang có
- Mở dự án | Đưa terminal hoặc ứng dụng desktop vào dự án cần làm việc
- Chọn agent | Dùng Tab để chuyển giữa build và plan
```

### Chọn phương án cài phù hợp

README cung cấp nhiều cách cài. Với máy có shell và muốn cài nhanh, bạn có thể dùng script. Với máy đã dùng npm, có thể cài gói toàn cục. Nếu dùng macOS hoặc Linux, Homebrew cũng là lựa chọn được README khuyến nghị khi muốn bản luôn được cập nhật.

Trước khi cài, hãy kiểm tra máy có phiên bản OpenCode cũ hơn 0.1.x hay không. README nhắc cần xóa các phiên bản cũ hơn 0.1.x trước khi cài. Tư liệu không cung cấp lệnh gỡ cụ thể, nên bạn không nên tự đoán lệnh gỡ theo hệ điều hành.

### Cài bằng script

Đây là lệnh YOLO được README cung cấp:

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

Lệnh này tải script cài đặt từ địa chỉ của dự án rồi chuyển cho `bash` chạy. Bạn cần mở terminal có `curl` và `bash`. Nếu lệnh báo thiếu một trong hai công cụ, hãy chọn trình quản lý gói phù hợp bên dưới hoặc xem hướng dẫn trong repo.

Theo README, script cài OpenCode vào thư mục `$HOME/.opencode/bin`. Người mới thường vấp ở chỗ terminal chưa nhận được lệnh sau khi cài. Khi đó, hãy kiểm tra lại thông báo của script và phần cấu hình đường dẫn mà script đã hướng dẫn; README được cung cấp chưa ghi lệnh kiểm tra phiên bản cụ thể.

### Cài bằng npm hoặc trình quản lý gói JavaScript

Nếu máy đã có npm, chạy đúng lệnh sau:

```bash
npm i -g @opencode/cli@latest      # or bun/pnpm/yarn
```

Lệnh `npm i -g` cài gói ở phạm vi toàn cục, nên bạn có thể gọi OpenCode từ các thư mục dự án khác nhau. Phần chú thích trong README cho biết có thể dùng bun, pnpm hoặc yarn thay cho npm, nhưng không đưa ra cú pháp riêng cho từng công cụ. Vì vậy, nếu dùng công cụ khác, hãy xem tài liệu cài đặt của repo thay vì tự thêm tên gói hoặc cờ lệnh.

README cũng liệt kê tên gói npm là `opencode`, nhưng lệnh cài đặt cụ thể trong phần Installation là `@opencode/cli@latest`. Khi làm theo tài liệu, bạn nên ưu tiên đúng lệnh cài đặt đã được ghi ở trên.

### Cài bằng Homebrew

Homebrew được README ghi cho macOS và Linux. Bản được khuyến nghị là:

```bash
brew install anomalyco/tap/opencode-v2 # macOS and Linux (recommended, always up to date)
```

README cũng có công thức chính thức nhưng cập nhật chậm hơn:

```bash
brew install opencode              # macOS and Linux (official brew formula, updated less)
```

Nếu muốn theo lựa chọn được README khuyến nghị và luôn cập nhật, dùng lệnh đầu tiên. Nếu tổ chức hoặc máy của bạn đã chuẩn hóa công thức `opencode`, lệnh thứ hai là lựa chọn chính thức khác.

### Cài trên Arch Linux, bằng mise hoặc Nix

README cung cấp ba lệnh sau:

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

`pacman` cài bản Stable trên Arch Linux. `paru` cài bản `opencode-beta` từ AUR và được ghi là bản mới nhất từ AUR. `mise` được README ghi cho mọi hệ điều hành. `nix run` chạy OpenCode qua Nix.

Các lệnh này phụ thuộc vào công cụ tương ứng đã có trên máy. Nếu bạn không dùng Arch Linux thì không nên chạy lệnh `pacman` hoặc `paru`. Nếu chưa quen Nix hoặc mise, hãy chọn npm hoặc script nếu môi trường của bạn đáp ứng yêu cầu.

### Cài ứng dụng desktop beta

README cho biết OpenCode có ứng dụng desktop beta. Các tệp tải xuống được liệt kê 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`

Bạn tải đúng tệp theo nền tảng từ trang tải xuống của dự án, mở trình cài đặt và làm theo hướng dẫn trên màn hình. Tư liệu được cung cấp không mô tả chi tiết giao diện desktop, cách chọn thư mục dự án hay cách cấu hình bên trong ứng dụng.

Nếu dùng macOS và đã cài Homebrew, README có thêm lệnh:

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

Đây là cách cài bản desktop qua Homebrew Cask. Không nên dùng lệnh này trên Windows hoặc Linux vì README chỉ ghi nó cho macOS.

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

Cách kiểm tra chắc chắn nhất là mở OpenCode trong môi trường bạn vừa cài và xem nó khởi động được hay không. README được cung cấp không ghi lệnh kiểm tra phiên bản, màn hình chào hoặc đầu ra mẫu cụ thể, nên mình không nên bịa một kết quả mong đợi.

Bạn có thể kiểm tra theo các dấu hiệu sau, dựa trên khả năng được README mô tả:

- Với bản CLI, lệnh cài đặt hoàn tất mà không báo lỗi và OpenCode có thể được gọi trong terminal.
- Với bản desktop, tệp cài đặt đúng nền tảng mở được ứng dụng.
- Khi đang ở giao diện OpenCode, phím `Tab` chuyển được giữa agent `build` và `plan`.
- Agent `plan` thể hiện đúng vai trò phân tích: mặc định không chỉnh sửa tệp và hỏi quyền trước khi chạy lệnh bash.
- Bạn có thể gọi `@general` trong tin nhắn để dùng subagent dành cho tìm kiếm phức tạp và nhiều bước.

Nếu cài xong nhưng terminal báo không tìm thấy lệnh, trước hết kiểm tra lại thư mục cài đặt `$HOME/.opencode/bin` khi bạn dùng install script. Nếu dùng npm, brew, pacman, mise hoặc Nix, kiểm tra công cụ quản lý gói đã hoàn tất và terminal đang dùng đúng môi trường. README chưa ghi thêm quy trình chẩn đoán cụ thể.

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

### Dev mới nhận một codebase chưa quen

Bạn mở terminal trong thư mục dự án rồi dùng agent `plan` để yêu cầu OpenCode lập bản đồ codebase. Ví dụ, bạn có thể nhập: “Hãy khám phá cấu trúc dự án, xác định điểm khởi động, các thư mục chính và luồng xử lý quan trọng. Chỉ phân tích, chưa chỉnh sửa tệp.”

Agent `plan` phù hợp với tình huống này vì nó được thiết kế cho phân tích và khám phá code, mặc định từ chối chỉnh sửa tệp và hỏi quyền trước khi chạy lệnh bash. Kết quả hữu ích là bạn hiểu dự án trước khi chuyển sang thay đổi.

### Lập kế hoạch trước khi sửa lỗi

Khi một tính năng đang lỗi, hãy bắt đầu ở agent `plan` và nhập yêu cầu như: “Tìm các phần liên quan đến lỗi đăng nhập, phân tích nguyên nhân có thể xảy ra và đề xuất các tệp cần sửa. Chưa thay đổi code.”

Sau khi đọc kế hoạch, nhấn `Tab` để chuyển sang `build` nếu bạn muốn OpenCode thực hiện công việc phát triển. Cách chuyển agent này giúp tách giai đoạn suy nghĩ khỏi giai đoạn chỉnh sửa trong cùng công cụ.

### Thực hiện một việc phát triển lặp lại

Một dev có thể dùng agent `build` cho yêu cầu cụ thể như: “Thực hiện thay đổi theo kế hoạch vừa thống nhất, cập nhật các phần liên quan và báo lại những tệp đã thay đổi.” README mô tả `build` là agent mặc định, có toàn quyền cho công việc phát triển.

Vì đây là agent có toàn quyền, bạn nên đọc lại yêu cầu, xem thay đổi và chỉ mở OpenCode trong thư mục dự án cần xử lý. Tư liệu hiện có không nêu một quy trình kiểm thử hoặc lệnh riêng cho từng loại dự án, nên phần kiểm tra sau khi thay đổi vẫn cần dựa vào quy trình của codebase.

### Tìm kiếm nhiều bước trong dự án

Khi câu hỏi cần rà qua nhiều phần của codebase, bạn có thể gọi subagent `general` bằng cách bắt đầu tin nhắn với `@general`. Ví dụ: “@general tìm tất cả nơi xử lý cấu hình, đối chiếu cách đọc biến môi trường và tóm tắt các điểm khác nhau.”

README chỉ nói `general` dành cho các tìm kiếm phức tạp và nhiều bước, không cung cấp một bộ prompt bắt buộc hay mẫu kết quả cụ thể. Vì vậy, hãy viết yêu cầu rõ phạm vi, đầu ra mong muốn và các giới hạn chỉnh sửa nếu bạn không muốn thay đổi tệp.

> Hãy hiểu code trước, lập kế hoạch rõ rồi mới trao quyền cho agent thực hiện.
>
> — Ông T

```note
Agent build có toàn quyền cho công việc phát triển. Hãy dùng agent plan khi cần phân tích chỉ đọc, kiểm tra kỹ phạm vi thư mục và không đưa thông tin nhạy cảm vào prompt nếu chưa hiểu cách dữ liệu được xử lý.
```

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

### Terminal không nhận lệnh sau khi cài bằng script

Install script cài OpenCode vào `$HOME/.opencode/bin`. Nếu terminal báo không tìm thấy lệnh, hãy kiểm tra thông báo của script và đường dẫn này. README được cung cấp chưa ghi lệnh thêm đường dẫn cụ thể, nên không nên tự đoán một dòng cấu hình shell.

### Chọn sai lệnh theo hệ điều hành

`brew` trong README dành cho macOS và Linux; `pacman` dành cho Arch Linux; `brew install --cask opencode-desktop` dành cho macOS. Trên Windows, README cung cấp tệp desktop `.exe`, không ghi lệnh CLI Windows tương ứng.

### Đang dùng phiên bản OpenCode quá cũ

README yêu cầu xóa các phiên bản cũ hơn 0.1.x trước khi cài. Nếu bản cài đặt cũ gây xung đột, hãy xác định cách bạn đã cài trước đó rồi làm theo phương án gỡ phù hợp; tài liệu được cung cấp không ghi lệnh gỡ cụ thể.

### Agent chỉnh sửa khi bạn chỉ muốn khảo sát

Đây là lỗi dễ xảy ra nếu bạn bắt đầu bằng agent `build`, vì `build` có toàn quyền cho công việc phát triển. Hãy chuyển sang `plan` bằng phím `Tab` và nói rõ yêu cầu chỉ phân tích, chưa chỉnh sửa. Agent `plan` mặc định từ chối sửa tệp và hỏi quyền trước khi chạy lệnh bash.

### Không biết nên dùng subagent nào

Với việc phát triển thông thường, dùng `build`; với phân tích và khám phá code, dùng `plan`; với tìm kiếm phức tạp nhiều bước, gọi `@general`. README không mô tả thêm cơ chế định tuyến, nên hãy chỉ định rõ agent trong yêu cầu khi nhiệm vụ có rủi ro.

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

OpenCode đáng thử nếu bạn muốn một coding agent mã nguồn mở, có giấy phép MIT, hỗ trợ cả terminal lẫn desktop beta và có cách phân tách rõ giữa lập kế hoạch với thực thi. Việc chuyển agent bằng `Tab`, agent `plan` chỉ đọc và subagent `general` cho tìm kiếm nhiều bước là những điểm thực tế, đặc biệt hữu ích khi làm việc với codebase chưa quen.

Giới hạn lớn nhất của tư liệu hiện có là README không ghi phiên bản Node.js hoặc yêu cầu hệ thống chi tiết, không nêu lệnh kiểm tra phiên bản, không mô tả quy trình dùng desktop đầy đủ và không nói rõ yêu cầu API key, chi phí hay cách dữ liệu được xử lý. Vì vậy, nếu bạn cần một hướng dẫn vận hành có thông tin nhà cung cấp mô hình, bảo mật dữ liệu hoặc chi phí cụ thể, hãy đọc thêm tài liệu cấu hình và bảo mật trong repo trước khi triển khai rộng.

Bạn nên chọn OpenCode khi muốn tự khám phá một coding agent mã nguồn mở và chấp nhận đọc thêm tài liệu theo môi trường của mình. Nếu cần công cụ có tài liệu cấu hình đầy đủ ngay từ đầu, hoặc cần biết chắc mô hình, chi phí và chính sách dữ liệu trước khi dùng trong công việc, hãy so sánh thêm các lựa chọn khác sau khi thu thập đủ thông tin tương ứng.

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

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

Repo dùng giấy phép MIT. Tuy nhiên, README được cung cấp không nói rõ chi phí sử dụng mô hình, dịch vụ liên quan hay ứng dụng desktop, nên chưa thể khẳng định toàn bộ quá trình dùng không phát sinh chi phí.

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

README liệt kê ứng dụng desktop beta cho Windows với tệp `opencode-desktop-win-x64.exe`. README không ghi lệnh cài CLI riêng cho Windows.

### Có cần GPU để chạy OpenCode không?

README không nêu yêu cầu GPU hoặc phần cứng đặc biệt. Tư liệu hiện có cũng không đủ để kết luận OpenCode chạy mô hình hoàn toàn trên máy hay cần dịch vụ bên ngoài.

### OpenCode cần Node.js phiên bản nào?

README có lệnh cài qua npm nhưng không nêu phiên bản Node.js hoặc npm cụ thể. Bạn nên xem thêm tài liệu của repo nếu môi trường npm gặp lỗi tương thích.

### OpenCode có sửa tệp được không?

Có. Agent `build` là agent mặc định, có toàn quyền cho công việc phát triển. Nếu chỉ muốn phân tích, dùng agent `plan`, vì agent này mặc định từ chối chỉnh sửa tệp.

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

README được cung cấp không mô tả cách dữ liệu được xử lý, lưu trữ hoặc gửi tới dịch vụ nào. Bạn nên đọc thêm tài liệu cấu hình và tệp bảo mật trong repo trước khi đưa mã nguồn nhạy cảm vào công cụ.

### OpenCode khác gì giữa build, plan và general?

`build` dành cho công việc phát triển với toàn quyền, `plan` dành cho phân tích và khám phá code theo chế độ chỉ đọc, còn `general` là subagent cho tìm kiếm phức tạp và nhiều bước. Bạn đổi giữa `build` và `plan` bằng phím `Tab`, và gọi `general` bằng `@general` trong tin nhắn.
