Cài được Claude Code và chạy được Claude Code là hai chuyện khác nhau. Đa số bài hướng dẫn chỉ lo chuyện đầu: chép cho bạn một dòng lệnh, chúc may mắn, rồi biến mất. Còn cái terminal đăng nhập xong mà treo cứng ở yêu cầu đầu tiên thì không ai nói tới. Bài này đi hết cả hai phần.
Trình tự dưới đây đúng là thứ tự tôi làm trên một máy mới hoàn toàn, dù là macOS, Linux hay Windows. Không có bước thừa, và bước cuối — cái mạng — là bước hay bị bỏ qua nhất.
Tại sao tách "cài xong" với "chạy được"
Cài xong chỉ phụ thuộc vào máy của bạn: Node đúng phiên bản chưa, lệnh gõ có sai chính tả không, quyền thư mục ổn chưa. Những thứ đó nằm gọn trong tầm tay bạn.
Chạy được thì khác. Lần chạy agent đầu tiên không phải một cú gọi API đơn lẻ — nó là một chuỗi qua lại liên tục giữa client và máy chủ. Chỉ cần một chặng trên đường truyền bị nghẽn, cả phiên trông như đông đá. Và đây là chỗ nhiều người hiểu sai: họ thấy lệnh đầu treo, kết luận "cài hỏng", rồi gỡ đi cài lại năm lần bảy lượt. Nếu nút thắt nằm ở đường mạng, gỡ cài cả trăm lần cũng vô ích.
Nhớ kỹ ranh giới này thì lúc trục trặc bạn sẽ biết nhìn đúng chỗ.
Trước khi gõ lệnh: kiểm tra môi trường
Claude Code chạy được trên cả ba hệ điều hành phổ biến. Riêng đường cài bằng npm thì cần Node.js từ phiên bản 18 trở lên. Tôi khuyên dùng thẳng Node.js 22 LTS — bản này đã được kiểm thử kỹ và ít gây bất ngờ.
Gõ node --version để xem máy đang chạy bản nào. Phần lớn lỗi cài đặt mà tôi từng gặp quy về đúng một nguyên nhân tầm thường: lệch phiên bản Node. Không có gì huyền bí cả.
Một điều nữa cần biết trước: CLI này đòi tài khoản đủ điều kiện, không nằm trong gói web miễn phí. Xác nhận tài khoản trước khi cài, kẻo đến bước đăng nhập mới phát hiện thì mất công.
npm hay trình cài đặt gốc
Có hai con đường, cả hai đều được hỗ trợ chính thức.
Trình cài đặt gốc không kéo theo phụ thuộc nào và tự lo việc cập nhật ngầm phía sau. Với một máy làm việc đơn lẻ, đây là lựa chọn nhẹ đầu nhất — cài xong gần như quên được nó đi.
Đường npm thì dùng lệnh npm install -g @anthropic-ai/claude-code. Hợp với những ai vốn đã quản lý sẵn chuỗi công cụ Node và muốn mọi thứ nằm chung một chỗ.
Dù đi đường nào, có một thứ tuyệt đối đừng làm: đừng thêm sudo vào trước lệnh npm. Gặp lỗi quyền, cách xử lý đúng là chỉnh lại bằng trình quản lý phiên bản Node (như nvm), chứ không phải cài đè bằng quyền root. Cài bằng root chỉ dời cái lỗi đi chỗ khác chứ không giải quyết được gì.
Đăng nhập và kiểm chứng từ đầu đến cuối
Khởi động CLI bằng lệnh claude rồi làm theo luồng đăng nhập nó hiện ra.
Đăng nhập xong đừng vội tin là ổn. Hãy chứng minh bản cài hoạt động trọn vẹn qua mấy bước nhỏ:
- Gõ
claude --versionđể chắc chắn tệp thực thi nằm đúng chỗ. - Trong phiên, chạy
/doctor— nó soi ra mấy lỗi cấu hình âm thầm trước khi chúng kịp gây phiền. - Ra một câu lệnh vặt, kiểu "liệt kê các tệp trong thư mục này", rồi xem nó có trả lời gọn ghẽ không.
Câu lệnh vặt đó qua lại được một vòng sạch sẽ, nghĩa là bản cài của bạn vững. Còn nếu đăng nhập thì được mà yêu cầu thật đầu tiên cứ treo, bản cài vẫn không sao đâu — vấn đề nằm ở phần kế tiếp.
Đoạn mạng mà hướng dẫn nào cũng quên
Đây là khúc mà các bài hướng dẫn cài đặt thông thường lờ đi.
CLI có thể cài hoàn hảo, đăng nhập trơn tru, mà vẫn như chết máy nếu đường tới API vừa chậm vừa rớt gói. Lý do đã nói ở trên: lần chạy agent đầu gồm nhiều lượt đi về, chỉ một chặng kẹt là cả phiên đứng hình.
Cách kiểm tra đơn giản — ping thử máy chủ API một lần. Nếu bạn ngồi cách xa và thấy độ trễ cao, thủ phạm chính là tuyến đường, không phải bản cài. Lúc này việc cần làm là đưa lưu lượng đi qua một đường truyền đã được tối ưu.
NasaCode dựng sẵn các node độ trễ thấp nhắm thẳng vào nhu cầu của lập trình viên, để một máy mới ở xa cũng hành xử y như máy ngồi sát máy chủ. Khác biệt giữa "phiên đầu treo" và "phiên đầu chạy mượt" nhiều khi chỉ nằm ở chỗ này.
Bốn cách cài, chọn cái hợp với bạn
| Cách | Phụ thuộc | Cập nhật | Hợp với ai | Lưu ý |
|---|---|---|---|---|
| Trình cài đặt gốc | Không có | Tự động chạy ngầm | Một máy, muốn khởi đầu nhanh | Mặc định nên chọn |
| npm toàn cục | Node.js 18 trở lên | Cài lại bản mới thủ công | Đã quen quản lý Node | Tuyệt đối không sudo |
| Qua trình quản lý phiên bản | nvm hoặc tương đương | Thủ công, tách biệt | Cần nhiều bản Node song song | Sạch nhất khi dính lỗi quyền |
| Bất kỳ cách trên + tuyến NasaCode | Theo cách đã chọn | Theo cách đã chọn | Mạng ở xa hoặc chập chờn | Giữ cho lần chạy đầu không treo |
Mấy thắc mắc hay gặp
Không có tài khoản trả phí thì dùng được không?
Không. Claude Code đòi một gói trả phí đủ điều kiện hoặc quyền truy cập console, và nó không nằm trong tầng web miễn phí. Kiểm tra tài khoản trước khi cài để khỏi tắc ngang ở bước đăng nhập.
npm cứ báo lỗi quyền là sao?
Gần như chắc chắn bạn đang chạy lệnh với quyền nâng cao, hoặc đang cài đè lên bản Node của hệ thống. Cài lại bằng trình quản lý phiên bản để gói toàn cục rơi vào không gian người dùng, lỗi tự hết.
Cài xong rồi mà lệnh đầu tiên treo cứng?
Bản cài ổn, kết nối thì không. Đo độ trễ tới máy chủ API trước đã. Độ trễ cao nghĩa là đường truyền của bạn đang là nút thắt, và một tuyến được tối ưu sẽ gỡ được chỗ nghẽn đó.
Người mới nên bắt đầu bằng cách nào?
Trình cài đặt gốc, ít ma sát nhất. Chỉ chuyển sang npm hay trình quản lý phiên bản khi có lý do rõ ràng — chẳng hạn cần chạy nhiều bản Node cùng lúc.
Tóm lại, một bản cài Claude Code tử tế gồm bốn việc chứ không phải một: xác nhận môi trường, cài theo cách hợp với máy mình, đăng nhập rồi kiểm chứng bằng một câu lệnh vặt, và làm cho đường tới API đủ ổn định trước khi thật sự dựa vào nó. Bỏ việc cuối, một bản cài hoàn hảo vẫn có thể đổ ở tác vụ đầu tiên.
Nếu mạng của bạn ở xa hoặc hay chập chờn, có thể tải client tại nasacode.com ngay khi cài Claude Code, để phiên đầu — và mọi phiên về sau — có được đường truyền độ trễ thấp mà nó cần.
