# 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 (repo 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ó giúp bạn đọc hiểu, lên kế hoạch và sửa code bằng ngôn ngữ thường. Cài khá dễ: có script một dòng, nhiều trình quản lý gói, và bản desktop (BETA) cho macOS, Windows, Linux.

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

opencode là một **agent lập trình AI mã nguồn mở**: bạn mô tả việc cần làm bằng lời thường, nó đọc code trong dự án và giúp bạn khám phá, lên kế hoạch hoặc sửa. Tác giả giới thiệu ngắn gọn repo là "The open source coding agent". Hiện repo có khoảng 226 nghìn sao và khoảng 30 nghìn fork, giấy phép MIT, và vẫn được cập nhật trong 3 tháng gần đây.

Bạn nên đọc bài này nếu là lập trình viên mới muốn có một "người phụ" đọc hộ code lạ, hoặc người làm kinh doanh, văn phòng có một dự án nhỏ (website, file script, công cụ nội bộ) và muốn có AI hỗ trợ ngay trong thư mục làm việc. Bạn không cần là chuyên gia, nhưng nên biết mở terminal và chạy một dòng lệnh.

Điểm đáng giá nhất theo mình là **hai chế độ làm việc tách bạch**. Chế độ `plan` chỉ đọc, không tự sửa file, rất hợp khi bạn còn lạ code. Chế độ `build` mới có toàn quyền chỉnh sửa. Ngoài ra repo còn có bản desktop (BETA) cho người không thích terminal.

```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 desktop.
- stars | 227k
- lang | TypeScript
- license | MIT
```

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

Dưới đây là những gì README nói rõ. Mình không thêm tính năng nào ngoài tư liệu.

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

opencode có hai agent dựng sẵn và bạn chuyển qua lại bằng phím `Tab`.

- **build**: agent mặc định, toàn quyền cho công việc phát triển. Dùng khi bạn đã biết mình muốn gì và để 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 và sẽ hỏi bạn trước khi chạy lệnh bash.

Lợi ích thực tế: bạn có thể cho AI "nhìn" dự án mà không lo nó tự ý đổi gì. README ghi rõ chế độ plan rất hợp để khám phá codebase lạ hoặc lên kế hoạch thay đổi.

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

Ngoài hai agent trên còn có subagent **general**, dành cho các tìm kiếm phức tạp và việc nhiều bước. Nó chủ yếu được dùng ngầm bên trong, nhưng bạn có thể gọi trực tiếp bằng `@general` trong tin nhắn. Hợp khi bạn cần lục nhiều chỗ trong dự án mới trả lời được một câu hỏi.

### Nhiều cách cài, cả terminal lẫn desktop

Bạn có thể cài bằng script một dòng, npm/bun/pnpm/yarn, Homebrew, pacman, paru, mise hoặc Nix. Ai không quen dòng lệnh có thể tải bản desktop (BETA) cho macOS, Windows và Linux. Cài dễ nghĩa là bạn mất ít thời gian hơn để bắt đầu thử.

### Mã nguồn mở, có tài liệu riêng

Giấy phép MIT, repo công khai, có tài liệu cấu hình tại trang chủ dự án (opencode.ai/docs) và README nhiều ngôn ngữ, trong đó có tiếng Việt. Khi cần chỉnh sâu, bạn xem tài liệu chứ không phải đoán.

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

Tư liệu README không liệt kê yêu cầu hệ thống chi tiết, nên mình chỉ nêu những gì có thật:

- **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 lệnh Homebrew, pacman và paru ghi cho macOS, Linux hoặc Arch Linux. `mise` ghi là dùng được trên mọi hệ điều hành.
- **Một công cụ cài đặt** nếu chọn cách cài bằng dòng lệnh: ví dụ npm (hoặc bun/pnpm/yarn), Homebrew, hoặc bash để chạy script cài.
- **Phiên bản Node/Python, GPU, RAM**: README chưa ghi yêu cầu cụ thể.
- **Tài khoản, API key, nhà cung cấp mô hình AI**: README chưa nói gì về việc này. Bạn xem trang tài liệu opencode.ai/docs để biết cách kết nối với mô hình AI.
- **Gỡ bản cũ**: README có lưu ý nên gỡ các phiên bản cũ hơn 0.1.x trước khi cài.

