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 là một coding agent (trợ lý lập trình AI) mã nguồn mở, giấy phép MIT, viết bằng TypeScript. Nó giúp bạn đọc, hỏi và sửa code bằng ngôn ngữ thường. Cài không khó: có script một dòng, nhiều trình quản lý gói và cả bản desktop (BETA).
OpenCode là một trợ lý lập trình AI mã nguồn mở (coding agent). Bạn nói chuyện với nó bằng ngôn ngữ thường, nó giúp bạn tìm hiểu, lên kế hoạch và sửa code trong dự án của bạn. Repo hiện có khoảng 226.506 sao và 30.658 fork, giấy phép MIT, viết chủ yếu bằng TypeScript, và vẫn được cập nhật trong 3 tháng gần đây.
Bạn nên xem qua OpenCode nếu bạn là lập trình viên mới, người làm kỹ thuật ở công ty nhỏ, hoặc người làm văn phòng hay kinh doanh có vài dự án code đơn giản (website, script xử lý file). Bạn không phải học nhiều lệnh. Cài xong, bạn mô tả việc cần làm và để agent đề xuất cách làm.
Điểm đáng giá nhất là hai chế độ làm việc tách bạch. Một chế độ được phép sửa code. Chế độ còn lại 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ó thay đổi file nào. Bài này đi từ cài đặt đến vài tình huống dùng thật, và nói rõ chỗ nào README chưa ghi.
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ì
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ó đầy đủ quyền cho công việc phát triển. Dùng khi bạn muốn nó viết hoặc sửa code thật.
- planagent 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.
Lợi ích thực tế: khi nhận một dự án chưa quen, bạn bật plan để hỏi "dự án này làm gì, file nào quan trọng" mà không sợ nó đụng vào code. Khi đã hiểu và đồng ý hướng đi, bạn mới chuyển sang build.
B.Subagent general cho việc tìm kiếm phức tạp
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ác việc nhiều bước. README cho biết 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. Nó hợp với những câu như "tìm mọi chỗ trong dự án có dùng chức năng X".
C.Nhiều cách cài, có cả bản desktop
Bạn có thể cài bằng một dòng script, bằng npm, Homebrew, pacman, paru, mise hoặc Nix. Ngoài ra còn có ứng dụng desktop (BETA) cho macOS, Windows và Linux. Người không quen terminal có thể bắt đầu từ bản desktop.
D.Mã nguồn mở, có tài liệu riêng
Repo dùng giấy phép MIT. Cách cấu hình chi tiết nằm ở trang tài liệu của dự án: opencode.ai/docs. Phần agent nằm ở opencode.ai/docs/agents.
II.Cần chuẩn bị gì
README không có mục yêu cầu hệ thống riêng. Những gì tư liệu cho biết:
- Hệ điều hànhcác lệnh trong README nhắm tới macOS và Linux (Homebrew, pacman, paru, script
curl ... | bash). Dòngmise use -g opencodeghi là dùng được trên mọi hệ điều hành. Bản desktop có file cho macOS (Apple Silicon và Intel), Windows (.exe) và Linux (.deb,.rpm,.AppImage). - Terminalnếu cài bằng dòng lệnh, bạn cần mở một cửa sổ terminal. Trên macOS là ứng dụng Terminal. Trên Windows có thể dùng PowerShell hoặc Windows Terminal.
- Phiên bản cũREADME có lời nhắc: hãy gỡ các phiên bản cũ hơn 0.1.x trước khi cài.
- Node, Python, GPU, API key, tài khoảnREADME không nói gì về các mục này. Nếu bạn cài qua
npm, máy đương nhiên cần có npm. Việc kết nối với dịch vụ AI nào, có cần key hay tài khoản không, bạn hãy xem ở tài liệu chính thức tại opencode.ai/docs.
README không nói OpenCode tính phí hay cần key như thế nào. Trước khi nhập bất kỳ API key nào, hãy đọc kỹ tài liệu chính thức. Đừng dán key vào chat hay commit key lên GitHub.
III.Cài đặt từng bước
- Chọn cách càiScript một dòng, trình quản lý gói, hoặc bản desktop
- Mở terminalChạy đúng một lệnh cài trong README
- Kiểm tra vị trí càiScript cài vào thư mục $HOME/.opencode/bin
- Vào thư mục dự áncd tới dự án bạn muốn làm việc
- Xem tài liệu cấu hìnhĐọc opencode.ai/docs để kết nối với mô hình AI
A.Chọn một cách cài (chỉ chọn một)
README liệt kê nhiều cách. Bạn chỉ cần chọn một cách hợp với máy mình. Nếu bạn đã có máy cài cũ, hãy nhớ gỡ bản cũ hơn 0.1.x trước.
B.Cách 1: script một dòng
README gọi cách này là "YOLO", nghĩa là nhanh nhưng bạn chạy một script tải từ mạng. Hãy chắc bạn tin nguồn này trước khi chạy.
curl -fsSL https://opencode.ai/v2/install | bashLệnh này tải script cài đặt rồi chạy luôn. Theo README, script cài OpenCode vào $HOME/.opencode/bin.
C.Cách 2: trình quản lý gói
Chọn đúng dòng cho hệ thống của bạn. Các dòng sau chép nguyên từ 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 # NixGhi chú chỗ dễ vấp:
- Dòng
npmcho biết bạn cũng có thể dùng bun, pnpm hoặc yarn thay cho npm. - Trên macOS/Linux, README ghi dòng
brew install anomalyco/tap/opencode-v2là khuyến nghị và luôn mới nhất. Công thứcbrew install opencodelà bản chính thức nhưng cập nhật chậm hơn. sudosẽ hỏi mật khẩu máy của bạn. Khi bạn gõ mật khẩu, màn hình thường không hiện ký tự nào. Đó là bình thường.
D.Cách 3: ứng dụng desktop (BETA)
Tải ở opencode.ai/download. Các file theo README: opencode-desktop-mac-arm64.dmg (Mac chip Apple), opencode-desktop-mac-x64.dmg (Mac Intel), opencode-desktop-win-x64.exe (Windows), và .deb, .rpm hoặc .AppImage cho Linux. Trên macOS bạn cũng có thể cài bằng Homebrew:
brew install --cask opencode-desktopE.Vào thư mục dự án
Agent làm việc trên dự án của bạn, nên hãy mở terminal ngay trong thư mục đó. Ví dụ nếu bạn lấy dự án từ GitHub:
git clone https://github.com/<tên-tài-khoản>/<tên-dự-án>.git
cd <tên-dự-án>Thay phần trong dấu <> bằng tên thật. Nếu dự án đã nằm sẵn trên máy, bạn chỉ cần cd vào đúng thư mục đó.
F.Cấu hình và khởi chạy
README chưa ghi cụ thể lệnh khởi chạy, cũng như cách thêm mô hình AI hay API key. Hãy đọc hướng dẫn ở opencode.ai/docs để làm đúng theo phiên bản bạn vừa cài. Với bản desktop, bạn chỉ cần mở ứng dụng sau khi cài.
IV.Kiểm tra đã chạy được chưa
README không đưa ra lệnh kiểm tra hay kết quả mẫu. Bạn có thể tự xác nhận theo các dấu hiệu hợp lý sau:
- Lệnh cài chạy xong mà không báo lỗi đỏ.
- Nếu cài bằng script, thư mục
$HOME/.opencode/binđã được tạo (README nói script cài vào đó). - Mở OpenCode (terminal hoặc ứng dụng desktop) và thấy giao diện làm việc xuất hiện.
- Bấm
Tabđể đổi giữa hai agent build và plan, theo đúng README.
Nếu terminal báo không tìm thấy lệnh, hãy đóng cửa sổ terminal, mở lại, rồi thử tiếp. Nếu vẫn lỗi, xem phần lỗi hay gặp bên dưới.
V.Dùng vào việc thật
Các tình huống dưới đây bám theo khả năng README mô tả: hai agent build/plan và @general. Câu mẫu là ví dụ do mình soạn để bạn dán vào ô chat.
A.Làm quen một dự án mới nhận bàn giao
Bạn là lập trình viên mới vào một công ty và được giao một dự án chưa từng thấy. Bạn mở terminal trong thư mục dự án, bật agent plan (chỉ đọc) bằng phím Tab, rồi hỏi:
Hãy giải thích cấu trúc dự án này. Thư mục nào làm gì? Nếu muốn thêm một trang mới thì nên bắt đầu từ file nào?Vì plan từ chối sửa file mặc định, bạn yên tâm là code vẫn nguyên vẹn. Kết quả là một bản mô tả dự án bằng tiếng thường để bạn đọc trước khi đụng vào code.
Hỏi trước, sửa sau: chế độ chỉ đọc giúp bạn hiểu dự án mà không phải lo làm hỏng nó.
Ông T
B.Lên kế hoạch trước khi sửa một chức năng
Bạn làm web bán hàng nhỏ và muốn thêm ô nhập mã giảm giá. Hãy để plan phân tích trước:
Mình muốn thêm ô nhập mã giảm giá ở trang thanh toán. Hãy liệt kê các file cần sửa và các bước thực hiện, chưa sửa gì cả.Bạn đọc kế hoạch, chỉnh lại nếu chưa đúng ý, rồi bấm Tab sang build và nhờ nó làm theo. Cách này tránh việc agent sửa lung tung ngay từ câu đầu tiên.
C.Tìm mọi chỗ dùng một đoạn logic
Bạn cần đổi cách tính phí ship nhưng không nhớ chỗ nào trong code có tính phí này. Gọi subagent general bằng @general:
@general Tìm tất cả những chỗ trong dự án có tính phí vận chuyển và cho mình biết mỗi chỗ nằm ở file nào.Bạn nhận được danh sách vị trí để kiểm tra. Đây đúng là loại việc "tìm kiếm phức tạp, nhiều bước" mà README nói general dùng cho.
D.Sửa lỗi nhỏ bằng agent build
Sau khi xác định một lỗi nhỏ (ví dụ hiển thị sai giá tiền), bạn ở chế độ build và mô tả triệu chứng:
Trang chi tiết sản phẩm đang hiện giá thiếu dấu phân cách hàng nghìn. Hãy tìm nguyên nhân và sửa.Bạn xem thay đổi nó đề xuất, kiểm tra lại bằng mắt, rồi mới chạy thử dự án.
VI.Lỗi hay gặp và cách xử lý
A.Gõ lệnh báo "command not found" hoặc không nhận lệnh
Thường là terminal chưa nhận đường dẫn mới sau khi cài. Hãy đóng hẳn cửa sổ terminal và mở lại. Nếu bạn cài bằng script, README nói file nằm ở $HOME/.opencode/bin, nên hãy kiểm tra thư mục này có tồn tại không. Việc thêm thư mục vào PATH, nếu cần, hãy làm theo tài liệu chính thức.
B.Cài bị lẫn bản cũ
README dặn gỡ phiên bản cũ hơn 0.1.x trước khi cài. Nếu bạn từng cài một bản rất cũ rồi cài lại mà chạy lạ, hãy gỡ bản cũ và cài lại từ đầu bằng đúng một cách.
C.Nhầm tên gói khi cài
README có vài dòng cài khác nhau: npm i -g @opencode/cli@latest, brew install opencode, brew install anomalyco/tap/opencode-v2... Đừng chạy lẫn nhiều dòng cùng lúc, dễ sinh ra nhiều bản chồng nhau. Chọn một dòng, và nếu thấy lệnh báo lỗi, hãy đối chiếu lại với trang cài đặt chính thức.
D.Agent không sửa được file
Có thể bạn đang ở chế độ plan, vốn từ chối sửa file mặc định. Bấm Tab để chuyển sang build nếu bạn thật sự muốn nó sửa code.
E.Dự án nhái tên OpenCode
README nhắc: các dự án khác dùng chữ "opencode" trong tên (như opencode-dashboard) không phải do đội OpenCode làm và không liên kết với họ. Khi tải thêm công cụ bổ sung, hãy kiểm tra kỹ nguồn gốc, nhất là khi nó yêu cầu key hoặc quyền truy cập.
VII.Có nên dùng không
Điểm mạnh
- Mã nguồn mở, giấy phép MIT, cộng đồng lớn (hiện có khoảng 226.506 sao).
- Hai chế độ build và plan giúp bạn kiểm soát mức độ "thả cho AI làm".
- Nhiều cách cài, có cả bản desktop (BETA) cho người ngại terminal.
- README có nhiều bản dịch, trong đó có tiếng Việt.
Giới hạn
- README ngắn. Cách cấu hình, kết nối mô hình AI và chi phí đều phải xem ở tài liệu chính thức.
- Bản desktop còn ở mức BETA, nên có thể chưa ổn định bằng bản dòng lệnh.
- Có vài lệnh cài khác nhau trong README, nên bạn cần cẩn thận chọn đúng cách và đối chiếu với trang chủ.
- Là agent AI, nó vẫn có thể hiểu sai yêu cầu hoặc viết code chưa đúng. Bạn luôn nên đọc lại thay đổi trước khi dùng thật.
Khi nào chọn cách khác: nếu bạn chỉ cần hỏi đáp một đoạn code ngắn thì một khung chat thông thường là đủ. Nếu bạn không muốn trao quyền sửa file cho bất kỳ agent nào, hãy giữ ở chế độ plan, hoặc chọn công cụ chỉ gợi ý code. Còn nếu bạn muốn một trợ lý làm việc trực tiếp trong dự án, có chế độ chỉ đọc để an tâm khám phá, OpenCode là một lựa chọn đá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ở với giấy phép MIT. README không nói về chi phí khi kết nối với dịch vụ AI bên ngoài. Bạn hãy xem tài liệu chính thức tại opencode.ai/docs để biết rõ.
OpenCode chạy được trên Windows không?
README có file cài desktop cho Windows là opencode-desktop-win-x64.exe (BETA). Dòng mise được ghi là dùng được trên mọi hệ điều hành. Các lệnh Homebrew và script bash trong README nhắm tới macOS và Linux.
Tôi 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. Chưa có thông tin về GPU hay RAM tối thiểu trong tư liệu.
Agent build và plan khác nhau thế nào?
Build là agent mặc định, có đầy đủ quyền cho công việc phát triển. Plan là agent 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.
@general dùng để làm gì?
Đây là subagent dành cho tìm kiếm phức tạp và các việc nhiều bước. README cho biết OpenCode dùng nó nội bộ, và bạn có thể gọi trực tiếp bằng cách gõ @general trong tin nhắn.
Script cài đặt lưu OpenCode ở đâu?
Theo README, script cài vào thư mục $HOME/.opencode/bin. Nếu cài bằng cách khác thì vị trí phụ thuộc vào trình quản lý gói bạn dùng.
Dữ liệu và mã nguồn của tôi có an toàn không?
README không có thông tin về cách xử lý dữ liệu. Repo có file SECURITY.md ở thư mục gốc, bạn nên đọc file đó và tài liệu chính thức trước khi dùng với code nhạy cảm.


