# opencode: trợ lý lập trình AI mã nguồn mở — 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. Bạn dùng nó để đọc hiểu, phân tích và sửa code bằng ngôn ngữ tự nhiên. Cài khá dễ: chỉ 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-06-22 · 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-mwek88sj

opencode là một agent lập trình AI mã nguồn mở: bạn giao việc bằng câu chữ bình thường, nó đọc code, phân tích và (nếu bạn cho phép) sửa code giúp bạn. Repo do nhóm anomalyco phát triển, viết bằng TypeScript, giấy phép MIT, hiện có khoảng 226.506 sao và 30.658 fork.

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 muốn tự động hoá việc nhỏ bằng code, hoặc chủ doanh nghiệp có một dự án phần mềm nhỏ mà chưa biết bắt đầu từ đâu. Điểm đáng giá nhất của opencode là hai chế độ làm việc rõ ràng. Chế độ `build` được phép sửa file. Chế độ `plan` chỉ đọc và phân tích, nên bạn có thể khám phá một dự án lạ mà không sợ nó lỡ tay thay đổi gì.

Bài này đi từ cài đặt đến vài tình huống dùng thực tế. Phần nào README của repo chưa ghi (ví dụ lệnh khởi chạy, cách nhập khoá của nhà cung cấp AI), mình sẽ nói thẳng và chỉ bạn chỗ xem tiếp, không đoán mò.

```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 (beta). Có hai chế độ: build để sửa code, plan chỉ đọc để phân tích.
- stars | 227k
- lang | TypeScript
- license | MIT
```

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

Theo README, opencode xoay quanh vài ý chính. Mình giải thích theo hướng bạn được lợi gì.

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

- **build** là agent mặc định, có toàn quyền cho công việc phát triển. Bạn dùng nó khi muốn viết hoặc sửa code thật.
- **plan** là agent chỉ đọc. Mặc định nó từ chối sửa file và hỏi xin phép trước khi chạy lệnh bash. Chế độ này hợp để làm quen một dự án mới hoặc lên kế hoạch thay đổi trước khi bắt tay làm.

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 là bắt đầu bằng `plan` để hiểu dự án, rồi mới sang `build`.

### Subagent general cho việc phức tạp

Ngoài hai agent trên 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. README nói nó chủ yếu được dùng nội bộ, nhưng bạn có thể gọi trực tiếp bằng `@general` trong tin nhắn.

### Có bản terminal và bản desktop

opencode cài được qua dòng lệnh và nhiều trình quản lý gói (npm, Homebrew, pacman, mise, Nix). Ngoài ra còn có ứng dụng desktop (đang ở dạng BETA) cho macOS, Windows và Linux. Người không quen terminal có thể thử bản desktop trước.

### Mã nguồn mở, giấy phép MIT

Bạn đọc được code, tự kiểm tra nó làm gì. Giấy phép MIT cho phép dùng khá thoải mái. Repo cũng có tài liệu hướng dẫn cấu hình đầy đủ tại trang chủ dự án, và cộng đồng trên Discord và X.

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

Tư liệu README chỉ nói những điều sau:

- **Hệ điều hành:** bản desktop có cho macOS (Apple Silicon và Intel), Windows và Linux. Các lệnh cài qua trình quản lý gói có ghi macOS, Linux, Arch Linux, Nix, và mise cho "mọi hệ điều hành".
- **Công cụ cài đặt:** tuỳ cách bạn chọn. Có thể là `curl` và `bash`, hoặc npm (bun, pnpm, yarn cũng được), hoặc Homebrew, pacman, mise, Nix.
- **Gỡ 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 nói gì. Chưa có thông tin về việc bạn cần nhà cung cấp mô hình AI nào hay cấu hình máy ra sao. Phần này bạn xem trong tài liệu chính thức ở trang chủ dự án (opencode.ai/docs).

```note
Một agent lập trình có thể đọc file và chạy lệnh trên máy bạn. Trước khi giao việc, hãy chọn một thư mục dự án có sao lưu (hoặc dùng git). Nếu có điền khoá API của dịch vụ AI nào đó, đừng dán khoá vào code hay gửi cho người khác. Chi phí gọi mô hình AI (nếu có) phụ thuộc nhà cung cấp bạn chọn; README chưa nói về chuyện này.
```

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

