OpenCode: agent viết code 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. Bạn giao việc bằng ngôn ngữ thường, nó đọc code, đề xuất và sửa giúp bạn. Cài khá dễ: có một dòng lệnh cài nhanh, nhiều trình quản lý gói, và cả bản ứng dụng 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 dự án, phân tích và (nếu bạn cho phép) sửa code giúp bạn. Tác giả giới thiệu ngắn gọn: "The open source coding agent".
Repo này hợp với lập trình viên mới muốn có một "người phụ" ngồi cạnh khi đọc code lạ, và với dev có kinh nghiệm muốn một công cụ AI không bị khoá vào một hãng. Người làm văn phòng, chủ shop có website nhỏ hay file tự động hoá cũng thử được, miễn là bạn chịu khó làm quen với terminal một chút.
Điểm đáng giá nhất: OpenCode có sẵn hai chế độ rõ ràng. Một chế độ được phép sửa file, một chế độ chỉ đọc và phân tích. Bạn đổi qua lại bằng phím Tab nên rất dễ giữ an toàn khi mới làm quen. Repo hiện có khoảng 226.506 sao và 30.658 fork, giấy phép MIT, và vẫn được cập nhật trong 3 tháng gần đây.
anomalyco/opencode
OpenCode là agent lập trình AI mã nguồn mở, có bản dòng lệnh lẫn bản desktop, với hai chế độ build (sửa code) và plan (chỉ đọc, phân tích).
I.OpenCode làm được gì
A.Hai agent có sẵn, đổi bằng phím Tab
OpenCode đi kèm hai agent dựng sẵn:
- buildagent mặc định, có đầy đủ quyền cho công việc phát triển. Dùng khi bạn muốn nó thực sự viết hoặc 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ế: khi mở một dự án lạ, bạn bật plan để nó giải thích và lên kế hoạch mà không đụng vào file nào. Khi đã ưng kế hoạch, bạn bấm Tab chuyển sang build để nó làm.
B.Subagent general cho việc tìm kiếm nhiều bước
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. Nó chủ yếu được dùng bên trong, nhưng bạn cũng gọi được trực tiếp bằng cách gõ @general trong tin nhắn. Hợp khi bạn cần tìm "chỗ nào trong dự án xử lý việc này" mà không biết bắt đầu từ file nào.
C.Có cả bản desktop (BETA)
Không thích terminal? OpenCode có ứng dụng desktop ở dạng BETA, cho macOS (Apple Silicon và Intel), Windows và Linux. Người mới sẽ thấy dễ chịu hơn vì chỉ cần tải về và cài như phần mềm thường.
D.Nhiều cách cài
README liệt kê nhiều đường cài: script một dòng, npm/bun/pnpm/yarn, Homebrew, pacman và paru (Arch Linux), mise, Nix. Bạn chọn cách quen tay nhất.
E.Tài liệu và cộng đồng
Phần cấu hình chi tiết nằm ở trang tài liệu của dự án (opencode.ai/docs). Dự án cũng có cộng đồng trên Discord và X.com để hỏi khi vướng.
II.Cần chuẩn bị gì
README chỉ nêu những điều sau, nên mình không thêm gì ngoài đó:
- Máy tính: macOS, Linux hoặc Windows. Bản desktop có file cài cho cả ba hệ. Với bản dòng lệnh, README liệt kê các cách cài cho macOS, Linux, Arch Linux, Nix và "mise: Any OS". README không nói riêng về cách cài dòng lệnh trên Windows, nên người dùng Windows nên ưu tiên bản desktop hoặc xem trang docs.
- Terminal: nếu cài bản dòng lệnh. Trên Windows là PowerShell, trên macOS/Linux là Terminal.
- Node/npm nếu bạn chọn cách cài bằng npm. README không nêu phiên bản tối thiểu.
- Homebrew nếu bạn chọn cách cài bằng brew.
- 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.
- Tài khoản, API key, phần cứng: README chưa ghi gì về các mục này. Cách kết nối với mô hình AI nằm trong tài liệu cấu hình ở opencode.ai/docs, bạn nên đọc ở đó trước khi bắt đầu.
III.Cài đặt từng bước
- Gỡ bản cũNếu từng cài OpenCode phiên bản cũ hơn 0.1.x thì gỡ đi trướ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
- Mở dự ánĐứng trong thư mục dự án rồi dùng OpenCode
- Đọc docs để cấu hìnhXem opencode.ai/docs cho phần thiết lập chi tiết
A.Bước 1: Gỡ bản cũ nếu có
README dặn: gỡ các phiên bản cũ hơn 0.1.x trước khi cài. Nếu đây là lần đầu bạn dùng OpenCode thì bỏ qua bước này.
B.Bước 2: Chọn một cách cài
Chọn đúng một dòng trong danh sách dưới đây, không cần chạy hết. Mở terminal ở bất kỳ thư mục nào cũng được vì đây là cài toàn cục.
# 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:
- Dòng
curl ... | bashlà cách nhanh nhất, tải script về và chạy luôn. Tác giả tự gắn nhãn "YOLO" vì bạn chạy script từ mạng mà không xem trước. Nếu bạn cẩn thận, hãy mở địa chỉ script ra đọc trước. Script sẽ cài OpenCode vào thư mục$HOME/.opencode/bin. - Dòng
npm i -g @opencode/cli@latesthợp với người đã có Node. README ghi chú bạ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à bản khuyến nghị và luôn mới nhất. Dòng thứ hai là formula chính thức của brew nhưng cập nhật chậm hơn. pacmanvàparudành cho Arch Linux.misedùng được trên mọi hệ điều hành.nix runcho người dùng Nix.
Chỗ người mới hay vấp: README liệt kê nhiều tên khác nhau (opencode, opencode-v2, @opencode/cli). Đây là các kênh phân phối khác nhau, đừng trộn lẫn. Chọn một kênh và dùng cho nhất quán.
Lệnh curl ... | bash chạy thẳng một script từ internet trên máy bạn. Chỉ dùng khi bạn tin nguồn, và tốt nhất là mở địa chỉ script ra đọc trước khi chạy.
C.Bước 3: Hoặc dùng bản desktop (BETA)
Nếu không muốn gõ lệnh, tải bản desktop tại opencode.ai/download. README ghi tên các file cài:
| Hệ điều hành | 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ì còn ở dạng BETA, bạn có thể gặp lỗi vặt. Nếu cần công việc ổn định, hãy theo dõi trang tải về và cộng đồng để biết bản mới.
D.Bước 4: Mở dự án của bạn
OpenCode làm việc trên code trong thư mục dự án. Nếu chưa có dự án, bạn có thể thử với một repo bất kỳ:
git clone https://github.com/anomalyco/opencode.git
cd opencodeLưu ý: lệnh clone ở trên chỉ để lấy mã nguồn về xem hoặc thử nghiệm. Bạn không cần clone repo này để dùng OpenCode. Dự án của chính bạn mới là thứ bạn nên mở.
README không ghi lệnh khởi động cụ thể và cách kết nối mô hình AI. Phần này bạn xem trong tài liệu chính thức tại opencode.ai/docs.
IV.Kiểm tra đã chạy được chưa
README không đưa ra lệnh kiểm tra riêng, nên mình chỉ nêu những dấu hiệu hợp lý dựa trên những gì nó ghi:
- Với bản dòng lệnhsau khi cài, terminal nhận ra lệnh và mở được giao diện của OpenCode. Cách khởi động cụ thể bạn xem ở opencode.ai/docs. Nếu dùng script cài, file nằm ở
$HOME/.opencode/bin; hãy kiểm tra thư mục này có file hay không. - Với bản desktopmở ứng dụng lên và thấy giao diện làm việc là đã cài được.
- Kiểm tra chế độbấm phím
Tab. Nếu chuyển được qua lại giữa build và plan thì bạn đang chạy đúng như README mô tả.
Nếu terminal báo không tìm thấy lệnh, hãy đóng terminal rồi mở lại. Nếu vẫn lỗi, xem mục lỗi hay gặp bên dưới.
V.Dùng vào việc thật
A.Lập trình viên mới đọc một dự án lạ
Bạn vừa vào công ty và được giao một repo hàng trăm file. Mở thư mục đó, bấm Tab để vào chế độ plan (chỉ đọc), rồi hỏi bằng tiếng thường:
Dự án này chạy từ đâu? Giải thích cấu trúc thư mục chính và luồng xử lý một yêu cầu đăng nhập.Vì plan từ chối sửa file mặc định và hỏi trước khi chạy lệnh bash, bạn có thể hỏi thoải mái mà không sợ làm hỏng gì. Kết quả: một bản giải thích để bạn đọc code nhanh hơn nhiều so với tự mò.
Hỏi ở chế độ plan trước, sửa ở chế độ build sau — đúng thứ tự đó thì AI khó làm hỏng việc của bạn.
Ông T
B.Chủ shop muốn sửa nhỏ trên website
Bạn có một website bán hàng nhỏ do người khác dựng và chỉ muốn đổi vài dòng chữ, hoặc thêm một dòng thông báo khuyến mãi. Mở thư mục website, để ở chế độ build và nhập:
Thêm dòng thông báo "Miễn phí giao hàng đơn từ 500k" ở đầu trang chủ. Cho mình xem thay đổi trước khi lưu.Kết quả: agent tìm đúng file, đề xuất và áp dụng chỉnh sửa. Trước khi làm, hãy sao lưu thư mục dự án, và nếu website do người khác quản lý thì nên báo họ biết.
C.Dev lên kế hoạch trước khi sửa lớn
Bạn cần đổi cách xử lý thanh toán nhưng chưa biết đụng vào những file nào. Dùng plan:
Mình muốn thêm một phương thức thanh toán mới. Liệt kê các file cần sửa và đề xuất các bước theo thứ tự.Sau khi đọc kế hoạch và thấy hợp lý, bấm Tab sang build và yêu cầu làm từng bước một. Cách này chậm hơn một chút nhưng bạn kiểm soát được từng thay đổi.
D.Tìm nhanh trong dự án lớn bằng @general
Bạn nhớ có đoạn code gửi email xác nhận đơn hàng nhưng không nhớ nằm ở đâu. Gọi subagent trực tiếp:
@general Tìm tất cả chỗ trong dự án có gửi email xác nhận đơn hàng và cho mình biết file nào làm việc đó.README mô tả general dùng cho tìm kiếm phức tạp và công việc nhiều bước, nên đây là đúng sở trường của nó. Kết quả là danh sách vị trí liên quan để bạn mở đọc.
VI.Lỗi hay gặp và cách xử lý
A.Gõ lệnh báo không tìm thấy (command not found)
Thường do terminal chưa nạp lại đường dẫn sau khi cài. Hãy đóng hẳn terminal rồi mở lại. Nếu bạn cài bằng script, file nằm ở $HOME/.opencode/bin, hãy kiểm tra thư mục này có tồn tại không. Nếu thiếu, thử cài lại bằng một cách khác trong danh sách.
B.Cài bằng npm bị từ chối quyền
Lệnh npm i -g cài toàn cục nên đôi khi cần quyền cao hơn. Cách an toàn là thử một kênh khác như brew hoặc mise thay vì ép chạy với quyền quản trị. Nếu vẫn muốn dùng npm, xem hướng dẫn của npm về cấu hình thư mục cài toàn cục.
C.Nhầm tên gói giữa các kênh
README có nhiều tên: opencode, opencode-v2, @opencode/cli. Nếu bạn cài hai kênh cùng lúc, có thể bị lẫn phiên bản. Hãy gỡ bản không dùng và giữ một kênh. Nhớ gỡ luôn các phiên bản cũ hơn 0.1.x như README dặn.
D.AI sửa file ngoài ý muốn
Ở chế độ build, agent có đầy đủ quyền làm việc. Nếu bạn chưa chắc yêu cầu của mình, hãy chuyển sang plan trước. Luôn để dự án trong Git hoặc sao lưu để quay lại được khi cần.
E.Chưa biết cấu hình mô hình AI
README chưa nói cách kết nối mô hình AI hay cần key nào. Đừng đoán: mở opencode.ai/docs, đọc phần cấu hình, hoặc hỏi ở Discord của dự án. Khi điền khoá bí mật, đừng dán vào chỗ công khai hay commit lên Git.
VII.Có nên dùng không
Điểm mạnh
- Mã nguồn mở, giấy phép MIT, dùng và xem code thoải mái.
- Hai chế độ build và plan giúp bạn kiểm soát mức quyền, rất tốt cho người mới.
- Có cả bản dòng lệnh lẫn bản desktop, nhiều cách cài.
- Cộng đồng lớn (hiện có khoảng 226.506 sao) và còn được cập nhật đều.
Giới hạn
- README ngắn, phần lớn hướng dẫn cấu hình nằm ở trang docs. Bạn phải đọc thêm mới dùng trọn vẹn.
- Bản desktop vẫn là BETA.
- README chưa nói về yêu cầu API key, chi phí dùng mô hình, hay cách chạy trên Windows với bản dòng lệnh. Những điểm này cần bạn tự kiểm tra trước khi triển khai nghiêm túc.
- Một agent AI vẫn có thể sai. Hãy đọc lại những gì nó sửa, nhất là với code liên quan tiền bạc hay dữ liệu khách hàng.
Khi nào chọn cách khác: nếu bạn chỉ cần hỏi đáp nhanh về lập trình, một khung chat thường là đủ. Nếu bạn không biết gì về terminal và không muốn học, hãy thử bản desktop trước, hoặc nhờ một dev trong nhóm cài giúp lần đầu. Còn nếu bạn muốn một agent mã nguồn mở, kiểm soát được quyền hạn và đổi qua lại giữa phân tích với chỉnh sửa, OpenCode là lựa chọn đáng 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 phần mềm không mất phí bản quyền. Tuy nhiên README không nói gì về chi phí khi kết nối với các mô hình AI, phần này chưa có thông tin, bạn nên xem opencode.ai/docs.
OpenCode chạy trên Windows được không?
Bản desktop (BETA) có file cài cho Windows là opencode-desktop-win-x64.exe. Với bản dòng lệnh, README không nói riêng về Windows, nhưng có liệt kê mise là cách cài cho mọi hệ điều hành. Bạn nên xem thêm trang tài liệu để biết chi tiết.
Có 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. Vì vậy chưa có thông tin chính thức về GPU hay cấu hình tối thiểu. Hãy xem trang docs của dự án.
Hai chế độ build và plan khác nhau thế nào?
Build là agent mặc định, có đầy đủ 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 bạn trước khi chạy lệnh bash. Bạn đổi qua lại bằng phím Tab.
Dữ liệu và code của mình có an toàn không?
README không mô tả chi tiết về việc xử lý dữ liệu. Repo có file SECURITY.md để bạn tham khảo chính sách bảo mật. Với code nhạy cảm, hãy kiểm tra kỹ cấu hình và nhà cung cấp mô hình bạn chọn trước khi dùng.
Cài OpenCode bằng cách nào là dễ nhất?
Nhanh nhất là dòng curl -fsSL https://opencode.ai/v2/install | bash, nhưng bạn nên cân nhắc vì nó chạy thẳng script từ mạng. Người dùng macOS có thể dùng Homebrew, người có Node có thể dùng npm. Nếu không thích gõ lệnh thì tải bản desktop.
Tìm hướng dẫn cấu hình chi tiết ở đâu?
README chỉ dẫn đến trang tài liệu chính thức tại opencode.ai/docs, trong đó có phần về agent. Dự án cũng có cộng đồng trên Discord và X.com để hỏi thêm.


