# 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 agent lập trình AI mã nguồn mở (giấy phép MIT), viết bằng TypeScript. Nó giúp bạn đọc, hỏi đáp và sửa code ngay trong dự án. Cài khá dễ: chỉ một dòng lệnh, hoặc tải ứng dụng desktop bản beta.

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

opencode là một agent lập trình AI mã nguồn mở. Hiểu đơn giản: bạn mở nó trong thư mục dự án, ra lệnh bằng tiế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".

Repo này hợp với lập trình viên mới muốn có một "người cùng làm" ngay trong terminal. Nó cũng hợp với người làm kinh doanh, văn phòng hay phải đụng vào một ít code hoặc script nhưng không muốn đọc từng dòng. Repo hiện có khoảng 226.506 sao và 30.658 fork, được cập nhật trong 3 tháng gần đây. Giấy phép MIT, nên bạn dùng tự do.

Điểm đáng giá nhất là cách chia hai chế độ rõ ràng. Chế độ `build` được toàn quyền làm việc. Chế độ `plan` chỉ đọc, để bạn khám phá code lạ mà không sợ nó sửa nhầm. Bạn đổi giữa hai chế độ bằng một 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, chạy bằng dòng lệnh hoặc ứng dụng desktop (beta).
- stars | 227k
- lang | TypeScript
- license | MIT
```

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

Mình tóm các tính năng chính theo README, kèm lợi ích thực tế.

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

- **build**: agent mặc định, có đầy đủ quyền cho công việc phát triển. Dùng khi bạn đã biết mình muốn gì và muốn nó bắt tay vào làm.
- **plan**: agent chỉ đọc, dùng để phân tích và khám phá code. Mặc định nó từ chối sửa file. Trước khi chạy lệnh bash, nó hỏi xin phép bạn.

Lợi ích: bạn tách được "nghĩ" và "làm". Mở dự án lạ, cứ bật `plan` để hỏi han trước. Khi hiểu rồi mới chuyển sang `build`.

### Subagent general cho việc tìm kiếm và nhiều bước

Ngoài hai agent trên còn có subagent `general`, dành cho các tìm kiếm phức tạp hoặc tác vụ 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. Khi câu hỏi kiểu "tìm giúp mình chỗ nào trong dự án xử lý việc này" mà kết quả nằm rải rác, đây là công cụ nên thử.

### Chạy bằng dòng lệnh hoặc ứng dụng desktop

Bạn có thể cài qua một dòng lệnh, qua nhiều trình quản lý gói (npm, brew, pacman, mise, nix), hoặc dùng ứng dụng desktop (BETA) cho macOS, Windows và Linux. Ai ngại terminal có thể bắt đầu bằng ứng dụng desktop.

### Mã nguồn mở, có tài liệu và cộng đồng

Có trang tài liệu cấu hình riêng tại opencode.ai/docs, cùng cộng đồng trên Discord và X. README có bản dịch tiếng Việt (README.vi.md) trong repo, bạn có thể đọc thêm.

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

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

- **Hệ điều hành**: README liệt kê cài được trên macOS, Linux (kể cả Arch Linux), và ứng dụng desktop cho Windows. Lệnh `curl ... | bash` là lệnh shell kiểu Linux/macOS. README không nói cách chạy lệnh này trên Windows. Người dùng Windows nên ưu tiên ứng dụng desktop.
- **Trình quản lý gói**: tuỳ cách cài bạn chọn, bạn cần npm (hoặc bun/pnpm/yarn), Homebrew, pacman, mise hoặc 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.
- **Tài khoản, API key, phần cứng**: README chưa ghi. Phần cấu hình nằm ở trang tài liệu opencode.ai/docs, bạn xem ở đó để biết cần khai báo gì.

```note
README chưa nói rõ chuyện API key và chi phí. Trước khi dùng nhiều, hãy đọc tài liệu cấu hình của dự án để biết bạn đang kết nối với dịch vụ AI nào và có bị tính phí không. Đừng dán key vào chỗ người khác nhìn thấy được.
```

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

```steps
- Gỡ bản cũ | Nếu từng cài phiên bản trước 0.1.x thì gỡ đi
- Chọn cách cài | Dòng lệnh một phát, trình quản lý gói, hoặc ứng dụng desktop
- Chạy lệnh cài | Dán đúng lệnh trong README vào terminal
- Mở thư mục dự án | Vào đúng thư mục code bạn muốn làm việc
- Đọc tài liệu cấu hình | Xem opencode.ai/docs để khai báo những gì cần thiết
```

### Bước 1: Gỡ 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. Nếu đây là lần đầu bạn dùng, bỏ qua bước này. README không nêu lệnh gỡ cụ thể. Bạn gỡ theo cách mà bạn đã dùng để cài bản cũ.

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

README đưa ra nhiều cách. Bạn chỉ cần chọn MỘT. Người mới nên chọn dòng đầu tiên hoặc trình quản lý gói bạn đã có sẵn.

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

Mở terminal (macOS: ứng dụng Terminal; Linux: cửa sổ terminal), rồi dán một dòng bên dưới. Đây là các lệnh nguyên văn từ README:

```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 để bạn khỏi vấp:

- Dòng `curl ... | bash` tải script cài đặt rồi chạy luôn. README gọi nó là "YOLO" vì bạn chạy thẳng mà không đọc script trước. Nếu muốn cẩn thận, hãy mở địa chỉ script ra đọc trước.
- Script này cài opencode vào thư mục `$HOME/.opencode/bin`.
- Các dòng còn lại là cài qua trình quản lý gói. Chỉ chọn một dòng, đừng chạy hết. Nếu chạy hết, bạn sẽ có nhiều bản cài chồng nhau.
- Với Homebrew, README ghi `anomalyco/tap/opencode-v2` là bản khuyến nghị và luôn mới. Còn `brew install opencode` là công thức chính thức nhưng cập nhật chậm hơn.
- Phần sau dấu `#` là ghi chú, bạn không cần gõ.

### Bước 3b: Hoặc cài ứng dụng desktop (BETA)

Nếu bạn không thích terminal, tải ứng dụng ở opencode.ai/download. README liệt kê các tệp:

| Nền tảng | Tệp 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ó thể cài bằng Homebrew:

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

### Bước 4: Mở thư mục dự án

README không có hướng dẫn riêng cho bước này. Mình nói theo cách thông thường: bạn cần đứng trong thư mục dự án của mình trước khi làm việc với agent, để nó thấy đúng code. Ví dụ:

```bash
cd ten-thu-muc-du-an-cua-ban
```

Thay `ten-thu-muc-du-an-cua-ban` bằng đường dẫn thật. Nếu muốn thử bản mã nguồn, bạn có thể lấy về bằng `git clone https://github.com/anomalyco/opencode.git`, nhưng với người dùng thông thường thì không cần.

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

README chỉ nói: muốn biết cách cấu hình opencode, hãy xem tài liệu tại opencode.ai/docs. Các chi tiết như khai báo nhà cung cấp AI, key, quyền hạn đều nằm ở đó. Mình không ghi lại để tránh nói sai.

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

README không có mục "kiểm tra cài đặt" hay lệnh mẫu để thử. Mình gợi ý cách hợp lý, nhưng bạn hãy đối chiếu tài liệu chính thức:

- Với ứng dụng desktop: mở ứng dụng lên, nếu cửa sổ hiện ra và bạn nhập được tin nhắn thì cài ổn.
- Với bản dòng lệnh: đóng terminal cũ, mở terminal mới, rồi thử gọi chương trình theo tên gói là `opencode`. README không ghi rõ lệnh khởi động. Nếu terminal báo không tìm thấy lệnh, xem mục lỗi bên dưới.
- Khi giao diện lên, thử bấm `Tab`. README nói phím này đổi giữa hai agent `build` và `plan`. Nếu thấy chế độ đổi, bạn đã chạy đúng.

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