```steps
- Chọn cách cài | Bản desktop hay dòng lệnh, tuỳ bạn quen cái nào
- Gỡ bản cũ | Nếu đã có opencode cũ hơn 0.1.x thì gỡ trước
- Chạy lệnh cài | Một dòng curl, hoặc npm/Homebrew/trình quản lý gói bạn dùng
- Kiểm tra vị trí cài | Script cài vào thư mục .opencode/bin trong thư mục home
- Xem docs để cấu hình | Nối với dịch vụ AI theo hướng dẫn chính thức
```

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

Nếu bạn chưa quen terminal, hãy dùng bản desktop (beta) tải từ trang opencode.ai/download. README liệt kê các file: `opencode-desktop-mac-arm64.dmg` (Mac chip Apple), `opencode-desktop-mac-x64.dmg` (Mac Intel), `opencode-desktop-win-x64.exe` (Windows), và `.deb`, `.rpm` hoặc `.AppImage` cho Linux. Người dùng Mac có Homebrew cũng cài được bản desktop bằng lệnh:

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

Nếu quen dòng lệnh, đi tiếp các bước dưới.

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

README ghi rõ: hãy gỡ các phiên bản cũ hơn 0.1.x trước khi cài. README không nói cách gỡ, nên nếu bạn từng cài theo kiểu nào (npm, brew…), hãy gỡ bằng đúng công cụ đó.

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

Đây là danh sách lệnh đúng nguyên văn trong README. Bạn chỉ cần chọn MỘT dòng phù hợp với máy mình, đừng chạy hết:

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

Một vài lưu ý cho người mới:

- Dòng `curl ... | bash` (README gọi vui là "YOLO") tải script về và chạy ngay. Nó tiện, nhưng bạn nên hiểu là mình đang chạy một script từ internet. Nếu muốn cẩn thận, hãy chọn trình quản lý gói.
- Dòng `npm i -g` cần bạn đã có Node.js và npm trên máy. README chưa nói yêu cầu phiên bản Node cụ thể.
- Hai dòng `brew` khác nhau: dòng đầu (kho `anomalyco/tap`) được README khuyên dùng vì luôn mới; dòng thứ hai là công thức chính thức nhưng cập nhật chậm hơn.
- Phần sau dấu `#` chỉ là ghi chú, bạn không cần gõ.
- Trên Windows, README không có lệnh cài riêng. Bạn có thể dùng bản desktop `.exe`, hoặc lệnh `npm i -g` / `mise use -g` nếu đã có sẵn công cụ đó.
- Về tên gói npm, README ghi `@opencode/cli@latest`, trong khi thông tin repo ghi tên gói là `opencode`. Hai tên này lệch nhau, nên nếu lệnh npm báo lỗi, bạn hãy đối chiếu lại với trang cài đặt chính thức.

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

README cho biết script cài đặt đưa opencode vào thư mục `$HOME/.opencode/bin`. Nếu sau khi cài mà terminal không nhận lệnh, hãy kiểm tra thư mục này có nằm trong PATH của bạn không. README chưa hướng dẫn thêm vào PATH, nên bạn xem thêm ở tài liệu chính thức.

### Cấu hình và khởi chạy

README chỉ nói: muốn biết cách cấu hình opencode, hãy xem tài liệu tại trang chủ (opencode.ai/docs). README chưa ghi lệnh khởi chạy cụ thể, cũng chưa ghi cách nhập khoá của nhà cung cấp AI. Vì vậy mình không viết lệnh đoán ở đây; bạn làm theo trang docs ở phần bắt đầu, nơi tác giả giữ hướng dẫn mới nhất.

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

Vì README không có lệnh kiểm tra riêng, bạn có thể dùng các dấu hiệu sau, tất cả đều bám theo tư liệu:

1. **Với script cài:** thư mục `$HOME/.opencode/bin` đã tồn tại và có file chương trình bên trong.
2. **Với bản desktop:** mở ứng dụng lên và thấy giao diện hiện ra bình thường.
3. **Với agent:** sau khi khởi chạy theo trang docs, bạn bấm `Tab` thì thấy đổi giữa hai chế độ `build` và `plan`. Đó là dấu hiệu rõ nhất rằng opencode đã chạy.

