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 là một agent lập trình AI mã nguồn mở (giấy phép MIT), viết chủ yếu bằng TypeScript. Nó giúp bạn khám phá, hiểu và sửa code bằng cách trò chuyện, có bản dòng lệnh và bản ứng dụng desktop (BETA). Cài đặt chỉ cần một dòng lệnh hoặc tải file cài, không khó nếu bạn đã quen mở terminal.
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 lời, nó đọc code trong dự án, đề xuất và thực hiện thay đổi, thậm chí chạy lệnh giúp bạn. Tác giả giới thiệu ngắn gọn: "The open source coding agent". Repo viết chủ yếu bằng TypeScript, dùng giấy phép MIT, nghĩa là bạn dùng miễn phí và xem được toàn bộ mã nguồn.
Vấn đề nó giải quyết rất đời thường. Bạn có một dự án code nhưng không rành, hoặc rành mà muốn làm nhanh hơn. Thay vì tự lục từng file, bạn nhờ agent đọc hộ, giải thích hộ, rồi sửa hộ. Người nên thử là lập trình viên mới, người làm kinh doanh hay văn phòng có vài đoạn script nội bộ cần chỉnh, và dev có kinh nghiệm muốn một công cụ chạy ngay trong terminal.
Điểm đáng giá nhất là hai chế độ làm việc rõ ràng. Chế độ build được toàn quyền để làm việc. Chế độ plan chỉ đọc, mặc định từ chối sửa file, nên bạn có thể yên tâm cho nó đi xem một dự án lạ mà không sợ nó làm hỏng gì. Repo hiện 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.
anomalyco/opencode
opencode là agent lập trình AI mã nguồn mở: đọc code, sửa file, chạy lệnh giúp bạn, có bản terminal và bản desktop, giấy phép MIT.
I.opencode làm được gì
Dưới đây là những gì tư liệu repo cho biết. Mình chỉ nói đúng những điều có thật, không thêm tính năng ngoài README.
A.Hai agent có sẵn, đổi bằng phím Tab
- buildagent mặc định, toàn quyền cho công việc phát triển. Dùng khi bạn đã biết mình muốn gì và để nó tự tay làm.
- 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 lại bạn trước khi chạy lệnh bash. Rất hợp khi bạn mở một dự án chưa quen hoặc muốn lên kế hoạch trước khi sửa.
Bạn đổi qua lại giữa hai agent bằng phím Tab. Lợi ích thực tế: bắt đầu bằng plan để hiểu và chốt hướng đi, rồi mới chuyển sang build để làm.
B.Subagent general cho việc phức tạp
Ngoài hai agent trên còn có subagent general, dùng cho tìm kiếm phức tạp và các tác vụ nhiều bước. README cho biết nó chủ yếu được dùng nội bộ, nhưng bạn cũng gọi được bằng cách gõ @general trong tin nhắn. Hữu ích khi câu hỏi của bạn cần lục nhiều nơi trong dự án.
C.Có bản terminal và bản desktop
Bạn dùng được qua dòng lệnh, hoặc cài ứng dụng desktop (đang ở dạng BETA) cho macOS, Windows và Linux. Ai ngại terminal có thể bắt đầu bằng bản desktop.
D.Nhiều cách cài
Repo hỗ trợ cài bằng script, npm/bun/pnpm/yarn, Homebrew, pacman và paru (Arch Linux), mise, Nix. Bạn chọn cách quen tay nhất.
E.Tài liệu nhiều ngôn ngữ
README có nhiều bản dịch, trong đó có tiếng Việt (file README.vi.md trong repo). Phần cấu hình chi tiết nằm ở trang tài liệu của dự án (opencode.ai/docs).
II.Cần chuẩn bị gì
Theo README, bạn cần:
- Hệ điều hành: macOS, Linux (cài bằng lệnh hoặc gói) hoặc Windows (có file cài
opencode-desktop-win-x64.execho bản desktop). Riêngmiseđược ghi là dùng được trên mọi hệ điều hành. - Một terminal nếu bạn dùng cách cài bằng lệnh. Trên Windows, dòng
curl ... | bashcần môi trường bash (ví dụ Git Bash). README không hướng dẫn riêng cho Windows, nên nếu thấy rối, hãy dùng bản desktop. - npm hoặc một trình quản lý gói nếu bạn chọn cách cài bằng
npm i -g. README không nêu phiên bản Node tối thiểu. - Dọn bản cũ: README ghi rõ nên gỡ các phiên bản cũ hơn 0.1.x trước khi cài.
Về tài khoản, API key hay phần cứng (GPU, RAM): README chưa nói gì. Để biết cách kết nối mô hình AI và cấu hình, bạn xem trang tài liệu tại opencode.ai/docs.
README không nói cách cấu hình khoá truy cập cho mô hình AI. Khi bạn tự điền bất kỳ khoá (API key) nào, hãy giữ kín, không dán vào chat công khai, không đưa vào file code rồi đẩy lên GitHub. Dịch vụ AI bên thứ ba có thể tính phí theo lượng dùng, hãy xem bảng giá của nhà cung cấp trước.
III.Cài đặt từng bước
- Gỡ bản cũXoá các phiên bản cũ hơn 0.1.x nếu máy bạn từng cài
- Chọn cách càiScript, npm, Homebrew, pacman, mise hoặc Nix tuỳ máy bạn
- Chạy lệnh càiMở terminal và dán đúng một lệnh ở bước chọn
- Hoặc cài bản desktopTải file cài từ trang tải về nếu không muốn dùng terminal
- Xem tài liệu cấu hìnhLàm theo opencode.ai/docs để kết nối mô hình AI
A.Gỡ bản cũ nếu có
README dặn: xoá các phiên bản cũ hơn 0.1.x trước khi cài. Nếu đây là lần đầu bạn cài, bỏ qua bước này. README không ghi cách gỡ cụ thể, nên bạn gỡ theo đúng cách bạn đã cài trước đó (ví dụ dùng chính trình quản lý gói đã cài nó).
B.Cài bằng script (cách nhanh nhất)
Mở terminal (macOS: ứng dụng Terminal; Linux: cửa sổ terminal; Windows: Git Bash) rồi dán lệnh sau. README gọi cách này là "YOLO" vì nó tải script về và chạy luôn.
curl -fsSL https://opencode.ai/v2/install | bashScript sẽ cài opencode vào thư mục $HOME/.opencode/bin. Chỗ người mới hay vấp: sau khi cài, hãy đóng và mở lại terminal để máy nhận lệnh mới. Nếu vẫn không thấy lệnh, kiểm tra thư mục $HOME/.opencode/bin có nằm trong PATH của bạn không.
C.Hoặc cài bằng trình quản lý gói
Bạn chỉ cần chạy một dòng phù hợp với máy mình. Đây là các dòng có trong README:
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:
- Có Homebrew trên macOS hoặc Linux: dùng dòng
brew install anomalyco/tap/opencode-v2, README ghi là cách được khuyên dùng và luôn mới nhất. Dòngbrew install opencodelà bản brew chính thức nhưng cập nhật chậm hơn. - Có npm: dùng dòng
npm i -g @opencode/cli@latest. Có thể thay npm bằng bun, pnpm hoặc yarn. - Dùng Arch Linux:
sudo pacman -S opencodecho bản ổn định,paru -S opencode-betacho bản mới nhất từ AUR. - Muốn một cách cho mọi hệ điều hành:
mise use -g opencode. - Dùng Nix:
nix run github:anomalyco/opencode.
Lưu ý: tên gói npm trong README là @opencode/cli. Nếu bạn thấy tên khác ở nơi khác, hãy làm theo README và trang tài liệu chính thức.
D.Hoặc cài bản desktop (BETA)
Nếu bạn không thích terminal, tải ứng dụng từ trang opencode.ai/download. Các file theo từng hệ điều hành:
- macOS chip Apple Silicon:
opencode-desktop-mac-arm64.dmg - macOS chip Intel:
opencode-desktop-mac-x64.dmg - Windows:
opencode-desktop-win-x64.exe - Linux:
.deb,.rpmhoặc.AppImage
Trên macOS có Homebrew, bạn cũng cài bản desktop bằng lệnh:
brew install --cask opencode-desktopBản desktop đang ở dạng BETA, nên có thể còn lỗi vặt.
E.Lấy cách cấu hình mô hình AI
README chưa ghi cách kết nối mô hình AI hay lệnh khởi động. Bạn xem mục tài liệu ở opencode.ai/docs để làm theo. Phần này mình không đoán mò để tránh chỉ sai lệnh.
IV.Kiểm tra đã chạy được chưa
README không có mục kiểm tra cài đặt riêng, nên mình nói theo cách an toàn:
- Với bản desktopmở ứng dụng lên. Nếu cửa sổ chính hiện ra, bạn đã cài xong.
- Với bản dòng lệnhmở terminal mới, gọi chương trình theo hướng dẫn khởi động trong tài liệu opencode.ai/docs. Nếu máy báo "command not found", nghĩa là terminal chưa nhận lệnh (xem phần lỗi bên dưới).
- Thử phím Tabkhi giao diện đã mở, bấm
Tabđể đổi giữa agentbuildvàplan. Thấy tên agent đổi là bạn đang dùng đúng bản opencode.
V.Dùng vào việc thật
Các tình huống dưới đây dựa trên khả năng README mô tả: hai agent build và plan, và subagent @general. Câu lệnh mẫu chỉ là cách mình diễn đạt yêu cầu bằng lời, không phải cú pháp riêng của công cụ.
A.Dev mới nhận một dự án lạ
Bạn vừa vào công ty và được giao một kho code chưa từng thấy. Hãy mở dự án, để ở agent plan (chỉ đọc, từ chối sửa file) và hỏi bằng lời tự nhiên:
Hãy giải thích dự án này làm gì, các thư mục chính nằm ở đâu và nên bắt đầu đọc từ file nào.Kết quả: bạn có bản tóm tắt cấu trúc dự án mà không lo agent lỡ tay sửa gì. README mô tả đúng đây là trường hợp lý tưởng của plan: khám phá code lạ và lên kế hoạch thay đổi.
Cứ để agent đọc trước, sửa sau. Hiểu xong mới cho phép nó đụng vào code.
Ông T
B.Lập kế hoạch trước khi sửa một tính năng
Giả sử bạn là chủ shop có một website bán hàng nhỏ do freelancer làm, giờ muốn thêm ô nhập mã giảm giá. Bạn vẫn ở plan và nhờ:
Tôi muốn thêm ô nhập mã giảm giá ở trang thanh toán. Hãy chỉ ra những file cần sửa và các bước làm, chưa sửa gì cả.Kết quả: một danh sách file và các bước. Bạn có thể đưa danh sách này cho freelancer, hoặc bấm Tab sang build để agent tự làm. Chỉ nên chuyển sang build khi bạn đã đọc kế hoạch và đồng ý.
C.Tìm thứ khó tìm bằng @general
Dự án có hàng trăm file và bạn cần biết hàm tính phí vận chuyển được gọi ở những đâu. Đây là việc tìm kiếm nhiều bước, đúng sở trường của subagent general. Trong tin nhắn, gõ:
@general Tìm mọi nơi trong dự án có tính phí vận chuyển và liệt kê theo file.Kết quả: danh sách các vị trí liên quan, giúp bạn khỏi phải tự tìm từng file. README cho biết @general dùng cho tìm kiếm phức tạp và tác vụ nhiều bước.
D.Nhờ agent làm việc thật với build
Nhân viên văn phòng có một script nhỏ gộp báo cáo từ nhiều file, nhưng cột ngày đang sai định dạng. Chuyển sang build và mô tả lỗi rõ ràng:
Script gộp báo cáo đang in ngày dạng tháng/ngày/năm. Hãy sửa để in ngày/tháng/năm.Kết quả: agent sửa file trong dự án giúp bạn. Vì build có toàn quyền, hãy làm trên bản sao hoặc dự án đã được lưu bằng Git để có thể quay lại nếu kết quả không như ý.
VI.Lỗi hay gặp và cách xử lý
README không có mục xử lý lỗi, nên dưới đây là những lỗi rất dễ xảy ra với loại công cụ này.
A.Gõ lệnh báo "command not found"
Thường do terminal chưa nhận lệnh mới cài. Đóng hẳn terminal, mở lại cửa sổ mới rồi thử lại. Nếu bạn cài bằng script, kiểm tra thư mục $HOME/.opencode/bin có nằm trong PATH không.
B.Cài bằng script bị lỗi trên Windows
Dòng curl ... | bash cần có bash. Trên Windows, hãy chạy trong Git Bash, hoặc đổi sang cài bản desktop với file opencode-desktop-win-x64.exe, hoặc dùng npm i -g @opencode/cli@latest nếu bạn đã có npm.
C.Lệnh npm báo thiếu quyền (permission)
Đây là lỗi thường gặp khi cài gói toàn cục. Đừng vội dùng quyền quản trị cho mọi thứ. Hãy thử cách cài khác trong README (ví dụ Homebrew, mise hoặc bản desktop), hoặc xem lại cách cấu hình npm trên máy bạn.
D.Nhầm với phiên bản cũ
README dặn xoá các bản cũ hơn 0.1.x trước khi cài. Nếu sau khi cài vẫn thấy hành vi lạ hoặc số phiên bản cũ, hãy gỡ bản cũ rồi cài lại.
E.Agent sửa nhiều hơn bạn muốn
Vì build có toàn quyền, nó có thể sửa nhiều file. Cách phòng: luôn bắt đầu bằng plan, dùng Git để lưu lại trạng thái trước khi cho build làm, và đọc kỹ thay đổi sau đó.
VII.Có nên dùng không
Điểm mạnh
- Miễn phí, mã nguồn mở, giấy phép MIT.
- Hai chế độ rõ ràng:
buildđể làm việc,planchỉ đọc để khám phá an toàn. - Có cả bản terminal và bản desktop, nhiều cách cài cho nhiều hệ điều hành.
- Cộng đồng lớn (khoảng 226.506 sao, 30.658 fork) và vẫn được cập nhật gần đây.
Giới hạn
- README ngắn, không nói cách cấu hình mô hình AI hay lệnh khởi động. Bạn phải đọc thêm tài liệu ở opencode.ai/docs.
- Bản desktop vẫn là BETA.
- Chi phí và quyền riêng tư phụ thuộc vào mô hình AI bạn kết nối. README chưa có thông tin về việc này, nên bạn tự kiểm tra trước khi đưa code nhạy cảm vào.
- Có vài dòng cài khác nhau trong README, bạn cần chọn đúng một cách phù hợp với máy mình.
Khi nào nên chọn cách khác: nếu bạn hoàn toàn không muốn đụng tới terminal hay cấu hình, hãy cân nhắc bản desktop trước. Nếu bạn cần một công cụ có hướng dẫn từng bước thật chi tiết ngay trong README, hãy đọc kỹ tài liệu chính thức trước khi quyết định.
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ở, dùng giấy phép MIT nên bạn dùng miễn phí. Tuy nhiên README không nói gì về chi phí của mô hình AI bạn kết nối, nên chưa có thông tin về việc đó. Bạn nên xem tài liệu và bảng giá của nhà cung cấp mô hình trước khi dùng nhiều.
opencode chạy được trên Windows không?
Có bản desktop cho Windows, file `opencode-desktop-win-x64.exe`. Dòng cài bằng script dùng `bash`, nên trên Windows bạn cần môi trường bash, hoặc dùng cách cài khác trong README như `npm i -g @opencode/cli@latest` nếu máy đã có npm.
Có cần GPU hay máy cấu hình 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 cụ thể về cấu hình tối thiểu. Bạn xem thêm tại trang tài liệu opencode.ai/docs.
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 quyền trước khi chạy lệnh bash. Bạn đổi giữa hai agent bằng phím `Tab`.
Dữ liệu và code của tôi có an toàn không?
README không nói về cách xử lý dữ liệu hay việc nó gửi code đến đâu. Chưa có thông tin cụ thể. Repo có file SECURITY.md để bạn tham khảo, và bạn nên kiểm tra kỹ mô hình AI mình kết nối trước khi đưa code nhạy cảm vào.
Tôi nên cài bằng cách nào cho dễ nhất?
Nếu quen terminal, cách nhanh nhất là dòng script `curl -fsSL https://opencode.ai/v2/install | bash`. Nếu dùng macOS hoặc Linux có Homebrew, README khuyên dùng `brew install anomalyco/tap/opencode-v2`. Nếu ngại dòng lệnh, hãy tải bản desktop (BETA) ở opencode.ai/download.
Tôi đã cài bản cũ, có cần làm gì không?
Có. README dặn xoá các phiên bản cũ hơn 0.1.x trước khi cài. README không nêu cách gỡ cụ thể, nên bạn gỡ theo đúng cách đã cài bản cũ.


