Hướng dẫn cài đặt Claude Code trên macOS

Cài đặt Claude code trên macOS và Linux rất đơn giản nếu bạn đã có Node.js. Cách nhanh nhất để cài đặt Claude code là qua npm, phương pháp này tốt hơn so với các wrapper tự chế vì các bản cập nhật sẽ gắn liền với gói chính thức thay vì một script bên thứ ba.

Kết quả

Sau khi thiết lập xong, bạn có thể khởi động Claude Code từ terminal, xác thực với Anthropic, và gán nó vào thư mục dự án. Điều này đủ để bắt đầu các prompt có nhận thức về codebase, chỉnh sửa mục tiêu, và quy trình làm việc hỗ trợ shell mà không cần thêm plugin cho editor trước.

Hướng dẫn nhanh này tập trung vào con đường ngắn nhất và đáng tin cậy. Những nhóm cần phiên bản cố định hoặc hình ảnh workstation được quản lý có thể thêm vào sau, nhưng việc cài đặt nên giữ gần với gói chính thức vì ít phần chuyển động hơn có nghĩa là ít lỗi trong quá trình onboarding hơn.

Điều kiện tiên quyết

Sử dụng một shell được hỗ trợ trên macOS hoặc Linux và cài đặt phiên bản Node.js hiện tại với npm có sẵn trong PATH. Bạn cần có tài khoản Anthropic để đăng nhập; kiểm tra trang giá chính thức để biết thông tin chi tiết về các gói Claude hiện tại.

Phần lớn các lần cài đặt thất bại đến từ cấu hình shell, không phải từ Claude Code. Nếu node, npm, hoặc các nhị phân npm toàn cầu thiếu trong PATH, gói có thể cài đặt đúng nhưng vẫn xuất hiện lỗi từ terminal.

Yêu cầu	Tại sao nó quan trọng	Cách xác minh
Node.js + npm	Đường cài đặt chính thức sử dụng npm.	node -v và npm -v
Shell macOS hoặc Linux	Claude Code được xây dựng cho việc sử dụng trong terminal.	echo $SHELL
Tài khoản Anthropic	Cần phải đăng nhập trước khi CLI có thể truy cập Claude.	Đăng nhập trên trang chính thức của Anthropic
Thư mục dự án	Chạy bên trong một repo cung cấp ngữ cảnh hữu ích cho công cụ.	pwd bên trong thư mục mục tiêu

Bước 1: Cài đặt Node.js nếu chưa có

Bỏ qua bước này nếu node -v và npm -v đã hoạt động. Node từ trình cài đặt chính thức hoặc một trình quản lý phiên bản là lựa chọn an toàn hơn vì các đường dẫn npm bị hỏng gây ra nhiều lỗi cài đặt hơn cả Claude Code.

Trên macOS, nhiều nhóm sử dụng Homebrew hoặc nvm. Trên Linux, một trình quản lý phiên bản thường sạch hơn so với các gói phân phối vì kho lưu trữ phân phối thường chậm hơn so với các bản phát hành Node hiện tại và có thể làm phân tán hành vi npm theo những cách gây nhầm lẫn cho các cài đặt CLI toàn cầu.

Xác minh quan trọng hơn phương pháp cài đặt. Nếu node -v trả về một phiên bản nhưng npm -v không thành công, hãy sửa Node trước khi chạm vào Claude Code, vì đường cài đặt chính thức Cài đặt Claude code phụ thuộc vào npm và không có lợi ích gì trong việc gỡ lỗi hai lớp bị hỏng cùng một lúc.

Bước 2: Chạy lệnh cài đặt claude code

Gói chính thức được cài đặt qua npm:

npm install -g @anthropic-ai/claude-code

Cài đặt toàn cầu là mặc định đúng cho một CLI. Cài đặt dự án cục bộ thêm ma sát đường dẫn và không giải quyết được gì trừ khi một nhóm đang cố định các phiên bản công cụ rất nghiêm ngặt cho một môi trường build đã khóa.

Đây là nơi nhiều tài liệu nội bộ trở nên quá thông minh. Các script wrapper, nhị phân sao chép và alias shell tạo ra các điểm thất bại thêm, trong khi lệnh npm trực tiếp giữ cho nguồn gốc sự thật rõ ràng và làm cho các bản cập nhật trở nên dự đoán được.

Nếu shell ném lỗi quyền trong quá trình cài đặt toàn cầu, hãy sửa tiền tố toàn cầu của npm hoặc sử dụng trình quản lý phiên bản Node thay vì ép sudo vào quy trình làm việc. Một CLI cần quyền cao hơn để cập nhật là một mặc định tồi trên các máy phát triển.

Bước 3: Xác nhận nhị phân có trên PATH

Chạy:

claude --version

Nếu shell không thể tìm thấy claude, npm có thể đã cài đặt nhị phân vào một thư mục không được xuất trên PATH. Đây là vấn đề của shell, không phải của Claude, vì vậy hãy sửa đường dẫn bin toàn cầu của npm trước khi thử cài đặt lại.

Việc cài đặt lại hiếm khi giúp nếu thư mục nhị phân không nhìn thấy được với shell. Kiểm tra tiền tố npm và cấu hình bin toàn cầu, sau đó xác nhận rằng thư mục tương ứng được tải bởi file khởi động shell hiện tại như .zshrc, .bashrc, hoặc cấu hình shell được sử dụng bởi hình ảnh workstation.

Kiểm tra với một terminal mới là cách kiểm tra tâm lý đơn giản nhất. Nếu claude --version chỉ hoạt động trong một phiên, sự thay đổi đường dẫn đã được áp dụng thủ công thay vì được lưu giữ trong cấu hình shell.

