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 AI coding agent mã nguồn mở (giấy phép MIT, viết bằng TypeScript) giúp bạn đọc hiểu, sửa và lên kế hoạch cho code bằng ngôn ngữ thường. Cài bằng một dòng lệnh, npm, Homebrew hoặc tải bản desktop (BETA). Người mới có thể bắt đầu trong vài phút, nhưng phần cấu hình chi tiết nằm ở trang docs của dự án.
OpenCode là một coding agent mã nguồn mở: bạn mô tả việc cần làm bằng lời thường, nó đọc mã nguồn, đề xuất và sửa file, chạy lệnh giúp bạn. Dự án viết bằng TypeScript, dùng giấy phép MIT, hiện có khoảng 226.506 sao và 30.658 fork trên GitHub. Con số lớn như vậy cho thấy đây là một trong những công cụ cùng loại được nhiều người quan tâm nhất.
Người nên thử là lập trình viên mới cần một người trợ giúp đọc code lạ, dev có kinh nghiệm muốn giao bớt việc lặp lại, hoặc người làm kinh doanh, văn phòng có biết chút tự động hoá và muốn nhờ AI dựng những đoạn mã nhỏ. Bạn không cần là chuyên gia để cài, vì có cả bản ứng dụng desktop (đang BETA).
Điểm đáng giá nhất theo README: có sẵn hai agent chuyển đổi bằng phím Tab. Một agent được sửa file, một agent chỉ đọc để phân tích và lên kế hoạch. Nhờ vậy bạn có thể cho AI xem dự án mà không sợ nó tự ý sửa lung tung.
anomalyco/opencode
OpenCode là coding agent mã nguồn mở: đọc code, sửa file, chạy lệnh theo yêu cầu của bạn, có chế độ plan chỉ đọc an toàn và cả bản desktop.
I.OpenCode làm được gì
Tư liệu của dự án mô tả khá gọn, nên mình chỉ nói những gì có ghi rõ.
Hai agent dựng sẵn, đổi bằng phím Tab. Agent build là mặc định, có toàn quyền cho công việc phát triển. Agent plan chỉ đọc: mặc định 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 mới 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» mà không lo bị đổi code.
Subagent general. Đây là agent phụ dành cho việc tìm kiếm phức tạp và công 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ợp khi bạn cần lục nhiều chỗ trong dự án rồi tổng hợp lại.
Nhiều cách cài. Có script một dòng, npm/bun/pnpm/yarn, Homebrew, pacman và paru cho Arch Linux, mise, Nix. Nghĩa là dù bạn dùng macOS hay Linux, gần như chắc chắn có cách cài quen tay.
Bản desktop (BETA). Có file cài cho macOS (Apple Silicon và Intel), Windows và Linux (.deb, .rpm, .AppImage). Người không quen terminal có thể chọn đường này.
Mã nguồn mở, giấy phép MIT. Bạn đọc được code, dùng cho cá nhân hay công việc, và có tài liệu riêng ở trang docs của dự án để chỉnh cấu hình sâu hơn.
II.Cần chuẩn bị gì
README ghi rất ít về yêu cầu, nên mình chỉ nêu đúng những gì có:
- Hệ điều hành: README có file cài cho macOS (Apple Silicon và Intel), Windows và Linux ở bản desktop. Với dòng lệnh, README liệt kê macOS và Linux (Homebrew), Arch Linux, mise (ghi là dùng được trên mọi hệ điều hành) và Nix.
- Trình quản lý gói: nếu chọn cách cài bằng npm thì máy bạn cần có npm (README ghi cũng dùng được bun, pnpm, yarn). Chọn Homebrew thì cần Homebrew.
- Dọn 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, phiên bản Node: README chưa nói gì về các mục này. Bạn xem thêm ở trang docs của dự án (opencode.ai/docs) trước khi cài để biết cần kết nối dịch vụ AI nào.
Các công cụ kiểu coding agent thường cần kết nối tới một mô hình AI, và có thể phát sinh chi phí ở phía nhà cung cấp mô hình. README của OpenCode chưa nói rõ phần này, nên hãy đọc docs trước khi nhập bất kỳ key nào, và đừng dán key vào chỗ người khác nhìn thấy được.
III.Cài đặt từng bước
- Chọn cách càiScript một dòng, npm, Homebrew hoặc bản 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 lệnh vào terminal và chờ xong
- Mở lại terminalĐể máy nhận lệnh mới
- Đọc docs để cấu hìnhXem hướng dẫn ở opencode.ai/docs
A.Chọn cách cài phù hợp
Mình gợi ý theo thói quen của bạn:
- Quen dòng lệnh, dùng macOS hoặc Linux: script một dòng hoặc Homebrew.
- Đã cài Node: dùng npm.
- Không muốn đụng terminal: tải bản desktop.
Terminal là cửa sổ gõ lệnh. Trên macOS bạn mở ứng dụng Terminal. Trên Linux mở ứng dụng terminal của bản phân phối. Trên Windows, README không ghi rõ cách chạy script bash, nên bạn có thể ưu tiên bản desktop opencode-desktop-win-x64.exe hoặc cách cài bằng npm/mise.
B.Gỡ phiên bản cũ (nếu có)
README có lưu ý: 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 từng cài, bạn gỡ theo đúng cách mình đã cài (ví dụ gỡ bằng chính npm hay Homebrew).
C.Chạy lệnh cài
Dưới đây là các lệnh nguyên văn trong README. Bạn chỉ cần chọn MỘT dòng, không chạy hết:
# 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 để bạn chọn đúng:
- Dòng
curl ... | bashtải script cài về và chạy luôn. README gọi đùa là «YOLO» vì bạn chạy script mà chưa đọc nó. Nếu thận trọng, hãy mở địa chỉ script trên trình duyệt đọc trước. - Dòng
npm i -g @opencode/cli@latestcài toàn cục bằng npm. Chữ-gnghĩa là cài cho cả máy, không chỉ một thư mục. README ghi bun, pnpm, yarn cũng dùng được. - Hai dòng
brewdành cho macOS và Linux. README đề xuấtanomalyco/tap/opencode-v2vì luôn mới nhất. Cònbrew install opencodelà công thức chính thức của Homebrew, cập nhật chậm hơn. pacmanvàparudành cho Arch Linux:pacmanbản ổn định,parubản mới nhất từ AUR.mise use -g opencodedùng được trên mọi hệ điều hành, nếu bạn đã có mise.nix run github:anomalyco/opencodedành cho người dùng Nix.
Chỗ người mới hay vấp: lệnh có sudo sẽ hỏi mật khẩu máy. Khi gõ mật khẩu, màn hình không hiện ký tự nào, đó là bình thường.
Về vị trí: README nói script cài đặt đưa OpenCode vào thư mục $HOME/.opencode/bin. Nếu sau khi cài mà terminal không nhận lệnh, hãy xem phần lỗi thường gặp bên dưới.
D.Dùng bản desktop nếu bạn ngại terminal
Tải từ trang opencode.ai/download. Theo README, tên file cho từng nền tảng như sau:
| 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 còn có thể cài bản desktop bằng Homebrew:
brew install --cask opencode-desktopLưu ý bản desktop đang ở giai đoạn BETA, nên có thể còn lỗi vặt.
E.Mở lại terminal và xem docs để cấu hình
Sau khi cài xong, hãy đóng terminal rồi mở lại để máy nhận lệnh mới. README chưa ghi lệnh để khởi động hay cách kết nối mô hình AI. Mọi hướng dẫn cấu hình nằm ở trang docs: https://opencode.ai/docs. Đây là chỗ bạn cần đọc tiếp trước khi dùng thật.
IV.Kiểm tra đã chạy được chưa
README không đưa lệnh kiểm tra cụ thể, nên mình không bịa ra cờ lệnh nào. Bạn có thể tự kiểm tra theo các dấu hiệu hợp lý sau:
- Lệnh cài chạy xong mà không báo lỗi đỏ.
- Với bản desktop: mở ứng dụng lên được và thấy giao diện chính.
- Khi đã mở được OpenCode theo docs, nhấn phím
Tabthì chuyển được giữa hai agent build và plan. README mô tả đây là cách đổi agent, nên nếu bạn thấy tên agent thay đổi là mọi thứ đang chạy đúng. - Thử gõ
@generaltrong một tin nhắn để gọi subagent general.
Nếu chưa thấy gì, quay lại phần lỗi thường gặp ở dưới.
V.Dùng vào việc thật
Các tình huống dưới đây bám theo những gì README nói OpenCode làm được: có agent build, agent plan và subagent general. Phần câu lệnh mẫu là gợi ý của mình, bạn viết lại theo dự án của bạn.
A.Tìm hiểu một dự án mới nhận mà không sợ hỏng
Bối cảnh: bạn là lập trình viên mới vừa vào công ty, được giao một thư mục code mà chưa ai giải thích. Bạn mở OpenCode ở thư mục đó, nhấn Tab để chuyển sang agent plan. Agent này chỉ đọc, mặc định từ chối sửa file và hỏi trước khi chạy lệnh bash.
Câu hỏi mẫu:
Hãy giải thích dự án này làm gì, thư mục nào chứa phần chính, và nếu mình muốn thêm trang đăng nhập thì nên bắt đầu từ file nào?Kết quả nhận được: một bản tóm tắt cấu trúc và các gợi ý điểm bắt đầu, trong khi code của bạn vẫn nguyên vẹn.
Cho AI đọc trước, sửa sau. Chế độ chỉ đọc giúp bạn yên tâm hỏi thoải mái.
Ông T
B.Lên kế hoạch trước khi sửa một tính năng
Bối cảnh: bạn làm freelance và khách nhờ đổi cách tính phí vận chuyển trong website. Bạn chưa chắc phần tính phí nằm ở đâu. Hãy để agent plan lập kế hoạch trước.
Mình cần đổi cách tính phí vận chuyển. Hãy tìm nơi đang tính phí, liệt kê các file cần sửa và đề xuất các bước, nhưng chưa sửa gì.Kết quả: một danh sách file và các bước. Bạn xem lại, thấy hợp lý thì nhấn Tab chuyển sang build và nhờ nó thực hiện từng bước. Làm theo thứ tự này bạn kiểm soát được cái gì sắp bị đổi.
C.Giao việc nhiều bước cho agent build
Bối cảnh: bạn là chủ shop nhỏ, có người viết giúp một script xuất đơn hàng ra file, nhưng thiếu cột số điện thoại. Bạn dùng agent build (mặc định, có đủ quyền cho công việc phát triển).
Trong script xuất đơn hàng, hãy thêm cột số điện thoại khách vào file kết quả và giữ nguyên các cột cũ.Kết quả: agent đề xuất và chỉnh code. Bạn nên mở lại file đã sửa, chạy thử trên dữ liệu mẫu rồi mới dùng với dữ liệu thật. Nếu dự án chưa có bản sao lưu, hãy tự sao lưu thư mục trước khi cho agent sửa.
D.Nhờ @general tìm và tổng hợp
Bối cảnh: bạn là dev, cần biết hàm nào đang gọi tới một module cũ trước khi gỡ nó. Việc này phải lục nhiều chỗ, đúng loại việc README gán cho subagent general («tìm kiếm phức tạp và công việc nhiều bước»).
@general tìm tất cả chỗ trong dự án đang dùng module thanh toán cũ và tóm tắt lại theo từng file.Kết quả: một bản tổng hợp các chỗ cần xử lý, giúp bạn ước lượng công việc trước khi bắt tay sửa.
VI.Lỗi hay gặp và cách xử lý
README không có mục xử lý sự cố, 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ụ cài qua dòng lệnh. Mình không khẳng định thông báo lỗi cụ thể.
Gõ tên lệnh mà terminal báo không tìm thấy. Hãy đóng và mở lại terminal. Nếu bạn cài bằng script, README nói file được đặt ở $HOME/.opencode/bin, nên kiểm tra thư mục này đã nằm trong biến PATH của máy chưa. Nếu chưa, xem docs của dự án để thêm vào.
Cài bằng npm bị từ chối quyền. Tránh dùng sudo vội vàng với npm. Hãy thử cách khác như Homebrew, mise hoặc bản desktop, những cách README đã liệt kê.
Trùng với bản cũ. README khuyên gỡ các bản cũ hơn 0.1.x trước khi cài. Nếu cài xong mà chạy ra phiên bản lạ, nhiều khả năng bản cũ vẫn còn. Gỡ nó theo đúng cách đã cài rồi cài lại.
Nhầm với dự án khác có chữ «opencode» trong tên. README nhắc rằng các dự án như «opencode-dashboard» hay «opencode-mobile» có thể không do đội OpenCode làm và không liên kết gì với họ. Hãy tải từ đúng nguồn: repo anomalyco/opencode hoặc trang opencode.ai.
Agent sửa file ngoài ý muốn. Agent build có toàn quyền. Nếu bạn chỉ muốn khám phá, hãy nhấn Tab sang agent plan. Với dự án quan trọng, luôn sao lưu hoặc dùng quản lý phiên bản như git trước khi giao việc.
VII.Có nên dùng không
Điểm mạnh. Mã nguồn mở với giấy phép MIT, nhiều cách cài, có cả bản terminal lẫn desktop. Thiết kế hai agent (build và plan) cho bạn một cách an toàn để cho AI đọc dự án trước khi cho phép nó sửa. Dự án còn được cập nhật trong 3 tháng gần đây và có cộng đồng trên Discord.
Giới hạn. README rất ngắn: không nói rõ cách khởi động, cách kết nối mô hình AI, hay yêu cầu hệ thống. Bạn phải đọc thêm docs. Bản desktop còn BETA. Bản cài bằng npm trong README là gói @opencode/cli, còn thông tin gói npm của dự án ghi tên opencode, nên bạn nên kiểm tra kỹ tên gói trên docs trước khi cài để tránh nhầm. Ngoài ra, README chưa nói gì về chi phí hay chuyện dữ liệu của bạn đi đâu khi dùng mô hình AI, nên hãy tự đọc kỹ trước khi cho nó xem mã nguồn nhạy cảm.
Nên chọn khi bạn muốn một coding agent mở, tự kiểm soát được, thích làm việc trong terminal hoặc muốn thử bản desktop.
Nên cân nhắc cách khác khi bạn không muốn đọc tài liệu cấu hình, không quen với việc kiểm tra lại kết quả AI sửa, hoặc cần cam kết rõ ràng về dữ liệu và chi phí mà README chưa trả lời.
Câu hỏi thường gặp
OpenCode có miễn phí không?
Chính OpenCode là mã nguồn mở, giấy phép MIT, nên tải và cài không mất tiền. Tuy nhiên README chưa nói gì về chi phí khi kết nối tới mô hình AI, nên bạn cần xem docs ở opencode.ai/docs để biết cụ thể.
OpenCode chạy được trên Windows không?
README có file cài bản desktop cho Windows là opencode-desktop-win-x64.exe, và ghi mise dùng được trên mọi hệ điều hành. README không giải thích cách chạy script cài bằng bash trên Windows, nên bạn nên chọn bản desktop hoặc đọc docs.
Cần GPU hoặc máy mạnh không?
README chưa có thông tin về yêu cầu phần cứng. Bạn xem thêm ở trang docs của dự án.
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 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ì?
Đó là subagent dùng cho việc tìm kiếm phức tạp và công 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à mã nguồn của tôi có an toàn không?
README chưa có thông tin về việc dữ liệu được xử lý ra sao. Repo có file SECURITY.md, và bạn nên đọc docs cùng các điều khoản của nhà cung cấp mô hình AI mà bạn kết nối. Với mã nhạy cảm, hãy sao lưu và cân nhắc kỹ trước khi dùng.
Có bản giao diện đồ hoạ không?
Có. OpenCode có ứng dụng desktop (BETA) cho macOS, Windows và Linux, tải tại opencode.ai/download. Trên macOS còn cài được bằng lệnh brew install --cask opencode-desktop.


