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 (anomalyco/opencode) là một coding agent 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 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 bản desktop (BETA).
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 thư mục dự án rồi giúp bạn phân tích hoặc sửa. Tác giả giới thiệu ngắn gọn là "The open source coding agent". Repo hiện có khoảng 226.506 sao và 30.658 fork trên GitHub, viết chủ yếu bằng TypeScript, giấy phép MIT, và vẫn được cập nhật trong 3 tháng gần đây.
Bạn nên xem qua nếu là lập trình viên mới muốn có "người kèm" khi đọc một dự án lạ, hoặc người làm văn phòng, chủ shop đang nhờ dev hay tự chỉnh vài đoạn code (website, file tự động hoá) và muốn có công cụ hỏi đáp trực tiếp trên code đó. Bạn không cần là chuyên gia, nhưng cần biết mở terminal và gõ lệnh.
Điểm đáng giá nhất của opencode là cách chia vai rõ ràng: một chế độ build có toàn quyền để làm việc, và một chế độ plan chỉ đọc, mặc định không sửa file. Bạn bấm phím Tab để chuyển qua lại. Nhờ vậy bạn có thể "nhìn" trước, an tâm rồi mới cho nó động vào code.
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.
I.opencode làm được gì
Theo README, opencode có những phần chính sau.
A.Hai agent có sẵn: build và plan
- build là agent mặc định, có toàn quyền cho công việc phát triển. Bạn dùng khi đã biết mình muốn gì và để nó bắt tay làm.
- plan là 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à hỏi lại bạn trước khi chạy lệnh bash. Rất hợp khi bạn mở một dự án chưa quen hoặc muốn lên kế hoạch thay đổi trước.
Bạn chuyển giữa hai agent bằng phím Tab. Lợi ích thực tế: bạn kiểm soát được mức "quyền" của AI ngay trong lúc làm việc, không phải đổi cấu hình.
B.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ùng cho các tìm kiếm phức tạp hoặc việc nhiều bước. README nói nó được dùng nội bộ, và bạn có thể gọi trực tiếp bằng cách gõ @general trong tin nhắn. Hữu ích khi câu hỏi kiểu "chỗ nào trong dự án xử lý việc này?" cần lần qua nhiều file.
C.Nhiều cách cài, có cả bản desktop
Bạn có thể cài qua script, npm, Homebrew, pacman, mise hoặc Nix. Ngoài ra có ứng dụng desktop (BETA) cho macOS, Windows và Linux, hợp với ai chưa quen terminal.
D.Mã nguồn mở, có tài liệu riêng
Giấy phép MIT, nên bạn xem được code và dùng tự do theo giấy phép. Phần cấu hình chi tiết nằm ở trang tài liệu của dự án (opencode.ai/docs), README không chép lại.
II.Cần chuẩn bị gì
README chỉ nói những điều sau:
- Một máy macOS, Linux hoặc Windows. Bản desktop có file cho macOS (Apple Silicon và Intel), Windows (
opencode-desktop-win-x64.exe) và Linux (.deb,.rpm,.AppImage). - Nếu dùng cách cài bằng npm thì cần có npm (README ghi "or bun/pnpm/yarn" nên các công cụ này cũng được).
- Nếu trước đây bạn đã cài phiên bản cũ hơn 0.1.x, README dặn gỡ đi trước khi cài.
Về tài khoản, API key hay phần cứng (GPU): README chưa ghi. Bạn xem mục cấu hình trong tài liệu tại opencode.ai/docs để biết cách kết nối với mô hình AI.
README không nói về chi phí hay key. Khi tài liệu hướng dẫn bạn điền khoá của một dịch vụ AI, hãy giữ kín khoá đó, đừng dán vào chat công khai hay đẩy lên GitHub. Hãy đọc kỹ bảng giá của dịch vụ bạn chọn trước khi cho AI chạy nhiều việc liên tục.
III.Cài đặt từng bướ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 tương ứng vào terminal
- Gỡ bản cũ nếu cóXoá phiên bản cũ hơn 0.1.x trước khi cài
- Mở dự áncd vào thư mục code bạn muốn làm việc
- Xem tài liệu cấu hìnhLàm theo opencode.ai/docs để kết nối mô hình AI
A.Chọn cách cài phù hợp với bạn
README liệt kê nhiều cách. Nếu chưa quen, bạn chọn một cái thôi, không cần chạy hết. Người dùng macOS hoặc Linux thường chọn script hoặc Homebrew. Ai ngại terminal có thể nhảy sang phần bản desktop ở cuối mục này.
B.Cài bằng script một dòng
Đây là cách README gọi vui là "YOLO" (chạy một phát cho xong). Mở terminal rồi dán:
curl -fsSL https://opencode.ai/v2/install | bashLệnh này tải script cài đặt từ trang chủ rồi chạy luôn. Theo README, script cài opencode vào thư mục $HOME/.opencode/bin. Lệnh này dùng bash, nên với Windows bạn nên cân nhắc một trong các cách khác bên dưới (npm, mise) hoặc bản desktop, vì README không nói rõ script chạy được trên Windows thuần hay không.
C.Cài bằng trình quản lý gói
Tất cả các dòng dưới đây chép nguyên từ README. Chọn một dòng phù hợp hệ thống của bạn:
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 # NixGhi chú nhanh:
npm i -glà cài toàn cục bằng npm, cần máy đã có Node và npm.- Hai dòng
brewdành cho macOS và Linux. README khuyên dòng đầu (anomalyco/tap/opencode-v2) vì luôn mới; dòng sau là bản chính thức của Homebrew nhưng cập nhật chậm hơn. pacmanvàparudành cho Arch Linux.mise use -g opencodedùng được trên mọi hệ điều hành nếu bạn đã có mise.nix runchạy thẳng từ GitHub nếu bạn dùng Nix.- Chỗ người mới hay vấp: tên gói trong README có chỗ là
opencode, có chỗ là@opencode/cli. Cứ chép đúng dòng của cách bạn chọn, đừng tự sửa.
D.Cài bản desktop (BETA)
Vào opencode.ai/download và tải file đúng hệ điều hành:
| Nền tảng | 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:
brew install --cask opencode-desktopVì đây là bản BETA, có thể còn lỗi vặt. Nếu gặp sự cố, thử bản terminal.
E.Mở dự án và bắt đầu
README chưa ghi lệnh khởi động cụ thể. Bạn xem hướng dẫn trong tài liệu tại opencode.ai/docs. Khi làm việc, hãy đứng trong thư mục dự án của bạn. Ví dụ với một dự án tải từ GitHub (thay <tên>/<repo> bằng dự án của bạn):
git clone https://github.com/<tên>/<repo>.git
cd <repo>IV.Kiểm tra đã chạy được chưa
README không nêu lệnh kiểm tra hay màn hình kết quả mong đợi. Cách an toàn để biết cài thành công:
- Mở một cửa sổ terminal mới (để máy nạp lại đường dẫn), rồi thử gọi lệnh
opencode. Nếu terminal báo không tìm thấy lệnh, xem phần lỗi thường gặp bên dưới. - Nếu cài bằng script, kiểm tra thư mục
$HOME/.opencode/bincó tồn tại không, vì README nói script cài vào đó. - Nếu dùng bản desktop, mở ứng dụng lên và thấy giao diện là xong bước cài.
- Khi vào được giao diện, thử bấm
Tab: README nói phím này chuyển giữa agent build và plan. Thấy chế độ đổi là bạn đã chạy đúng.
V.Dùng vào việc thật
README chỉ mô tả các agent chứ không đưa ví dụ cụ thể. Các tình huống dưới đây là cách mình gợi ý áp dụng, bám đúng khả năng đó.
A.Nhân viên mới đọc một dự án code chưa từng thấy
Bạn vừa nhận bàn giao một website nội bộ, mở ra thấy hàng chục thư mục. Hãy để opencode ở chế độ plan (chỉ đọc, không sửa). Gõ câu hỏi bằng tiếng Việt:
Dự án này làm gì? Hãy tóm tắt 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 được bản giải thích bằng lời, và vì đang ở plan nên không có file nào bị đổi. Nếu nó xin chạy lệnh bash, nó sẽ hỏi bạn trước.
Cứ để AI đọc trước, sửa sau. Chế độ chỉ đọc là cách rẻ nhất để biết mình đang làm việc với cái gì.
Ông T
B.Chủ shop muốn sửa nhỏ trên trang bán hàng
Bạn có một trang giới thiệu sản phẩm bằng code đơn giản và muốn đổi số hotline, thêm một dòng chính sách đổi trả. Trước tiên, ở chế độ plan, hỏi nó sẽ sửa ở đâu. Khi đã thấy hợp lý, bấm Tab sang build rồi ra lệnh:
Đổi số hotline thành số mới ở mọi nơi trong dự án, và thêm dòng "Đổi trả trong 7 ngày" dưới phần mô tả sản phẩm.Kết quả: các file được sửa theo yêu cầu. Bạn nên mở lại trang để xem bằng mắt, hoặc nhờ dev xác nhận, trước khi đưa lên chạy thật.
C.Tìm nhanh trong dự án lớn bằng @general
Dev mới thường mất nhiều thời gian để tìm "chỗ tính phí vận chuyển nằm ở đâu". Dùng subagent general để tìm:
@general Tìm tất cả chỗ trong dự án có tính phí vận chuyển và liệt kê tên file kèm giải thích ngắn.Kết quả: một danh sách file liên quan thay vì bạn tự lần từng thư mục.
D.Lên kế hoạch trước khi đổi lớn
Bạn định đổi cách lưu đơn hàng và sợ làm hỏng mọi thứ. Ở chế độ plan, nhờ nó phân tích:
Nếu mình muốn đổi cách lưu đơn hàng, những file nào bị ảnh hưởng? Hãy đề xuất các bước làm theo thứ tự, chưa sửa gì cả.Kết quả: một kế hoạch từng bước để bạn đọc, chỉnh, rồi mới chuyển sang build khi thấy yên tâm.
VI.Lỗi hay gặp và cách xử lý
A.Gõ opencode báo không tìm thấy lệnh
Thường do terminal chưa nạp lại đường dẫn sau khi cài. Hãy đóng và mở terminal mới. Nếu cài bằng script, README nói file nằm ở $HOME/.opencode/bin; kiểm tra xem thư mục này có tồn tại không và đã nằm trong biến PATH của máy chưa. README chưa ghi cách thêm PATH, nên bạn xem hướng dẫn trong tài liệu dự án.
B.Lệnh curl ... | bash không chạy trên Windows
Lệnh dùng bash, môi trường Windows thường không có sẵn. Thay vì cố sửa, hãy dùng cách khác trong README: mise use -g opencode (README ghi "Any OS"), npm i -g nếu bạn đã có npm, hoặc tải file opencode-desktop-win-x64.exe.
C.Cài xong nhưng bản chạy là phiên bản cũ hoặc xung đột
README dặn: gỡ các phiên bản cũ hơn 0.1.x trước khi cài. Nếu bạn từng cài opencode bằng cách khác, hãy gỡ bản đó đi rồi cài lại để tránh hai bản chồng nhau.
D.Nhầm tên gói khi cài bằng npm hoặc brew
Trong README, tên gói khác nhau tuỳ cách cài (@opencode/cli, opencode, opencode-v2...). Hãy chép đúng nguyên dòng lệnh, không tự đổi tên. Với brew, README nói rõ dòng nào là bản mới nhất, dòng nào cập nhật chậm.
E.AI sửa code không như ý
Ngay cả agent tốt cũng có lúc hiểu sai. Cách xử lý an toàn: để nó phân tích ở chế độ plan trước, chỉ chuyển sang build khi đã đồng ý với hướng làm, và luôn giữ bản sao lưu hoặc quản lý code bằng git để quay lại được.
VII.Có nên dùng không
Điểm mạnh. Mã nguồn mở với giấy phép MIT, cộng đồng lớn (khoảng 226.506 sao). Có nhiều cách cài, kể cả bản desktop cho người ngại terminal. Cặp agent build/plan cho bạn kiểm soát mức quyền một cách rõ ràng: xem trước, rồi mới làm.
Giới hạn. README khá ngắn: chưa nói rõ lệnh khởi động, cách kết nối mô hình AI, yêu cầu phiên bản hay chi phí, bạn phải đọc thêm tài liệu trên opencode.ai/docs. Bản desktop vẫn là BETA. Cách đặt tên gói trong README chưa thật nhất quán, người mới dễ rối. Dữ liệu code của bạn đi đâu còn phụ thuộc vào mô hình AI bạn chọn, mà tư liệu ở đây chưa nói.
Khi nào chọn cách khác. Nếu bạn không đụng đến code và chỉ cần trò chuyện hỏi đáp thông thường, một ứng dụng chat là đủ. Nếu công ty bạn có quy định nghiêm về dữ liệu, hãy hỏi bộ phận IT và đọc kỹ tài liệu trước khi cho AI đọc mã nguồn nội bộ.
Với người muốn thử một coding agent mở, dễ cài và có sẵn chế độ chỉ đọc để học dần, opencode là lựa chọn đáng bỏ ít phút thử.
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ở theo giấy phép MIT nên dùng không mất tiền mua phần mềm. Tuy nhiên README không nói gì về chi phí của mô hình AI mà bạn kết nối. Bạn cần xem tài liệu tại opencode.ai/docs để biết chi tiết.
opencode có chạy được trên Windows không?
Có bản desktop cho Windows (file opencode-desktop-win-x64.exe, đang ở dạng BETA). README cũng ghi mise dùng được trên mọi hệ điều hành và có lệnh cài bằng npm. Riêng script curl dùng bash nên README chưa nói rõ có chạy trên Windows thuần hay không.
opencode có cần GPU không?
README không nhắc đến yêu cầu GPU hay cấu hình phần cứng. Chưa có thông tin về việc này trong tư liệu, bạn nên xem thêm tại opencode.ai/docs.
Agent build và plan khác nhau thế nào?
build là agent mặc định, có toàn quyền cho 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.
@general dùng để làm gì?
general là subagent dành cho các tìm kiếm phức tạp và việc nhiều bước. README nói nó được dùng nội bộ và bạn cũng có thể gọi trực tiếp 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 mô tả chi tiết về xử lý dữ liệu. Chế độ plan giúp hạn chế việc sửa file ngoài ý muốn, nhưng việc code được gửi đến đâu còn phụ thuộc cấu hình bạn chọn. Chưa có thông tin cụ thể trong tư liệu, hãy đọc tài liệu và chính sách bảo mật của dự án (có file SECURITY.md trong repo).
Tài liệu hướng dẫn cấu hình nằm ở đâu?
README trỏ tới trang tài liệu của dự án tại opencode.ai/docs, trong đó có phần về agent và cấu hình. Dự án cũng có cộng đồng trên Discord và X.com.


