# OpenCode: trợ lý lập trình AI mã nguồn mở chạy ngay trong terminal — hướng dẫn cài đặt và dùng

> OpenCode là một coding agent (trợ lý lập trình AI) mã nguồn mở, giấy phép MIT, viết bằng TypeScript. Bạn cài bằng một dòng lệnh, trình quản lý gói hoặc tải bản desktop (đang BETA), rồi dùng nó để đọc, phân tích và sửa code. Cài đặt khá dễ, nhưng README không ghi cách nối với mô hình AI nên bạn cần xem thêm tài liệu trên trang chủ.

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

OpenCode là một coding agent mã nguồn mở: một trợ lý AI đọc code trong thư mục dự án của bạn, trả lời câu hỏi về code, rồi giúp bạn sửa hoặc viết thêm. Mô tả của tác giả rất gọn: «The open source coding agent». Repo viết bằng TypeScript, dùng giấy phép MIT, hiện có khoảng 226.506 sao và 30.658 fork. Đây là con số khá lớn, cho thấy rất nhiều người đang dùng và theo dõi.

Bạn nên xem thử nếu bạn là lập trình viên mới, người làm văn phòng hay chủ shop có biết chút ít về code. Ví dụ bạn có một file kế toán viết bằng script, một website bán hàng nhỏ, hoặc một đống code kế thừa mà không ai dám đụng vào. Thay vì đọc từng dòng, bạn nhờ trợ lý giải thích hoặc đề xuất chỉnh sửa.

Điểm đáng giá nhất là OpenCode có sẵn hai chế độ làm việc. Một chế độ được quyền sửa file để làm việc thật. Một chế độ chỉ đọc để bạn khám phá và lên kế hoạch mà không sợ nó đổi nhầm thứ gì. Bạn chuyển qua lại chỉ bằng phím Tab.

```repo
- repo | anomalyco/opencode
- kind | Agent
- desc | OpenCode là agent lập trình AI mã nguồn mở, có hai chế độ build và plan, cài bằng một dòng lệnh hoặc dùng bản ứng dụng desktop.
- stars | 227k
- lang | TypeScript
- license | MIT
```

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

Dưới đây là những điểm chính mà README nói đến, kèm lợi ích thực tế.

### Hai agent có sẵn: build và plan

OpenCode đi kèm hai agent, và bạn đổi qua lại bằng phím `Tab`.

- **build** là agent mặc định, có đầy đủ quyền cho công việc phát triển. Bạn dùng nó khi muốn nhờ 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 việc sửa file và hỏi quyền bạn trước khi chạy lệnh bash.

Lợi ích: khi mở một dự án lạ, bạn bật plan trước để hiểu cấu trúc và lên kế hoạch. Chỉ khi hài lòng bạn mới chuyển sang build. Cách này giảm rủi ro AI sửa lung tung.

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

Ngoài hai agent trên còn có một subagent tên **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 dùng nó nội bộ, và bạn cũng có thể gọi trực tiếp bằng `@general` trong tin nhắn. Khi câu hỏi kiểu «tìm giúp mình mọi chỗ đang xử lý thanh toán» thì đây là công cụ hợp lý.

### Nhiều cách cài, nhiều nền tảng

Bạn có thể cài bằng script, npm, Homebrew, pacman (Arch Linux), mise, hoặc chạy bằng Nix. Ngoài ra còn có bản ứng dụng desktop (BETA) cho macOS, Windows và Linux. Người không quen terminal có thể chọn bản desktop cho dễ.

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

Bạn đọc được toàn bộ mã nguồn, dùng và sửa theo giấy phép MIT. Với doanh nghiệp nhỏ, điều này giúp yên tâm hơn về việc bị khoá vào một nhà cung cấp.

### Tài liệu và cộng đồng

README có nhiều bản dịch, trong đó có tiếng Việt (file README.vi.md trong repo). Tài liệu cấu hình nằm ở trang chủ dự án, ngoài ra còn có cộng đồng trên Discord và X.

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

README chỉ nói ít về yêu cầu, nên mình liệt kê đúng những gì có trong tư liệu.

