OpenCode: coding agent 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à coding agent mã nguồn mở dùng để khám phá codebase, lập kế hoạch và thực hiện công việc phát triển phần mềm. Repo có giao diện dòng lệnh, bản desktop beta và hai agent tích hợp là build và plan. Cài CLI khá ngắn gọn trên macOS, Linux hoặc qua npm; Windows có bản desktop beta.
OpenCode là coding agent mã nguồn mở dành cho công việc phát triển phần mềm. Bạn có thể dùng nó để đọc code, tìm kiếm trong dự án, lập kế hoạch thay đổi hoặc thực hiện công việc phát triển trực tiếp trong codebase.
Repo phù hợp với lập trình viên mới, nhóm phát triển muốn có trợ lý code trong terminal và người thích dùng một công cụ mở thay vì phụ thuộc hoàn toàn vào ứng dụng đóng. Điểm đáng giá nhất là OpenCode có hai agent tích hợp cho hai mức quyền khác nhau: build để làm việc đầy đủ với dự án và plan để phân tích, khám phá code theo chế độ chỉ đọc.
Dự án dùng TypeScript, có giấy phép MIT và hiện có khoảng 226580 sao cùng 30675 fork. Repo vẫn còn được cập nhật trong 3 tháng gần đây, nên bạn có thể xem đây là một dự án đang hoạt động.
anomalyco/opencode
OpenCode là coding agent mã nguồn mở, hỗ trợ đọc, phân tích và chỉnh sửa code ngay trong dự án.
I.OpenCode làm được gì
A.Làm việc với codebase bằng trợ lý AI
OpenCode được mô tả là một coding agent mã nguồn mở. Trong thực tế, bạn có thể đưa yêu cầu về codebase để công cụ hỗ trợ khám phá, phân tích và thực hiện công việc phát triển. Điều này hữu ích khi bạn mới nhận một dự án và chưa biết các thư mục, tệp hoặc phần logic liên quan nằm ở đâu.
Thay vì tự mở từng tệp để lần theo luồng xử lý, bạn có thể bắt đầu bằng câu hỏi tự nhiên về dự án. Cách làm này phù hợp với cả người mới học lập trình lẫn dev cần rút ngắn thời gian tìm hiểu code cũ.
B.Có agent build cho công việc phát triển
build là agent mặc định và có quyền truy cập đầy đủ cho công việc phát triển. Đây là lựa chọn khi bạn muốn OpenCode hỗ trợ xử lý một yêu cầu cụ thể trong dự án, chẳng hạn xem xét code và thực hiện thay đổi theo yêu cầu của bạn.
Với người mới, nên mô tả rõ mục tiêu, phạm vi tệp và kết quả mong muốn. Với dev đã quen dự án, bạn có thể dùng build như một trợ lý trong quy trình sửa lỗi, thêm chức năng hoặc làm rõ đoạn code.
C.Có agent plan để phân tích an toàn hơn
plan là agent chỉ đọc dành cho phân tích và khám phá code. Agent này mặc định từ chối chỉnh sửa tệp và sẽ hỏi quyền trước khi chạy lệnh bash.
Đây là lựa chọn tốt khi bạn chưa hiểu một codebase, muốn biết nguyên nhân lỗi hoặc cần lập kế hoạch trước khi cho phép thay đổi. Bạn có thể chuyển giữa build và plan bằng phím Tab.
D.Có subagent general cho tìm kiếm phức tạp
OpenCode có thêm subagent general cho các công việc tìm kiếm phức tạp và nhiều bước. Bạn có thể gọi subagent này trong tin nhắn bằng @general.
Tính năng này hữu ích khi câu hỏi cần tìm qua nhiều phần của dự án hoặc cần kết hợp nhiều bước khám phá. Bạn nên mô tả rõ câu hỏi và giới hạn tìm kiếm để kết quả dễ kiểm tra hơn.
E.Có bản desktop beta
Ngoài CLI, OpenCode còn có ứng dụng desktop beta. Bản tải xuống được cung cấp cho macOS Apple Silicon, macOS Intel, Windows và Linux. Người dùng không quen terminal có thể chọn bản desktop, còn dev thích làm việc trực tiếp trong thư mục dự án có thể chọn CLI.
README nêu các gói Linux gồm .deb, .rpm hoặc .AppImage. Với macOS, README có thêm lệnh cài desktop app qua Homebrew.
F.Có nhiều cách cài đặt
README cung cấp script cài đặt nhanh, npm, Bun, pnpm, Yarn, Homebrew, Pacman, AUR, mise và Nix. Nhờ vậy, bạn có thể chọn cách phù hợp với hệ điều hành và công cụ đang dùng.
Dự án cũng có gói npm được khai báo là opencode, trong khi lệnh cài CLI trong README dùng @opencode/cli@latest. Khi cài, bạn nên ưu tiên đúng lệnh được README cung cấp thay vì tự đổi tên gói.
II.Cần chuẩn bị gì
Bạn cần một máy tính có hệ điều hành phù hợp với phương thức cài đặt bạn chọn. README nêu CLI có thể cài bằng npm, Bun, pnpm, Yarn, Homebrew, Pacman, AUR, mise hoặc Nix. Homebrew được nêu cho macOS và Linux. Pacman và AUR dành cho Arch Linux.
Nếu chọn ứng dụng desktop, README nêu các bản cho macOS Apple Silicon, macOS Intel, Windows và Linux. Windows được đề cập ở bản desktop beta với tệp .exe; README không đưa ra lệnh cài CLI riêng cho Windows.
Nếu dùng cách cài bằng npm, bạn cần có npm trên máy. README không ghi phiên bản Node.js cụ thể, nên không nên tự suy đoán một phiên bản bắt buộc.
Nếu dùng Homebrew, Pacman, AUR, mise hoặc Nix, bạn cần trình quản lý gói tương ứng. README không trình bày yêu cầu phần cứng tối thiểu.
README không nêu cụ thể tài khoản dịch vụ, API key, nhà cung cấp mô hình hay cấu hình thanh toán nào bắt buộc. Vì vậy, phần cài đặt dưới đây chỉ hướng dẫn những gì có trong tư liệu. Nếu OpenCode yêu cầu cấu hình thêm sau khi mở lần đầu, bạn cần xem tài liệu cấu hình của dự án.
README không nêu API key, nhà cung cấp mô hình hoặc chi phí sử dụng. Không dán secret vào tin nhắn, tệp dự án hay lịch sử terminal nếu bạn chưa biết rõ OpenCode lưu và sử dụng cấu hình đó như thế nào.
III.Cài đặt từng bước
- Chọn cách càiChọn script, npm, trình quản lý gói hoặc desktop app phù hợp
- Cài OpenCodeChạy đúng lệnh trong README
- Kiểm tra thư mục càiLưu ý vị trí cài mặc định của script
- Mở dự ánChạy OpenCode trong codebase cần làm việc
- Chọn agentDùng Tab để chuyển giữa build và plan
A.Chọn phương thức cài đặt
Nếu bạn muốn cài nhanh CLI trên môi trường có curl và shell, README cung cấp script cài đặt. Nếu máy đã có npm, bạn có thể cài gói CLI toàn cục. Người dùng macOS hoặc Linux có thể dùng Homebrew.
Nếu bạn dùng Windows hoặc không quen terminal, hãy chọn ứng dụng desktop beta. README ghi bản Windows là opencode-desktop-win-x64.exe. README không đưa ra câu lệnh PowerShell tương ứng, nên không nên tự tạo thêm lệnh cài CLI từ thông tin hiện có.
Trước khi cài, README nhắc cần gỡ các phiên bản cũ hơn 0.1.x. Hãy kiểm tra phiên bản cũ của OpenCode nếu máy bạn đã từng cài trước đây.
B.Cài CLI bằng script
Mở terminal, dán đúng lệnh sau rồi chờ script hoàn tất:
curl -fsSL https://opencode.ai/v2/install | bashcurl tải nội dung script cài đặt. Các tùy chọn trong lệnh yêu cầu kết nối thất bại phải báo lỗi và không hiển thị tiến trình tải. Phần | bash chuyển script cho Bash thực thi.
README cho biết script cài OpenCode vào $HOME/.opencode/bin. Nếu sau khi cài terminal báo không tìm thấy lệnh, có thể thư mục này chưa nằm trong PATH. README không cung cấp lệnh chỉnh PATH, nên bạn cần xem hướng dẫn môi trường của hệ điều hành hoặc tài liệu dự án.
C.Cài CLI bằng npm
Nếu đã có npm, chạy lệnh README cung cấp:
npm i -g @opencode/cli@latestTham số -g cài gói ở phạm vi toàn cục để lệnh có thể được gọi bên ngoài một dự án cụ thể. @latest yêu cầu bản mới nhất theo tên gói trong lệnh.
README ghi có thể dùng Bun, pnpm hoặc Yarn thay cho npm, nhưng không chép lệnh riêng cho từng trình quản lý gói. Vì vậy, nếu bạn chưa biết cú pháp tương ứng, hãy dùng npm hoặc xem tài liệu của dự án.
D.Cài bằng Homebrew
Trên macOS hoặc Linux, README khuyến nghị tap của dự án:
brew install anomalyco/tap/opencode-v2README cũng có công thức chính thức nhưng được cập nhật ít thường xuyên hơn:
brew install opencodeBạn chỉ nên chọn một trong hai lệnh trên để bắt đầu. Nếu mục tiêu là dùng bản được README khuyến nghị và luôn cập nhật, chọn lệnh anomalyco/tap/opencode-v2.
README còn cung cấp cách cài desktop app trên macOS:
brew install --cask opencode-desktopLệnh này dành cho ứng dụng desktop, không phải lệnh CLI thông thường.
E.Cài bằng các trình quản lý gói khác
Nếu bạn dùng Arch Linux, README cung cấp hai lựa chọn:
sudo pacman -S opencodeparu -S opencode-betaLệnh đầu cài bản Stable qua Pacman. Lệnh thứ hai cài bản Latest from AUR qua paru. Với sudo, terminal có thể yêu cầu mật khẩu tài khoản hệ thống.
README cũng có lệnh cho mise và Nix:
mise use -g opencodenix run github:anomalyco/opencodeCác lệnh này phù hợp khi bạn đã dùng mise hoặc Nix. Nếu chưa dùng các công cụ đó, chọn npm hoặc script thường dễ bắt đầu hơn.
F.Cài ứng dụng desktop
README cho biết OpenCode có ứng dụng desktop beta và cung cấp tệp theo nền tảng:
- macOS Apple Silicon:
opencode-desktop-mac-arm64.dmg - macOS Intel:
opencode-desktop-mac-x64.dmg - Windows:
opencode-desktop-win-x64.exe - Linux:
.deb,.rpmhoặc.AppImage
Tải đúng tệp theo máy của bạn rồi mở trình cài đặt. Với Windows, cần chọn đúng bản win-x64.exe. README không nói thêm về yêu cầu phiên bản Windows hoặc cách cấu hình chi tiết sau khi cài.
IV.Kiểm tra đã chạy được chưa
Cách kiểm tra cơ bản là mở OpenCode sau khi cài và thử làm việc trong một codebase. README cho biết OpenCode có hai agent tích hợp là build và plan, đồng thời có thể chuyển đổi bằng phím Tab.
Nếu giao diện cho phép bạn chuyển giữa build và plan, đó là dấu hiệu các agent tích hợp đã được nhận diện. Hãy chọn plan trước để khám phá dự án. Theo README, agent này ở chế độ chỉ đọc, mặc định từ chối chỉnh sửa tệp và hỏi quyền trước khi chạy lệnh bash.
Sau đó, thử một yêu cầu ngắn như:
Hãy mô tả cấu trúc chính của dự án này và chỉ ra nơi xử lý chức năng đăng nhập.Kết quả mong đợi là OpenCode phân tích codebase và trả lời về các phần liên quan. Nếu muốn kiểm tra agent build, hãy chuyển bằng Tab rồi yêu cầu một thay đổi nhỏ, có phạm vi rõ ràng. Trước khi chấp nhận thay đổi, hãy đọc lại tệp và nội dung mà agent đề xuất.
README không cung cấp một lệnh kiểm tra phiên bản cụ thể hoặc một màn hình đầu ra cố định. Vì vậy, không nên coi một chuỗi phiên bản tự đoán là tiêu chí bắt buộc.
V.Dùng vào việc thật
A.Dev mới nhận một codebase lạ
Bạn vừa nhận một dự án TypeScript nhưng chưa biết luồng chạy chính nằm ở đâu. Mở OpenCode trong thư mục dự án, chọn plan bằng phím Tab, rồi gửi yêu cầu:
Hãy khám phá codebase này ở chế độ chỉ đọc. Tóm tắt các thư mục chính, điểm khởi động của ứng dụng và luồng xử lý của chức năng người dùng. Không chỉnh sửa tệp.plan phù hợp vì agent này được thiết kế cho phân tích và khám phá code, đồng thời mặc định từ chối chỉnh sửa. Kết quả giúp bạn có bản đồ ban đầu trước khi tự đọc từng phần.
B.Nhân viên văn phòng cần hiểu một công cụ nội bộ
Bạn không phải lập trình viên chuyên nghiệp nhưng cần biết một thư mục mã nguồn đang làm gì trước khi bàn giao cho đội kỹ thuật. Dùng plan và hỏi bằng ngôn ngữ đơn giản:
Hãy giải thích dự án này cho người không chuyên. Chức năng chính là gì, dữ liệu đi qua những phần nào, và tệp nào nên được hỏi đội kỹ thuật khi có lỗi?OpenCode có thể hỗ trợ khám phá codebase và tìm kiếm qua nhiều tệp. Bạn nên xem câu trả lời như bản định hướng ban đầu, sau đó nhờ dev xác nhận các thông tin quan trọng.
C.Dev muốn lập kế hoạch sửa lỗi trước
Khi gặp lỗi nhưng chưa muốn sửa ngay, chọn plan và mô tả hiện tượng, nơi phát sinh cùng điều kiện tái hiện:
Khi người dùng đăng nhập thất bại, hãy tìm các phần có liên quan, đưa ra giả thuyết nguyên nhân và lập kế hoạch kiểm tra. Chỉ đọc, không chạy lệnh thay đổi dữ liệu và không sửa tệp.Agent sẽ phù hợp với giai đoạn tìm nguyên nhân và lập kế hoạch. Khi đã hiểu hướng xử lý, bạn có thể chuyển sang build bằng Tab nếu muốn tiếp tục công việc phát triển.
D.Nhóm phát triển cần tìm kiếm nhiều bước
Nếu câu hỏi liên quan đến nhiều thư mục hoặc nhiều lớp xử lý, gọi subagent general:
@general Hãy tìm toàn bộ các phần liên quan đến luồng tạo báo cáo, từ điểm nhận yêu cầu đến nơi xuất kết quả. Tóm tắt tệp và mối liên hệ giữa chúng.README mô tả general là subagent dành cho tìm kiếm phức tạp và công việc nhiều bước. Cách này phù hợp khi bạn muốn giao phần khám phá rộng cho một trợ lý chuyên tìm kiếm, sau đó tự kiểm tra các tệp được nêu.
Công cụ tốt nhất không phải là công cụ sửa thay bạn, mà là công cụ giúp bạn hiểu đúng phần cần sửa.
Ông T
VI.Lỗi hay gặp và cách xử lý
A.Terminal báo không tìm thấy lệnh sau khi cài bằng script
README ghi script cài vào $HOME/.opencode/bin. Nếu terminal không nhận lệnh, thư mục cài có thể chưa được thêm vào PATH hoặc terminal chưa nhận cấu hình mới.
Hãy mở lại terminal và kiểm tra lại. Nếu vẫn lỗi, xem hướng dẫn cài đặt và cấu hình môi trường trong tài liệu dự án. Không nên tự đoán một đường dẫn khác.
B.Cài nhầm phiên bản cũ
README nhắc cần gỡ các phiên bản cũ hơn 0.1.x trước khi cài. Nếu máy đã từng cài OpenCode, hãy kiểm tra và xử lý bản cũ trước khi chạy lệnh mới.
Nếu bạn dùng nhiều phương thức cài như npm và Homebrew, hãy xác định lệnh đang trỏ đến bản nào để tránh nhầm giữa các bản cài.
C.Chọn sai gói desktop theo phần cứng
macOS có hai tệp desktop: bản Apple Silicon và bản Intel. Chọn sai kiến trúc có thể khiến ứng dụng không chạy đúng.
Trên Windows, hãy dùng tệp opencode-desktop-win-x64.exe được README nêu. Với Linux, chọn đúng định dạng .deb, .rpm hoặc .AppImage phù hợp với hệ thống.
D.Dùng build khi chỉ muốn xem code
build là agent mặc định và có quyền truy cập đầy đủ cho công việc phát triển. Nếu bạn chỉ muốn phân tích hoặc chưa sẵn sàng cho chỉnh sửa, hãy chuyển sang plan bằng Tab.
plan được thiết kế để chỉ đọc, mặc định từ chối chỉnh sửa tệp và hỏi quyền trước khi chạy lệnh bash. Đây là lựa chọn an toàn hơn cho lần khám phá đầu tiên.
E.Không biết cần API key hoặc nhà cung cấp nào
README được cung cấp không nêu API key, nhà cung cấp mô hình hoặc cấu hình tài khoản. Bạn không nên tự điền một biến môi trường hay khóa bất kỳ chỉ vì thấy công cụ AI cần cấu hình.
Hãy xem tài liệu cấu hình của OpenCode nếu ứng dụng yêu cầu bước tiếp theo. Chỉ sử dụng key đúng mục đích và tránh gửi key vào tin nhắn hoặc commit.
VII.Có nên dùng không
OpenCode đáng thử nếu bạn muốn một coding agent mã nguồn mở, có thể dùng trong quy trình khám phá và phát triển code. Repo có giấy phép MIT, có khoảng 226580 sao và 30675 fork, hỗ trợ nhiều cách cài đặt, có CLI và có desktop app beta. Hai agent build và plan cũng tạo ra ranh giới khá rõ giữa làm việc đầy đủ và phân tích chỉ đọc.
Điểm mạnh nhất là khả năng bắt đầu từ việc khám phá codebase. Người mới có thể dùng plan để hiểu dự án trước, còn dev có thể chuyển sang build khi đã xác định công việc. Subagent general cũng hữu ích cho các yêu cầu tìm kiếm nhiều bước.
Giới hạn là README ngắn và không nêu chi tiết về API key, nhà cung cấp mô hình, yêu cầu phần cứng, phiên bản Node.js hoặc cách cấu hình sau khi cài. Bản desktop được ghi rõ là beta, nên người dùng cần cân nhắc khi đưa vào quy trình quan trọng.
Nếu bạn cần một công cụ có tài liệu cấu hình đầy đủ ngay trong README, cần biết rõ chi phí hoặc cần hướng dẫn Windows bằng CLI, tư liệu hiện có chưa đủ để kết luận OpenCode đáp ứng các yêu cầu đó. Bạn nên đọc thêm tài liệu chính thức trước khi triển khai cho cả nhóm.
Tóm lại, OpenCode phù hợp để thử nghiệm và hỗ trợ phát triển code, đặc biệt khi bạn muốn khám phá dự án bằng chế độ chỉ đọc trước khi cho phép chỉnh sửa. Cách bắt đầu an toàn là cài công cụ, mở một codebase không quan trọng, chọn plan, rồi kiểm tra từng kết quả trước khi dùng build.
Câu hỏi thường gặp
OpenCode có miễn phí không?
Repo có giấy phép MIT. Tuy nhiên, README không nêu chi phí sử dụng mô hình, tài khoản hoặc nhà cung cấp dịch vụ, nên chưa thể khẳng định toàn bộ quá trình sử dụng không phát sinh chi phí.
OpenCode có chạy được trên Windows không?
Có. README liệt kê ứng dụng desktop beta cho Windows với tệp `opencode-desktop-win-x64.exe`. README không cung cấp lệnh cài CLI riêng cho Windows.
Có cần GPU để chạy OpenCode không?
README không nêu yêu cầu GPU hoặc phần cứng tối thiểu. Vì vậy, chưa có đủ thông tin để kết luận bạn có cần GPU hay không.
Có cần API key không?
README được cung cấp không nêu API key, nhà cung cấp mô hình hoặc tài khoản bắt buộc. Nếu ứng dụng yêu cầu cấu hình sau khi mở, bạn cần xem tài liệu chính thức của dự án.
OpenCode khác gì giữa agent build và plan?
`build` là agent mặc định, có quyền truy cập đầy đủ cho công việc phát triển. `plan` dành cho phân tích và khám phá ở chế độ chỉ đọc, mặc định từ chối chỉnh sửa tệp và hỏi quyền trước khi chạy lệnh bash.
Có thể dùng OpenCode mà không chỉnh sửa code không?
Có thể dùng agent `plan` để phân tích và khám phá code. README mô tả agent này là chỉ đọc và cho biết có thể chuyển đổi giữa các agent bằng phím `Tab`.
OpenCode có bản ứng dụng desktop không?
Có, nhưng README ghi là bản beta. Bản desktop được liệt kê cho macOS Apple Silicon, macOS Intel, Windows và Linux.


