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ở (MIT), viết bằng TypeScript, giúp bạn đọc, hiểu và sửa code bằng ngôn ngữ tự nhiên. Repo có hai agent dựng sẵn là build (toàn quyền) và plan (chỉ đọc). Cài đặt khá dễ: một dòng curl hoặc qua npm, Homebrew và vài trình quản lý gói khác, ngoài ra còn có bản ứng dụng desktop đang ở dạng 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 và giúp bạn phân tích hoặc chỉnh sửa. Tác giả giới thiệu ngắn gọn: "The open source coding agent". 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.
Bạn nên xem bài này nếu là lập trình viên mới, người làm văn phòng hay chủ shop có một ít code (website bán hàng, file xử lý dữ liệu, bot nhỏ) và muốn có một trợ lý ngồi cạnh để hỏi: "file này làm gì?", "sửa giúp mình chỗ này". Bạn không cần hiểu hết code, nhưng cần biết mở terminal và gõ lệnh.
Điều đáng giá nhất của opencode là cách chia quyền rõ ràng. Có sẵn một agent toàn quyền để làm việc, và một agent chỉ đọc để xem xét dự án mà không sợ nó lỡ tay sửa file. Với người mới, đây là lớp an toàn rất dễ hiểu.
anomalyco/opencode
opencode là agent lập trình AI mã nguồn mở, giấy phép MIT, có chế độ build để sửa code và chế độ plan chỉ đọc để phân tích dự án an toàn.
I.opencode làm được gì
README của repo khá ngắn, nên mình chỉ nói những gì nó ghi rõ.
A.Hai agent dựng sẵn, đổi qua lại bằng phím Tab
opencode có hai agent bạn đổi qua lại bằng phím Tab:
- buildagent mặc định, toàn quyền, dùng cho công việc phát triển thực sự như viết thêm tính năng hay sửa lỗi.
- 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ế: khi mới nhận một dự án lạ, bạn bật plan để nó giải thích cấu trúc, đề xuất hướng sửa. Khi đã ưng kế hoạch, bạn chuyển sang build để thực hiện.
B.Subagent general cho việc tìm kiếm phức tạp
Ngoài hai agent trên còn có general, một subagent dành cho tìm kiếm phức tạp và các việc nhiều bước. README cho biết nó chủ yếu được dùng nội bộ, và bạn có thể gọi trực tiếp bằng @general trong tin nhắn. Hữu ích khi bạn cần tìm một thứ nằm rải rác trong nhiều file.
C.Nhiều cách cài, nhiều nền tảng
Bạn có thể cài bằng script, npm (hoặc bun, pnpm, yarn), Homebrew, pacman và paru trên Arch Linux, mise hoặc Nix. Ngoài ra còn có ứng dụng desktop (BETA) cho macOS, Windows và Linux, dành cho ai không thích dùng terminal.
D.Mã nguồn mở, giấy phép MIT
Bạn xem được code, dùng và sửa theo giấy phép MIT. Tài liệu cấu hình chi tiết nằm trên trang riêng của dự án.
II.Cần chuẩn bị gì
Tư liệu README nói rất ít về yêu cầu hệ thống, nên mình chỉ ghi những gì có:
- Hệ điều hànhscript và các trình quản lý gói trong README hướng tới macOS và Linux (Homebrew, pacman, paru, Nix). Lệnh
mise use -g opencodeđược ghi là dùng cho mọi hệ điều hành. Bản desktop có file cài cho Windows (opencode-desktop-win-x64.exe). - Công cụ cài đặttuỳ cách bạn chọn, cần sẵn curl, npm (hoặc bun/pnpm/yarn), Homebrew, mise hoặc Nix.
- Gỡ bản cũREADME lưu ý nê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ứngREADME chưa nói gì về các mục này. Vì là agent AI, bạn nhiều khả năng phải cấu hình nguồn mô hình AI, nhưng cách làm cụ thể bạn hãy xem ở trang tài liệu https://opencode.ai/docs.
README không nói opencode có thu phí hay không, cũng không nói chi phí gọi mô hình AI. Nếu sau này bạn nhập API key của một dịch vụ AI, hãy đặt hạn mức chi tiêu trên trang của dịch vụ đó và đừng dán key vào file bạn định đưa lên GitHub.
III.Cài đặt từng bước
- Chọn cách càiScript một dòng, npm hoặc trình quản lý gói bạn quen
- 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ờ hoàn tất
- Mở lại terminalĐể máy nhận lệnh mới
- Xem tài liệuCấu hình thêm theo trang docs của dự án
A.Bước 1: Chọn cách cài phù hợp
README đưa ra nhiều cách. Người mới nên chọn đúng một cách, đừng chạy hết. Nếu dùng macOS hoặc Linux và đã có Homebrew thì chọn brew. Nếu đã quen Node thì dùng npm. Nếu muốn nhanh nhất thì dùng script.
B.Bước 2: Gỡ bản cũ (nếu có)
README ghi: 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.
C.Bước 3: Chạy lệnh cài
Mở terminal (trên macOS là Terminal, trên Linux là cửa sổ terminal, trên Windows là PowerShell hoặc Windows Terminal), rồi dán một trong các lệnh sau. Đây là nguyên văn từ README:
# 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 khỏi vấp:
- Dòng
curl ... | bashtải script cài về rồi chạy luôn. README tự gọi nó là kiểu "YOLO", nghĩa là nhanh nhưng bạn không xem trước script. Nếu cẩn thận, hãy chọn một cách cài qua trình quản lý gói. - Dòng
npm i -g @opencode/cli@latestcài toàn cục bằng npm. Chữ "or bun/pnpm/yarn" nghĩa là bạn thaynpm i -gbằng lệnh tương đương của bun, pnpm hoặc yarn. Lưu ý: tên gói trong lệnh này là@opencode/cli, trong khi tư liệu về repo ghi tên gói làopencode. Nếu lệnh npm báo không tìm thấy gói, bạn hãy đối chiếu lại với trang cài đặt trên https://opencode.ai. - Hai dòng
brew: dòng đầu (anomalyco/tap/opencode-v2) được README khuyên dùng vì luôn mới nhất. Dòng sau là bản chính thức của Homebrew nhưng cập nhật ít hơn. - Hai dòng Arch Linux:
pacmancho bản ổn định,parucho bản mới nhất từ AUR. - Dòng
misedùng được trên mọi hệ điều hành nếu bạn đã có mise. - Dòng
nix runchạy trực tiếp mà không cài cố định, dành cho người dùng Nix.
Khi dùng script cài, README cho biết opencode được cài vào thư mục $HOME/.opencode/bin.
D.Bước 4: Mở lại terminal
Sau khi cài xong, hãy đóng và mở lại cửa sổ terminal. README không viết bước này, nhưng đây là thói quen chung để máy nhận lệnh mới. Nếu cài bằng script, bạn có thể phải thêm thư mục $HOME/.opencode/bin vào PATH. README chưa nói script có tự làm việc này không, nên hãy xem hướng dẫn trên trang cài đặt của dự án.
E.Bước 5: Dùng bản desktop (tuỳ chọn)
Nếu ngại terminal, bạn tải bản desktop (BETA) tại opencode.ai/download. README liệt kê các file: opencode-desktop-mac-arm64.dmg cho Mac chip Apple, opencode-desktop-mac-x64.dmg cho Mac Intel, opencode-desktop-win-x64.exe cho Windows, và .deb, .rpm hoặc .AppImage cho Linux. Trên macOS bạn cũng có thể cài bằng Homebrew:
# macOS (Homebrew)
brew install --cask opencode-desktopVì đang là BETA, bạn có thể gặp lỗi lặt vặt hơn so với bản terminal.
IV.Kiểm tra đã chạy được chưa
README không ghi lệnh kiểm tra hay màn hình kết quả mong đợi. Vì vậy mình chỉ gợi ý cách kiểm tra chung, bạn nhớ đối chiếu với tài liệu chính thức:
- Mở terminal mới, vào một thư mục dự án thử nghiệm (không phải dự án quan trọng).
- Gõ tên lệnh
opencode, là tên gói trong tư liệu. Nếu máy không nhận ra lệnh, kiểm tra lại PATH như ở bước 4. - Nếu giao diện mở ra, thử nhấn
Tab. README nói phím này đổi giữa hai agent build và plan, nên bạn sẽ thấy tên agent đang dùng thay đổi.
Với bản desktop, bạn chỉ cần mở ứng dụng lên. Bạn mở được cửa sổ chính là cài thành công.
V.Dùng vào việc thật
Các tình huống dưới đây bám vào hai chế độ build, plan và subagent general mà README mô tả. Câu lệnh mẫu chỉ là lời nhắn bằng tiếng thường, không phải cú pháp riêng của công cụ.
A.Tình huống 1: Nhận một dự án lạ và cần hiểu nhanh
Bạn là lập trình viên mới, vừa được giao một thư mục code của người đi trước để lại. Mở terminal ở thư mục đó, chạy opencode, nhấn Tab để chuyển sang agent plan (chỉ đọc). Sau đó nhắn:
Hãy giải thích dự án này làm gì, các thư mục chính có vai trò gì, và file nào là điểm bắt đầu.Kết quả: bạn nhận được bản tóm tắt cấu trúc mà không lo nó sửa nhầm file nào. README nói rõ plan mặc định từ chối sửa file và hỏi trước khi chạy lệnh bash.
Muốn hiểu một dự án lạ, hãy để agent chỉ đọc đi trước, rồi mới cho agent toàn quyền vào làm.
Ông T
B.Tình huống 2: Lập kế hoạch trước khi sửa website bán hàng
Bạn là chủ shop có website nhỏ do thuê người làm, muốn thêm một nút hoặc đổi cách hiển thị giá. Ở chế độ plan, bạn nhắn:
Mình muốn đổi cách hiển thị giá sản phẩm. Hãy chỉ ra những file cần sửa và đề xuất các bước, chưa sửa gì cả.Kết quả: một danh sách file và bước làm. Bạn đọc, thấy hợp lý thì nhấn Tab sang build và nhắn "làm theo kế hoạch trên". Nếu không chắc, bạn có thể đưa kế hoạch cho người làm web của mình xem trước.
C.Tình huống 3: Tìm một đoạn code nằm rải rác
Nhân viên văn phòng có một bộ script xử lý báo cáo Excel, không nhớ chỗ nào đang tính tổng doanh thu. Bạn gọi subagent bằng cách nhắn:
@general tìm giúp mình tất cả chỗ trong dự án có tính tổng doanh thu và cho biết nằm ở file nào.README mô tả general dùng cho tìm kiếm phức tạp và việc nhiều bước. Kết quả mong đợi là danh sách vị trí tìm được để bạn đi thẳng tới đúng file.
D.Tình huống 4: Sửa một lỗi nhỏ ở chế độ build
Bạn có một script bị lỗi khi đọc file khách hàng. Ở chế độ build (mặc định, toàn quyền), bạn nhắn mô tả lỗi và dán thông báo lỗi vào. Agent đọc code, đề xuất và áp dụng chỉnh sửa. Hãy làm việc này trên bản sao hoặc trong thư mục đã có sao lưu, vì build có toàn quyền chỉnh sửa. Sau khi sửa, bạn tự chạy lại script để kiểm tra.
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 chuyện rất dễ xảy ra với loại công cụ này.
A.Gõ opencode báo không tìm thấy lệnh
Thường do terminal chưa nhận lệnh mới hoặc thư mục cài chưa nằm trong PATH. Hãy đóng và mở lại terminal. Nếu cài bằng script, thư mục cài là $HOME/.opencode/bin, bạn kiểm tra xem thư mục này đã được thêm vào PATH chưa.
B.Lệnh npm báo không tìm thấy gói
README ghi @opencode/cli@latest, còn tên gói trong tư liệu repo là opencode. Nếu có lệnh nào báo lỗi, hãy thử cách cài khác trong danh sách (brew hoặc script), hoặc xem lại trang cài đặt chính thức.
C.Cài chồng lên bản cũ gây lỗi lạ
README dặn gỡ các bản cũ hơn 0.1.x trước khi cài. Nếu opencode chạy không ổn sau khi cài, hãy gỡ bản cũ rồi cài lại bằng đúng một cách.
D.Agent sửa nhầm file
Đây là rủi ro của chế độ build, vì nó toàn quyền. Cách phòng: dùng plan để lên kế hoạch trước, làm việc trên dự án có sao lưu hoặc có Git, và đọc lại những gì nó đã thay đổi trước khi dùng thật.
E.Không biết nhập API key hay chọn mô hình AI ở đâu
README chưa hướng dẫn phần này. Hãy đọc trang tài liệu cấu hình tại https://opencode.ai/docs, hoặc hỏi ở cộng đồng Discord của dự án (liên kết có trong README).
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 nghìn sao) và repo còn được cập nhật trong 3 tháng gần đây.
- Hai chế độ build và plan giúp tách việc đọc, lập kế hoạch khỏi việc sửa. Rất hợp với người mới.
- Nhiều cách cài, có cả bản desktop và README có bản tiếng Việt.
Giới hạn:
- README chính rất ngắn. Phần cấu hình, kết nối mô hình AI và chi phí đều phải đọc thêm ở trang docs.
- Bản desktop đang ở BETA.
- Danh sách lệnh cài có vài chỗ cần đối chiếu (như tên gói npm), nên người mới cần cẩn thận.
- Vì là agent có quyền sửa file và chạy lệnh, bạn vẫn phải tự đọc lại kết quả. Đừng giao nguyên dự án quan trọng mà không sao lưu.
Khi nào nên chọn cách khác: nếu bạn chỉ cần hỏi đáp vài câu về lập trình, một khung chat AI thông thường đã đủ. Nếu bạn không muốn đụng vào terminal, hãy thử bản desktop trước, hoặc dùng công cụ có giao diện đồ hoạ quen thuộc hơn. Còn nếu bạn muốn một agent mã nguồn mở, tự kiểm soát được quyền truy cập ngay trên máy, opencode là lựa chọn đáng thử.
Lưu ý từ README: nếu bạn làm dự án có chữ "opencode" trong tên (ví dụ opencode-dashboard), hãy ghi rõ dự án đó không do đội ngũ opencode tạo ra và không liên kết với họ.
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 bạn xem và dùng code tự do. README không nói gì về chi phí gọi mô hình AI phía sau. Phần này chưa có thông tin trong tư liệu, bạn nên xem trang docs của dự án.
opencode chạy được trên Windows không?
Có bản ứng dụng desktop (BETA) cho Windows là file opencode-desktop-win-x64.exe. Với bản dòng lệnh, README ghi lệnh mise là dùng được trên mọi hệ điều hành, còn các cách khác chủ yếu nhắm macOS và Linux. Bạn nên xem trang cài đặt chính thức để biết cách cài trên Windows.
Cài opencode có khó không?
Không khó. Bạn chỉ cần dán một dòng lệnh vào terminal, ví dụ lệnh curl hoặc brew trong README. Nếu ngại terminal, bạn có thể tải bản desktop và cài như một ứng dụng thông thường.
Agent build và plan khác nhau thế nào?
Build là agent mặc định, toàn quyền, dùng để làm 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 giữa hai agent bằng phím Tab.
opencode có cần GPU hay máy cấu hình mạnh không?
README không nêu yêu cầu phần cứng nào. Vì vậy mình chưa có thông tin để khẳng định. Bạn nên xem trang tài liệu của dự án.
Dữ liệu và code của mình có an toàn không?
README không có mục nói về quyền riêng tư hay nơi dữ liệu được gửi đến. Điều có thể khẳng định là agent plan mặc định không sửa file và hỏi trước khi chạy bash. Repo có file SECURITY.md để bạn tham khảo chính sách bảo mật.
@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. README cho biết nó chủ yếu đượ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.


