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, lên kế hoạch và sửa code bằng ngôn ngữ tự nhiên. Cài đặt khá dễ: một dòng lệnh, một trình quản lý gói, hoặc tải ứng dụng desktop.
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, đề xuất và sửa giúp bạn. Tác giả giới thiệu ngắn gọn là "The open source coding agent". Repo viết chủ yếu bằng TypeScript, dùng giấy phép MIT và hiện có khoảng 226.500 sao, 30.600 fork. Con số đó cho thấy khá đông người đang dùng và theo dõi nó.
Ai nên đọc bài này? Lập trình viên mới muốn có một "người phụ" ngay trong dự án. Người làm kinh doanh hoặc văn phòng có chút code (file tự động hoá, trang web nhỏ) cũng dùng được. Nếu bạn là người rất mới, bài này sẽ đi chậm từng bước, chỉ rõ chỗ hay vấp.
Điểm đáng giá nhất của opencode là có sẵn hai chế độ: một chế độ được phép sửa file, một chế độ chỉ đọc để phân tích. Bạn có thể bảo nó xem trước, rồi mới cho nó làm. Ngoài ra nó có cả bản ứng dụng desktop (đang beta) cho người ngại dòng lệnh.
anomalyco/opencode
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 (beta).
I.opencode làm được gì
Theo README, opencode có hai agent dựng sẵn và bạn đổi qua lại bằng phím Tab.
- buildagent mặc định, có toàn quyền cho việc phát triển. Hợp khi bạn muốn nó thật sự viết và sửa code.
- planagent chỉ đọc, dùng để phân tích và khám phá code. Mặc định nó từ chối sửa file, và hỏi bạ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 này chạy thế nào?" mà không lo nó lỡ tay đổi gì.
Ngoài hai agent đó còn có một subagent tên general, dùng cho việc tìm kiếm phức tạp và nhiều bước. opencode tự dùng nó ở bên trong, và bạn cũng có thể gọi bằng cách gõ @general trong tin nhắn. Khi câu hỏi cần lục nhiều chỗ, bạn nhờ nó đi tìm thay vì tự mò.
Về cách dùng, opencode có nhiều đường vào: dòng lệnh cài bằng script, bằng nhiều trình quản lý gói (npm, bun, pnpm, yarn, Homebrew, pacman, mise, Nix), và bản desktop cho macOS, Windows, Linux. Bạn chọn đường nào quen tay nhất.
Họ có nhiều bản dịch README, trong đó có cả tiếng Việt (file README.vi.md trong repo). Điều này thuận tiện nếu bạn muốn đọc thêm bằng tiếng mẹ đẻ.
II.Cần chuẩn bị gì
Tư liệu README khá ngắn, nên mình chỉ nêu những gì có ghi:
- Hệ điều hànhscript cài và các lệnh Homebrew, pacman nhắm tới macOS và Linux. Lệnh
mise use -g opencodeđược ghi là dùng cho "Any OS". Với Windows, README có file cài đặt bản desktopopencode-desktop-win-x64.exe. - Bản desktopmacOS Apple Silicon (
.dmgarm64), macOS Intel (.dmgx64), Windows (.exe), Linux (.deb,.rpmhoặc.AppImage). - Gỡ bản cũREADME dặn gỡ các phiên bản cũ hơn 0.1.x trước khi cài.
- Node/Bunchỉ cần nếu bạn cài bằng npm, bun, pnpm hay yarn. README không nêu phiên bản tối thiểu.
- Tài khoản, API key, phần cứngREADME chưa nói gì. Muốn biết cách cấu hình mô hình AI, bạn xem trang tài liệu của dự án tại opencode.ai/docs.
Lệnh cài đầu tiên trong README tải một script từ mạng rồi chạy luôn (curl ... | bash). Chỉ chạy khi bạn tin nguồn. Nếu còn phân vân, hãy chọn cách cài qua trình quản lý gói. Ngoài ra, agent build có toàn quyền, nên hãy thử trên một thư mục dự án bạn đã sao lưu.
III.Cài đặt từng bước
- Gỡ bản cũXoá phiên bản cũ hơn 0.1.x nếu có
- Chọn cách càiScript một dòng, trình quản lý gói, hoặc bản desktop
- Chạy lệnh càiDán lệnh vào terminal và đợi hoàn tất
- Mở dự ánVào thư mục code của bạn rồi khởi chạy opencode
- Đổi chế độNhấn Tab để chuyển giữa build và plan
A.Gỡ phiên bản cũ nếu có
README dặn: xoá các bản cũ hơn 0.1.x trước khi cài. README không ghi cách gỡ cụ thể, nên cách gỡ phụ thuộc vào việc bạn đã cài bằng gì trước đó (npm, brew…). Nếu bạn chưa từng cài opencode, bỏ qua bước này.
B.Chọn một cách cài
README liệt kê nhiều cách. Bạn chỉ cần chọn MỘT. Mở terminal (macOS/Linux: ứng dụng Terminal; Windows: PowerShell hoặc Windows Terminal) rồi chạy lệnh tương ứng.
Cách nhanh nhất, README gọi vui là "YOLO":
curl -fsSL https://opencode.ai/v2/install | bashLệnh này tải script cài đặt về và chạy ngay. Script cài opencode vào thư mục $HOME/.opencode/bin. Nếu cài xong mà gõ lệnh không nhận, hãy kiểm tra thư mục này có nằm trong PATH chưa. README không nói script có tự thêm vào PATH hay không.
Các cách dùng trình quản lý gói, chép đúng từ README:
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 # NixChỗ dễ nhầm: đây là cả danh sách, đừng chạy hết. Chỉ chọn một dòng hợp hệ điều hành của bạn. Ví dụ người dùng Mac thường chọn dòng brew install anomalyco/tap/opencode-v2, vì README ghi dòng này là bản khuyến nghị và luôn mới nhất. Dòng brew install opencode là formula chính thức của Homebrew nhưng cập nhật chậm hơn.
Lưu ý nhỏ: tên gói npm trong README là @opencode/cli, còn trang repo ghi tên gói là opencode. Hai tên này khác nhau, nên nếu lệnh npm báo lỗi, hãy kiểm tra lại README mới nhất của dự án.
C.Hoặc dùng ứng dụng desktop (beta)
Nếu bạn không thích dòng lệnh, tải bản desktop tại opencode.ai/download. Chọn file theo máy:
| Nền tảng | File |
|---|---|
| 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:
brew install --cask opencode-desktopBản này đang ở giai đoạn beta, nên có thể còn lỗi vặt.
D.Mở dự án và khởi chạy
README không ghi lệnh khởi chạy sau khi cài. Vì tên gói là opencode, nhiều khả năng bạn chạy bằng chính tên đó trong thư mục dự án, nhưng mình khuyên bạn xác nhận lại ở trang tài liệu opencode.ai/docs. Với bản desktop, bạn chỉ cần mở ứng dụng lên.
Nếu dự án của bạn còn trên GitHub, bạn có thể lấy về bằng lệnh phổ thông:
git clone https://github.com/anomalyco/opencode.git
cd opencodeĐây là việc lấy mã nguồn của chính opencode. Với việc dùng thường ngày, bạn không cần bước này, hãy cd vào thư mục dự án của bạn.
E.Đổi chế độ build và plan
Sau khi mở được giao diện, nhấn phím Tab để chuyển giữa agent build và plan. Mặc định bạn đang ở build (toàn quyền). Hãy tập thói quen: việc nào chưa chắc thì chuyển sang plan trước.
IV.Kiểm tra đã chạy được chưa
README không mô tả màn hình hay kết quả mong đợi. Mình chỉ có thể gợi ý các dấu hiệu hợp lý:
- Lệnh cài kết thúc không báo lỗi.
- Với script cài, thư mục
$HOME/.opencode/binđã xuất hiện. - Giao diện opencode mở lên được, và nhấn
Tabthì chuyển được giữa build và plan. - Gõ
@generalkèm một câu hỏi thì nhận được phản hồi.
Nếu cả bốn đều ổn, bạn đã sẵn sàng. Nếu AI không trả lời, nhiều khả năng bạn chưa cấu hình nhà cung cấp mô hình. README không nói chi tiết, hãy xem trang docs.
V.Dùng vào việc thật
Dưới đây là các tình huống mình thấy khớp với những gì README mô tả. Các câu lệnh mẫu chỉ là gợi ý cách hỏi, kết quả thực tế phụ thuộc mô hình AI bạn cấu hình.
A.Nhân viên mới tiếp quản một dự án lạ
Bạn vừa vào công ty, được giao một thư mục code mà không ai giải thích. Hãy mở opencode trong thư mục đó, nhấn Tab để sang agent plan. Vì plan chỉ đọc nên bạn yên tâm không làm hỏng gì. Bạn hỏi:
Giải thích cấu trúc thư mục này. Phần nào xử lý đơn hàng? Mình nên đọc file nào trước?Kết quả: một bản tóm tắt để bạn có bản đồ trước khi đụng vào code.
Việc nào chưa chắc, cứ cho nó xem trước bằng plan, rồi mới cho nó làm bằng build.
Ông T
B.Chủ shop muốn sửa một trang web nhỏ
Bạn có trang giới thiệu cửa hàng do người quen làm, giờ muốn đổi số điện thoại và giờ mở cửa. Ở agent build, bạn gõ:
Tìm tất cả chỗ ghi số điện thoại và giờ mở cửa trong dự án, đổi thành 0900 000 000 và 8h-21h.Kết quả: nó tìm các chỗ liên quan rồi sửa. Bạn nên xem lại các thay đổi trước khi đưa lên mạng. Nếu có thể, hãy sao lưu thư mục trước.
C.Lập trình viên cần lên kế hoạch trước khi sửa lớn
Bạn muốn đổi cách tính phí vận chuyển trong code. Ở chế độ plan, bạn mô tả yêu cầu và nhờ nó liệt kê file nào bị ảnh hưởng, rủi ro ở đâu. Khi plan đã hợp lý, bạn nhấn Tab sang build và bảo nó làm từng phần nhỏ. Cách này giúp bạn kiểm soát được việc sửa và tránh những thay đổi tràn lan.
D.Tìm kiếm nhiều bước với general
Bạn cần biết một hàm được gọi ở những đâu và ảnh hưởng gì. Thay vì tự tìm, hãy gọi subagent:
@general Tìm mọi nơi gọi hàm tinhPhiVanChuyen và liệt kê theo file.README nói subagent này dành cho tìm kiếm phức tạp và việc nhiều bước. Kết quả là một danh sách để bạn xem xét tiếp.
VI.Lỗi hay gặp và cách xử lý
A.Gõ lệnh báo không tìm thấy
Sau khi cài bằng script, thư mục cài là $HOME/.opencode/bin. Nếu terminal không nhận lệnh, hãy đóng terminal rồi mở lại. Nếu vẫn không được, kiểm tra thư mục đó đã có trong PATH chưa. Cách đặt PATH khác nhau theo hệ điều hành, và README không hướng dẫn.
B.Cài chồng nhiều cách khiến chạy nhầm bản cũ
README dặn gỡ bản cũ hơn 0.1.x trước khi cài. Nếu bạn lỡ cài bằng cả npm lẫn brew, có thể máy đang chạy bản không như ý. Hãy gỡ bớt, chỉ giữ một cách cài.
C.Lệnh npm báo lỗi hoặc không tìm thấy gói
README ghi npm i -g @opencode/cli@latest, trong khi tên gói công bố của repo là opencode. Nếu lệnh lỗi, thử cách cài khác (script, Homebrew, mise) và xem lại trang docs để biết lệnh đúng mới nhất.
D.AI sửa file không như ý
Agent build có toàn quyền nên nó có thể đổi nhiều file. Cách an toàn: làm việc trên bản sao hoặc nhánh riêng, yêu cầu nhỏ và cụ thể, rồi xem lại từng thay đổi. Khi chưa chắc, chuyển sang plan.
E.Không biết cấu hình mô hình AI ở đâu
README không nói. Hãy đọc trang tài liệu opencode.ai/docs (README nhắc đây là nơi hướng dẫn cấu hình). Đừng dán khoá bí mật vào chỗ công khai hay đưa lên GitHub.
VII.Có nên dùng không
Điểm mạnh: mã nguồn mở, giấy phép MIT, có nhiều cách cài, có bản desktop cho người ngại terminal, và có sẵn hai chế độ build/plan giúp bạn chủ động kiểm soát. Repo còn được cập nhật trong vài tháng gần đây, và cộng đồng khá đông.
Giới hạn: README ngắn, chưa nói rõ cách khởi chạy, cách thêm API key hay yêu cầu phiên bản. Bản desktop vẫn là beta. Cách cài đặt cũng hơi rối vì có nhiều lựa chọn và có chỗ tên gói chưa thống nhất. Người hoàn toàn mới sẽ cần đọc thêm tài liệu trên trang chủ.
Khi nên chọn cách khác: nếu bạn chỉ cần hỏi đáp nhanh về code mà không muốn cài gì, một khung chat AI trên web có thể đủ. Nếu bạn cần công cụ có hướng dẫn từng bước và hỗ trợ chính thức bằng tiếng Việt, hãy cân nhắc kỹ. Còn nếu bạn muốn một agent lập trình mã nguồn mở, tự chủ, chạy cạnh code của mình, 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?
Repo là mã nguồn mở với giấy phép MIT, nên phần mềm dùng tự do. README không nói về chi phí của mô hình AI hay dịch vụ đi kèm. Bạn cần xem trang tài liệu của dự án để biết chi tiết.
opencode chạy được trên Windows không?
README có file cài đặt bản desktop cho Windows là opencode-desktop-win-x64.exe (đang beta). Các lệnh cài bằng script, Homebrew, pacman nhắm tới macOS và Linux. Lệnh mise được ghi là dùng cho mọi hệ điều hành.
Cần GPU hay máy mạnh không?
README không nêu yêu cầu phần cứng nào. Chưa có thông tin về việc có cần GPU hay không, bạn nên xem tài liệu trên trang chủ opencode.ai.
agent 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 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 tìm kiếm phức tạp và các việc nhiều bước. opencode dùng nó nội bộ, và bạn cũng có thể gọi bằng cách gõ @general trong tin nhắn.
Dữ liệu và code của mình có an toàn không?
README không nói về cách xử lý dữ liệu. Chỉ có hai điều được ghi rõ: plan không sửa file mặc định và hỏi trước khi chạy bash. Repo có file SECURITY.md để bạn tham khảo thêm.
Cài xong rồi thì xem hướng dẫn cấu hình ở đâu?
README chỉ đến trang tài liệu của dự án tại opencode.ai/docs để biết cách cấu hình, cùng một trang riêng về agents. Cộng đồng có Discord và X.com được nêu ở cuối README.