Bước 4: Xác thực và mở một dự án

Chuyển vào repo mà bạn muốn Claude Code kiểm tra, sau đó khởi động CLI:

cd /path/to/project
claude

CLI sẽ yêu cầu xác thực nếu máy chưa đăng nhập. Chạy từ repo mục tiêu thì tốt hơn là mở ở nơi khác vì nhận thức về file phụ thuộc vào thư mục làm việc hiện tại.

Đây là nơi đầu tiên mà chất lượng cài đặt gặp gỡ tính hữu ích thực tế. Một lần khởi động thành công từ thư mục sai chỉ chứng minh rằng nhị phân hoạt động, trong khi một lần khởi động bên trong repo chứng minh công cụ có thể thấy các file quan trọng.

Xác thực nên được coi là một điểm kiểm tra riêng biệt với cài đặt. Nếu claude khởi động nhưng đăng nhập thất bại, gói được cài đặt đúng và sửa chữa tiếp theo thuộc về quyền truy cập tài khoản, chính sách mạng, hoặc quy trình xác thực dựa trên trình duyệt thay vì npm.

Bước 5: Giao cho nó một nhiệm vụ giới hạn

Bắt đầu với một prompt hẹp như xem xét một module, giải thích một bài kiểm tra thất bại, hoặc đề xuất một refactor cho một file. Các nhiệm vụ nhỏ giúp phát hiện các vấn đề về quyền, truy cập repo, và chất lượng prompt nhanh hơn so với các yêu cầu rộng như “cải thiện codebase này.”

Một prompt tốt đầu tiên là: “Tóm tắt kiến trúc của repo này và xác định nơi an toàn nhất để thêm một endpoint API mới.” Điều này kiểm tra khả năng đọc repo, hiểu code, và đầu ra thực tiễn trong một lần thử.

Các prompt giới hạn thì tốt hơn vì chúng tạo ra một điều kiện thành công rõ ràng. Nếu câu trả lời sai lệch các điểm đầu vào, bỏ qua các bài kiểm tra, hoặc phát minh ra các file, nhóm sẽ ngay lập tức nhận ra rằng ngữ cảnh hoặc quyền cần được cải thiện trước khi tin tưởng vào các chỉnh sửa.

Các prompt rộng che giấu cài đặt xấu sau các đầu ra mơ hồ. Một nhiệm vụ chính xác ép CLI phải chứng minh rằng Cài đặt Claude code không chỉ hoàn tất, mà thực sự hữu ích trong repo mà các nhà phát triển dự định sử dụng nó.

Thứ đầu tiên cần thử

Yêu cầu Claude Code kiểm tra repo hiện tại và tạo ra một bản đồ ngắn về các thư mục, điểm vào, và các lệnh kiểm tra. Điều này tốt hơn so với việc yêu cầu chỉnh sửa trước vì các nhóm có thể xác minh chất lượng ngữ cảnh trước khi công cụ ghi bất kỳ điều gì.

Prompt ví dụ: “Đọc repo này và liệt kê các dịch vụ chính, lệnh dev cục bộ, và khu vực có rủi ro cao nhất để thay đổi.”

Một nhiệm vụ định hướng chỉ đọc là lần chạy đầu tiên an toàn nhất vì nó tiết lộ mức độ CLI hiểu cấu trúc, tên gọi, và quy trình làm việc của nhà phát triển. Nếu tóm tắt khớp với repo, môi trường đã sẵn sàng cho những nhiệm vụ đáng tin cậy hơn như đề xuất sửa lỗi, sửa kiểm tra, hoặc refactor.

Điều này cũng cung cấp cho các nhóm một prompt cơ bản để onboarding. Sử dụng cùng một nhiệm vụ đầu tiên trên các máy giúp dễ dàng phát hiện xem vấn đề đến từ repo, tài khoản, hay cài đặt shell của một nhà phát triển.

Các lỗi thường gặp

• Cài đặt Node nhưng không xuất thư mục bin toàn cầu của npm. Nếu claude --version không thành công sau khi cài đặt npm, hãy kiểm tra tiền tố npm và cấu hình bin toàn cầu thay vì cài đặt lại gói nhiều lần.
• Sử dụng sudo npm install -g như sửa chữa đầu tiên. Điều này có thể để lại các file thuộc quyền root trong đường dẫn gói toàn cầu và làm cho các bản cập nhật sau khó khăn hơn so với vấn đề ban đầu.
• Chạy Claude bên ngoài repo. CLI hoạt động tốt nhất với dự án là thư mục hiện tại; nếu không thì các tham chiếu file trở nên mơ hồ hoặc vô dụng.
• Bắt đầu với một nhiệm vụ lớn. “Kiểm toán toàn bộ monolith này” là một prompt đầu tiên tệ vì nó che giấu các vấn đề cài đặt phía sau các đầu ra chung chung.
• Ghi cứng chi tiết kế hoạch vào tài liệu nội bộ. Kiểm tra trang giá chính thức của Anthropic thay vào đó: https://www.anthropic.com/pricing.

Tên gói chính thức, lệnh, và tài liệu có thể thay đổi, vì vậy hãy xác minh lệnh Cài đặt Claude code hiện tại trên tài liệu của Anthropic trước khi đưa vào onboarding của nhóm. Đối với hầu hết các nhóm phát triển, npm là mặc định đúng vì nó đơn giản, có thể lập trình, và dễ kiểm tra hơn so với các wrapper tùy chỉnh hoặc nhị phân sao chép.