OpenCode: agent lập trình mã nguồn mở chạy 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, giúp bạn đọc, hỏi đáp và sửa code ngay trên máy. Repo có sẵn hai agent là build (toàn quyền) và plan (chỉ đọc), và có cả bản desktop (beta). Cài không khó: chạy một dòng lệnh hoặc dùng trình quản lý gói quen thuộc.
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 ngôn ngữ thường, agent đọc dự án, đề xuất và sửa code giúp bạn. Dự án do nhóm anomalyco phát triển, viết bằng TypeScript, dùng giấy phép MIT và có trang chủ riêng là opencode.ai.
Repo này hợp với lập trình viên mới muốn có một "người phụ" biết đọc code. Nó cũng hợp với người làm kinh doanh, văn phòng có chút nền tảng kỹ thuật, cần hiểu một dự án lạ mà không phải đọc từng file. Hiện repo có khoảng 226.506 sao và 30.658 fork, và vẫn được cập nhật trong 3 tháng gần đây.
Điểm đáng giá nhất là cách chia quyền rất rõ. Agent build làm được mọi việc, còn agent 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 lo nó tự sửa file. Ngoài ra còn có bản ứng dụng desktop (beta) cho ai không thích gõ lệnh.
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 ứng dụng desktop.
I.OpenCode làm được gì
Theo README, OpenCode có mấy phần chính sau.
A.Hai agent chuyển nhanh bằng phím Tab
- build là agent mặc định, toàn quyền cho công việc phát triển. Bạn dùng nó khi muốn nó thực sự viết hoặc sửa code.
- 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. Rất hợp khi bạn mới nhận một dự án lạ hoặc muốn lập kế hoạch thay đổi trước khi động vào.
Bạn đổi qua lại giữa hai agent bằng phím Tab. Lợi ích thực tế là bạn tách bạch "nghĩ" và "làm", nên ít rủi ro hơn.
B.Subagent general cho việc tìm kiếm phức tạp
Repo còn có subagent general, dùng cho các tìm kiếm phức tạp và việc nhiều bước. Chủ yếu nó đượ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.Nhiều cách cài, có cả bản desktop
Bạn có thể cài bằng script, npm, Homebrew, pacman, paru, mise hoặc Nix. Ngoài ra có ứng dụng desktop (đang beta) cho macOS, Windows và Linux. Nhờ vậy gần như hệ điều hành nào cũng có đường vào.
D.Mã nguồn mở, có tài liệu riêng
Giấy phép MIT cho phép bạn xem code và dùng khá thoải mái. Cách cấu hình chi tiết nằm ở trang tài liệu opencode.ai/docs, nên README chỉ giữ phần cài đặt và giới thiệu agent.
II.Cần chuẩn bị gì
README ghi khá ít, nên mình chỉ nêu đúng những gì có:
- Hệ điều hành: bản desktop có cho macOS (Apple Silicon và Intel), Windows và Linux (
.deb,.rpm,.AppImage). Các lệnh Homebrew dùng cho macOS và Linux, pacman và paru cho Arch Linux, mise cho "mọi hệ điều hành", Nix cho người dùng Nix. - 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.
- Phiên bản Node/Python, tài khoản, API key, phần cứng: README chưa nói gì về các mục này. Vì vậy mình không đoán. Nếu cần biết agent kết nối với mô hình AI nào và phải khai báo key ra sao, bạn xem tài liệu tại opencode.ai/docs.
Có một điểm bạn nên biết: lệnh npm trong README dùng gói @opencode/cli, trong khi thông tin repo ghi tên gói npm là opencode. Hai thứ này khác nhau. Mình chép đúng lệnh trong README, nếu gặp lỗi bạn đối chiếu lại với trang tải về chính thức.
III.Cài đặt từng bước
- Gỡ bản cũXoá phiên bản trước 0.1.x nếu máy đang có
- Chọn cách càiScript, npm, Homebrew hoặc trình quản lý gói của hệ điều hành
- Chạy lệnh càiMở terminal và dán đúng một lệnh trong README
- Hoặc tải bản desktopTải file đúng hệ điều hành ở trang tải về
- Mở lại terminalĐể máy nhận lệnh mới rồi thử khởi chạy
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. README không nói cách gỡ. Nếu bạn từng cài OpenCode bằng cách nào, hãy gỡ bằng chính cách đó (ví dụ cài bằng Homebrew thì gỡ bằng Homebrew). Chưa từng cài thì bỏ qua bước này.
B.Bước 2: Chọn một cách cài
Trong README, các lệnh nằm chung một khối. Bạn chỉ cần chọn một dòng phù hợp, đừ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 # NixGợi ý chọn nhanh:
- Dùng macOS hoặc Linux, muốn bản mới nhất: dùng
brew install anomalyco/tap/opencode-v2(README ghi là cách được khuyên dùng). - Đã có npm (hoặc bun/pnpm/yarn): dùng
npm i -g @opencode/cli@latest. - Dùng Arch Linux:
sudo pacman -S opencodecho bản ổn định, hoặcparu -S opencode-betacho bản mới nhất từ AUR. - Muốn một cách chung cho mọi hệ điều hành:
mise use -g opencode. - Dùng Nix:
nix run github:anomalyco/opencode. - Thích nhanh gọn: dòng
curl ... | bashđứng đầu. README gọi nó đùa là "YOLO". Lệnh này tải một script từ mạng về chạy luôn, nên chỉ dùng khi bạn tin nguồn đó.
Chỗ người mới hay vấp: dòng bắt đầu bằng # là chú thích, không cần gõ. Phần chữ sau # ở cuối dòng cũng chỉ là ghi chú. Mở terminal ở đâu cũng được, vì đây là cài toàn máy (cờ -g của npm có nghĩa đó). Trên Windows, README không viết riêng lệnh cài cho dòng lệnh, nên cách an toàn nhất là dùng bản desktop ở bước sau.
C.Bước 3: Biết script cài vào đâu
Nếu bạn dùng script cài đặt, README cho biết nó cài OpenCode vào thư mục $HOME/.opencode/bin. Nếu sau khi cài mà terminal báo không tìm thấy lệnh, đây là chỗ đầu tiên cần xem. README không nói gì thêm về việc thêm thư mục này vào PATH, nên bạn cần xem tài liệu nếu gặp tình huống đó.
D.Bước 4: Hoặc tải bản desktop (beta)
Nếu không muốn dùng terminal, hãy tải bản ứng dụng ở trang 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ó Homebrew cũng cài được bằng lệnh sau:
# macOS (Homebrew)
brew install --cask opencode-desktopChọn đúng chip: máy Mac đời mới (chip M1 trở lên) dùng bản arm64, máy Mac cũ dùng chip Intel thì chọn bản x64. Bản desktop vẫn đang beta nên có thể còn lỗi vặt.
E.Bước 5: Mở lại terminal
Sau khi cài, hãy đóng và mở lại cửa sổ terminal để máy nhận lệnh mới. README chưa ghi rõ lệnh khởi chạy. Tên gói là opencode, nên bạn thử gõ tên đó. Nếu khác, hãy xem hướng dẫn ở opencode.ai/docs.
README không nói về việc khai báo tài khoản hay API key. Nếu tài liệu yêu cầu điền key của một nhà cung cấp AI, hãy giữ key riêng tư, đừng dán vào chỗ công khai và đừng gửi cho người khác. Dịch vụ AI tính phí theo mức dùng thường có thể tốn tiền, nên hãy theo dõi chi phí ngay từ đầu.
IV.Kiểm tra đã chạy được chưa
README không đưa ra lệnh kiểm tra phiên bản hay kết quả mẫu, nên mình không bịa ra. Cách kiểm tra thực tế, dựa trên những gì tư liệu có:
- Terminal nhận lệnh: mở một terminal mới, thử khởi chạy bằng tên
opencode. Nếu giao diện agent hiện lên thì cài thành công. - Thử phím Tab: theo README,
Tabchuyển giữa agent build và plan. Nếu bạn thấy chuyển được, tức là bạn đang dùng đúng OpenCode. - Với bản desktop: mở ứng dụng lên là thấy giao diện. Nếu file tải về không mở được, kiểm tra lại bạn đã chọn đúng hệ điều hành và chip chưa.
Nếu máy báo không tìm thấy lệnh, xem lại thư mục $HOME/.opencode/bin (nếu cài bằng script) hoặc mục lỗi bên dưới.
V.Dùng vào việc thật
README không đưa ví dụ lệnh cụ thể, nên các tình huống dưới đây bám vào đúng khả năng đã nêu: hai agent build/plan, subagent @general, và việc đọc, sửa code. Câu lệnh mẫu chỉ là cách bạn nhập nội dung trong khung chat của OpenCode.
Đừng để AI sửa code khi bạn chưa hiểu dự án. Cứ cho nó đọc trước, rồi mới cho nó viết.
Ông T
A.Tình huống 1: Nhận một dự án lạ và muốn hiểu nó
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 khác. Thay vì mò từng file, bạn mở OpenCode trong thư mục đó và đổi sang agent plan bằng phím Tab. Vì plan chỉ đọc, bạn yên tâm nó không đụng đến file nào.
Bạn hỏi bằng tiếng Việt, ví dụ:
Dự án này làm gì? Liệt kê các thư mục chính và cho mình biết nên đọc file nào trước.Kết quả bạn nhận được là một bản tóm tắt cấu trúc dự án và gợi ý thứ tự đọc. Plan còn hỏi quyền trước khi chạy lệnh bash, nên bạn vẫn kiểm soát được.
B.Tình huống 2: Lập kế hoạch trước khi sửa
Bạn làm chủ một website bán hàng nhỏ do thuê người viết, và muốn thêm một tính năng. Đừng cho sửa ngay. Ở chế độ plan, bạn mô tả việc cần làm:
Mình muốn thêm trường ghi chú đơn hàng. Hãy cho mình biết sẽ phải sửa những file nào và các bước làm theo thứ tự.Bạn nhận được một danh sách bước và các file liên quan. Bạn có thể đưa danh sách này cho người viết code gốc xem, hoặc tự chuyển sang agent build để thực hiện.
C.Tình huống 3: Giao agent build làm việc nhỏ có giới hạn
Bạn là dev đã hiểu dự án và có một việc rõ ràng như sửa lỗi chính tả trong thông báo, đổi tên một hàm, hay thêm một đoạn kiểm tra đầu vào. Bấm Tab sang build, rồi mô tả đúng một việc:
Trong file xử lý đăng nhập, thêm kiểm tra email rỗng và trả về thông báo lỗi bằng tiếng Việt.Build có toàn quyền nên nó sẽ chỉnh file trực tiếp. Hãy xem lại phần thay đổi trước khi dùng. Nếu bạn dùng Git để quản lý code thì càng dễ so sánh và quay lại.
D.Tình huống 4: Tìm kiếm phức tạp bằng @general
Dự án lớn, bạn cần tìm mọi chỗ gọi một chức năng và xem chúng liên quan thế nào. Bạn nhắc subagent trong tin nhắn:
@general tìm tất cả nơi dùng chức năng gửi email và tóm tắt luồng chạy.README mô tả @general dành cho các tìm kiếm phức tạp và việc nhiều bước. Kết quả là bản tổng hợp mà bạn khó có được nếu chỉ tìm chữ thủ công.
VI.Lỗi hay gặp và cách xử lý
A.Báo không tìm thấy lệnh sau khi cài
Đây là lỗi rất hay gặp với công cụ dòng lệnh. Trước hết đóng hẳn terminal và mở lại. Nếu cài bằng script, nhớ README cho biết file nằm ở $HOME/.opencode/bin. Kiểm tra thư mục đó có tồn tại không. Nếu cần thêm vào PATH, bạn xem tài liệu ở opencode.ai/docs vì README chưa hướng dẫn.
B.Cài lệnh npm nhưng gói không đúng
README dùng @opencode/cli, trong khi thông tin repo ghi tên gói là opencode. Nếu lệnh npm báo lỗi hoặc cài ra thứ không đúng, đừng thử bừa nhiều gói. Hãy quay về cách cài khác (Homebrew, script) hoặc kiểm tra tên chính xác ở trang tải về chính thức. Cũng cẩn thận với các dự án có chữ "opencode" trong tên: README nhắc rằng một số dự án như "opencode-dashboard" hay "opencode-mobile" không do nhóm OpenCode làm và không liên kết với họ.
C.Xung đột với bản cũ
README dặn gỡ các bản cũ hơn 0.1.x trước khi cài. Nếu máy chạy ra giao diện lạ hoặc lệnh không như mô tả, rất có thể bạn đang chạy bản cũ. Hãy gỡ bản cũ bằng đúng cách đã cài, rồi cài lại.
D.Chọn nhầm file desktop
Trên Mac, file arm64 chỉ chạy trên chip Apple Silicon, còn x64 dành cho chip Intel. Mở không được thì thường là chọn sai. Vào menu Apple, chọn "Giới thiệu về máy Mac này" để xem chip, rồi tải lại bản đúng.
E.Agent đã sửa code theo cách bạn không muốn
Đây là rủi ro tự nhiên với agent có toàn quyền như build. Cách phòng: dùng plan để xem trước, giao từng việc nhỏ, và giữ code trong Git hoặc có bản sao lưu để quay lại. Đừng giao nó cả dự án quan trọng khi chưa có bản sao.
VII.Có nên dùng không
Điểm mạnh. OpenCode miễn phí để dùng phần mềm và mã nguồn mở theo giấy phép MIT, nên bạn xem được nó làm gì. Việc chia rõ hai chế độ build và plan rất thực dụng cho người mới. Nhiều cách cài, có cả bản desktop, và dự án đang được cập nhật đều. Cộng đồng lớn (hàng trăm nghìn sao) cũng là một tín hiệu tốt, và README có nhiều bản dịch, trong đó có tiếng Việt.
Giới hạn. README rất ngắn. Nó chưa nói về yêu cầu phiên bản, cách khai báo key hay lệnh khởi chạy, nên bạn phải đọc thêm tài liệu trên trang chủ. Bản desktop còn là beta. Các lệnh cài khá nhiều và có chỗ không thống nhất về tên gói, nên người mới dễ bối rối. Chi phí dùng mô hình AI (nếu có) tuỳ bạn chọn nhà cung cấp nào, và tư liệu chưa nói về điều đó.
Khi nào nên chọn cách khác. Nếu bạn hoàn toàn không đụng đến code mà chỉ cần trò chuyện với AI, một ứng dụng chat thông thường sẽ đơn giản hơn. Nếu công ty bạn có quy định nghiêm ngặt về dữ liệu, hãy hỏi bộ phận kỹ thuật trước khi cho bất kỳ agent nào đọc code, vì tư liệu chưa nói rõ dữ liệu được xử lý ra sao. Còn nếu bạn muốn một agent lập trình mã nguồn mở, cài nhanh và có chế độ chỉ đọc để làm quen an toàn thì OpenCode đáng thử.
Câu hỏi thường gặp
OpenCode có miễn phí không?
Bản thân OpenCode là phần mềm mã nguồn mở theo giấy phép MIT. Tư liệu chưa nói gì về chi phí của mô hình AI hay dịch vụ đi kèm, nên bạn xem tài liệu ở opencode.ai/docs để biết cần tài khoản hoặc key nào.
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. README chưa ghi lệnh cài riêng cho dòng lệnh trên Windows, ngoài các lệnh chung như npm và mise (mise được ghi là dùng cho mọi hệ điều hành).
Cài OpenCode bằng cách nào nhanh nhất?
README có một dòng curl chạy script cài đặt, ghi là cài vào $HOME/.opencode/bin. Người dùng macOS và Linux còn có lệnh Homebrew, được README khuyên dùng vì luôn mới. Bạn chỉ cần chọn một cách, không phải chạy hết.
Agent build và plan khác nhau thế nào?
Build là agent mặc định, 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 trước khi chạy lệnh bash. Bạn đổi qua lại bằng phím Tab.
Có cần GPU hoặc máy cấu hình mạnh không?
Tư liệu chưa có thông tin về yêu cầu phần cứng hay GPU. Bạn nên xem tài liệu ở opencode.ai/docs trước khi cài.
Dữ liệu và code của tôi có an toàn không?
Tư liệu README không nói về cách xử lý dữ liệu. Vì repo mã nguồn mở nên bạn có thể tự xem code, và repo có file SECURITY.md. Với code nhạy cảm, hãy hỏi bộ phận kỹ thuật và đọc tài liệu trước khi dùng.
Các dự án có chữ "opencode" trong tên có phải của nhóm này không?
Chưa chắc. README dặn các dự án liên quan dùng chữ opencode trong tên (như opencode-dashboard, opencode-mobile) phải ghi rõ là không do nhóm OpenCode làm và không liên kết với họ.


