# 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ý AI viết và sửa code) 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, bằng trình quản lý gói như npm hoặc brew, hoặc tải bản desktop (đang BETA). Cài không khó, nhưng README chưa ghi cách nối với nhà cung cấp mô hình AI nên bạn cần đọc 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-08-11 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/opencode-tro-ly-lap-trinh-ai-ma-nguon-mo-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 và giúp bạn viết hoặc sửa code. Tác giả mô tả ngắn gọn là "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 một công cụ cùng loại.

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 hay kinh doanh có đụng đến code, hoặc người muốn thử một trợ lý lập trình mà không bị khóa vào một hãng nào. Bạn không cần là chuyên gia. Bạn chỉ cần mở được terminal và biết thư mục dự án của mình nằm ở đâu.

Điểm đáng giá nhất là hai chế độ làm việc có sẵn. Chế độ build có toàn quyền để làm việc. Chế độ plan chỉ đọc, dùng để khám phá code và lên kế hoạch mà không sợ AI sửa nhầm file. Bạn chuyển giữa hai chế độ bằng phím Tab. Ngoài ra còn có bản ứng dụng desktop (đang BETA) cho ai không thích dùng terminal.

```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, có sẵn hai chế độ build và plan để bạn chuyển bằng phím Tab.
- 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 dựng sẵn: build và plan

Agent **build** là mặc định, có toàn quyền cho công việc phát triển. Dùng nó khi bạn đã biết mình muốn gì và muốn AI làm luôn.

Agent **plan** chỉ đọc. Theo README, nó từ chối sửa file theo mặc định và hỏi quyền trước khi chạy lệnh bash. Lợi ích thực tế: bạn mở một dự án lạ, hỏi "phần đăng nhập nằm ở đâu?" mà không lo AI tự ý đổi code. README cũng ghi plan hợp với việc khám phá codebase chưa quen và lên kế hoạch thay đổi.

### Chuyển chế độ bằng phím Tab

Bạn không phải thoát ra rồi cấu hình lại. Cứ bấm `Tab` là đổi giữa build và plan. Thói quen tốt là bắt đầu bằng plan để hiểu vấn đề, rồi chuyển sang build khi đã đồng ý với kế hoạch.

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

Ngoài hai agent trên còn có subagent **general**, dùng cho tìm kiếm phức tạp và các tác vụ nhiều bước. README nói nó chủ yếu được dùng nội bộ. Khi cần, bạn gọi nó bằng `@general` ngay trong tin nhắn.

### Nhiều cách cài, có bản desktop

Bạn có thể cài bằng script, npm, brew, pacman, mise hay nix. Ngoài ra có bản desktop cho macOS, Windows và Linux. Nhờ vậy người ngại dòng lệnh vẫn có lối vào.

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

Cấu hình chi tiết nằm ở trang tài liệu của dự án (opencode.ai/docs). Repo còn có README bằng nhiều ngôn ngữ, trong đó có tiếng Việt. Dự án có Discord và tài khoản trên X.com để hỏi đáp.

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

README không có mục "yêu cầu hệ thống" riêng. Mình chỉ nêu 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 và Linux. Các lệnh cài bằng brew nói rõ là cho macOS và Linux. Lệnh pacman dành cho Arch Linux. `mise` ghi là dùng được trên mọi hệ điều hành.
- **Công cụ cài:** tùy cách bạn chọn, bạn cần curl, npm (hoặc bun, pnpm, yarn), Homebrew, mise hoặc nix.
- **Phiên bản cũ:** README khuyên gỡ các bản cũ hơn 0.1.x trước khi cài.
- **Tài khoản và API key:** README chưa nói cần tài khoản hay key nào, và cũng chưa nói cách nối OpenCode với nhà cung cấp mô hình AI. Phần này bạn xem ở trang tài liệu trên opencode.ai/docs.
- **Phần cứng:** README chưa có thông tin về yêu cầu GPU hay RAM.

```note
Một agent AI có thể đọc file và chạy lệnh trên máy bạn. Lần đầu hãy thử trên một thư mục dự án nhỏ, đã sao lưu. Nếu sau này bạn dùng key của nhà cung cấp AI, đừng dán key vào chat, và đừng commit key lên GitHub. Chi phí gọi mô hình tính theo nhà cung cấp bạn chọn, README không nói về chuyện này.
```

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

```steps
- Gỡ bản cũ | Nếu bạn từng cài OpenCode bản cũ hơn 0.1.x, hãy gỡ đi trước
- Chọn cách cài | Chọn một lệnh phù hợp hệ điều hành: script, npm, brew, pacman, mise hoặc nix
- Chạy lệnh cài | Mở terminal và dán đúng một lệnh bạn đã chọn
- Hoặc tải bản desktop | Nếu không thích terminal, tải bản BETA cho máy của bạn
- Xem tài liệu cấu hình | Đọc docs để nối với mô hình AI và tùy chỉnh
```

### 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ếu bạn chưa từng cài OpenCode thì bỏ qua bước này.

### Chọn một cách cài và chạy trong terminal

Terminal là cửa sổ gõ lệnh. Trên Windows bạn mở PowerShell hoặc Terminal. Trên macOS bạn mở ứng dụng Terminal. Bạn chỉ cần chạy **một** dòng dưới đây, không chạy cả danh sách. Danh sách này chép đúng 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
```

