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 coding agent (trợ lý lập trình AI) mã nguồn mở, giấy phép MIT, viết bằng TypeScript. Bạn mô tả việc cần làm, agent sẽ đọc code, đề xuất kế hoạch hoặc sửa file giúp bạn. Cài đặt chỉ cần một dòng lệnh hoặc tải bản desktop, nên khá dễ với người mới.
opencode là một coding agent mã nguồn mở: một trợ lý AI đọc được thư mục code của bạn, hiểu nó, rồi giúp bạn phân tích, lên kế hoạch và sửa code bằng ngôn ngữ thường. Repo do nhóm anomalyco phát triển, viết chủ yếu bằng TypeScript, dùng giấy phép MIT. Hiện repo có khoảng 226.506 sao và 30.658 fork, và vẫn được cập nhật trong vài tháng gần đây.
Nếu bạn là lập trình viên mới, bạn có thể dùng nó như một người hướng dẫn ngồi cạnh: hỏi «file này làm gì», «luồng đăng nhập chạy thế nào». Nếu bạn làm kinh doanh hoặc văn phòng và có một dự án nhỏ (website bán hàng, file script xử lý dữ liệu), bạn có thể nhờ nó đọc và giải thích trước khi động vào bất cứ thứ gì.
Điểm đáng giá nhất là nó có hai chế độ rõ ràng. Chế độ plan chỉ đọc, không sửa file, rất an toàn để làm quen. Chế độ build mới có toàn quyền sửa code. Bạn đổi qua lại bằng phím Tab. Ngoài ra nó có bản terminal lẫn bản desktop (đang beta), nên người ngại dòng lệnh vẫn có lựa chọn.
anomalyco/opencode
opencode là agent lập trình AI mã nguồn mở, giúp bạn đọc hiểu, lên kế hoạch và sửa code bằng ngôn ngữ thường; có bản terminal và bản desktop (beta).
I.opencode làm được gì
Dưới đây là các khả năng chính mà README nêu, kèm ý nghĩa thực tế cho bạn.
A.Hai agent có sẵn: build và plan
opencode có sẵn hai agent, đổi qua lại bằng phím Tab.
- build là agent mặc định, có đầy đủ quyền cho công việc phát triển. Bạn dùng nó khi đã biết mình muốn gì và để nó bắt tay vào làm.
- 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: bạn không phải lo AI tự ý sửa lung tung khi mới mở một dự án lạ. Cứ bật plan để hỏi và xem, rồi mới chuyển sang build.
B.Subagent general cho việc tìm kiếm 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 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 cách gõ @general trong tin nhắn. Khi câu hỏi kiểu «tìm giúp mình mọi chỗ đang xử lý thanh toán», đây là công cụ phù hợp.
C.Chạy trong terminal hoặc bằng ứng dụng desktop
Bản desktop (BETA) có sẵn cho macOS (chip Apple Silicon và Intel), Windows và Linux. Nhờ vậy bạn chọn giao diện hợp với mình: terminal nếu quen dòng lệnh, ứng dụng cửa sổ nếu muốn thân thiện hơn.
D.Mã nguồn mở, có tài liệu và cộng đồng
Mã nguồn công khai theo giấy phép MIT, nên bạn đọc, dùng và kiểm tra thoải mái. Cách cấu hình chi tiết nằm ở tài liệu chính thức tại opencode.ai/docs. Dự án cũng có cộng đồng trên Discord và X.
II.Cần chuẩn bị gì
README ghi khá ít yêu cầu, nên mình chỉ nêu những gì có trong đó:
- Hệ điều hành: bản terminal có hướng dẫn cho macOS, Linux (Arch Linux có gói riêng) và cách dùng được trên mọi hệ điều hành qua mise. Bản desktop có file cài cho Windows (
opencode-desktop-win-x64.exe), macOS và Linux. - 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.
- Công cụ cài: tùy cách bạn chọn, cần sẵn npm (hoặc bun/pnpm/yarn), Homebrew, pacman, paru, mise hoặc Nix. Cách
curlthì chỉ cần terminal có sẵn lệnh đó. - Tài khoản, API key, phần cứng: README chưa nói gì về các mục này. Chưa có thông tin về việc cần key của nhà cung cấp AI nào hay có cần GPU không. Bạn xem phần cấu hình trong tài liệu tại https://opencode.ai/docs trước khi bắt đầu.
Khi cho AI quyền sửa file và chạy lệnh, hãy dùng thử trên một thư mục dự án có bản sao lưu hoặc đã commit git. Và nếu sau này bạn điền API key của dịch vụ AI nào đó, đừng dán key vào nơi công khai hay gửi cho người khác.
III.Cài đặt từng bước
- Gỡ bản cũXoá các phiên bản opencode cũ hơn 0.1.x nếu có
- Chọn cách càiChọn một lệnh trong danh sách phù hợp hệ điều hành của bạn
- Chạy lệnh càiMở terminal và dán đúng lệnh đã chọn
- Hoặc tải bản desktopTải file cài từ opencode.ai/download nếu không thích terminal
- Xem tài liệu cấu hìnhĐọc docs để thiết lập trước khi dùng
A.Gỡ bản cũ nếu có
README có một 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 ghi lệnh gỡ cụ thể, nên bạn gỡ bằng đúng công cụ đã dùng để cài trước đó (ví dụ npm hay Homebrew).
B.Chọn một cách cài bằng dòng lệnh
Mở terminal (macOS/Linux: ứng dụng Terminal; Windows: PowerShell hoặc terminal bạn quen dùng). Rồi chọn một dòng phù hợp trong danh sách dưới đây. Đừng chạy hết cả danh sách, vì mỗi dòng là một cách cài khác nhau.
# 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 ngắn để bạn chọn:
- curl: tải và chạy script cài một lần. README tự gọi đây là cách «YOLO», tức là nhanh nhưng bạn chạy script mà chưa đọc nó. Nếu muốn cẩn thận, hãy mở địa chỉ script trong trình duyệt xem trước.
- npm/bun/pnpm/yarn: hợp với người đã có Node hoặc bun. Dòng
npm i -gcài toàn cục để dùng ở mọi thư mục. - brew: hợp với macOS và Linux. README ghi dòng
anomalyco/tap/opencode-v2là khuyến nghị và luôn mới nhất, còn dòngbrew install opencodelà công thức chính thức của Homebrew nhưng cập nhật chậm hơn. - pacman/paru: dành cho Arch Linux (bản ổn định và bản mới nhất từ AUR).
- mise: dùng được trên mọi hệ điều hành.
- nix: dành cho người dùng Nix.
Chỗ người mới hay vấp: phần sau dấu # chỉ là ghi chú, bạn không cần gõ. Ngoài ra lệnh có sudo sẽ hỏi mật khẩu máy.
Lưu ý thêm: README liệt kê tên gói là @opencode/cli ở dòng npm, trong khi tên gói npm của repo ghi là opencode. Nếu lệnh npm báo lỗi, hãy thử cách cài khác hoặc đối chiếu trang docs.
C.Hoặc tải bản desktop
Bản desktop (BETA) tải tại opencode.ai/download. Các file theo README:
| 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 |
Người dùng macOS cũng có thể cài bản desktop bằng Homebrew:
# macOS (Homebrew)
brew install --cask opencode-desktopVới người không quen dòng lệnh, đây là đường ngắn nhất: tải file, bấm đúp, cài như phần mềm bình thường.
D.Biết script cài đặt để file ở đâu
Nếu bạn dùng script curl, README cho biết nó cài 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ó tồn tại không. README không nói gì thêm về việc tự thêm vào PATH.
E.Đọc tài liệu cấu hình
README chỉ hướng về tài liệu chính thức để cấu hình: https://opencode.ai/docs. README chưa ghi cụ thể cách kết nối với dịch vụ AI hay nhập key, nên hãy mở trang docs và làm theo ở đó trước khi bắt đầu hỏi agent.
IV.Kiểm tra đã chạy được chưa
README không đưa ra lệnh kiểm tra riêng hay màn hình kết quả mẫu. Vì vậy mình chỉ gợi ý cách tự kiểm tra hợp lý, chưa phải điều README khẳng định:
- Với bản desktop: mở ứng dụng lên. Nếu cửa sổ hiện ra và bạn mở được một thư mục dự án, nghĩa là cài thành công.
- Với bản terminal: mở một cửa sổ terminal mới (để máy nạp lại đường dẫn lệnh) và thử gọi chương trình. README không ghi tên lệnh khởi chạy, nhưng tên gói là
opencodenên nhiều khả năng bạn gõopencode. Nếu không chắc, hãy đối chiếu trong docs. - Khi giao diện mở ra, thử bấm
Tab. Theo README, bạn sẽ chuyển giữa hai agent build và plan. Thấy đổi được là agent đã hoạt động đúng.
Nếu terminal báo «không tìm thấy lệnh», xem lại phần lỗi thường gặp bên dưới.
V.Dùng vào việc thật
Dưới đây là vài tình huống bám đúng những gì README mô tả: hai agent, subagent general và việc đọc, sửa code. Các câu lệnh mẫu là ví dụ bạn gõ vào khung chat của agent.
A.Nhân viên văn phòng mới được giao một dự án code có sẵn
Bạn vừa nhận một thư mục code từ đồng nghiệp đã nghỉ việc và chưa biết bắt đầu từ đâu. Hãy mở dự án, bấm Tab để chọn agent plan, rồi hỏi:
Hãy giải thích cấu trúc thư mục này. File nào là điểm bắt đầu của chương trình?Vì plan mặc định từ chối sửa file và hỏi bạn trước khi chạy lệnh bash, bạn yên tâm đọc và hỏi. Kết quả là một bản tóm tắt để bạn nắm tổng quan trước khi làm gì tiếp. Đây đúng là việc README nói plan phù hợp: khám phá một codebase lạ.
Cứ để agent plan đọc và giải thích trước, chỉ chuyển sang build khi bạn đã hiểu mình muốn sửa gì.
Ông T
B.Chủ shop muốn chỉnh một file trên website nhỏ
Bạn có một website bán hàng nhỏ và muốn đổi nội dung một trang. Làm theo hai nhịp: ở chế độ plan, hỏi «muốn đổi dòng giới thiệu ở trang chủ thì sửa file nào?». Khi đã biết file, bấm Tab sang build rồi nhập yêu cầu cụ thể, ví dụ:
Đổi dòng giới thiệu ở trang chủ thành: Giao hàng nhanh trong ngày.Kết quả: agent build tự sửa file giúp bạn. Hãy mở file ra xem lại thay đổi trước khi đưa lên website thật, và nên lưu bản sao trước khi để build làm việc.
C.Lập trình viên mới tìm mọi chỗ dùng một chức năng
Bạn cần biết chức năng thanh toán xuất hiện ở những file nào trong dự án lớn. Dùng subagent general bằng cách gõ @general trong tin nhắn:
@general tìm giúp mình tất cả nơi gọi hàm xử lý thanh toán và liệt kê theo file.README mô tả general dành cho tìm kiếm phức tạp và công việc nhiều bước, nên đây là loại câu hỏi hợp với nó. Kết quả là một danh sách để bạn lần theo.
D.Dev lên kế hoạch trước khi thay đổi lớn
Trước khi đổi cách lưu dữ liệu, bạn muốn có kế hoạch từng bước. Ở agent plan, nhập:
Mình muốn đổi cách lưu dữ liệu người dùng. Hãy phân tích code hiện tại và đề xuất các bước, chưa sửa gì cả.Kết quả là một bản kế hoạch dựa trên code thật của bạn. Sau khi xem và đồng ý, bạn chuyển sang build để thực hiện dần từng bước nhỏ. README nói rõ plan phù hợp cho việc «lên kế hoạch thay đổi».
VI.Lỗi hay gặp và cách xử lý
README không có mục xử lý sự cố. Các lỗi dưới đây là những tình huống dễ gặp với loại công cụ này, kèm cách xử lý an toàn.
A.Terminal báo không tìm thấy lệnh sau khi cài
Thường do terminal cũ chưa nạp lại đường dẫn. Hãy đóng và mở terminal mới. Nếu bạn cài bằng script curl, kiểm tra xem $HOME/.opencode/bin có tồn tại không, vì README cho biết script cài vào đó. Nếu vẫn không được, thử một cách cài khác trong danh sách.
B.Lệnh npm báo lỗi không tìm thấy gói
README ghi tên gói trong lệnh npm khác với tên gói npm của repo (opencode). Đừng tự đoán tên gói. Hãy thử Homebrew, script cài, hoặc đọc trang docs để lấy lệnh cài đúng và mới nhất.
C.Cài chồng lên bản cũ gây xung đột
README khuyên gỡ bản cũ hơn 0.1.x trước khi cài. Nếu bạn từng cài bằng cách khác, hãy gỡ bằng đúng công cụ đó rồi cài lại một cách duy nhất.
D.Agent sửa sai hoặc sửa quá tay
Đây là rủi ro chung của mọi coding agent. Hãy để dự án trong git hoặc sao lưu trước, dùng plan để xem trước, và chỉ bật build với yêu cầu nhỏ, rõ ràng. Luôn đọc lại thay đổi trước khi dùng thật.
E.Chưa kết nối được với dịch vụ AI
README không nói rõ bước này. Nếu agent không trả lời, hãy mở https://opencode.ai/docs và làm theo phần cấu hình. Không dán key vào file nào bạn định chia sẻ công khai.
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.506 sao) và vẫn được cập nhật.
- Hai chế độ build và plan giúp bạn kiểm soát mức quyền: đọc trước, sửa sau.
- Nhiều cách cài, có cả bản desktop cho Windows, macOS và Linux.
- Có subagent general cho các tìm kiếm nhiều bước.
Giới hạn:
- Bản desktop vẫn ghi là BETA, nên có thể chưa ổn định bằng bản terminal.
- README khá ngắn: chưa nói cách khởi chạy, cách nhập key, hay yêu cầu phần cứng. Bạn phải đọc thêm tài liệu chính thức.
- Có sự không khớp giữa tên gói trong README và tên gói npm, nên cần cẩn thận khi cài bằng npm.
- Giống mọi AI lập trình, kết quả phải được bạn đọc lại và kiểm tra.
Khi nào chọn cách khác: nếu bạn chỉ cần sửa một lỗi nhỏ một lần và không muốn cài gì, một khung chat AI thông thường có thể đủ. Còn nếu bạn thường xuyên làm việc trong một thư mục code và muốn AI đọc trực tiếp, opencode đáng để thử, nhất là với chế độ plan an toàn để làm quen.
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 dùng và xem mã tự do. README không nói về chi phí của dịch vụ AI chạy phía sau. Chưa có thông tin về việc cần trả phí cho nhà cung cấp mô hình nào, bạn xem tại opencode.ai/docs.
opencode có chạy được trên Windows không?
Có bản desktop cho Windows, file là opencode-desktop-win-x64.exe, tải tại opencode.ai/download. Bản desktop hiện ghi là BETA. README cũng liệt kê cách cài mise dùng được trên mọi hệ điều hành.
Cần GPU hay cấu hình máy mạnh không?
README không nêu yêu cầu phần cứng nào, kể cả GPU. Chưa có thông tin chính thức về chuyện này trong tư liệu, bạn xem thêm trong tài liệu tại opencode.ai/docs.
Hai 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 quyền 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.
@general dùng để làm gì?
General là một subagent 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 cách gõ @general trong tin nhắn.
Cài opencode vào đâu và có cần gỡ bản cũ không?
Script cài đặt đưa opencode vào thư mục $HOME/.opencode/bin. README khuyên gỡ các phiên bản cũ hơn 0.1.x trước khi cài để tránh xung đột.
Dữ liệu và code của tôi có an toàn không?
README không có phần nào nói về cách xử lý dữ liệu hay quyền riêng tư. Chưa có thông tin cụ thể, bạn nên xem SECURITY.md trong repo và tài liệu chính thức. Về phía bạn, hãy dùng chế độ plan để làm quen và sao lưu dự án trước khi cho phép sửa file.