- **Hệ điều hành:** bản desktop có file cho macOS (Apple Silicon và Intel), Windows (`opencode-desktop-win-x64.exe`) và Linux (`.deb`, `.rpm`, `.AppImage`). Các cách cài bằng dòng lệnh nhắc đến macOS, Linux, Arch Linux, Nix và mise («Any OS»).
- **Công cụ cài đặt:** tuỳ cách bạn chọn, bạn cần `curl` và bash, hoặc npm (bun/pnpm/yarn cũng được), hoặc Homebrew, hoặc mise, hoặ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.
- **Tài khoản, API key, phần cứng:** README không nói. Một coding agent thường cần nối với một mô hình AI, nhưng cách nối cụ thể README chưa ghi. Bạn xem phần cấu hình trong tài liệu tại trang chủ dự án.

```note
README không nói OpenCode tính phí hay dùng mô hình nào. Nếu bạn nối nó với dịch vụ AI có tính tiền theo lượng dùng, hãy kiểm tra chi phí trước, và đừng dán API key vào file code hoặc chia sẻ lên mạng.
```

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

```steps
- Chọn cách cài | Chọn một trong: script, npm, Homebrew, pacman, mise, Nix hoặc bản desktop
- Mở terminal | Mở cửa sổ dòng lệnh trên máy của bạn
- Chạy lệnh cài | Dán đúng một dòng lệnh từ README
- Vào thư mục dự án | Dùng cd để vào thư mục code bạn muốn làm việc
- Xem tài liệu cấu hình | Đọc docs ở trang chủ để nối mô hình AI và bắt đầu
```

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

README liệt kê rất nhiều cách. Bạn chỉ cần chọn một. Gợi ý theo người dùng:

- Người dùng macOS hoặc Linux quen Homebrew: dùng `brew`.
- Người đã có Node và npm: dùng `npm`.
- Người dùng Windows hoặc không thích gõ lệnh: dùng bản desktop (phần cuối bước 3).

### Bước 2: Mở terminal

Trên macOS và Linux, mở ứng dụng Terminal. Trên Windows, bạn có thể dùng PowerShell hoặc Windows Terminal cho các lệnh như npm. Riêng dòng `curl ... | bash` cần có bash, nên README không nói rõ nó chạy trên Windows thế nào. Nếu bạn dùng Windows và chưa rõ, hãy chọn npm, mise hoặc bản desktop.

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

Đây là toàn bộ các lệnh có trong README. 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 ngắn:

- Dòng đầu (ghi chú «YOLO») tải script cài từ trang chủ rồi chạy luôn. Nhanh, nhưng bạn đang chạy một script mà chưa đọc nó. Nếu muốn an toàn hơn, hãy chọn một trình quản lý gói.
- `npm i -g ...` cài toàn cục qua npm. README ghi bạn có thể thay npm bằng bun, pnpm hoặc yarn.
- Hai dòng `brew` dành cho macOS và Linux. README ghi dòng `anomalyco/tap/opencode-v2` là bản khuyên dùng và luôn mới nhất, còn dòng `brew install opencode` là công thức chính thức của Homebrew nhưng cập nhật chậm hơn.
- `pacman` và `paru` dành cho Arch Linux (bản ổn định và bản mới nhất từ AUR).
- `mise` dùng được trên mọi hệ điều hành.
- `nix run ...` chạy thẳng bằng Nix, không cài lâu dài.

Chỗ dễ vấp: các dòng có chữ sau dấu `#` chỉ là ghi chú, bạn không cần gõ phần đó. Ngoài ra, bạn chỉ nên chọn một cách, đừng cài chồng nhiều cách lên nhau. README cũng nhắc gỡ bản cũ hơn 0.1.x trước khi cài.

```note
Script cài đặt đặt OpenCode vào thư mục $HOME/.opencode/bin. Nếu sau khi cài mà terminal báo không tìm thấy lệnh, hãy kiểm tra xem thư mục này đã nằm trong PATH của bạn chưa.
```

**Dùng bản desktop (BETA):** tải từ trang opencode.ai/download. Windows tải file `opencode-desktop-win-x64.exe`. macOS có file `.dmg` cho Apple Silicon và Intel. Linux có `.deb`, `.rpm` hoặc `.AppImage`. Người dùng macOS cũng có thể cài bằng Homebrew:

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

Lệnh `--cask` dành cho các ứng dụng có giao diện đồ hoạ trên macOS.

### Bước 4: Vào thư mục dự án

Bạn nên làm việc bên trong thư mục của dự án cần xử lý, để trợ lý chỉ nhìn thấy code của dự án đó. Ví dụ với một repo trên GitHub:

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

