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 coding agent (trợ lý AI lập trình) mã nguồn mở, giấy phép MIT, viết bằng TypeScript. Nó giúp bạn khám phá, lên kế hoạch và sửa code bằng ngôn ngữ thường. Cài khá dễ: một dòng lệnh, hoặc qua npm/brew, hoặc tải app desktop bản beta.
opencode là một "coding agent" mã nguồn mở: một trợ lý AI đọc code trong dự án của bạn, trả lời câu hỏi, đề xuất và thực hiện thay đổi theo yêu cầu bằng ngôn ngữ thường. Repo do nhóm anomalyco phát triển, viết chủ yếu bằng TypeScript, giấy phép MIT, hiện có khoảng 226.506 sao và 30.658 fork trên GitHub.
Bạn nên đọc bài này nếu là lập trình viên mới, người làm văn phòng hay chủ shop đang tự dựng website, file tự động hoá, và muốn có "người phụ" biết đọc cả thư mục code thay vì phải dán từng đoạn vào khung chat. Dự án còn được cập nhật trong 3 tháng gần đây, nên không phải repo bỏ hoang.
Điểm đáng giá nhất là hai chế độ làm việc có thể đổi nhanh bằng phím Tab. Chế độ build được toàn quyền để làm việc thật. Chế độ plan chỉ đọc, mặc định từ chối sửa file, rất hợp để khám phá code lạ mà không sợ hỏng gì. Ngoài ra, opencode còn có bản app desktop (đang BETA) cho người không thích terminal.
anomalyco/opencode
opencode là coding agent mã nguồn mở: đọc code, sửa file, chạy lệnh giúp bạn, có chế độ build để làm và plan để chỉ xem.
I.opencode làm được gì
Tư liệu của repo khá ngắn, nên mình chỉ nói những gì có trong đó.
- Hai agent có sẵn, đổi bằng phím Tab.
buildlà agent mặc định, toàn quyền cho công việc phát triển.planlà agent chỉ đọc, dùng để phân tích và khám phá code. Lợi ích thực tế: bạn có một "chế độ an toàn" để hỏi han trước, rồi mới chuyển sang chế độ được làm. - Plan hỏi trước khi chạy lệnh. Ở chế độ plan, các thay đổi file bị từ chối mặc định và nó hỏi xin phép trước khi chạy lệnh bash. Người mới vì vậy đỡ lo bị sửa nhầm hay chạy nhầm.
- Subagent
general. Đây là trợ lý phụ dành cho tìm kiếm phức tạp và việc nhiều bước. Nó được dùng nội bộ, và bạn cũng có thể gọi trực tiếp bằng@generaltrong tin nhắn. - Nhiều cách cài. Có script một dòng, npm, Homebrew, Arch Linux (pacman và AUR), mise, Nix. Bạn chọn cách quen tay nhất.
- Có app desktop (BETA). Có bản cho macOS (Apple Silicon và Intel), Windows và Linux (.deb, .rpm, .AppImage).
- Mã nguồn mở, giấy phép MIT. Bạn xem được code, tự kiểm tra nó làm gì, và dùng thoải mái theo giấy phép.
Những thứ như đổi model, cấu hình chi tiết thì README không nêu, mà trỏ sang tài liệu chính thức ở trang chủ opencode.ai (mục docs).
II.Cần chuẩn bị gì
README không liệt kê yêu cầu hệ thống chi tiết. Đây là những gì tư liệu cho biết:
- Hệ điều hành: có tuỳ chọn cho macOS, Linux và Windows (qua app desktop). Cách cài bằng Homebrew ghi rõ cho macOS và Linux. mise ghi là dùng được trên mọi hệ điều hành.
- Công cụ cài đặt: tuỳ cách bạn chọn. Dùng npm thì cần có Node/npm (README ghi thêm "hoặc bun/pnpm/yarn"). Dùng Homebrew thì cần có brew. Dùng script thì cần có
curlvàbash. - 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.
- Tài khoản, API key, phần cứng: README chưa ghi gì về việc này. Một coding agent thường cần kết nối tới một model AI nào đó, nhưng cách kết nối cụ thể bạn hãy xem trong tài liệu ở trang opencode.ai/docs.
Khi dán API key hay đăng nhập dịch vụ AI nào, hãy làm theo hướng dẫn trong tài liệu chính thức. Đừng gửi key qua chat hay chụp màn hình công khai. Dịch vụ AI bên ngoài có thể tính phí theo lượng dùng, nên hãy kiểm tra bảng giá trước khi cho agent làm việc dài.
III.Cài đặt từng bước
- Chọn cách càiScript một dòng, npm, brew hoặc cách khác phù hợp máy bạn
- Chạy lệnh càiMở terminal và dán đúng một lệnh trong README
- Kiểm tra thư mục càiScript cài vào $HOME/.opencode/bin
- Hoặc tải app desktopDành cho người không thích terminal (BETA)
- Đọc tài liệu cấu hìnhXem opencode.ai/docs để kết nối model
A.Chọn cách cài phù hợp
README đưa ra khá nhiều lựa chọn. Bạn chỉ cần chọn một cách, đừng chạy tất cả. Gợi ý nhanh cho người mới:
- Đã có Node/npm: dùng dòng npm.
- Dùng macOS hoặc Linux và có Homebrew: dùng brew.
- Muốn nhanh nhất: dùng script một dòng (README gọi vui là "YOLO", nghĩa là chạy thẳng script từ mạng, bạn nên cân nhắc).
- Không thích dòng lệnh: tải app desktop (xem bước sau).
Nếu máy bạn từng cài opencode bản cũ hơn 0.1.x, hãy gỡ nó trước.
B.Chạy lệnh cài
Mở terminal (macOS/Linux: ứng dụng Terminal; Windows: PowerShell hoặc Windows Terminal). Rồi dán một trong các lệnh dưới đây, đúng như README ghi:
# 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 ngắn từng dòng:
- Dòng
curl ... | bashtải script cài đặt rồi chạy luôn. Nó tiện, nhưng vì chạy thẳng script từ mạng, bạn chỉ nên dùng khi tin nguồn. - Dòng
npm i -g @opencode/cli@latestcài toàn cục qua npm. Phần# or bun/pnpm/yarnlà ghi chú: bạn có thể dùng trình quản lý gói khác thay npm. - Hai dòng
brewđều dành cho macOS và Linux. README ghi dòng đầu (anomalyco/tap/opencode-v2) là bản khuyến nghị, luôn mới. Dòng thứ hai là bản chính thức của Homebrew, 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 runchạy thẳng từ GitHub bằng Nix.
Chỗ dễ vấp: dấu # và phần chữ phía sau chỉ là ghi chú. Khi dán lệnh, bạn có thể bỏ phần ghi chú đi cho gọn.
Một điểm mình thấy README chưa thật nhất quán: tên gói npm của repo là opencode, trong khi lệnh npm trong README lại dùng @opencode/cli. Nếu một lệnh báo lỗi, bạn hãy xem lại README và trang opencode.ai để chắc chắn lệnh nào đang đúng.
C.Biết nó được cài ở đâu
Nếu cài bằng script, README cho biết opencode được đặt tại thư mục sau:
$HOME/.opencode/binĐây là thư mục tên .opencode/bin nằm trong thư mục cá nhân của bạn (thư mục bắt đầu bằng dấu chấm thường bị ẩn). Nếu sau khi cài mà terminal không nhận lệnh, hãy kiểm tra xem thư mục này có nằm trong PATH không. README chưa hướng dẫn việc này.
D.Hoặc tải app desktop (BETA)
Từ trang opencode.ai/download, bạn tải file theo hệ điều hành:
| Nền tảng | 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 |
Trên macOS còn có thể cài bằng Homebrew:
brew install --cask opencode-desktopLưu ý đây là bản BETA, nên có thể còn lỗi vặt.
E.Đọc tài liệu để cấu hình
README chỉ nói chung: muốn biết cấu hình opencode thế nào, hãy xem tài liệu tại opencode.ai/docs. Phần agent có trang riêng tại opencode.ai/docs/agents. Việc kết nối model AI, README chưa ghi chi tiết, nên bạn đọc ở đó.
IV.Kiểm tra đã chạy được chưa
README không có mục "kiểm tra sau khi cài" hay lệnh mẫu để thử. Vì vậy mình chỉ gợi ý những cách an toàn:
- Mở một cửa sổ terminal mới (để PATH được nạp lại) và thử gọi lệnh
opencode. Tên gói npm làopencode, nhiều khả năng đây cũng là tên lệnh, nhưng README không ghi rõ nên bạn đối chiếu với tài liệu ở trang chủ. - Nếu cài bằng script, kiểm tra xem thư mục
$HOME/.opencode/binđã được tạo chưa. - Nếu dùng app desktop, mở app lên và xem có vào được giao diện không.
- Nếu chạy được, thử bấm
Tabđể đổi giữa hai agentbuildvàplan. Đó là dấu hiệu rõ nhất theo README.
V.Dùng vào việc thật
Các tình huống dưới đây bám vào những gì README mô tả: hai agent build/plan, subagent general, và việc chạy trong dự án của bạn. Câu mẫu là gợi ý của mình, bạn tự điều chỉnh cho dự án của mình.
A.Hiểu một dự án lạ trước khi đụng vào
Bạn là lập trình viên mới vào công ty, được giao một thư mục code mà không ai giải thích. Hãy mở terminal ngay trong thư mục đó, chạy opencode và chuyển sang agent plan (phím Tab). Rồi hỏi bằng tiếng thường, ví dụ:
Dự án này làm gì? Các thư mục chính có vai trò gì? Muốn thêm trang đăng nhập thì nên sửa ở đâu?Vì plan là chế độ chỉ đọc, mặc định từ chối sửa file và hỏi trước khi chạy lệnh bash, bạn yên tâm khám phá. Kết quả là một bản tóm tắt cấu trúc dự án và gợi ý nơi cần sửa, trước khi bạn viết dòng code nào.
Hỏi trước bằng chế độ chỉ đọc, đồng ý rồi mới cho phép sửa. Đó là cách dùng AI không phải hối hận.
Ông T
B.Lên kế hoạch thay đổi rồi mới làm
Bạn là chủ shop nhỏ, có website bán hàng do người khác dựng, giờ muốn đổi cách hiển thị giá. Ở chế độ plan, bạn mô tả:
Mình muốn hiển thị giá theo định dạng 1.000.000đ thay vì 1000000. Hãy chỉ ra những file cần sửa và đề xuất cách làm, chưa sửa gì.Bạn đọc kế hoạch, thấy ổn thì bấm Tab sang build và nói: "Làm theo kế hoạch trên". Kết quả là thay đổi được thực hiện theo từng bước bạn đã duyệt, thay vì để AI tự quyết hết.
C.Nhờ trợ lý phụ tìm kiếm việc nhiều bước
Dự án lớn, bạn cần tìm mọi chỗ dùng một chức năng cũ để thay thế. README cho biết subagent general phục vụ tìm kiếm phức tạp và công việc nhiều bước, và bạn gọi được bằng @general trong tin nhắn:
@general Tìm tất cả những chỗ đang gọi hàm tính phí vận chuyển và liệt kê theo file.Bạn nhận về danh sách các vị trí liên quan, rồi dùng chính danh sách đó để sửa từng chỗ ở chế độ build.
D.Làm việc không cần gõ lệnh với app desktop
Nếu bạn làm văn phòng, ngại terminal, hãy thử app desktop (BETA) tải từ trang opencode.ai/download. Bạn dùng cùng ý tưởng: hỏi để hiểu, rồi nhờ sửa. README không mô tả giao diện app chi tiết, nên bạn cứ mở lên và làm quen, đồng thời xem tài liệu nếu bí.
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 tình huống rất dễ gặp với loại công cụ cài qua dòng lệnh. Cách xử lý đều theo hướng an toàn.
1. Gõ lệnh báo "không tìm thấy lệnh" (command not found).
Thường do terminal chưa nạp lại PATH, hoặc thư mục cài chưa nằm trong PATH. Hãy đóng terminal rồi mở cửa sổ mới. Nếu cài bằng script, kiểm tra thư mục $HOME/.opencode/bin có tồn tại không. Chưa rõ thì xem tài liệu ở trang chủ.
2. Lệnh npm báo lỗi hoặc không tìm thấy gói.
Tên gói trong README có chỗ chưa thống nhất (gói npm ghi là opencode, lệnh lại dùng @opencode/cli). Hãy kiểm tra Node/npm đã cài chưa, đọc kỹ thông báo lỗi, và thử một cách cài khác như brew hoặc script. Đừng dùng sudo cho npm chỉ để "cho qua" lỗi nếu bạn chưa hiểu nó.
3. Nhầm lẫn giữa nhiều phiên bản.
README dặn gỡ các bản cũ hơn 0.1.x trước khi cài. Ngoài ra có hai công thức brew khác nhau (opencode-v2 và opencode). Chỉ giữ một cách cài, và nếu thấy lạ thì gỡ bản cũ rồi cài lại.
4. Agent không sửa được file. Có thể bạn đang ở chế độ plan, nơi mặc định từ chối sửa file. Bấm Tab để chuyển sang build khi thực sự muốn nó làm thay đổi.
5. Lo ngại khi chạy script từ mạng.
Lệnh curl ... | bash chạy thẳng script tải về. Nếu bạn không yên tâm, hãy chọn cách cài khác như npm hoặc brew, hoặc đọc kỹ nội dung script trước khi chạy. README cũng gọi cách này là "YOLO".
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) và vẫn được cập nhật.
- Có cách cài cho nhiều hệ điều hành, cộng thêm app desktop cho người ngại terminal.
- Hai chế độ build/plan giúp bạn kiểm soát: khám phá trước, sửa sau.
- Có trợ lý phụ
@generalcho việc tìm kiếm và nhiều bước.
Giới hạn cần biết:
- README ngắn, thiếu nhiều thông tin người mới cần: cách kết nối model AI, lệnh khởi chạy, cách kiểm tra sau cài. Bạn sẽ phải đọc thêm tài liệu ở opencode.ai/docs.
- App desktop còn ở bản BETA.
- README có chỗ chưa thống nhất về tên gói/lệnh cài npm, nên bạn cần đối chiếu khi cài.
- Tư liệu không nói gì về chi phí, yêu cầu phần cứng hay chính sách dữ liệu, nên mình không thể khẳng định.
Khi nào nên chọn cách khác: nếu bạn hoàn toàn không đụng tới code và chỉ cần chat hỏi đáp thông thường, một ứng dụng chat AI là đủ. Nếu công ty có quy định nghiêm về việc đưa mã nguồn cho dịch vụ bên ngoài, hãy hỏi bộ phận IT hoặc bảo mật trước khi dùng bất kỳ coding agent nào.
Tóm lại: opencode đáng thử nếu bạn muốn một trợ lý lập trình mã nguồn mở có chế độ "chỉ xem" an toàn. Hãy bắt đầu ở chế độ plan trên một dự án nhỏ, quen tay rồi mới cho nó sửa thật.
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. Tư liệu không nói gì về chi phí của các dịch vụ AI mà nó có thể kết nối tới, nên mình chưa có thông tin. Bạn xem tài liệu ở opencode.ai/docs và bảng giá của nhà cung cấp model bạn chọn.
opencode chạy được trên Windows không?
README có file app desktop cho Windows (opencode-desktop-win-x64.exe), hiện ở bản BETA. Cách cài bằng dòng lệnh thì README ghi rõ macOS, Linux và mise dùng được trên mọi hệ điều hành. README không nói thêm về Windows ở phần dòng lệnh.
Có cần GPU hay máy mạnh không?
README không nêu yêu cầu phần cứng nào, nên chưa có thông tin chính thức. Bạn xem thêm trong tài liệu ở opencode.ai/docs.
Khác nhau giữa agent build và plan là gì?
build là agent mặc định, toàn 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 giữa hai agent bằng phím Tab.
Dữ liệu và code của mình có an toàn không?
Tư liệu README không nói về cách xử lý dữ liệu. Repo có file SECURITY.md, bạn nên đọc để biết chính sách bảo mật. Với code nhạy cảm, hãy kiểm tra kỹ dịch vụ AI bạn kết nối và hỏi bộ phận IT nếu làm cho công ty.
Cài opencode bằng cách nào là dễ nhất?
Nhanh nhất là script một dòng `curl -fsSL https://opencode.ai/v2/install | bash`, hoặc dùng npm/brew nếu bạn đã quen. Người không thích terminal có thể tải app desktop (BETA) từ trang opencode.ai/download.
@general dùng để làm gì?
Đây là subagent dành cho tìm kiếm phức tạp và công việc nhiều bước. README cho biết nó được dùng nội bộ, và bạn cũng có thể gọi nó bằng @general trong tin nhắn.