```note
Chưa có thông tin trong README về chi phí hay cách kết nối mô hình AI. Nếu sau này bạn dùng key của một dịch vụ AI có tính phí, hãy giữ key kín, không dán vào chat công khai, không đưa vào file rồi đẩy lên GitHub, và kiểm tra mức phí trên trang của nhà cung cấp.
```

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

```steps
- Gỡ bản cũ | Nếu từng cài opencode phiên bản dưới 0.1.x thì gỡ trước
- Chọn cách cài | Script một dòng, trình quản lý gói, hoặc bản desktop
- Chạy lệnh cài | Dán lệnh vào terminal và chờ cài xong
- Mở lại terminal | Để máy nhận lệnh mới, rồi kiểm tra
- Đọc tài liệu cấu hình | Xem opencode.ai/docs để kết nối mô hình AI
```

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

README ghi: 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 bạn gỡ theo đúng cách đã cài lúc trước (ví dụ nếu cài bằng npm thì gỡ bằng npm). Nếu bạn chưa từng cài opencode thì bỏ qua bước này.

### Cài bằng script một dòng

Đây là cách README gọi vui là "YOLO", vì chạy thẳng một script tải từ mạng. Hãy mở terminal (macOS, Linux; trên Windows nếu bạn có Git Bash thì mở Git Bash) và dán:

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

Lệnh này tải script cài từ trang chủ rồi chạy bằng bash. Theo README, script sẽ cài opencode vào thư mục `$HOME/.opencode/bin`. Nếu bạn muốn xem script trước khi chạy cho yên tâm, hãy mở địa chỉ đó trên trình duyệt để đọc.

### Hoặc cài bằng trình quản lý gói

Chọn đúng một dòng hợp với máy của bạn. Mình chép nguyên văn từ README:

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

Ghi chú cho người mới, vì đây là chỗ dễ vấp:

- **Chỉ chạy một dòng**, đừng dán cả khối. Mỗi dòng là một cách cài khác nhau.
- Dòng `npm i -g ...` cài toàn cục. Bạn cần đã có npm trên máy. Phần sau dấu `#` chỉ là chú thích, không cần gõ.
- Hai dòng `brew` khác nhau: dòng đầu (`anomalyco/tap/opencode-v2`) được README khuyên dùng vì luôn mới nhất; dòng thứ hai là công thức chính thức của Homebrew, cập nhật chậm hơn.
- `sudo` sẽ hỏi mật khẩu máy của bạn. Khi gõ mật khẩu, màn hình không hiện ký tự nào, đó là bình thường.

### Hoặc dùng bản desktop (BETA)

Nếu bạn không thích terminal, tải bản desktop từ trang opencode.ai/download. Theo README, tên file như sau:

- 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 bạn cũng có thể cài bản desktop bằng Homebrew:

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

Bản desktop đang ở mức BETA, nghĩa là có thể còn lỗi vặt. Người dùng Windows không rành dòng lệnh nên bắt đầu từ cách này.

### Đọc tài liệu để cấu hình

README chỉ dẫn chung: muốn biết cách cấu hình opencode, xem tài liệu tại opencode.ai/docs. Đây là nơi bạn tìm cách kết nối mô hình AI mà bạn muốn dùng. Mình không đoán thay README ở phần này.

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

README không ghi lệnh kiểm tra hay màn hình mong đợi. Bạn có thể tự kiểm tra như sau, theo thứ tự:

1. **Đóng hẳn terminal rồi mở lại.** Việc này giúp máy nhận thư mục cài mới (script cài vào `$HOME/.opencode/bin`).
2. **Thử gọi opencode.** README chưa ghi lệnh khởi động. Tên gói là `opencode`, nên bạn có thể thử gõ `opencode` trong thư mục dự án; nếu máy báo không tìm thấy lệnh thì xem mục lỗi bên dưới và trang tài liệu.
3. **Với bản desktop**, mở ứng dụng như bình thường. Nếu cửa sổ ứng dụng hiện lên là cài thành công.
4. **Thử phím Tab**: README nói bạn đổi giữa agent build và plan bằng phím `Tab`. Nếu đổi được thì giao diện đang hoạt động đúng.

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