Nếu bước nào không ra như vậy, xem phần lỗi thường gặp ở dưới.

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

Các tình huống dưới đây bám theo khả năng README có nêu: hai agent build/plan, subagent general. Câu lệnh mẫu là cách nói tự nhiên với agent, không phải lệnh cố định của repo.

### Lập trình viên mới đọc hiểu dự án của công ty

Bạn vừa vào làm, được giao một dự án mấy chục thư mục mà không ai có thời gian giải thích. Bạn mở opencode ở thư mục dự án, bấm `Tab` để chuyển sang agent `plan` (chỉ đọc, mặc định từ chối sửa file) rồi hỏi:

```text
Hãy giải thích cấu trúc thư mục dự án này. Phần nào xử lý đăng nhập? Nếu muốn thêm một trang báo cáo mới thì nên đụng vào những file nào?
```

Kết quả bạn nhận được là một bản giải thích bằng tiếng Việt, kèm danh sách file liên quan, mà dự án không bị thay đổi gì. Đây đúng là việc README gọi là "explore unfamiliar codebases".

> Cứ hỏi ở chế độ chỉ đọc trước, hiểu rồi mới cho nó sửa.
>
> — Ông T

### Chủ shop muốn chỉnh một trang web nhỏ

Bạn có một website bán hàng đơn giản do bạn cũ lập trình, giờ muốn đổi dòng thông báo khuyến mãi và số hotline. Bạn mở opencode ở thư mục website, ở agent `plan` nhờ nó chỉ ra file chứa các dòng đó. Khi đã biết chắc, bạn bấm `Tab` sang `build` và ra lệnh:

```text
Đổi dòng thông báo ở đầu trang thành "Giảm 10% đơn đầu tiên" và cập nhật số hotline mới. Chỉ sửa những chỗ đó, đừng đổi gì khác.
```

Kết quả là code được sửa đúng chỗ. Bạn nên xem lại những gì nó thay đổi (nếu dùng git thì xem phần khác biệt) trước khi đưa lên mạng.

### Nhân viên văn phòng cần lên kế hoạch trước khi sửa

Bạn có một công cụ nội bộ nhỏ, ví dụ script xử lý bảng tính, muốn thêm một tính năng nhưng sợ làm hỏng. Ở agent `plan`, bạn hỏi:

```text
Tôi muốn thêm cột "tổng doanh thu theo tháng" vào kết quả. Hãy đề xuất các bước thực hiện, nêu file cần sửa và rủi ro. Chưa sửa gì cả.
```

Bạn nhận được một kế hoạch từng bước. Khi plan cần chạy lệnh bash, README nói agent sẽ hỏi xin phép bạn trước, nên bạn nắm quyền quyết định. Nếu thấy hợp lý, chuyển sang `build` để thực hiện.

### Dev cần tìm nhanh trong dự án lớn

Trong một dự án lớn, bạn cần biết hàm tính phí vận chuyển được gọi ở những đâu. Bạn có thể nhắc đến subagent `general` ngay trong tin nhắn:

```text
@general tìm tất cả nơi gọi hàm tính phí vận chuyển và tóm tắt mỗi nơi dùng nó để làm gì.
```

README mô tả `general` dành cho tìm kiếm phức tạp và việc nhiều bước. Kết quả mong đợi là một bản tổng hợp gọn, đỡ cho bạn việc tự tìm từng file.

## 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. Mình nói rõ để bạn biết đây là gợi ý chung, không phải thông báo lỗi chính thức của repo.

### Gõ lệnh mà terminal báo không tìm thấy

Thường là do thư mục chứa chương trình chưa nằm trong PATH, hoặc bạn chưa mở lại terminal sau khi cài. Hãy đóng terminal, mở cửa sổ mới rồi thử lại. Script cài đặt đưa chương trình vào `$HOME/.opencode/bin`, nên hãy kiểm tra thư mục này có nằm trong PATH không.

### Lệnh npm báo lỗi gói

