opencode: trợ lý lập trình AI mã nguồn mở — 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 dùng nó để đọc hiểu, phân tích và sửa code bằng ngôn ngữ tự nhiên. Cài khá dễ: chỉ 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 giao việc bằng câu chữ bình thường, nó đọc code, phân tích và (nếu bạn cho phép) sửa code giúp bạn. Repo do nhóm anomalyco phát triển, viết bằng TypeScript, giấy phép MIT, hiện có khoảng 226.506 sao và 30.658 fork.
Bạn nên đọc bài này nếu là lập trình viên mới, người làm văn phòng muốn tự động hoá việc nhỏ bằng code, hoặc chủ doanh nghiệp có một dự án phần mềm nhỏ mà chưa biết bắt đầu từ đâu. Điểm đáng giá nhất của opencode là hai chế độ làm việc rõ ràng. Chế độ build được phép sửa file. Chế độ plan chỉ đọc và phân tích, nên bạn có thể khám phá một dự án lạ mà không sợ nó lỡ tay thay đổi gì.
Bài này đi từ cài đặt đến vài tình huống dùng thực tế. Phần nào README của repo chưa ghi (ví dụ lệnh khởi chạy, cách nhập khoá của nhà cung cấp AI), mình sẽ nói thẳng và chỉ bạn chỗ xem tiếp, không đoán mò.
anomalyco/opencode
opencode là agent lập trình AI mã nguồn mở, có bản terminal và bản desktop (beta). Có hai chế độ: build để sửa code, plan chỉ đọc để phân tích.
I.opencode làm được gì
Theo README, opencode xoay quanh vài ý chính. Mình giải thích theo hướng bạn được lợi gì.
A.Hai agent có sẵn, đổi bằng phím Tab
- build là agent mặc định, có toàn quyền cho công việc phát triển. Bạn dùng nó khi muốn viết hoặc sửa code thật.
- plan là agent chỉ đọc. Mặc định nó từ chối sửa file và hỏi xin phép trước khi chạy lệnh bash. Chế độ này hợp để làm quen một dự án mới hoặc lên kế hoạch thay đổi trước khi bắt tay làm.
Bạn chuyển qua lại giữa hai agent bằng phím Tab. Thói quen tốt cho người mới là bắt đầu bằng plan để hiểu dự án, rồi mới sang build.
B.Subagent general cho việc 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 và công việc nhiều bước. README nói 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.
C.Có bản terminal và bản desktop
opencode cài được qua dòng lệnh và nhiều trình quản lý gói (npm, Homebrew, pacman, mise, Nix). Ngoài ra còn có ứng dụng desktop (đang ở dạng BETA) cho macOS, Windows và Linux. Người không quen terminal có thể thử bản desktop trước.
D.Mã nguồn mở, giấy phép MIT
Bạn đọc được code, tự kiểm tra nó làm gì. Giấy phép MIT cho phép dùng khá thoải mái. Repo cũng có tài liệu hướng dẫn cấu hình đầy đủ tại trang chủ dự án, và cộng đồng trên Discord và X.
II.Cần chuẩn bị gì
Tư liệu README chỉ nói những điều sau:
- Hệ điều hành: bản desktop có cho macOS (Apple Silicon và Intel), Windows và Linux. Các lệnh cài qua trình quản lý gói có ghi macOS, Linux, Arch Linux, Nix, và mise cho "mọi hệ điều hành".
- Công cụ cài đặt: tuỳ cách bạn chọn. Có thể là
curlvàbash, hoặc npm (bun, pnpm, yarn cũng được), hoặc Homebrew, pacman, mise, Nix. - Gỡ bản cũ: README khuyên gỡ các phiên bản cũ hơn 0.1.x trước khi cài.
Về tài khoản, API key hay phần cứng (GPU, RAM), README chưa nói gì. Chưa có thông tin về việc bạn cần nhà cung cấp mô hình AI nào hay cấu hình máy ra sao. Phần này bạn xem trong tài liệu chính thức ở trang chủ dự án (opencode.ai/docs).
Một agent lập trình có thể đọc file và chạy lệnh trên máy bạn. Trước khi giao việc, hãy chọn một thư mục dự án có sao lưu (hoặc dùng git). Nếu có điền khoá API của dịch vụ AI nào đó, đừng dán khoá vào code hay gửi cho người khác. Chi phí gọi mô hình AI (nếu có) phụ thuộc nhà cung cấp bạn chọn; README chưa nói về chuyện này.
III.Cài đặt từng bước
- Chọn cách càiBản desktop hay dòng lệnh, tuỳ bạn quen cái nào
- Gỡ bản cũNếu đã có opencode cũ hơn 0.1.x thì gỡ trước
- Chạy lệnh càiMột dòng curl, hoặc npm/Homebrew/trình quản lý gói bạn dùng
- Kiểm tra vị trí càiScript cài vào thư mục .opencode/bin trong thư mục home
- Xem docs để cấu hìnhNối với dịch vụ AI theo hướng dẫn chính thức
A.Chọn cách cài phù hợp
Nếu bạn chưa quen terminal, hãy dùng bản desktop (beta) tải từ trang opencode.ai/download. README liệt kê các file: opencode-desktop-mac-arm64.dmg (Mac chip Apple), opencode-desktop-mac-x64.dmg (Mac Intel), opencode-desktop-win-x64.exe (Windows), và .deb, .rpm hoặc .AppImage cho Linux. Người dùng Mac có Homebrew cũng cài được bản desktop bằng lệnh:
brew install --cask opencode-desktopNếu quen dòng lệnh, đi tiếp các bước dưới.
B.Gỡ phiên bản cũ (nếu có)
README ghi rõ: hãy gỡ các phiên bản cũ hơn 0.1.x trước khi cài. README không nói cách gỡ, nên nếu bạn từng cài theo kiểu nào (npm, brew…), hãy gỡ bằng đúng công cụ đó.
C.Chạy lệnh cài
Đây là danh sách lệnh đúng nguyên văn trong README. Bạn chỉ cần chọn MỘT dòng phù hợp với máy mình, đừ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 # NixMột vài lưu ý cho người mới:
- Dòng
curl ... | bash(README gọi vui là "YOLO") tải script về và chạy ngay. Nó tiện, nhưng bạn nên hiểu là mình đang chạy một script từ internet. Nếu muốn cẩn thận, hãy chọn trình quản lý gói. - Dòng
npm i -gcần bạn đã có Node.js và npm trên máy. README chưa nói yêu cầu phiên bản Node cụ thể. - Hai dòng
brewkhác nhau: dòng đầu (khoanomalyco/tap) được README khuyên dùng vì luôn mới; dòng thứ hai là công thức chính thức nhưng cập nhật chậm hơn. - Phần sau dấu
#chỉ là ghi chú, bạn không cần gõ. - Trên Windows, README không có lệnh cài riêng. Bạn có thể dùng bản desktop
.exe, hoặc lệnhnpm i -g/mise use -gnếu đã có sẵn công cụ đó. - Về tên gói npm, README ghi
@opencode/cli@latest, trong khi thông tin repo ghi tên gói làopencode. Hai tên này lệch nhau, nên nếu lệnh npm báo lỗi, bạn hãy đối chiếu lại với trang cài đặt chính thức.
D.Biết nó được cài ở đâu
README cho biết 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 kiểm tra thư mục này có nằm trong PATH của bạn không. README chưa hướng dẫn thêm vào PATH, nên bạn xem thêm ở tài liệu chính thức.
E.Cấu hình và khởi chạy
README chỉ nói: muốn biết cách cấu hình opencode, hãy xem tài liệu tại trang chủ (opencode.ai/docs). README chưa ghi lệnh khởi chạy cụ thể, cũng chưa ghi cách nhập khoá của nhà cung cấp AI. Vì vậy mình không viết lệnh đoán ở đây; bạn làm theo trang docs ở phần bắt đầu, nơi tác giả giữ hướng dẫn mới nhất.
IV.Kiểm tra đã chạy được chưa
Vì README không có lệnh kiểm tra riêng, bạn có thể dùng các dấu hiệu sau, tất cả đều bám theo tư liệu:
- Với script cài: thư mục
$HOME/.opencode/binđã tồn tại và có file chương trình bên trong. - Với bản desktop: mở ứng dụng lên và thấy giao diện hiện ra bình thường.
- Với agent: sau khi khởi chạy theo trang docs, bạn bấm
Tabthì thấy đổi giữa hai chế độbuildvàplan. Đó là dấu hiệu rõ nhất rằng opencode đã chạy.
Nếu bước nào không ra như vậy, xem 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 khả năng README có nêu: hai agent build/plan, subagent general. Câu lệnh mẫu là cách nói tự nhiên với agent, không phải lệnh cố định của repo.
A.Lập trình viên mới đọc hiểu dự án của công ty
Bạn vừa vào làm, được giao một dự án mấy chục thư mục mà không ai có thời gian giải thích. Bạn mở opencode ở thư mục dự án, bấm Tab để chuyển sang agent plan (chỉ đọc, mặc định từ chối sửa file) rồi hỏi:
Hãy giải thích cấu trúc thư mục dự án này. Phần nào xử lý đăng nhập? Nếu muốn thêm một trang báo cáo mới thì nên đụng vào những file nào?Kết quả bạn nhận được là một bản giải thích bằng tiếng Việt, kèm danh sách file liên quan, mà dự án không bị thay đổi gì. Đây đúng là việc README gọi là "explore unfamiliar codebases".
Cứ hỏi ở chế độ chỉ đọc trước, hiểu rồi mới cho nó sửa.
Ông T
B.Chủ shop muốn chỉnh một trang web nhỏ
Bạn có một website bán hàng đơn giản do bạn cũ lập trình, giờ muốn đổi dòng thông báo khuyến mãi và số hotline. Bạn mở opencode ở thư mục website, ở agent plan nhờ nó chỉ ra file chứa các dòng đó. Khi đã biết chắc, bạn bấm Tab sang build và ra lệnh:
Đổi dòng thông báo ở đầu trang thành "Giảm 10% đơn đầu tiên" và cập nhật số hotline mới. Chỉ sửa những chỗ đó, đừng đổi gì khác.Kết quả là code được sửa đúng chỗ. Bạn nên xem lại những gì nó thay đổi (nếu dùng git thì xem phần khác biệt) trước khi đưa lên mạng.
C.Nhân viên văn phòng cần lên kế hoạch trước khi sửa
Bạn có một công cụ nội bộ nhỏ, ví dụ script xử lý bảng tính, muốn thêm một tính năng nhưng sợ làm hỏng. Ở agent plan, bạn hỏi:
Tôi muốn thêm cột "tổng doanh thu theo tháng" vào kết quả. Hãy đề xuất các bước thực hiện, nêu file cần sửa và rủi ro. Chưa sửa gì cả.Bạn nhận được một kế hoạch từng bước. Khi plan cần chạy lệnh bash, README nói agent sẽ hỏi xin phép bạn trước, nên bạn nắm quyền quyết định. Nếu thấy hợp lý, chuyển sang build để thực hiện.
D.Dev cần tìm nhanh trong dự án lớn
Trong một dự án lớn, bạn cần biết hàm tính phí vận chuyển được gọi ở những đâu. Bạn có thể nhắc đến subagent general ngay trong tin nhắn:
@general tìm tất cả nơi gọi hàm tính phí vận chuyển và tóm tắt mỗi nơi dùng nó để làm gì.README mô tả general dành cho tìm kiếm phức tạp và việc nhiều bước. Kết quả mong đợi là một bản tổng hợp gọn, đỡ cho bạn việc tự tìm từng file.
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 nói rõ để bạn biết đây là gợi ý chung, không phải thông báo lỗi chính thức của repo.
A.Gõ lệnh mà terminal báo không tìm thấy
Thường là do thư mục chứa chương trình chưa nằm trong PATH, hoặc bạn chưa mở lại terminal sau khi cài. Hãy đóng terminal, mở cửa sổ mới rồi thử lại. Script cài đặt đưa chương trình vào $HOME/.opencode/bin, nên hãy kiểm tra thư mục này có nằm trong PATH không.
B.Lệnh npm báo lỗi gói
Tên gói trong README (@opencode/cli) lệch với tên gói ghi trong thông tin repo (opencode). Hãy thử một cách cài khác trong danh sách (ví dụ Homebrew hoặc mise), hoặc mở trang cài đặt chính thức để xem tên gói mới nhất. Đừng thử các tên gói lạ mà bạn không chắc nguồn.
C.Xung đột 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ạ hoặc báo lỗi kỳ cục, hãy gỡ bản cũ bằng đúng công cụ đã dùng để cài nó rồi cài lại từ đầu.
D.Lỡ để agent sửa nhiều hơn ý muốn
Agent build có toàn quyền trong dự án. Cách phòng là dùng plan để lên kế hoạch trước, yêu cầu rõ "chỉ sửa những chỗ này", và luôn có bản sao lưu hoặc git. Nếu thấy thay đổi không ổn, hãy khôi phục từ bản sao lưu thay vì nhờ agent sửa chồng lên.
E.Không biết điền khoá hay đăng nhập dịch vụ AI ở đâu
README chưa có thông tin này. Bạn xem mục cấu hình trong tài liệu chính thức tại opencode.ai/docs, hoặc hỏi ở Discord của dự án. Đừng dán khoá API vào các nơi công khai khi nhờ người khác giúp.
VII.Có nên dùng không
Điểm mạnh. Đây là dự án mã nguồn mở, giấy phép MIT, được cập nhật trong 3 tháng gần đây, cộng đồng lớn (khoảng 226 nghìn sao). Có nhiều cách cài, cả terminal lẫn bản desktop cho Windows, macOS, Linux. Cặp agent build và plan giúp người mới làm việc an toàn hơn: đọc trước, sửa sau.
Giới hạn. README rất ngắn: chưa ghi lệnh khởi chạy, yêu cầu về phiên bản Node, cách kết nối dịch vụ AI hay chi phí. Bạn phải đọc thêm tài liệu chính thức. Bản desktop vẫn là beta. Tên gói npm giữa README và thông tin repo chưa khớp, nên người mới có thể vấp ở bước này. Ngoài ra, giống mọi agent lập trình, nó chạy trên máy bạn và có thể sửa file, nên cần thói quen sao lưu.
Khi nào chọn cách khác. Nếu bạn chỉ cần hỏi đáp đơn giản về code, một khung chat thông thường có thể đủ. Nếu bạn hoàn toàn không đụng code và không muốn tự cài đặt, opencode chưa phải thứ "mở ra là dùng" ngay. Ngược lại, nếu bạn muốn một trợ lý lập trình mã nguồn mở, kiểm soát được và có chế độ chỉ đọc để làm quen dự án, opencode đá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. Tuy nhiên README chưa nói gì về chi phí dùng mô hình AI hay dịch vụ đi kèm. Bạn nên xem tài liệu chính thức trước khi dùng nhiều.
opencode chạy được trên Windows không?
Có bản desktop (beta) cho Windows, tên file là `opencode-desktop-win-x64.exe`. Với dòng lệnh, README liệt kê `npm i -g` và `mise use -g` (ghi là dùng được trên mọi hệ điều hành), còn lệnh curl cần môi trường bash. README chưa có hướng dẫn riêng cho Windows ngoài các lựa chọn này.
Chế độ 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` chỉ đọc: mặc định từ chối sửa file và hỏi xin phép trước khi chạy lệnh bash. Bạn đổi giữa hai chế độ bằng phím `Tab`.
Tôi có cần GPU hay máy cấu hình mạnh không?
README chưa có thông tin về yêu cầu phần cứng. Bạn nên xem tài liệu chính thức của dự án để biết rõ.
Dữ liệu và code của tôi có an toàn không?
README không nói về cách xử lý dữ liệu, nên mình không có thông tin để khẳng định. Vì agent có thể đọc file và chạy lệnh trên máy bạn, hãy thử trên dự án có sao lưu, dùng chế độ `plan` trước, và đừng để lộ khoá API. Repo có file SECURITY.md để bạn tham khảo chính sách bảo mật.
Cài opencode bằng cách nào là dễ nhất?
Với người ngại terminal, tải bản desktop (beta) từ trang opencode.ai/download là dễ nhất. Với người quen dòng lệnh, có thể dùng một dòng curl, npm, Homebrew hoặc mise như README liệt kê. Trên Mac, Homebrew với kho `anomalyco/tap` được README khuyên dùng vì luôn mới.
Tôi nên xem hướng dẫn cấu hình ở đâu?
README chỉ dẫn đến tài liệu chính thức tại opencode.ai/docs, trong đó có mục về agents. Dự án cũng có cộng đồng trên Discord và X.com để hỏi thêm.