Gợi ý chọn nhanh, dựa trên chú thích của README:

- Dòng đầu (`curl ... | bash`) được README đặt tên "YOLO", nghĩa là cài nhanh và liều. Nó tải một script từ mạng về chạy ngay. Nếu bạn thận trọng, hãy chọn cách dùng trình quản lý gói.
- Người dùng macOS hoặc Linux: README gọi `brew install anomalyco/tap/opencode-v2` là cách khuyên dùng và luôn mới nhất. Công thức `brew install opencode` là bản chính thức nhưng cập nhật chậm hơn.
- Người dùng npm: dùng `npm i -g @opencode/cli@latest`. README ghi bạn có thể thay npm bằng bun, pnpm hoặc yarn. Lưu ý tên gói npm trong thông tin repo là `opencode`, còn README ghi `@opencode/cli`. Nếu lệnh báo lỗi không tìm thấy gói, hãy mở trang tài liệu để xem tên gói đang dùng.
- Người dùng Windows: các lệnh `curl ... | bash` và `brew` được ghi cho môi trường kiểu Unix. README không nói rõ chúng chạy trên PowerShell hay không. Cách an toàn là dùng npm nếu bạn đã có Node, dùng `mise`, hoặc tải bản desktop.
- Người dùng Arch Linux: dùng `pacman` (bản ổn định) hoặc `paru` (bản mới nhất từ AUR).

Một chỗ người mới hay vấp: dấu `#` trong khối trên là chú thích. Bạn không cần gõ phần sau dấu `#`, chỉ gõ phần lệnh phía trước.

### Nơi script cài đặt đặt OpenCode

Nếu dùng script, README cho biết OpenCode được cài vào `$HOME/.opencode/bin`. Nếu gõ tên lệnh mà máy báo không tìm thấy, thư mục này có thể chưa nằm trong PATH. README chưa nói cách xử lý, bạn xem thêm trong tài liệu.

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

Bản desktop tải ở trang opencode.ai/download. README liệt kê các file:

| Hệ điều hành | File 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 bạn cũng có thể cài bằng Homebrew:

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

Vì đang BETA, bản desktop có thể còn lỗi vặt. Nếu bạn làm việc quan trọng, hãy thử trước trên dự án nhỏ.

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

README chỉ hướng dẫn cài và giới thiệu agent. Phần cấu hình, ví dụ chọn mô hình AI, bạn xem ở opencode.ai/docs.

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

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

- Với bản desktop: mở ứng dụng lên được và thấy giao diện làm việc là xong bước cài.
- Với bản terminal: sau khi cài, mở một cửa sổ terminal **mới** (để máy nhận lệnh vừa cài). 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", xem lại phần PATH ở trên hoặc mục lỗi bên dưới.
- Khi chạy được, bạn sẽ có hai chế độ build và plan như README mô tả. Bấm `Tab` để chuyển. Nếu bấm Tab mà thấy đổi được chế độ, nghĩa là bạn đã vào đúng chương trình.

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