Các tình huống dưới đây bám theo những gì README nói là opencode làm được: đổi agent bằng Tab, plan chỉ đọc, build toàn quyền, và `@general` cho tìm kiếm phức tạp. Câu lệnh mẫu là gợi ý của mình để bạn viết theo.

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

Bạn vừa vào công ty và được giao một repo mà không ai ghi chú gì. Hãy mở opencode trong thư mục dự án, bấm `Tab` để chọn agent **plan**, rồi hỏi:

```text
Dự án này làm gì? Liệt kê các thư mục chính và nói file nào là điểm bắt đầu.
```

Vì plan mặc định không sửa file và hỏi trước khi chạy bash, bạn có thể yên tâm khám phá. Kết quả là một bản tóm tắt cấu trúc dự án để bạn đỡ phải mò từng file.

> Cho AI đọc trước, sửa sau. Chế độ chỉ đọc giúp bạn hiểu dự án mà không sợ nó đổi gì.
>
> — Ông T

### Chủ shop có website nhỏ cần sửa một chỗ

Giả sử bạn có một trang web bán hàng nhỏ do người khác làm và muốn đổi dòng chữ khuyến mãi ở trang chủ. Trước hết ở chế độ plan, bạn hỏi:

```text
Dòng chữ khuyến mãi ở trang chủ nằm ở file nào? Nếu mình muốn đổi nội dung thì sửa thế nào?
```

Khi đã thấy kế hoạch hợp lý, bấm `Tab` sang **build** và yêu cầu nó làm đúng việc đó. Kết quả là một thay đổi nhỏ, rõ ràng. Hãy tự mở trang web lên xem lại trước khi dùng thật, và nên sao lưu thư mục trước khi để AI sửa.

### Nhân viên văn phòng tìm nơi dùng một cấu hình

Bạn có một bộ script nội bộ và muốn biết chỗ nào đang dùng một địa chỉ email cũ. Đây là kiểu tìm kiếm nhiều bước, hợp với subagent general. Bạn gọi trong tin nhắn:

```text
@general tìm tất cả chỗ trong dự án có dùng địa chỉ email cũ và cho mình danh sách file kèm dòng liên quan
```

Bạn nhận về danh sách vị trí cần xem. Sau đó có thể chuyển sang build để sửa từng chỗ, hoặc tự sửa nếu muốn kiểm soát hoàn toàn.

### Người không quen terminal muốn thử trước

Nếu bạn chỉ muốn xem opencode làm được gì mà chưa muốn đụng dòng lệnh, hãy tải bản desktop (BETA) cho hệ điều hành của mình, mở một thư mục dự án thử nghiệm, và đặt vài câu hỏi ở chế độ plan. Dùng thư mục thử, chưa phải dự án thật, là cách an toàn nhất để làm quen.

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

Phần này là những lỗi rất dễ xảy ra với công cụ cài qua dòng lệnh, không phải lỗi có trong README.

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

Nguyên nhân thường là terminal chưa nhận thư mục cài mới. Hãy đóng hẳn terminal rồi mở lại. Nếu vẫn lỗi và bạn cài bằng script, kiểm tra xem thư mục `$HOME/.opencode/bin` có tồn tại và đã nằm trong PATH của bạn chưa. Nếu cài bằng npm, hãy kiểm tra npm toàn cục đã được cấu hình đúng.

### Cài bằng npm hoặc brew báo không tìm thấy gói

README dùng nhiều tên khác nhau cho từng kênh (ví dụ `@opencode/cli` cho npm, `opencode-v2` trong tap của tác giả, `opencode` ở công thức Homebrew chính thức). Hãy chép đúng từng ký tự như trong bài, đừng tự đổi tên. Nếu vẫn không được, quay lại trang README hoặc opencode.ai/docs xem tên gói mới nhất.

### Cài trên Windows không chạy được script bash

Lệnh `curl ... | bash` cần có bash. Nếu bạn dùng Windows thường, hãy chọn bản desktop `opencode-desktop-win-x64.exe` từ trang tải. Đây là cách README liệt kê cho Windows.

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