Tên gói trong README (`@opencode/cli`) lệch với tên gói ghi trong thông tin repo (`opencode`). Hãy thử một cách cài khác trong danh sách (ví dụ Homebrew hoặc mise), hoặc mở trang cài đặt chính thức để xem tên gói mới nhất. Đừng thử các tên gói lạ mà bạn không chắc nguồn.

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

README khuyên gỡ các bản cũ hơn 0.1.x trước khi cài. Nếu cài xong mà chạy ra phiên bản lạ hoặc báo lỗi kỳ cục, hãy gỡ bản cũ bằng đúng công cụ đã dùng để cài nó rồi cài lại từ đầu.

### Lỡ để agent sửa nhiều hơn ý muốn

Agent `build` có toàn quyền trong dự án. Cách phòng là dùng `plan` để lên kế hoạch trước, yêu cầu rõ "chỉ sửa những chỗ này", và luôn có bản sao lưu hoặc git. Nếu thấy thay đổi không ổn, hãy khôi phục từ bản sao lưu thay vì nhờ agent sửa chồng lên.

### Không biết điền khoá hay đăng nhập dịch vụ AI ở đâu

README chưa có thông tin này. Bạn xem mục cấu hình trong tài liệu chính thức tại opencode.ai/docs, hoặc hỏi ở Discord của dự án. Đừng dán khoá API vào các nơi công khai khi nhờ người khác giúp.

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

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

**Giới hạn.** README rất ngắn: chưa ghi lệnh khởi chạy, yêu cầu về phiên bản Node, cách kết nối dịch vụ AI hay chi phí. Bạn phải đọc thêm tài liệu chính thức. Bản desktop vẫn là beta. Tên gói npm giữa README và thông tin repo chưa khớp, nên người mới có thể vấp ở bước này. Ngoài ra, giống mọi agent lập trình, nó chạy trên máy bạn và có thể sửa file, nên cần thói quen sao lưu.

**Khi nào chọn cách khác.** Nếu bạn chỉ cần hỏi đáp đơn giản về code, một khung chat thông thường có thể đủ. Nếu bạn hoàn toàn không đụng code và không muốn tự cài đặt, opencode chưa phải thứ "mở ra là dùng" ngay. Ngược lại, nếu bạn muốn một trợ lý lập trình mã nguồn mở, kiểm soát được và có chế độ chỉ đọc để làm quen dự án, opencode đáng để thử.

## 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. Tuy nhiên README chưa nói gì về chi phí dùng mô hình AI hay dịch vụ đi kèm. Bạn nên xem tài liệu chính thức trước khi dùng nhiều.

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

Có bản desktop (beta) cho Windows, tên file là `opencode-desktop-win-x64.exe`. Với dòng lệnh, README liệt kê `npm i -g` và `mise use -g` (ghi là dùng được trên mọi hệ điều hành), còn lệnh curl cần môi trường bash. README chưa có hướng dẫn riêng cho Windows ngoài các lựa chọn này.

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

`build` là agent mặc định, có 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 xin phép trước khi chạy lệnh bash. Bạn đổi giữa hai chế độ bằng phím `Tab`.

### Tôi có cần GPU hay máy cấu hình mạnh không?

README chưa có thông tin về yêu cầu phần cứng. Bạn nên xem tài liệu chính thức của dự án để biết rõ.

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

README không nói về cách xử lý dữ liệu, nên mình không có thông tin để khẳng định. Vì agent có thể đọc file và chạy lệnh trên máy bạn, hãy thử trên dự án có sao lưu, dùng chế độ `plan` trước, và đừng để lộ khoá API. Repo có file SECURITY.md để bạn tham khảo chính sách bảo mật.

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

Với người ngại terminal, tải bản desktop (beta) từ trang opencode.ai/download là dễ nhất. Với người quen dòng lệnh, có thể dùng một dòng curl, npm, Homebrew hoặc mise như README liệt kê. Trên Mac, Homebrew với kho `anomalyco/tap` được README khuyên dùng vì luôn mới.

### Tôi nên xem hướng dẫn cấu hình ở đâu?

README chỉ dẫn đến tài liệu chính thức tại opencode.ai/docs, trong đó có mục về agents. Dự án cũng có cộng đồng trên Discord và X.com để hỏi thêm.