Các tình huống dưới đây bám vào ba thứ README có: agent plan, agent build và `@general`. Prompt mẫu là gợi ý của mình để bạn bắt chước. README không đưa sẵn prompt nào.

### Dev mới vào công ty, cần hiểu dự án lạ

Bạn vừa nhận một repo hàng trăm file và chưa biết bắt đầu từ đâu. Hãy mở OpenCode trong thư mục dự án, để ở chế độ **plan** (bấm Tab nếu đang ở build). Vì plan từ chối sửa file theo mặc định, bạn yên tâm hỏi thoải mái:

```text
Hãy giải thích cấu trúc thư mục của dự án này. Phần xử lý đăng nhập nằm ở file nào?
```

Kết quả: bạn có bản tóm tắt cấu trúc và chỉ dẫn tới các file liên quan, không có file nào bị đụng vào. Nếu agent cần chạy lệnh bash, nó sẽ hỏi quyền bạn trước.

> Cứ đọc hiểu trước, sửa sau — chế độ chỉ đọc giúp bạn dám hỏi mà không sợ phá code.
>
> — Ông T

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

Bạn có một trang bán hàng đơn giản do người khác dựng và muốn đổi dòng chữ khuyến mãi ở đầu trang. Hãy lên kế hoạch trước ở chế độ plan:

```text
Tôi muốn đổi dòng thông báo khuyến mãi ở đầu trang. Hãy chỉ ra file nào cần sửa và sửa thế nào, chưa chỉnh gì cả.
```

Đọc xong kế hoạch, bạn bấm Tab sang **build** và nhắn: "Hãy làm đúng như kế hoạch trên." Kết quả là thay đổi nhỏ, rõ ràng, và bạn đã đọc trước nó sẽ làm gì. Nên sao lưu thư mục hoặc dùng Git trước khi để agent sửa.

### Nhân viên văn phòng cần một script nhỏ để xử lý việc lặp lại

Giả sử bạn hay phải đổi tên hàng loạt file báo cáo. Ở chế độ build, bạn mô tả việc bằng tiếng Việt:

```text
Viết giúp tôi một script đổi tên tất cả file trong thư mục hiện tại theo dạng baocao_01, baocao_02, ... Hãy cho tôi xem script trước khi chạy.
```

Kết quả là một file script bạn có thể đọc, hiểu rồi mới chạy. Câu "cho tôi xem trước khi chạy" là thói quen tốt khi dùng agent có quyền chạy lệnh trên máy.

### Dev cần tìm nhanh trong code lớn bằng @general

Khi câu hỏi cần lục nhiều file và nhiều bước, bạn gọi subagent general trực tiếp trong tin nhắn:

```text
@general Tìm tất cả chỗ trong dự án có gọi hàm gửi email và liệt kê giúp tôi theo từng file.
```

README nói `@general` dành cho tìm kiếm phức tạp và tác vụ nhiều bước. Kết quả bạn nhận là danh sách tổng hợp thay vì phải 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ố. Các lỗi dưới đây là những lỗi rất dễ gặp với loại công cụ cài bằng dòng lệnh. Mình nêu cách xử lý an toàn, còn chi tiết riêng cho OpenCode bạn đối chiếu với tài liệu.

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

Nguyên nhân hay gặp là terminal đang mở từ trước khi cài, hoặc thư mục cài chưa nằm trong PATH. Hãy đóng terminal, mở cửa sổ mới rồi thử lại. Nếu cài bằng script, README cho biết nơi cài là `$HOME/.opencode/bin`. Hãy kiểm tra thư mục này có tồn tại không.

### Lệnh npm báo không tìm thấy gói

README ghi `npm i -g @opencode/cli@latest` nhưng tên gói npm trong thông tin repo là `opencode`. Hai tên này khác nhau. Hãy xem lại hướng dẫn mới nhất trên opencode.ai rồi chọn cách cài khác như brew, mise hoặc bản desktop nếu npm vẫn lỗi.

### Cài lên máy đã có bản cũ rồi bị xung đột

