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
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 (repo anomalyco/opencode) là một coding agent mã nguồn mở, giấy phép MIT. Nó giúp bạn đọc, hiểu và sửa code bằng ngôn ngữ thường, và có hai chế độ: build (được sửa file) và plan (chỉ đọc). Cài đặt chỉ cần một dòng lệnh hoặc tải bản desktop, nên người mới cũng làm được.
opencode là một trợ lý lập trình AI mã nguồn mở. Nó là công cụ bạn mở lên, nói bằng ngôn ngữ thường điều muốn làm với một dự án code, và nó đọc, phân tích, rồi giúp bạn sửa hoặc lên kế hoạch. Tác giả mô tả repo ngắn gọn là "The open source coding agent".
Repo này hợp với ba nhóm người. Thứ nhất là lập trình viên mới, muốn có người hướng dẫn khi đọc một dự án lạ. Thứ hai là dân văn phòng, người làm kinh doanh có vài file script hoặc website nhỏ cần chỉnh mà không rành code. Thứ ba là dev lâu năm muốn một agent chạy ngay trong terminal, không phụ thuộc một trình soạn code riêng.
Điểm đáng giá nhất của opencode là có sẵn hai chế độ làm việc, đổi qua lại bằng phím Tab. Chế độ plan chỉ đọc, an toàn để khám phá. Chế độ build được sửa file. Repo hiện có khoảng 226.506 sao và 30.658 fork, giấy phép MIT, ngôn ngữ chính là TypeScript, và vẫn được cập nhật trong 3 tháng gần đây.
anomalyco/opencode
opencode là agent lập trình AI mã nguồn mở: đọc code, sửa code, chạy lệnh giúp bạn, có chế độ build và plan, kèm bản ứng dụng desktop.
I.opencode làm được gì
Tư liệu của repo tập trung vào vài thứ cốt lõi. Mình tóm lại theo lợi ích thực tế.
A.Hai agent có sẵn: build và plan
opencode có hai agent dựng sẵn, bạn chuyển qua lại bằng phím Tab.
- build là agent mặc định, có toàn quyền để làm việc phát triển. Bạn dùng nó khi đã biết mình muốn gì và muốn nó bắt tay vào sửa.
- 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. Trước khi chạy lệnh bash, nó hỏi xin phép bạn.
Lợi ích: bạn không sợ lỡ tay làm hỏng dự án khi mới tìm hiểu. Cứ để ở plan cho tới khi hiểu rõ, rồi mới sang build.
B.Agent phụ general
Ngoài hai agent chính còn có một subagent tên general, dùng cho các việc tìm kiếm phức tạp và việc nhiều bước. Theo README, 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.Có cả bản ứng dụng desktop (BETA)
Nếu ngại terminal, opencode có bản ứng dụng desktop ở dạng beta cho macOS (Apple Silicon và Intel), Windows và Linux. Bạn tải từ trang chủ dự án rồi cài như phần mềm thường.
D.Nhiều cách cài, nhiều ngôn ngữ tài liệu
README liệt kê rất nhiều cách cài: script một dòng, npm, Homebrew, Arch Linux, mise, Nix. README còn có bản tiếng Việt ngay trong repo (file README.vi.md), tiện nếu bạn muốn đối chiếu.
II.Cần chuẩn bị gì
Tư liệu README chỉ nêu những điều sau, mình không thêm gì ngoài đó:
- Hệ điều hành: macOS, Linux có hướng dẫn cài bằng lệnh. Windows có file cài cho bản desktop (
opencode-desktop-win-x64.exe). README không ghi rõ cách cài bản dòng lệnh trên Windows, bạn xem thêm ở trang tài liệu của dự án. - Công cụ cài đặt: tùy cách bạn chọn. Ví dụ muốn dùng npm thì máy cần có Node và npm. Muốn dùng Homebrew thì cần Homebrew.
- Dọn bản cũ: README nhắc gỡ các phiên bản cũ hơn 0.1.x trước khi cài.
- Tài khoản, API key, phần cứng: README không nói tới. Chuyện kết nối với mô hình AI nào và cấu hình ra sao nằm ở tài liệu chính thức của dự án. Mình không đoán ở đây.
README không nói rõ opencode kết nối tới mô hình AI nào hay tính phí thế nào. Trước khi dùng cho việc quan trọng, bạn đọc phần cấu hình trong tài liệu chính thức để biết dữ liệu code của bạn được gửi đi đâu và có phát sinh chi phí không.
III.Cài đặt từng bước
- Gỡ bản cũXóa các phiên bản cũ hơn 0.1.x nếu máy từng cài
- Mở terminalMở cửa sổ dòng lệnh trên máy của bạn
- Chạy lệnh càiChọn một cách: script một dòng, npm, Homebrew hoặc cách khác
- Hoặc tải bản desktopTải file cài từ trang chủ nếu không muốn dùng terminal
- Mở trong thư mục dự ánĐi vào thư mục code rồi khởi chạy opencode
A.Bước 1: Gỡ bản cũ nếu có
README ghi: 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 bao giờ cài opencode thì bỏ qua bước này. README không nói gỡ bằng lệnh nào, nên nếu bạn từng cài bằng cách nào thì gỡ bằng đúng công cụ đó (ví dụ cài bằng npm thì gỡ bằng npm).
B.Bước 2: Mở terminal
Trên macOS, mở ứng dụng Terminal. Trên Linux, mở terminal của bản phân phối bạn dùng. Với người mới, chỗ hay vấp là gõ lệnh vào sai chỗ: lệnh phải gõ trong cửa sổ terminal, không phải trong trình duyệt hay file văn bản.
C.Bước 3: Chạy một lệnh cài
README đưa ra nhiều cách. Bạn chỉ chọn MỘT cách phù hợp với máy mình. Dưới đây là nguyên văn các lệnh trong 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 dễ chọn:
- Dòng
curl ... | bash(README gọi vui là "YOLO") tải script cài về và chạy luôn. Nhanh, nhưng bạn nên hiểu là nó chạy script từ Internet trên máy mình. Script này cài opencode vào thư mục$HOME/.opencode/bin. - Dòng
npm i -g @opencode/cli@latestcài toàn cục bằng npm. README ghi chú có thể thay bằng bun, pnpm hoặc yarn. - Hai dòng
brewdành cho macOS và Linux. README đề xuất dòngbrew install anomalyco/tap/opencode-v2vì luôn bản mới nhất. Dòngbrew install opencodelà bản chính thức của Homebrew nhưng cập nhật chậm hơn. pacmanvàparudành cho Arch Linux.misedùng được trên mọi hệ điều hành.nix rundành cho người dùng Nix.
Một lưu ý thật thà: tên gói trong README (ví dụ @opencode/cli, opencode-v2) và tên gói opencode trên npm có thể khác nhau tùy thời điểm. Nếu một lệnh báo không tìm thấy gói, bạn thử cách khác trong danh sách, hoặc xem trang cài đặt ở trang chủ dự án.
D.Bước 4: Hoặc tải bản desktop
Nếu bạn dùng Windows hoặc không quen terminal, hãy tải bản desktop từ trang tải về trên trang chủ dự án. README liệt kê các file:
- 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
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.
E.Bước 5: Mở opencode trong thư mục dự án
README chưa ghi rõ lệnh khởi chạy sau khi cài. Cách thường gặp với công cụ kiểu này là đi vào thư mục dự án rồi gọi tên chương trình. Bạn kiểm tra lại cách chạy chính xác ở trang tài liệu của dự án. Phần đi vào thư mục thì chắc chắn đúng:
cd ten-thu-muc-du-an-cua-banChỗ người mới hay vấp: hãy cd đúng vào thư mục chứa code bạn muốn làm việc. Agent sẽ làm việc dựa trên thư mục bạn đang đứng.
IV.Kiểm tra đã chạy được chưa
README không đưa ra lệnh kiểm tra hay màn hình mẫu. Bạn tự kiểm tra theo cách an toàn như sau:
- Với cách cài bằng script, xem thư mục
$HOME/.opencode/bincó tồn tại không, vì README nói script cài vào đó. - Mở terminal mới (đóng cái cũ rồi mở lại) và thử gọi chương trình. Nếu terminal báo không tìm thấy lệnh, nhiều khả năng đường dẫn chưa được nạp vào terminal.
- Với bản desktop, mở ứng dụng lên. Nếu giao diện hiện ra là cài thành công.
- Khi đã vào được giao diện, bấm
Tabthử. README nói phím này chuyển giữa agent build và plan. Thấy chế độ đổi là mọi thứ hoạt động.
V.Dùng vào việc thật
Bên dưới là các tình huống mình dựng dựa trên đúng những khả năng README nêu: chế độ plan, chế độ build, và @general. Câu lệnh mẫu chỉ là gợi ý cách nói, không phải cú pháp bắt buộc.
A.Tình huống 1: Nhân viên mới tiếp nhận một dự án lạ
Bạn vừa vào công ty, được giao một thư mục code mà chưa ai giải thích. Hãy mở opencode trong thư mục đó và giữ ở chế độ plan (chỉ đọc, từ chối sửa file mặc định). Bạn hỏi bằng tiếng Việt, ví dụ:
Dự án này làm gì? Các thư mục chính dùng để làm gì? Nếu muốn thêm một trang báo cáo mới thì nên bắt đầu từ file nào?Kết quả: bạn nhận được bản giải thích cấu trúc dự án mà không sợ nó đụng vào file nào. README nói rõ chế độ này lý tưởng để khám phá codebase lạ.
Cứ để nó đọc và vạch kế hoạch trước, rồi mới cho phép sửa. Đó là thói quen rẻ nhất để không phải hối hận.
Ông T
B.Tình huống 2: Chủ shop nhờ sửa một đoạn code nhỏ
Bạn có website bán hàng nhỏ do người khác viết, giờ muốn đổi dòng thông báo khuyến mãi. Bạn dùng plan để nhờ nó chỉ ra file nào chứa dòng chữ đó. Khi đã rõ, bấm Tab sang build và nhờ:
Đổi dòng thông báo khuyến mãi ở đầu trang thành: Miễn phí giao hàng đơn từ 300.000đKết quả: agent build, có toàn quyền phát triển, sửa file giúp bạn. Bạn nên mở file xem lại thay đổi trước khi đưa lên website thật.
C.Tình huống 3: Lập trình viên lên kế hoạch trước khi sửa lớn
Bạn cần đổi cách lưu dữ liệu trong một module. Ở chế độ plan, bạn mô tả mục tiêu và nhờ nó liệt kê các file bị ảnh hưởng và thứ tự nên làm. README cho biết ở chế độ này nó hỏi quyền trước khi chạy lệnh bash, nên bạn kiểm soát được từng lệnh. Khi kế hoạch ổn, chuyển sang build để thực hiện từng phần nhỏ.
D.Tình huống 4: Tìm kiếm nhiều bước bằng @general
Bạn cần tìm mọi chỗ trong dự án đang dùng một hàm cũ và xem nên thay bằng gì. Việc này gồm nhiều bước tìm kiếm. Bạn gọi subagent chuyên việc đó bằng cách gõ @general trong tin nhắn:
@general tìm tất cả chỗ gọi hàm tinhGia và tóm tắt mỗi chỗ dùng như thế nàoKết quả: bạn nhận được bản tổng hợp các vị trí tìm được. Tên hàm ở đây chỉ là ví dụ, bạn thay bằng tên thật trong dự án của mình.
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 lỗi rất dễ gặp với loại công cụ cài bằng dòng lệnh. Mình chỉ đề xuất cách xử lý an toàn.
A.Lệnh báo không tìm thấy gói hoặc không tìm thấy lệnh
Tên gói trong README và trên kho gói có thể lệch nhau. Hãy thử một cách cài khác trong danh sách, hoặc xem hướng dẫn cài trên trang chủ dự án. Sau khi cài, đóng terminal và mở lại để máy nạp đường dẫn mới.
B.Cài chồng lên bản cũ gây xung đột
README nhắc gỡ bản cũ hơn 0.1.x trước khi cài. Nếu bạn gặp hành vi lạ sau khi cài, kiểm tra xem máy có nhiều bản opencode cùng lúc không (ví dụ một bản cài bằng npm, một bản cài bằng brew). Giữ lại một bản và gỡ bản còn lại bằng đúng công cụ đã cài nó.
C.Chạy script cài từ Internet làm bạn lo
Dòng curl ... | bash chạy script ngay trên máy bạn. Nếu bạn chưa yên tâm, hãy chọn cách cài bằng trình quản lý gói như Homebrew hoặc npm, hoặc tải bản desktop. Đây không phải lỗi, nhưng là quyết định đáng cân nhắc.
D.Agent sửa file không như ý
Chế độ build có toàn quyền, nên đôi khi nó sửa nhiều hơn bạn muốn. Cách phòng: luôn sao lưu hoặc dùng quản lý phiên bản như git cho dự án trước khi cho phép sửa, và dùng chế độ plan để duyệt kế hoạch trước. Sau khi sửa, xem lại từng thay đổi.
E.Bản desktop gặp lỗi lạ
Bản desktop đang ở mức BETA nên có thể chưa ổn định. Nếu gặp lỗi, thử bản dòng lệnh, hoặc hỏi cộng đồng qua Discord của dự án mà README có nêu.
VII.Có nên dùng không
Điểm mạnh: mã nguồn mở theo giấy phép MIT, nên bạn xem được code và dùng tự do. Có hai chế độ build và plan tách bạch, rất hợp để làm quen an toàn. Có nhiều cách cài, kể cả bản desktop cho người ngại terminal. Cộng đồng lớn: hiện có khoảng 226.506 sao và 30.658 fork, và repo vẫn được cập nhật đều.
Giới hạn: README rất ngắn, không nói rõ cách khởi chạy, cách kết nối mô hình AI hay chi phí. Bạn bắt buộc phải đọc thêm tài liệu chính thức. Danh sách lệnh cài khá nhiều và tên gói không thống nhất, có thể làm người mới bối rối. Bản desktop còn là BETA. Cách cài trên Windows cho bản dòng lệnh chưa được README nói rõ.
Khi nên chọn cách khác: nếu bạn chỉ cần một khung chat để hỏi đáp chung chung, không làm việc trên thư mục code, thì một ứng dụng chat AI thông thường đơn giản hơn. Nếu công ty bạn có quy định chặt về việc đưa mã nguồn ra dịch vụ bên ngoài, hãy hỏi bộ phận IT trước khi dùng bất kỳ agent lập trình nào, kể cả opencode.
Nói gọn: nếu bạn muốn một agent lập trình mã nguồn mở, bắt đầu ở chế độ plan cho an toàn, thì opencode đáng để thử. Cứ cài thử trên một thư mục dự án nhỏ trước.
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 dùng tự do. Tuy nhiên README không nói về chi phí khi kết nối mô hình AI bên ngoài. Bạn xem tài liệu chính thức của dự án để biết rõ.
opencode chạy được trên Windows không?
Có bản ứng dụng desktop (BETA) cho Windows, file là opencode-desktop-win-x64.exe, tải từ trang chủ dự án. README không ghi rõ cách cài bản dòng lệnh trên Windows, bạn xem thêm trang tài liệu của dự án.
Chế độ build và plan khác nhau thế nào?
build là agent mặc định, có toàn quyền để làm việc phát triển. plan là agent chỉ đọc, mặc định từ chối sửa file và hỏi quyền trước khi chạy lệnh bash. Bạn chuyển giữa hai chế độ bằng phím Tab.
Có cần GPU hay máy mạnh không?
README không nêu yêu cầu về phần cứng hay GPU. Hiện chưa có thông tin chính thức về cấu hình tối thiểu trong tư liệu.
Dữ liệu code của tôi có an toàn không?
README không mô tả chi tiết cách xử lý dữ liệu. Repo có file SECURITY.md để bạn tham khảo chính sách bảo mật. Hãy đọc tài liệu và hỏi bộ phận IT nếu code của bạn là thông tin nhạy cảm.
@general dùng để làm gì?
Đó là một subagent dành cho các tìm kiếm phức tạp và việc nhiều bước. README cho biết nó chủ yếu 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 bằng cách nào là dễ nhất?
Với người mới, tải bản desktop từ trang chủ là dễ nhất vì không cần gõ lệnh. Nếu quen terminal, README đưa ra nhiều lựa chọn như script một dòng, npm, Homebrew. README đề xuất Homebrew (lệnh brew install anomalyco/tap/opencode-v2) cho macOS và Linux vì luôn bản mới nhất.


