opencode: trợ lý lập trình AI mã nguồn mở chạy ngay trên máy — 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), giúp bạn đọc hiểu, phân tích và sửa code bằng cách trò chuyện. Có bản dòng lệnh và bản desktop (BETA) cho macOS, Windows, Linux. Cài khá dễ: chỉ cần một dòng lệnh hoặc tải file cài đặt từ trang chủ.
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, nó giúp bạn đọc code, phân tích dự án và thực hiện thay đổi. Repo do tác giả mô tả ngắn gọn là "the open source coding agent", viết chủ yếu bằng TypeScript, dùng giấy phép MIT.
Người nên thử là lập trình viên mới muốn có người "ngồi cạnh" giải thích code, và cả người làm kinh doanh, văn phòng đang nhận một dự án phần mềm hay một thư mục code mà không biết bắt đầu từ đâu. Hiện repo có khoảng 226.506 sao và 30.658 fork, và vẫn được cập nhật trong 3 tháng gần đây, nên đây là một dự án khá đông người dùng và còn sống.
Điểm đáng giá nhất là hai chế độ làm việc tách bạch: build (toàn quyền, để làm việc) và plan (chỉ đọc, để khám phá và lên kế hoạch). Bạn chuyển qua lại bằng phím Tab. Nhờ vậy bạn có thể cho AI xem code trước mà không sợ nó sửa lung tung.
anomalyco/opencode
opencode là agent lập trình AI mã nguồn mở, có chế độ build để sửa code và chế độ plan chỉ đọc để phân tích, cài bằng một dòng lệnh hoặc app desktop.
I.opencode làm được gì
Tư liệu của repo khá gọn, nên mình chỉ nói những gì có thật trong đó.
A.Hai agent có sẵn: build và plan
- build là agent mặc định, có đầy đủ quyền để làm việc phát triển. Khi bạn đã rõ mình muốn gì, đây là chế độ để giao việc.
- 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 bạn trước khi chạy lệnh bash.
Lợi ích thực tế: khi nhận một dự án lạ, bạn bật plan để hỏi "dự án này làm gì, file nào quan trọng". Chưa có gì bị thay đổi. Khi đã hiểu và đồng ý hướng đi, bạn bấm Tab để sang build.
B.Subagent general
Ngoài hai agent trên còn có subagent general, dùng cho các tìm kiếm phức tạp và công việc nhiều bước. README cho biết nó chủ yếu được dùng nội bộ, nhưng bạn có thể gọi trực tiếp bằng @general trong tin nhắn. Hữu ích khi câu hỏi cần lục nhiều nơi trong dự án.
C.Có cả bản dòng lệnh lẫn bản desktop
Ngoài cài bằng dòng lệnh, opencode có ứng dụng desktop (đang ở mức BETA) cho macOS (Apple Silicon và Intel), Windows và Linux. Người không quen terminal có thể bắt đầu từ app này.
D.Nhiều cách cài
README liệt kê script cài một dòng, npm, Homebrew, pacman, paru, mise và Nix. Bạn chọn cách quen tay nhất với hệ điều hành của mình.
E.Mã nguồn mở, giấy phép MIT
Bạn đọc được mã, dùng và tự kiểm tra. Giấy phép MIT là loại rất thoáng.
II.Cần chuẩn bị gì
Tư liệu của repo không ghi yêu cầu chi tiết về phiên bản Node hay Python, cũng không nói về GPU. Những gì có trong README:
- Hệ điều hành: bản desktop có cho macOS (Apple Silicon, Intel), Windows và Linux. Cách cài bằng terminal ghi macOS, Linux, Arch Linux, Nix; riêng
miseghi là dùng được trên mọi hệ điều hành. - Công cụ cài đặt: tùy cách bạn chọn, bạn cần sẵn
curlvàbash, hoặc npm/bun/pnpm/yarn, hoặc Homebrew, v.v. - 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, cấu hình mô hình AI: README chưa nói. Phần này xem tại tài liệu chính thức: https://opencode.ai/docs.
README không nêu cách kết nối mô hình AI hay chi phí. Nếu sau này bạn dùng dịch vụ AI có tính phí hoặc phải điền key, hãy đọc kỹ tài liệu chính thức trước, và đừng dán key vào nơi công khai.
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 app desktop
- Gỡ bản cũNếu có bản cũ hơn 0.1.x thì gỡ trước
- Chạy lệnh càiDán lệnh phù hợp vào terminal
- Mở dự ánVào thư mục code của bạn rồi khởi động opencode
- Đọc tài liệuXem cách cấu hình tại opencode.ai/docs
A.Chọn cách cài phù hợp
README đưa ra nhiều lựa chọn. Người mới nên chọn một trong hai: script một dòng (nhanh nhất), hoặc app desktop nếu ngại terminal. Nếu bạn dùng Windows và không quen dòng lệnh, app desktop là hướng dễ nhất (xem bước cuối của phần này).
B.Gỡ bản cũ (nếu có)
README lưu ý: gỡ các phiên bản cũ hơn 0.1.x trước khi cài. README không ghi lệnh gỡ, nên hãy gỡ theo đúng cách bạn đã cài bản cũ đó (ví dụ qua chính trình quản lý gói bạn từng dùng).
C.Cài bằng script một dòng
Mở terminal (macOS/Linux: ứng dụng Terminal; Windows: dùng môi trường có bash) rồi dán lệnh sau. README gọi nó vui là "YOLO", vì nó tải script về và chạy luôn:
# YOLO
curl -fsSL https://opencode.ai/v2/install | bashScript sẽ cài opencode vào thư mục $HOME/.opencode/bin. Chạy script từ mạng thì nên tin nguồn; nếu bạn thấy ngại, hãy chọn trình quản lý gói bên dưới.
D.Cài bằng trình quản lý gói
README liệt kê các lệnh sau, chọn đúng một dòng hợp với máy bạn:
# 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 # NixVài ghi chú cho người mới:
- Mỗi dòng là một cách khác nhau. Đừng chạy hết cả khối, chỉ chạy một dòng.
- Dòng
npmdùng-gnghĩa là cài toàn cục trên máy; bạn cần có Node và npm sẵn. Có thể thay bằng bun, pnpm hoặc yarn. - Hai dòng
brewdành cho macOS và Linux. README ghi dòng đầu (anomalyco/tap/opencode-v2) là cách được khuyến nghị vì luôn mới nhất, dòng thứ hai là công thức chính thức của Homebrew nhưng cập nhật chậm hơn. pacmanlà bản ổn định cho Arch Linux, cònparulấy bản mới nhất từ AUR.miseđược ghi là dùng cho mọi hệ điều hành.
E.Hoặc dùng app desktop (BETA)
Tải tại opencode.ai/download. Tên file theo README:
| 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, nếu dùng Homebrew thì có thể cài app bằng:
# macOS (Homebrew)
brew install --cask opencode-desktopVì còn ở mức BETA, bạn nên chuẩn bị tinh thần là có thể gặp trục trặc nhỏ.
IV.Kiểm tra đã chạy được chưa
README không có mục "kiểm tra sau cài" và cũng không ghi rõ lệnh khởi động. Vì tên gói là opencode, cách hợp lý để thử là mở một terminal mới (để máy nhận đường dẫn mới), rồi gõ:
opencodeĐây là suy ra từ tên gói chứ không phải lệnh chép từ README, nên nếu máy báo không tìm thấy lệnh, hãy xem tài liệu tại https://opencode.ai/docs.
Nếu cài bằng script một dòng, README nói file được đặt ở $HOME/.opencode/bin. Bạn có thể mở thư mục đó để xem file đã nằm đó chưa. Nếu dùng app desktop, chỉ cần mở app lên và thấy giao diện hiện ra là xong.
Khi đã vào được giao diện, thử bấm Tab. README nói phím này đổi giữa hai agent build và plan, nên đây là cách kiểm tra nhanh rằng mọi thứ đang hoạt động.
V.Dùng vào việc thật
Dưới đây là các tình huống mình thấy hợp với khả năng mà README mô tả. Câu lệnh mẫu chỉ là gợi ý cách bạn nói chuyện với agent, không phải cú pháp bắt buộc.
A.Làm quen một dự án lạ bằng chế độ plan
Bối cảnh: bạn là nhân viên mới, được giao một thư mục code của công ty mà chưa ai giải thích.
Cách làm: mở opencode trong thư mục đó, bấm Tab cho đến khi ở chế độ plan. Vì plan chỉ đọc, bạn yên tâm hỏi thoải mái. Ví dụ:
Dự án này làm gì? Hãy tóm tắt cấu trúc thư mục và chỉ cho mình file nào nên đọc trước.Kết quả: bạn có bản tóm tắt dễ hiểu, và chưa có file nào bị đổi. Nếu agent định chạy lệnh bash, nó sẽ hỏi bạn trước.
B.Lên kế hoạch trước khi sửa lỗi
Bối cảnh: bạn là lập trình viên mới, có một lỗi hiển thị sai trên trang web và chưa biết sửa ở đâu.
Cách làm: ở chế độ plan, mô tả lỗi và nhờ phân tích:
Trang danh sách đơn hàng hiển thị sai tổng tiền. Hãy tìm nơi tính tổng và đề xuất cách sửa, chưa cần sửa ngay.Đọc kế hoạch, thấy hợp lý thì bấm Tab sang build và yêu cầu thực hiện.
Kết quả: bạn kiểm soát được thứ tự: hiểu trước, sửa sau.
Cho AI đọc trước, đồng ý rồi mới cho nó sửa — đó là cách dùng agent mà không phải đứng tim.
Ông T
C.Tìm kiếm phức tạp bằng @general
Bối cảnh: chủ một cửa hàng nhỏ thuê người viết web bán hàng, nay muốn hiểu nhờ đâu mà đơn hàng được gửi email xác nhận, nhưng không biết nó nằm ở đâu trong code.
Cách làm: gọi subagent bằng @general trong tin nhắn:
@general Tìm giúp mình toàn bộ chỗ trong dự án có liên quan đến việc gửi email xác nhận đơn hàng và giải thích luồng chạy.Kết quả: README cho biết general dành cho các tìm kiếm phức tạp và việc nhiều bước, nên đây là loại câu hỏi phù hợp. Bạn nhận được lời giải thích để trao đổi lại với người viết code.
D.Giao việc cho agent build
Bối cảnh: bạn là dev, cần thêm một thay đổi nhỏ đã rõ yêu cầu, ví dụ đổi chữ trên một nút hoặc thêm kiểm tra dữ liệu đầu vào.
Cách làm: ở chế độ build (mặc định), nêu việc cụ thể:
Thêm kiểm tra: nếu số điện thoại để trống thì hiện thông báo lỗi ở form đặt hàng.Kết quả: agent có toàn quyền nên sẽ tiến hành sửa. Bạn nên đọc lại các thay đổi trước khi dùng thật, và với dự án quan trọng hãy lưu bản dự phòng (ví dụ qua git) trước khi giao việc.
VI.Lỗi hay gặp và cách xử lý
README không có mục xử lý lỗi, nên các lỗi dưới đây là những tình huống rất dễ gặp với loại công cụ này, kèm hướng khắc phục an toàn.
A.Gõ lệnh báo "không tìm thấy lệnh"
Thường do terminal chưa nhận đường dẫn mới sau khi cài. Hãy đóng terminal, mở cái mới và thử lại. Với script một dòng, file nằm ở $HOME/.opencode/bin, nên nếu cần hãy kiểm tra thư mục này có nằm trong PATH của bạn chưa.
B.Nhầm lẫn giữa nhiều bản cài
Nếu bạn từng cài bản cũ, rồi cài thêm bản mới bằng cách khác, máy có thể chạy nhầm bản cũ. README khuyên gỡ các bản cũ hơn 0.1.x trước khi cài. Hãy gỡ bản cũ đúng theo cách bạn đã cài nó.
C.Nhầm chế độ plan và build
Nếu bạn muốn agent sửa file mà nó từ chối, có thể bạn đang ở chế độ plan (mặc định từ chối sửa file). Bấm Tab để sang build. Ngược lại, nếu chỉ muốn khám phá mà lỡ để ở build, hãy chuyển về plan trước khi hỏi.
D.Agent sửa sai hoặc sửa quá tay
Agent build có toàn quyền nên có thể thay đổi nhiều hơn bạn nghĩ. Cách an toàn: làm việc trong thư mục có quản lý phiên bản (git) để hoàn tác được, giao việc nhỏ từng bước, và đọc lại thay đổi trước khi dùng.
E.Cấu hình mô hình hoặc tài khoản chưa xong
Nếu mở được giao diện nhưng agent không trả lời, nhiều khả năng bước kết nối mô hình AI chưa được thiết lập. README chưa nói chi tiết phần này, hãy làm theo tài liệu tại https://opencode.ai/docs, hoặc hỏi trong cộng đồng Discord của dự án.
VII.Có nên dùng không
Điểm mạnh
- Mã nguồn mở, giấy phép MIT, có số người dùng lớn (khoảng 226.506 sao) và vẫn được cập nhật.
- Hai chế độ build và plan giúp bạn kiểm soát rủi ro: đọc trước, sửa sau.
- Nhiều cách cài, có cả app desktop cho Windows, macOS, Linux.
- README có nhiều bản dịch, trong đó có tiếng Việt.
Giới hạn
- README chưa ghi rõ yêu cầu hệ thống, cách kết nối mô hình AI hay chi phí, bạn phải đọc thêm tài liệu chính thức.
- Bản desktop còn ở mức BETA.
- Chế độ build có toàn quyền, nên người mới cần thói quen sao lưu và kiểm tra kết quả.
- Có thể bạn bối rối vì nhiều lệnh cài khác nhau; README ghi tên gói npm ở hai dạng (tên gói
opencodevà lệnh@opencode/cli), nên nếu một lệnh không chạy, hãy thử cách cài khác hoặc đối chiếu lại với trang chủ.
Khi nào chọn cách khác: nếu bạn không đụng đến code mà chỉ cần một chatbot hỏi đáp thông thường, một ứng dụng chat là đủ. Còn nếu bạn muốn một trợ lý nằm cạnh code, đọc, phân tích và sửa trong dự án, opencode là lựa chọn đáng thử, nhất là khi bạn thích công cụ mã nguồn mở.
Trang chủ: https://opencode.ai. Tài liệu cấu hình: https://opencode.ai/docs.
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. Tư liệu chưa nói gì về chi phí khi kết nối với các mô hình AI, nên bạn cần xem tài liệu tại opencode.ai/docs trước khi dùng.
opencode chạy được trên Windows không?
Có bản desktop (BETA) cho Windows với file opencode-desktop-win-x64.exe. Với cách cài bằng terminal, README chỉ nói rõ macOS, Linux, Arch Linux, Nix và mise (mọi hệ điều hành), chưa có hướng dẫn riêng cho Windows.
Có cần GPU để chạy không?
Tư liệu chưa có thông tin về phần cứng hay GPU. Bạn nên xem tài liệu chính thức để biết chi tiết.
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 là agent chỉ đọc: mặc định từ chối sửa file và hỏi trước khi chạy lệnh bash, hợp để khám phá code lạ hoặc lên kế hoạch. Bạn đổi qua lại bằng phím Tab.
@general dùng để làm gì?
general là subagent cho các tìm kiếm phức tạp và công việc nhiều bước. README cho biết nó chủ yếu được dùng nội bộ, nhưng bạn có thể gọi trực tiếp bằng @general trong tin nhắn.
Script cài đặt đặt opencode ở đâu?
Script cài sẽ đặt opencode vào thư mục $HOME/.opencode/bin, theo README.
Dữ liệu và mã nguồn của tôi có an toàn không?
Tư liệu chưa có thông tin về cách xử lý dữ liệu. Repo có tệp SECURITY.md và mã nguồn mở nên bạn có thể tự kiểm tra, nhưng với code nhạy cảm bạn nên đọc kỹ tài liệu chính thức trước.