README khuyên gỡ các 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 còn bản cũ nào cài bằng cách khác trên máy không.

### Lệnh curl chạy mà không có gì xảy ra hoặc báo lỗi trên Windows

Dòng `curl ... | bash` cần có `bash`. Trên Windows PowerShell thuần, cách này có thể không chạy. Hãy chuyển sang npm, mise hoặc bản desktop, hoặc chạy trong môi trường có bash nếu bạn đã có sẵn.

### AI sửa file không như ý

Đây là lỗi dễ xảy ra với mọi coding agent. Hãy để Git theo dõi dự án hoặc sao lưu trước khi dùng chế độ build. Khi chưa chắc, dùng chế độ plan trước để xem kế hoạch. Nếu đã lỡ sửa sai, bạn khôi phục từ Git hoặc bản sao lưu.

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

**Điểm mạnh.** Mã nguồn mở, giấy phép MIT, nên bạn đọc được code và dùng tự do. Repo rất được quan tâm (khoảng 226.506 sao) và vẫn được cập nhật trong vài tháng gần đây. Có nhiều cách cài, có cả bản desktop, và README có bản tiếng Việt. Cặp agent build và plan giúp người mới dùng AI an toàn hơn: khám phá bằng plan, hành động bằng build.

**Giới hạn.** README rất ngắn. Nó không hướng dẫn nối mô hình AI, không nói về chi phí, và không có phần xử lý lỗi, nên người mới sẽ phải đọc thêm tài liệu. Tên gói npm trong README và trong thông tin repo chưa khớp nhau, dễ làm bạn lúng túng. Bản desktop còn BETA. README cũng không nói gì về chất lượng kết quả hay hiệu năng so với công cụ khác, nên mình không đánh giá phần này.

**Khi nào nên chọn cách khác.** Nếu bạn hoàn toàn không đụng đến code hoặc terminal và chỉ cần chatbot hỏi đáp thông thường, một công cụ chat là đủ. Nếu công ty bạn có quy định chặt về việc cho phép AI đọc code, hãy hỏi bộ phận IT trước khi dùng bất kỳ coding agent nào.

Nếu bạn muốn thử một coding agent mở, bắt đầu bằng bản desktop hoặc một dòng lệnh cài đơn giản, rồi dùng chế độ plan trên một dự án nhỏ. Cách này ít rủi ro và đủ để bạn biết nó có hợp với mình không.

## 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 và xem code được tự do. README chưa nói gì về chi phí khi nối với nhà cung cấp mô hình AI, nên phần này chưa có thông tin. Bạn xem thêm ở trang tài liệu của dự án.

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

Có bản desktop cho Windows là file opencode-desktop-win-x64.exe (đang BETA). Với bản dòng lệnh, README ghi nhiều cách cài nhưng không nói rõ cách nào dành riêng cho Windows. Lệnh `mise` được ghi là dùng được trên mọi hệ điều hành.

### Tôi cần GPU hoặc 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, nên chưa có thông tin về GPU hay RAM. Bạn xem thêm trong trang tài liệu của dự án.

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

Build là agent mặc định, có 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 chuyển qua lại bằng phím Tab.

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

README không có phần nói về quyền riêng tư hay nơi dữ liệu được gửi đến, nên chưa có thông tin cụ thể. Điều chắc chắn là agent build có toàn quyền, còn plan hỏi quyền trước khi chạy lệnh. Với dự án quan trọng, bạn nên sao lưu trước và đọc tài liệu chính thức.

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

General là subagent dành cho tìm kiếm phức tạp và các tác vụ nhiều bước. README nói nó chủ yếu được dùng nội bộ, và bạn có thể gọi trực tiếp bằng @general trong tin nhắn.

### Tôi nên cài bằng cách nào cho dễ nhất?

Nếu ngại terminal, tải bản desktop ở trang tải về của dự án. Nếu dùng macOS hoặc Linux, README gọi `brew install anomalyco/tap/opencode-v2` là cách khuyên dùng và luôn mới. Nếu đã có npm, bạn có thể dùng lệnh npm trong README, nhưng cần lưu ý tên gói trong README và thông tin repo chưa khớp.
