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
Bài này là một góc nhìn khác về anomalyco/opencode — repo từng đổi tên nên mình viết lại với cách tiếp cận khác. Bài hướng dẫn chính: 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 →

Tóm tắt nhanh
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 và sửa code bằng ngôn ngữ thường ngày. Cài khá dễ: chỉ cần một dòng lệnh, một trình quản lý gói, hoặc tải ứng dụng desktop bản beta.
opencode là một agent lập trình AI mã nguồn mở. Hiểu đơn giản: đây là một trợ lý AI làm việc cùng bạn ngay trên dự án code, bạn nhắn yêu cầu bằng lời, nó đọc code, đề xuất và sửa giúp. Repo hiện có khoảng 226.506 sao và 30.658 fork, dùng giấy phép MIT, viết chủ yếu bằng TypeScript, 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 bạn là lập trình viên mới, người làm văn phòng hay chủ shop hay phải nhờ người khác sửa file, sửa website, viết script nhỏ, hoặc đơn giản là muốn thử một công cụ AI viết code mà không bị gắn chặt vào một hãng nào. Phần lớn công sức nằm ở việc cài đặt, nên bài này đi chậm và chỉ bạn từng bước.
Điểm đáng giá nhất của opencode theo tư liệu trong repo: có hai agent dựng sẵn, bạn đổi qua lại bằng phím Tab. Một agent được toàn quyền làm việc, một agent chỉ đọc và phân tích. Nhờ vậy bạn có thể cho AI «xem trước, nghĩ trước» rồi mới cho nó động vào file.
anomalyco/opencode
opencode là agent lập trình AI mã nguồn mở: đọc code, sửa file, chạy lệnh theo yêu cầu của bạn, có sẵn chế độ build và plan, cài bằng một dòng lệnh.
I.opencode làm được gì
Tư liệu của repo khá ngắn gọn, nên mình chỉ nói những gì thật sự có trong đó.
A.Hai agent dựng sẵn: build và plan
agent build là mặc định, có toàn quyền cho việc phát triển: đọc, sửa file, chạy lệnh. Dùng khi bạn đã biết mình muốn gì và muốn AI làm luôn.
agent plan thì chỉ đọc. Mặc định nó từ chối sửa file, và hỏi bạn trước khi chạy lệnh bash. README ghi rõ nó hợp để khám phá một codebase lạ hoặc lên kế hoạch thay đổi. Với người mới, đây là chế độ an toàn để làm quen: bạn hỏi «dự án này làm gì», «file nào xử lý đơn hàng» mà không sợ AI lỡ tay sửa lung tung.
Bạn chuyển giữa hai agent bằng phím Tab.
B.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 việc nhiều bước. Nó chủ yếu được dùng nội bộ, nhưng bạn cũng gọi được bằng cách gõ @general trong tin nhắn. Hữu ích khi bạn cần lục cả dự án lớn để tìm một thứ.
C.Nhiều cách cài, kể cả ứng dụng desktop
README liệt kê nhiều đường cài: script một dòng, npm, Homebrew, Arch Linux, mise, Nix. Ngoài ra có ứng dụng desktop (bản BETA) cho macOS, Windows và Linux, dành cho bạn nào ngại gõ lệnh.
D.Mã nguồn mở, giấy phép MIT
Bạn đọc được code, tự kiểm tra nó làm gì, và dùng theo giấy phép MIT. Repo cũng có tài liệu riêng tại trang chủ dự án để chỉnh cấu hình chi tiết hơn.
II.Cần chuẩn bị gì
Tư liệu README không liệt kê yêu cầu hệ thống đầy đủ, 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 (x64) và Linux (
.deb,.rpm,.AppImage). Các cách cài bằng dòng lệnh nhắc đến macOS, Linux, Arch Linux và «Any OS» (qua mise). - Công cụ cài: tuỳ cách bạn chọn, bạn cần sẵn
curl, hoặc npm (hay bun/pnpm/yarn), hoặc Homebrew, hoặc 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 nói gì về các mục này. Vì đây là agent AI nên rất có thể bạn sẽ phải kết nối một dịch vụ mô hình AI, nhưng cách làm cụ thể mình không có trong tư liệu. Bạn xem phần tài liệu trên trang chủ dự án (mục docs) để biết chi tiết.
README không nói về key hay chi phí. Nếu sau này bạn kết nối một dịch vụ AI tính phí, hãy đọc kỹ bảng giá của dịch vụ đó và không dán key vào chỗ công khai (ví dụ file code bạn đẩy lên GitHub).
III.Cài đặt từng bước
- Chọn cách càiChọn một trong các cách: script, npm, Homebrew, mise… hoặc app desktop
- Gỡ bản cũXoá phiên bản cũ hơn 0.1.x nếu có
- Chạy lệnh càiDán đúng một dòng lệnh phù hợp máy của bạn vào terminal
- Kiểm tra vị trí càiBiết opencode nằm ở thư mục nào nếu dùng script
- Mở và thửVào thư mục dự án và bắt đầu hỏi agent
A.Chọn cách cài phù hợp
Bạn chỉ cần chọn MỘT cách. Gợi ý nhanh cho người mới:
- Muốn nhanh nhất: dùng script một dòng (README gọi vui là «YOLO»).
- Đã có Node/npm: dùng npm.
- Dùng Mac hoặc Linux có Homebrew: dùng brew.
- Không thích gõ lệnh: tải app desktop ở phần cuối bước này.
«Terminal» là cửa sổ gõ lệnh. Trên Windows bạn mở PowerShell hoặc Windows Terminal; trên Mac mở ứng dụng Terminal. Các lệnh dưới đây dán vào đó rồi nhấn Enter.
B.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. Nếu bạn chưa từng cài opencode thì bỏ qua bước này. README không nói cách gỡ, nên nếu cần bạn xem lại cách gỡ theo đúng công cụ bạn đã dùng để cài trước đó.
C.Chạy lệnh cài
Đây là khối lệnh nguyên văn trong README. Chọn đúng MỘT dòng:
# 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 # NixGiải thích ngắn:
- Dòng
curl ... | bashtải script cài về rồi chạy luôn. Nhanh nhưng bạn đang chạy một script từ mạng, nên chỉ dùng khi bạn tin nguồn. - Dòng
npm i -g ...cài toàn cục bằng npm. Dấu#và phần chữ sau nó chỉ là ghi chú trong README, bạn không cần gõ. - Hai dòng
brewkhác nhau: dòng đầu README đánh dấu là khuyến nghị và luôn mới; dòng sau là công thức chính thức nhưng cập nhật ít hơn. pacmanvàparudành cho Arch Linux;misechạy mọi hệ điều hành;nix runchạy thẳng không cần cài.
Chỗ người mới hay vấp: dán cả khối lệnh trên vào terminal. Đừng làm vậy. Nó là danh sách các lựa chọn, bạn chỉ chép đúng một dòng.
Ngoài ra README ghi rõ tên gói trong dòng npm là @opencode/cli, còn tên gói npm của repo là opencode. Nếu lệnh npm báo lỗi không tìm thấy gói, hãy thử cách khác (script hoặc brew) và xem lại phần cài đặt trong tài liệu chính thức.
D.Biết nó được cài ở đâu
README cho biết script cài sẽ đặt opencode vào $HOME/.opencode/bin. Nghĩa là thư mục .opencode/bin trong thư mục người dùng của bạn. Nếu cài xong mà terminal không nhận lệnh, nhiều khả năng thư mục này chưa nằm trong PATH; mở terminal mới trước, rồi xem tài liệu nếu vẫn lỗi.
E.Hoặc dùng ứng dụng desktop (BETA)
Bạn có thể tải ứng dụng desktop ở trang tải về của dự án (opencode.ai/download). Các file theo README:
| 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 có thể cài bằng Homebrew:
# macOS (Homebrew)
brew install --cask opencode-desktopBản desktop đang ở giai đoạn BETA nên có thể còn lỗi vặt.
F.Mở dự án và bắt đầu
README không ghi lệnh khởi chạy. Tên gói và công thức brew đều là opencode, nhiều khả năng bạn mở terminal trong thư mục dự án rồi gõ tên đó, nhưng bạn nên kiểm chứng lại trong tài liệu chính thức. Nếu bạn dùng app desktop thì chỉ cần mở ứng dụng.
Nếu muốn có mã nguồn về xem hoặc thử build:
git clone https://github.com/anomalyco/opencode.git
cd opencodeCách build từ mã nguồn README chưa ghi. Xem file CONTRIBUTING.md và package.json trong repo (repo dùng bun, có file bun.lock).
IV.Kiểm tra đã chạy được chưa
README chưa mô tả màn hình hay kết quả mong đợi sau khi cài. Dựa trên những gì có trong tư liệu, bạn có thể tự kiểm tra như sau:
- Mở một cửa sổ terminal MỚI (để PATH được nạp lại), rồi chạy opencode. Nếu mở ra giao diện của chương trình thay vì báo «không tìm thấy lệnh» thì cài đã thành công.
- Thử bấm phím
Tab. Theo README, phím này chuyển giữa agent build và agent plan. Nếu bạn thấy chế độ đổi qua lại, mọi thứ đang chạy đúng. - Nếu dùng app desktop: mở được ứng dụng là đạt.
Nếu bước 1 lỗi, xem phần «Lỗi hay gặp» bên dưới.
V.Dùng vào việc thật
README không nêu ví dụ prompt, nên các tình huống dưới đây là gợi ý dựa trên hai agent và khả năng đã mô tả. Câu lệnh mẫu chỉ là cách mình đặt câu hỏi, không phải cú pháp bắt buộc.
A.Làm quen một dự án lạ bằng agent plan
Bối cảnh: bạn vừa nhận một dự án web từ đồng nghiệp, không biết bắt đầu từ đâu. Chuyển sang agent plan (phím Tab) để AI chỉ đọc, không sửa.
Bạn có thể hỏi: «Dự án này làm gì? Liệt kê các thư mục chính và nói file nào xử lý đăng nhập.» Kết quả: bạn nhận một bản giải thích bằng tiếng Việt, và không file nào bị đụng đến, vì plan mặc định từ chối sửa file.
Cho AI đọc trước, sửa sau: bạn mất thêm một phút nhưng tránh được cả buổi chiều gỡ rối.
Ông T
B.Lên kế hoạch trước khi sửa lớn
Bối cảnh: chủ shop nhờ thêm tính năng mới vào trang bán hàng. Bạn vẫn dùng plan và nhập: «Mình muốn thêm mã giảm giá ở bước thanh toán. Hãy chỉ ra những file cần sửa và đề xuất các bước.»
Plan sẽ hỏi bạn trước khi chạy lệnh bash. Kết quả là một danh sách việc cần làm, bạn đọc, chỉnh, rồi mới giao cho agent build thực hiện.
C.Giao việc cụ thể cho agent build
Bối cảnh: bạn là nhân viên văn phòng cần sửa một đoạn script xuất báo cáo bị sai định dạng ngày. Chuyển sang build và nhập: «Đọc file xuất báo cáo, sửa lỗi định dạng ngày thành ngày/tháng/năm, rồi cho mình xem đã đổi những gì.»
Kết quả: agent đọc file, sửa và báo lại phần thay đổi. Vì build có toàn quyền, hãy chắc là bạn đã sao lưu hoặc đã dùng Git trước khi giao việc.
D.Tìm thứ khó tìm với @general
Bối cảnh: dự án lớn, bạn cần biết nơi nào trong code gọi tới một chức năng gửi email. Trong tin nhắn bạn gõ: «@general tìm tất cả chỗ có gửi email và tóm tắt mỗi chỗ làm gì.»
Kết quả: subagent general chạy các bước tìm kiếm nhiều bước thay bạn và trả về bản tổng hợp.
VI.Lỗi hay gặp và cách xử lý
A.Gõ lệnh báo «không tìm thấy lệnh»
Thường do terminal chưa nạp lại PATH, hoặc thư mục cài chưa có trong PATH. Hãy đóng terminal, mở cái mới. Nếu cài bằng script, nhớ README nói nó nằm ở $HOME/.opencode/bin; kiểm tra xem thư mục này có tồn tại không. Vẫn lỗi thì thử cài lại bằng cách khác (ví dụ brew).
B.Dòng npm báo không tìm thấy gói
README ghi @opencode/cli, nhưng tên gói của repo là opencode, hai tên không khớp hẳn. Đừng tự đoán tên khác. Hãy dùng script hoặc Homebrew, hoặc xem tài liệu chính thức để biết tên gói đúng.
C.Xung đột với bản cũ
Nếu bạn từng cài phiên bản cũ hơn 0.1.x, README khuyên gỡ trước. Dấu hiệu là lệnh chạy ra bản cũ hoặc hành vi lạ. Gỡ bằng đúng công cụ đã cài (npm, brew…) rồi cài lại.
D.AI sửa nhầm file
Agent build có toàn quyền, nên có thể sửa thứ bạn không định sửa. Cách phòng: dùng Git để theo dõi thay đổi, sao lưu trước khi giao việc lớn, và dùng agent plan để duyệt kế hoạch trước.
E.Dán nguyên khối lệnh cài
Lỗi rất phổ biến của người mới: dán cả khối lệnh trong README. Mỗi dòng là một lựa chọn khác nhau. Chỉ chạy một dòng hợp với máy bạn; nếu lỡ chạy nhiều, kiểm tra xem máy có bị cài trùng không.
VII.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 (khoảng 226.506 sao) và còn được cập nhật.
- Hai chế độ build và plan giúp bạn kiểm soát mức độ để AI can thiệp.
- Nhiều cách cài, có cả ứng dụng desktop cho Windows, macOS, Linux.
- Có tài liệu riêng và nhiều bản dịch README, trong đó có tiếng Việt.
Giới hạn:
- README ngắn: chưa có ví dụ dùng, chưa nói rõ cách kết nối mô hình AI, yêu cầu hệ thống hay chi phí. Bạn phải đọc thêm tài liệu chính thức.
- Bản desktop đang ở giai đoạn BETA.
- Tên gói trong dòng npm của README và tên gói của repo không giống hẳn nhau, dễ gây bối rối.
- Agent có quyền sửa file và chạy lệnh nên cần thận trọng.
Khi nên chọn cách khác: nếu bạn không đụng đến code và chỉ cần một công cụ chat AI thông thường để hỏi đáp, một ứng dụng chat đơn giản sẽ hợp hơn. Nếu bạn cần một công cụ đã có hướng dẫn từng bước đầy đủ cho người không rành kỹ thuật, bạn nên chờ khi tài liệu hoàn thiện hơn.
Tóm lại: nếu bạn muốn thử một trợ lý lập trình AI mã nguồn mở, ít bị ràng buộc và sẵn lòng đọc thêm tài liệu, opencode là lựa chọn đáng thử. Bắt đầu bằng agent plan cho an toàn.
Câu hỏi thường gặp
opencode có miễn phí không?
Bản thân repo dùng giấy phép MIT, là mã nguồn mở. Tuy nhiên tư liệu README không nói gì về chi phí của dịch vụ AI mà bạn có thể kết nối. Bạn nên xem tài liệu trên trang chủ dự án trước khi dùng.
opencode chạy được trên Windows không?
Có file ứng dụng desktop cho Windows là opencode-desktop-win-x64.exe (bản BETA). Với dòng lệnh, README liệt kê npm và mise (ghi là dùng được mọi hệ điều hành). README không có hướng dẫn riêng cho PowerShell.
Cần GPU hay máy mạnh không?
Tư liệu không nói gì về yêu cầu phần cứng, nên mình chưa có thông tin để khẳng định. Bạn xem thêm tài liệu chính thức của dự án.
Khác nhau giữa agent build và plan là gì?
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 trước khi chạy lệnh bash. Bạn đổi qua lại bằng phím Tab.
Dữ liệu và code của mình có an toàn không?
README không mô tả chính sách dữ liệu. Repo có file SECURITY.md, bạn nên đọc. Ngoài ra, hãy cẩn thận với agent build vì nó có quyền sửa file và chạy lệnh; nên dùng Git và sao lưu.
Cài opencode bằng cách nào dễ nhất?
Dễ nhất là script một dòng (curl) hoặc tải ứng dụng desktop. Nếu dùng Homebrew thì README khuyến nghị công thức anomalyco/tap/opencode-v2. Script sẽ cài vào thư mục $HOME/.opencode/bin.
Gọi subagent general như thế nào?
Trong tin nhắn bạn gõ @general kèm yêu cầu. Theo README, subagent này dùng cho tìm kiếm phức tạp và các việc nhiều bước, và cũng được dùng nội bộ.