Dưới đây là các tình huống bám đúng khả năng README mô tả: hai agent, subagent `@general`, và đổi chế độ bằng `Tab`. Câu lệnh mẫu chỉ là cách bạn nhắn bằng tiếng thường, không phải cú pháp bắt buộc.

### Dev mới nhận dự án lạ

Bối cảnh: bạn mới vào công ty, được giao một dự án mà không ai có thời gian giải thích. Bạn sợ chạm vào sẽ làm hỏng.

Cách làm: mở opencode trong thư mục dự án, giữ ở chế độ `plan` (chỉ đọc). Hỏi những câu như:

```text
Dự án này làm gì? Các thư mục chính dùng để làm gì?
Tính năng đăng nhập nằm ở đâu trong code?
```

Kết quả: bạn có bản đồ sơ bộ của dự án. Chế độ `plan` mặc định từ chối sửa file và hỏi xin phép trước khi chạy lệnh bash, nên rủi ro thấp.

> Cứ để nó đọc trước, chỉ cho nó sửa khi bạn đã hiểu nó định làm gì.
>
> — Ông T

### Chủ shop nhờ sửa một script nhỏ

Bối cảnh: bạn có một script đổi định dạng file đơn hàng do người quen viết. Giờ file xuất ra thêm một cột, script bị lỗi.

Cách làm: đứng trong thư mục chứa script, bật `plan` để nhờ giải thích script đang làm gì và lỗi chắc nằm ở đâu. Hiểu rồi thì nhấn `Tab` sang `build` và nhắn:

```text
File đầu vào giờ có thêm một cột. Hãy sửa script cho chạy lại bình thường và giữ nguyên các cột cũ.
```

Kết quả: agent đề xuất và thực hiện chỉnh sửa. Bạn nên sao lưu file gốc trước khi cho nó sửa, và đọc lại thay đổi trước khi dùng cho đơn hàng thật.

### Nhân viên văn phòng cần tìm thứ nằm rải rác

Bối cảnh: thư mục dự án của nhóm có hàng chục file, bạn cần biết chỗ nào nhắc đến một thông số cụ thể (ví dụ tên một khách hàng hoặc một mức phí).

Cách làm: nhờ subagent `general` bằng cách gọi `@general` trong tin nhắn:

```text
@general Tìm giúp mình tất cả chỗ nhắc đến "phí vận chuyển" và tóm tắt mỗi chỗ trong một dòng.
```

Kết quả: danh sách vị trí kèm tóm tắt, thay vì bạn phải mở từng file. README mô tả `general` dành cho tìm kiếm phức tạp và tác vụ nhiều bước, đúng với kiểu việc này.

### Lên kế hoạch trước khi thay đổi lớn

Bối cảnh: bạn muốn đổi cách tính giá trong một ứng dụng nhưng chưa rõ ảnh hưởng đến những đâu.

Cách làm: ở chế độ `plan`, hỏi:

```text
Nếu mình muốn đổi cách tính giá, cần sửa những file nào? Liệt kê thứ tự nên làm.
```

Kết quả: một danh sách các bước, chưa có file nào bị sửa. Bạn có thể đưa danh sách này cho đồng nghiệp xem lại, rồi mới chuyển sang `build` để thực hiện.

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

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

Thường do terminal chưa nhận đường dẫn mới sau khi cài. Hãy đóng hẳn terminal rồi mở lại. Nếu bạn cài bằng script, tệp nằm ở `$HOME/.opencode/bin`. Hãy kiểm tra thư mục này có tồn tại không. README không nói thêm về việc thêm vào PATH, nên xem tài liệu nếu vẫn không được.

### Cài chồng nhiều cách rồi bị lẫn phiên bản