README cảnh báo nên gỡ phiên bản cũ hơn 0.1.x trước khi cài. Nếu bạn thấy hành vi lạ sau khi cài, hãy kiểm tra xem máy có hai bản cài cùng lúc không (một bản npm và một bản script chẳng hạn) và gỡ bản không cần.

### AI sửa nhầm file

Chế độ build có toàn quyền chỉnh sửa. Cách an toàn: luôn bắt đầu ở chế độ plan để xem kế hoạch, chỉ chuyển sang build khi hài lòng, và sao lưu hoặc dùng quản lý phiên bản (như git) cho dự án quan trọng trước khi để AI sửa.

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

**Điểm mạnh**

- Mã nguồn mở, giấy phép MIT, cộng đồng rất lớn (khoảng 226 nghìn sao) và vẫn được cập nhật.
- Hai chế độ build và plan giúp bạn kiểm soát mức độ AI được phép làm.
- Nhiều cách cài, có cả bản desktop và README tiếng Việt.
- Có tài liệu và cộng đồng (Discord, X) để hỏi khi vướng.

**Giới hạn cần biết**

- README ngắn: chưa ghi yêu cầu hệ thống chi tiết, cách kết nối mô hình AI, hay lệnh khởi động. Bạn sẽ phải đọc thêm tài liệu trên trang chủ.
- Bản desktop đang ở mức BETA.
- README chưa nói về chi phí sử dụng mô hình AI, nên bạn cần tự tìm hiểu mức phí của nhà cung cấp mà bạn chọn.
- Một agent có quyền sửa file luôn cần bạn kiểm tra lại kết quả. Đừng đưa thẳng vào hệ thống đang chạy thật khi chưa xem.

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

Nếu bạn chỉ cần hỏi đáp nhanh về một đoạn code, một khung chat thông thường là đủ, không cần cài agent. Nếu bạn muốn một công cụ có hướng dẫn từng bước chi tiết cho người chưa từng đụng terminal, hãy bắt đầu bằng bản desktop hoặc nhờ người quen cài giúp lần đầu. Còn nếu bạn là dev muốn một agent mã nguồn mở có thể tự chỉnh theo ý và không bị gắn chặt với một hãng, opencode là lựa chọn đáng thử.

Lưu ý nhỏ: README nhắc rằng các dự án có tên chứa "opencode" (như opencode-dashboard) mà không phải do nhóm tác giả làm thì phải ghi rõ là không liên kết. Khi tìm công cụ liên quan, bạn nên xác nhận đúng repo của tác giả gốc.

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

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

Repo là mã nguồn mở, giấy phép MIT, nên bạn tải và dùng phần mềm được. README chưa nói gì về chi phí của mô hình AI mà bạn kết nối vào. Bạn cần xem tài liệu tại opencode.ai/docs và trang của nhà cung cấp mô hình để biết mức phí.

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

README liệt kê bản desktop (BETA) cho Windows với file opencode-desktop-win-x64.exe. Các lệnh cài bằng script bash, Homebrew, pacman hay paru ghi cho macOS và Linux. Riêng mise ghi là dùng được trên mọi hệ điều hành.

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

README chưa ghi yêu cầu về GPU, RAM hay phiên bản Node. Chưa có thông tin cụ thể, bạn nên xem trang tài liệu opencode.ai/docs.

### Khác nhau giữa agent build và plan là gì?

Build là agent mặc định, 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 quyền 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ì?

Đây là subagent dành cho các tìm kiếm phức tạp và công việc nhiều bước. Nó chủ yếu được dùng ngầm bên trong, 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ề cách xử lý dữ liệu. Repo có file SECURITY.md để bạn xem chính sách bảo mật. Mình khuyên bạn dùng chế độ plan khi khám phá, và sao lưu dự án trước khi để agent sửa file.

### Tôi nên cài bằng cách nào nếu mới bắt đầu?

Nếu bạn quen dòng lệnh, dùng script một dòng hoặc trình quản lý gói bạn đã có. Nếu không quen, hãy tải bản desktop (BETA) từ opencode.ai/download. Trước khi cài, README nhắc gỡ các phiên bản cũ hơn 0.1.x.