Đây chỉ là ví dụ về cách vào một thư mục. Thực tế bạn `cd` vào thư mục dự án của chính bạn.

### Bước 5: Xem tài liệu để cấu hình

README chưa ghi lệnh mở chương trình, cách nối với mô hình AI hay cách nhập API key. Bạn xem phần hướng dẫn cấu hình ở trang chủ dự án (opencode.ai/docs). Phần giới thiệu về agent nằm ở opencode.ai/docs/agents.

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

README không đưa ra lệnh kiểm tra phiên bản hay màn hình mong đợi. Vì vậy mình chỉ gợi ý những dấu hiệu chung, và bạn nên đối chiếu với tài liệu chính thức:

- Lệnh cài chạy xong mà không báo lỗi đỏ.
- Với script cài, thư mục `$HOME/.opencode/bin` đã được tạo.
- Với bản desktop, ứng dụng mở lên được sau khi cài.
- Khi mở OpenCode, bạn thử bấm `Tab`. README nói phím này chuyển giữa agent build và plan, nên nếu thấy chế độ đổi là bạn đã vào đúng giao diện.

Nếu chưa chắc, bạn mở trang tài liệu để xem cách chạy lần đầu.

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

README không đưa ví dụ prompt cụ thể. Các tình huống dưới đây bám đúng những gì README mô tả: agent plan để khám phá, agent build để làm, `@general` để tìm kiếm nhiều bước. Câu lệnh mẫu chỉ là gợi ý cách bạn có thể nhập, bạn tự điều chỉnh theo dự án.

> Cứ để plan đọc trước, chỉ khi hiểu rồi mới cho build ra tay.
>
> — Ông T

### Làm quen với một dự án lạ

Bối cảnh: bạn là lập trình viên mới, vừa được giao một repo của công ty mà không có ai hướng dẫn. Bạn mở OpenCode trong thư mục dự án và giữ ở chế độ plan, vì README ghi rõ plan rất hợp để khám phá codebase lạ. Rồi bạn hỏi kiểu: «Dự án này có những phần chính nào, file nào xử lý đăng nhập?». Kết quả: bạn nhận một bản giải thích cấu trúc mà không có file nào bị sửa, vì plan từ chối sửa file theo mặc định.

### Lên kế hoạch trước khi sửa

Bối cảnh: chủ shop online nhờ bạn thêm tính năng tính phí vận chuyển theo khu vực vào website. Bạn để plan đọc code và đề xuất các bước cần sửa. Khi kế hoạch hợp lý, bạn bấm `Tab` để sang build rồi nhờ làm theo kế hoạch đó. Kết quả: bạn kiểm soát được từng bước, và biết trước những file nào sẽ bị đụng tới.

### Tìm kiếm nhiều bước bằng @general

Bối cảnh: dự án có hàng trăm file và bạn cần biết mọi chỗ đang dùng một hàm cũ trước khi đổi tên. Bạn gõ trong tin nhắn: `@general tìm tất cả chỗ gọi hàm tính giá và tóm tắt lại`. README nói general dành cho các tìm kiếm phức tạp và công việc nhiều bước. Kết quả: bạn nhận danh sách các chỗ liên quan để tự rà soát.

### Chạy lệnh bash có kiểm soát

Bối cảnh: nhân viên văn phòng biết chút script, muốn nhờ AI chạy thử một lệnh để kiểm tra kết quả. Ở chế độ plan, OpenCode hỏi quyền bạn trước khi chạy bash. Bạn đọc kỹ lệnh được đề xuất rồi mới đồng ý. Kết quả: bạn vẫn là người quyết định cuối cùng, không bị chạy lệnh ngoài ý muốn.

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

README không có mục xử lý lỗi, nên mấy lỗi dưới đây là những tình huống rất dễ gặp với loại công cụ này. Bạn đối chiếu thêm với tài liệu chính thức.

### Terminal báo không tìm thấy lệnh sau khi cài

Nguyên nhân thường là thư mục chứa chương trình chưa nằm trong PATH, hoặc terminal chưa nạp lại. Với script cài, chương trình nằm ở `$HOME/.opencode/bin`. Bạn đóng terminal mở lại, rồi kiểm tra thư mục này đã có trong PATH chưa.

### Cài chồng nhiều cách hoặc còn bản cũ

Nếu bạn cài bằng cả npm lẫn Homebrew, máy có thể có hai bản và lệnh gọi nhầm bản cũ. README cũng khuyên gỡ bản cũ hơn 0.1.x trước khi cài. Hãy gỡ bản cũ rồi chỉ giữ một cách cài.