README đưa nhiều cách cài song song. Nếu bạn chạy hết, máy có thể có vài bản khác nhau. Hãy gỡ bớt, chỉ giữ một cách. Nhớ rằng README khuyên gỡ bản cũ hơn 0.1.x trước khi cài.

### Agent sửa file ngoài ý muốn

Chế độ `build` có đầy đủ quyền. Nếu bạn chỉ muốn hỏi và xem, hãy chuyển sang `plan` bằng phím `Tab`. Với dự án quan trọng, hãy sao lưu hoặc dùng Git để quay lại bản trước nếu cần.

### Chạy lệnh `curl ... | bash` trên Windows không được

Đây là lệnh shell cho macOS/Linux, và README không hướng dẫn cách chạy trên Windows. Cách an toàn là tải ứng dụng desktop `opencode-desktop-win-x64.exe` từ opencode.ai/download.

### Không biết điền key hay cấu hình nhà cung cấp AI ở đâu

Đây là chỗ người mới hay vấp nhất. README chưa ghi. Hãy mở opencode.ai/docs và làm theo phần cấu hình. Không dán key vào các đoạn chat công khai hay file bạn sẽ chia sẻ.

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

**Điểm mạnh**

- Mã nguồn mở, giấy phép MIT, dùng và xem code tự do.
- Có chế độ `plan` chỉ đọc, hợp để khám phá code lạ một cách an toàn.
- Nhiều cách cài, có cả ứng dụng desktop cho Windows, macOS, Linux.
- Cộng đồng lớn (khoảng 226.506 sao) và repo còn được cập nhật.

**Giới hạn**

- Ứng dụng desktop vẫn là BETA, có thể chưa ổn định bằng bản dòng lệnh.
- README rất ngắn. Mọi chi tiết về cấu hình, key, chi phí phải đọc ở tài liệu riêng.
- Chế độ `build` có toàn quyền, nên bạn cần cẩn thận và kiểm tra kết quả, nhất là với dữ liệu thật.
- Lệnh cài kiểu "YOLO" chạy script thẳng từ mạng, bạn nên cân nhắc đọc trước.

**Khi nào nên chọn cách khác**

Nếu bạn hoàn toàn không đụng đến code hay script, một chatbot thông thường là đủ. Nếu công ty bạn có quy định chặt về dữ liệu, hãy tìm hiểu kỹ dữ liệu của bạn đi đâu khi dùng agent. README chưa có thông tin về điều này.

Tóm lại: nếu bạn muốn một trợ lý lập trình AI mã nguồn mở, có chế độ đọc-chỉ để thử trước, thì opencode đáng cài thử. Hãy bắt đầu ở chế độ `plan` và cho nó sửa file khi bạn đã yên tâm.

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

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

Có ứng dụng desktop bản BETA cho Windows, tệp `opencode-desktop-win-x64.exe`, tải ở opencode.ai/download. Lệnh cài `curl ... | bash` là kiểu shell Linux/macOS, README không hướng dẫn chạy nó trên Windows. Bạn nên ưu tiên ứng dụng desktop.

### 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. Chưa có thông tin về việc cần GPU hay không. Bạn nên xem thêm trong tài liệu chính thức.

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

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

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

`general` là subagent dành cho các tìm kiếm phức tạp và tác vụ 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.

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

README không nói về việc dữ liệu được xử lý hay gửi đi đâu, nên chưa có thông tin để kết luận. Hãy đọc tài liệu và chính sách của nhà cung cấp AI mà bạn kết nối. Với dự án quan trọng, bạn nên dùng chế độ `plan` và sao lưu trước khi cho sửa.

### Có cần gỡ phiên bản cũ trước khi cài không?

README khuyên gỡ các phiên bản cũ hơn 0.1.x trước khi cài. Nếu đây là lần đầu bạn dùng thì không cần làm gì thêm.
