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 (anomalyco/opencode) là một coding agent mã nguồn mở, giấy phép MIT, viết bằng TypeScript. Nó giúp bạn khám phá, sửa và lên kế hoạch cho code bằng AI. Cài khá dễ: một dòng curl, một lệnh package manager, hoặc tải bản desktop (BETA).
OpenCode là một coding agent (trợ lý AI chuyên viết và sửa code) mã nguồn mở, giấy phép MIT, viết bằng TypeScript. Tác giả mô tả ngắn gọn: "The open source coding agent". Hiện repo có khoảng 226.506 sao và 30.658 fork trên GitHub, và vẫn được cập nhật trong 3 tháng gần đây.
Bạn nên xem qua nếu là lập trình viên mới, người làm kỹ thuật trong doanh nghiệp, hoặc người làm văn phòng muốn có một "người phụ" đọc hiểu một dự án code, giải thích nó và đề xuất thay đổi. Bạn không cần là chuyên gia mới thử được.
Điểm đáng giá nhất là hai chế độ làm việc tách bạch. build có toàn quyền để làm việc. plan chỉ đọc và phân tích, mặc định từ chối sửa file. Nhờ vậy bạn có thể cho AI đi xem một dự án lạ mà không lo nó tự ý đổi code. Ngoài ra, OpenCode có cả bản dòng lệnh lẫn bản desktop (BETA), nên người ngại terminal vẫn có đường vào.
anomalyco/opencode
OpenCode là agent lập trình AI mã nguồn mở, có hai chế độ build và plan, cài bằng một dòng lệnh hoặc dùng bản desktop.
I.OpenCode làm được gì
README của repo khá ngắn, trọng tâm là cách cài và các agent. Dưới đây là những gì tư liệu nói rõ.
A.Hai agent có sẵn, đổi bằng phím Tab
OpenCode có sẵn hai agent và bạn chuyển qua lại bằng phím Tab:
- buildagent mặc định, có toàn quyền cho công việc phát triển. Dùng khi bạn đã sẵn sàng để AI viết hoặc sửa code.
- planagent chỉ đọc, dùng để phân tích và khám phá code. Nó từ chối sửa file theo mặc định và hỏi xin phép trước khi chạy lệnh bash.
Lợi ích thực tế: khi 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". Khi đã hiểu và muốn thay đổi, bạn mới Tab sang build.
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. OpenCode dùng nó 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. Hợp khi câu hỏi của bạn cần lục nhiều nơi trong dự án.
C.Nhiều cách cài, kể cả bản desktop
README liệt kê script cài một dòng, npm/bun/pnpm/yarn, Homebrew, pacman và paru (Arch Linux), mise, nix. Ngoài ra còn bản Desktop (BETA) cho macOS, Windows và Linux. Bạn chọn cách quen tay nhất với máy mình.
D.Có tài liệu và cộng đồng
Cách cấu hình chi tiết nằm ở trang tài liệu chính thức của dự án (opencode.ai/docs). Repo cũng có README nhiều ngôn ngữ, trong đó có tiếng Việt (README.vi.md), và có cộng đồng trên Discord và X.
II.Cần chuẩn bị gì
Tư liệu README nói rất ít về yêu cầu hệ thống. Những gì có thể khẳng định:
- Hệ điều hànhbản desktop có file cho macOS (Apple Silicon và Intel), Windows (x64) và Linux (
.deb,.rpmhoặc.AppImage). Các lệnh cài bằng package manager ghi cho macOS, Linux và "mọi hệ điều hành" (mise). - Gỡ bản cũREADME khuyến cáo gỡ các phiên bản cũ hơn 0.1.x trước khi cài.
- Công cụ càituỳ cách bạn chọn, cần sẵn curl, npm (hoặc bun/pnpm/yarn), Homebrew, mise hoặc nix.
- Tài khoản, API key, phần cứngREADME chưa nói. Một coding agent thường cần kết nối tới một mô hình AI, nhưng cách kết nối và có tốn phí hay không thì mình chưa có thông tin trong tư liệu. Bạn xem ở trang tài liệu của dự án trước khi dùng.
README chưa nói OpenCode cần API key hay tài khoản nào. Nếu sau này bạn nhập key của một dịch vụ AI, hãy giữ kín key và kiểm tra giá của dịch vụ đó. Đừng dán key vào chỗ công khai hoặc đẩy lên GitHub.
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ỡ trước
- Chọn cách càiScript curl, npm, Homebrew, mise, nix hoặc bản desktop
- Chạy lệnh càiMở terminal và dán lệnh tương ứng
- Kiểm tra vị trí càiScript cài vào thư mục $HOME/.opencode/bin
- Đọc tài liệu cấu hìnhXem opencode.ai/docs để thiết lập tiếp
A.Gỡ bản cũ (nếu có)
README ghi: "Remove versions older than 0.1.x before installing." Nếu đây là lần đầu bạn dùng OpenCode thì bỏ qua bước này. README không ghi lệnh gỡ, nên cách gỡ phụ thuộc bạn đã cài bằng cách nào (ví dụ gỡ bằng chính package manager đã dùng).
B.Chọn một cách cài
Bạn chỉ cần chọn MỘT cách. Mở terminal (macOS/Linux: ứng dụng Terminal; Windows: PowerShell hoặc Windows Terminal) rồi chạy lệnh tương ứng. Dưới đâ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 chọn:
- curl ... | bash (README gọi vui là "YOLO"): tải script về và chạy ngay. Tiện nhưng bạn chạy một script từ internet mà không đọc trước. Cẩn thận hơn thì mở địa chỉ script ra đọc trước khi chạy.
- npm i -g @opencode/cli@latest: cài toàn cục bằng npm, README ghi dùng được cả bun, pnpm, yarn. Lưu ý tên gói trong lệnh này là
@opencode/cli. Đừng tự đổi thành tên khác. - brew install anomalyco/tap/opencode-v2: README ghi cách này được khuyến nghị cho macOS và Linux vì luôn cập nhật. Bản
brew install opencodelà formula chính thức nhưng cập nhật chậm hơn. - pacman / paru: dành cho Arch Linux.
opencodelà bản ổn định,opencode-betalà bản mới nhất từ AUR. - mise use -g opencode: dùng được trên mọi hệ điều hành nếu bạn có mise.
- nix run github:anomalyco/opencode: chạy trực tiếp bằng Nix.
Trên Windows, README không nói rõ cách nào là khuyến nghị. Lựa chọn dễ nhất với người mới là bản desktop ở bước sau.
C.Hoặc cài bản Desktop (BETA)
Bản desktop tải tại trang opencode.ai/download. README liệt kê các file:
| 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, bạn cũng có thể cài bằng Homebrew:
brew install --cask opencode-desktopBản desktop đang ở mức BETA, nên có thể còn lỗi vặt. Bạn nên tải từ đúng trang chính thức nêu trên.
D.Biết nơi script cài đặt đặt file
Nếu cài bằng script curl, README cho biết OpenCode được đặt 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 chưa. README không ghi chi tiết bước thêm PATH, nên cách làm tuỳ vào shell bạn đang dùng.
E.Đọc tài liệu để cấu hình thêm
README chỉ dẫn: muốn biết cách cấu hình OpenCode, hãy vào trang tài liệu chính thức tại opencode.ai/docs. Phần agent có trang riêng tại opencode.ai/docs/agents. README không ghi cách cấu hình nguồn mô hình AI, nên đây là chỗ bạn cần đọc tiếp.
IV.Kiểm tra đã chạy được chưa
README không có mục "kiểm tra cài đặt" và không ghi tên lệnh khởi chạy hay màn hình mong đợi. Vì vậy mình chỉ nêu những dấu hiệu hợp lý, không phải cam kết từ README:
- Lệnh cài chạy xong mà không báo lỗi.
- Nếu dùng script curl, thư mục
$HOME/.opencode/bincó xuất hiện sau khi cài. - Với bản desktop, bạn mở được ứng dụng như phần mềm bình thường.
- Tên gói trên Homebrew, pacman, mise đều là
opencode. Sau khi cài, bạn thử gõ tên đó trong terminal. Nếu máy báo không tìm thấy lệnh, xem mục lỗi bên dưới.
Khi mở được giao diện, bạn thử nhấn Tab để chuyển giữa build và plan. README nói đây là cách đổi agent, nên đó là dấu hiệu tốt rằng bạn đang dùng đúng công cụ.
V.Dùng vào việc thật
Các tình huống dưới đây bám vào những gì README nói: hai agent build và plan, subagent general, và việc làm trên một dự án code. Câu lệnh mẫu chỉ là gợi ý cách nói chuyện với AI, không phải cú pháp bắt buộc.
A.Chủ shop nhận lại website bán hàng từ người làm cũ
Bạn là chủ một shop online, thuê freelancer làm web, giờ họ nghỉ và để lại một thư mục code. Bạn muốn hiểu nó mà chưa muốn đụng vào.
Mở OpenCode ở thư mục dự án và đảm bảo đang ở chế độ plan (chỉ đọc, từ chối sửa file mặc định). Bạn nhập câu hỏi mẫu:
Hãy giải thích dự án này làm gì, gồm những phần chính nào, và phần nào liên quan đến giỏ hàng?Kết quả: bạn nhận được bản giải thích bằng ngôn ngữ thường, đủ để làm việc với một lập trình viên mới mà không bị "nói gì cũng gật đầu". Vì plan không sửa file, code của bạn an toàn.
B.Lập trình viên mới đọc một codebase lạ
Bạn vừa vào công ty và được giao một dự án cũ. README đề xuất đúng việc này: plan "ideal for exploring unfamiliar codebases or planning changes".
Bạn dùng plan để hỏi, chẳng hạn:
Tìm giúp mình nơi xử lý đăng nhập và liệt kê các file liên quan.Nếu câu hỏi cần lục nhiều nơi, bạn có thể gọi subagent bằng cách gõ @general trong tin nhắn, theo README. Kết quả là một danh sách file và giải thích, giúp bạn tiết kiệm buổi đầu ngồi lần mò.
Cho AI đọc trước, sửa sau: bật plan để hiểu, rồi mới Tab sang build.
Ông T
C.Lên kế hoạch thay đổi trước khi viết code
Trưởng nhóm muốn thêm một tính năng nhỏ, chẳng hạn xuất báo cáo ra file. Bạn ở chế độ plan và nhờ:
Mình muốn thêm nút xuất báo cáo. Hãy đề xuất các bước, file nào cần sửa, và rủi ro cần lưu ý.Vì plan hỏi xin phép trước khi chạy lệnh bash, bạn kiểm soát được những gì nó định làm. Bạn có một bản kế hoạch để duyệt, rồi mới chuyển sang build để thực hiện.
D.Nhờ AI làm việc thật bằng build
Sau khi đã duyệt kế hoạch, bạn nhấn Tab để sang build, agent có toàn quyền cho công việc phát triển. Bạn giao một việc rõ ràng, nhỏ:
Làm theo kế hoạch trên, chỉ sửa phần xuất báo cáo, đừng đụng các file khác.Kết quả là AI sửa file trực tiếp. Hãy dùng Git hoặc sao lưu thư mục trước khi giao việc cho build để quay lại được nếu không ưng. Chia việc nhỏ và dặn rõ phạm vi giúp bạn dễ kiểm tra kết quả hơn.
VI.Lỗi hay gặp và cách xử lý
README không có mục xử lý lỗi, nên các mục dưới đây là những lỗi rất dễ gặp với loại công cụ này, kèm cách xử lý an toàn.
A.Gõ tên lệnh mà máy báo không tìm thấy
Thường do thư mục cài chưa nằm trong PATH, hoặc bạn chưa mở lại terminal sau khi cài. Hãy đóng và mở lại terminal. Nếu cài bằng script curl, kiểm tra xem $HOME/.opencode/bin có tồn tại và có trong PATH không.
B.Cài chồng lên bản cũ gây rối
README khuyến cáo gỡ các phiên bản cũ hơn 0.1.x trước khi cài. Nếu bạn thấy phiên bản hoặc hành vi lạ, gỡ bản cũ rồi cài lại bằng đúng một cách cài, đừng trộn nhiều cách (ví dụ vừa npm vừa brew).
C.Gõ nhầm tên gói
Trong README, lệnh npm dùng gói @opencode/cli, còn các package manager khác dùng opencode hoặc opencode-v2, opencode-beta. Nên chép đúng từng dòng lệnh, đừng đoán tên. Nếu lệnh npm báo không tìm thấy gói, hãy kiểm tra lại README mới nhất hoặc dùng cách cài khác.
D.AI sửa file ngoài ý muốn
Build có toàn quyền, nên nó có thể đổi nhiều hơn bạn tưởng. Cách xử lý: dùng plan để xem trước, giao việc nhỏ, và luôn có bản sao lưu hoặc commit Git trước khi cho build chạy. Nếu kết quả không ưng, khôi phục từ bản sao lưu thay vì cố sửa tay từng chỗ.
E.Không biết cấu hình nguồn mô hình AI
README không nói chi tiết. Đây là chỗ người mới hay vấp nhất. Hãy đọc trang tài liệu chính thức tại opencode.ai/docs, hoặc hỏi ở Discord của dự án. Tránh làm theo hướng dẫn lạ từ nguồn không rõ, nhất là khi họ yêu cầu bạn dán key.
VII.Có nên dùng không
Điểm mạnh
- Mã nguồn mở, giấy phép MIT, nên bạn được xem code và dùng tự do theo điều khoản đó.
- Có hai chế độ build và plan, giúp tách việc "đọc, hiểu" khỏi việc "sửa". Với người mới, đây là lớp an toàn đáng giá.
- Nhiều cách cài và có bản desktop cho Windows, macOS, Linux.
- Cộng đồng lớn (khoảng 226.506 sao) và repo vẫn được cập nhật.
Giới hạn
- README ngắn, chưa nói rõ yêu cầu hệ thống, cách kết nối mô hình 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.
- Có chút khác nhau giữa các tên gói trong README (
@opencode/cli,opencode,opencode-v2,opencode-beta), nên người mới dễ rối. - Giao toàn quyền cho build đòi hỏi bạn có thói quen sao lưu và kiểm tra kết quả.
Khi nào nên chọn cách khác
Nếu bạn chỉ cần hỏi đáp AI về một đoạn code ngắn, một khung chat thông thường là đủ và đơn giản hơn. Nếu bạn cần cam kết rõ về chi phí, bảo mật hay hỗ trợ doanh nghiệp, hãy kiểm tra kỹ tài liệu và điều khoản của dự án vì README chưa có thông tin này. Còn nếu bạn muốn một trợ lý AI chạy ngay trong dự án, có chế độ chỉ đọc để làm quen an toà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. README không nói về chi phí của mô hình AI mà bạn kết nối vào. Bạn nên xem tài liệu tại opencode.ai/docs để biết rõ.
OpenCode chạy được trên Windows không?
Có bản desktop (BETA) cho Windows là file opencode-desktop-win-x64.exe, tải tại opencode.ai/download. README không nói rõ script curl có chạy trên Windows hay không. Mise được ghi là dùng được trên mọi hệ điều hành.
OpenCode cài bằng lệnh nào?
README có nhiều cách: script curl, npm/bun/pnpm/yarn (gói @opencode/cli), Homebrew, pacman, paru, mise và nix. Trên macOS và Linux, README khuyến nghị lệnh brew install anomalyco/tap/opencode-v2. Script curl cài vào thư mục $HOME/.opencode/bin.
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 là agent 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 qua lại bằng phím Tab.
Cần GPU hoặc máy cấu hình mạnh không?
README không nêu yêu cầu phần cứng. Mình chưa có thông tin về việc cần GPU hay không. Bạn xem thêm ở trang tài liệu chính thức của dự án.
Dữ liệu và code của tôi có an toàn không?
README không mô tả chi tiết về xử lý dữ liệu. Repo có file SECURITY.md để bạn tham khảo chính sách bảo mật. Trong lúc dùng, hãy ưu tiên chế độ plan khi chỉ cần đọc, và sao lưu trước khi cho build sửa code.
Có hỗ trợ tiếng Việt không?
Repo có sẵn bản README tiếng Việt (README.vi.md) cùng nhiều ngôn ngữ khác. README không nói về việc giao diện hay agent có hỗ trợ tiếng Việt hay không, nên mình chưa có thông tin chắc chắn.