### Nhầm tên gói

README có nhiều tên gói gần giống nhau: `opencode`, `opencode-v2`, `opencode-beta`, `@opencode/cli`. Mỗi trình quản lý gói dùng một tên riêng. Bạn hãy chép đúng nguyên dòng lệnh trong README, đừng tự sửa tên. Cũng cần cảnh giác với các dự án khác có chữ «opencode» trong tên, vì README nhắc rằng những dự án như vậy không phải do nhóm OpenCode làm.

### Agent không cho sửa file

Nếu bạn bảo sửa mà không thấy file nào thay đổi, rất có thể bạn đang ở chế độ plan, vốn từ chối sửa file theo mặc định. Bấm `Tab` để chuyển sang build.

### Chưa nối được với mô hình AI

README không nói cách nhập key hay chọn mô hình. Nếu OpenCode mở lên mà không trả lời, hãy đọc phần cấu hình trong tài liệu ở trang chủ. Khi nhập key, nhớ cất kín, không dán vào chat công khai.

## 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.
- Có hai chế độ build và plan rõ ràng. Chế độ plan chỉ đọc và hỏi quyền trước khi chạy bash, rất hợp cho người mới.
- Nhiều cách cài, có cả bản desktop cho Windows, macOS và Linux.
- Có bản README tiếng Việt trong repo.

**Giới hạn:**

- README ngắn, chưa ghi lệnh mở chương trình, cách nối mô hình AI hay yêu cầu phần cứng. Bạn phải đọc thêm tài liệu trên trang chủ.
- Bản desktop đang ở mức BETA.
- Danh sách lệnh cài khá nhiều tên gói gần giống nhau, người mới dễ rối.
- Mình chưa có thông tin về chi phí, mức độ an toàn dữ liệu hay cách so sánh với các công cụ cùng loại, vì tư liệu không nói.

**Khi nào nên chọn cách khác:** nếu bạn hoàn toàn không muốn dùng terminal và cũng không muốn thử bản BETA, hoặc cần tài liệu tiếng Việt đầy đủ từng bước, thì nên xem thêm các công cụ khác. Còn nếu bạn muốn một trợ lý lập trình mở, linh hoạt và sẵn sàng đọc docs thêm một chút, OpenCode đáng để thử trên một dự án nhỏ trước.

## 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ở, giấy phép MIT, nên bạn được dùng và xem mã nguồn. README không nói gì về chi phí của mô hình AI mà bạn nối vào. Mình chưa có thông tin về điểm này, bạn xem tài liệu trên trang chủ dự án.

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

Có bản ứng dụng desktop cho Windows, file `opencode-desktop-win-x64.exe`, tải từ opencode.ai/download (đang BETA). README cũng nhắc cách cài mise «Any OS» và npm. Riêng dòng curl dùng bash thì README không nói rõ cách chạy trên Windows.

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

README không nêu yêu cầu phần cứng nào. Mình chưa có thông tin về việc này, bạn xem thêm tài liệu của dự án.

### Agent build và plan khác nhau thế nào?

Build là agent mặc định, có đầy đủ quyền để làm việc phát triển. Plan chỉ đọc: mặc định từ chối sửa file và hỏi quyền trước khi chạy bash. Bạn bấm phím Tab để chuyển qua lại.

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

README không mô tả chi tiết về chuyện này. Repo có file SECURITY.md, bạn có thể đọc để biết chính sách bảo mật. Bạn cũng nên dùng chế độ plan khi chưa muốn AI sửa file, và đọc kỹ các lệnh bash trước khi đồng ý chạy.

### Tên gói npm là gì, cài bằng lệnh nào?

Tư liệu ghi tên gói npm là opencode. Trong README, lệnh npm ghi là `npm i -g @opencode/cli@latest` (có thể thay npm bằng bun, pnpm hoặc yarn). Bạn nên chép đúng dòng lệnh trong README.

### Mình có thể góp ý hoặc đóng góp code cho OpenCode không?

Có. Repo có file CONTRIBUTING.md hướng dẫn đóng góp, và README nhắc bạn đọc kỹ trước khi gửi pull request. Cộng đồng có Discord và X.com. Nếu bạn làm dự án riêng có chữ «opencode» trong tên, README yêu cầu ghi rõ là không liên kết với nhóm OpenCode.
