# Hướng dẫn cài đặt Claude Code cho người mới bắt đầu > Hướng dẫn chi tiết cài đặt Claude Code trên macOS, Windows, Linux để tối ưu hóa quy trình lập trình bằng AI và tự động hóa các tác vụ trực tiếp trong terminal. Nguồn: https://camnangai.com/cong-cu/huong-dan-cai-dat-claude-code Xuất bản: 2026-07-30 Sau khi **cài đặt Claude Code**, bạn sẽ có một tác nhân lập trình (agentic coding tool) chạy thẳng trong terminal. Công cụ này đọc được toàn bộ mã nguồn, chạy lệnh CLI và tự sửa file theo yêu cầu của bạn. Nếu bạn chưa rõ nó là gì, hãy đọc [Claude Code là gì?](https://camnangai.com/cong-cu/claude-code-la-gi) trước. Các điều kiện cần thiết: - Hệ điều hành: macOS 13.0+, Windows 10 (version 1809+) hoặc Windows Server 2019+, Ubuntu 20.04+, Debian 10+, hoặc Alpine Linux 3.19+. - Phần cứng: tối thiểu 4 GB RAM; kiến trúc x64 hoặc ARM64. - Kết nối Internet. - Ứng dụng terminal (Bash, Zsh, PowerShell hoặc CMD). - Tài khoản Claude trả phí (Pro, Max, Team hoặc Enterprise) hoặc tài khoản Claude Console. Bản miễn phí không dùng được Claude Code. ![Màn hình chào của Claude Code trong terminal ngay sau khi khởi động lần đầu, hiển thị số phiên bản, mô hình đang dùng và thư mục làm việc](https://camnangai.com/articles/huong-dan-cai-dat-claude-code/01-infographic.webp) _Ảnh chụp màn hình: Claude Code 2.1.220_ ## Bước 1 — Cài đặt Claude Code lên máy của bạn Chọn một cách, bỏ qua phần còn lại. ![Bốn cách cài đặt Claude Code song song nhau — script cài trực tiếp, Homebrew hoặc WinGet, trình quản lý gói Linux, và npm — người đọc chỉ chọn một nhánh](https://camnangai.com/articles/huong-dan-cai-dat-claude-code/02-vn.webp) ### Cài đặt trực tiếp (khuyên dùng) Cách này tự cập nhật phiên bản mới ở chế độ nền và tự quản lý launcher qua symlink. **macOS / Linux / WSL:** ```bash curl -fsSL https://claude.ai/install.sh | bash ``` **Windows PowerShell:** ```powershell irm https://claude.ai/install.ps1 | iex ``` **Windows CMD:** ```batch curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd ``` Để cài bản stable thay vì bản mới nhất, thêm `-s stable` vào lệnh trên macOS/Linux: `curl -fsSL https://claude.ai/install.sh | bash -s stable`. **Lưu ý nếu bạn dùng Windows:** nếu dấu nhắc lệnh bắt đầu bằng `PS C:\`, bạn đang ở PowerShell; nếu chỉ có `C:\`, bạn đang ở CMD. Nên cài thêm [Git for Windows](https://git-scm.com/downloads/win) để Claude Code dùng được Bash tool. ### Dùng trình quản lý gói (Homebrew hoặc WinGet) Cách này không tự cập nhật — bạn phải tự chạy lệnh nâng cấp. ```bash brew install --cask claude-code ``` Cask `claude-code` đi theo kênh ổn định, thường chậm hơn khoảng một tuần và bỏ qua những bản có lỗi nặng. Nếu muốn nhận mọi bản ngay khi phát hành, dùng `claude-code@latest`. ```powershell winget install Anthropic.ClaudeCode ``` Với WinGet, thỉnh thoảng chạy `winget upgrade Anthropic.ClaudeCode` để cập nhật. ### Dùng trình quản lý gói Linux (apt, dnf, apk) Claude Code có repository chính thức được ký số cho apt, dnf và apk. Trên Debian/Ubuntu, bạn đăng ký key rồi khai báo repo tại `/etc/apt/sources.list.d/claude-code.list`, sau đó chạy `sudo apt update && sudo apt install claude-code`. Trên Fedora/RHEL, tạo file repo tại `/etc/yum.repos.d/claude-code.repo` rồi chạy `sudo dnf install claude-code`. Riêng Alpine cần cài trước các gói phụ thuộc, vì bản gốc không có sẵn `bash` và `curl`: ```sh apk add bash curl libgcc libstdc++ ripgrep ``` Sau đó mở `settings.json` và thêm biến môi trường `USE_BUILTIN_RIPGREP` để công cụ tìm kiếm chạy đúng trên môi trường musl. Lưu ý biến này nằm trong khối `env`, không đặt thẳng ở cấp ngoài cùng: ```json { "env": { "USE_BUILTIN_RIPGREP": "0" } } ``` ### Dùng npm (Node.js 22 trở lên) Từ phiên bản v2.1.198, gói npm yêu cầu **Node.js 22 trở lên**. Đừng dùng `sudo` khi cài để tránh lỗi phân quyền EACCES. ```bash npm install -g @anthropic-ai/claude-code ``` ## Bước 2 — Kiểm tra Claude Code đã cài đúng chưa Kiểm tra phiên bản đã cài: ```bash claude --version ``` ![Cửa sổ terminal hiển thị kết quả của lệnh claude --version kèm số phiên bản, và kết quả chẩn đoán của lệnh claude doctor](https://camnangai.com/articles/huong-dan-cai-dat-claude-code/03.webp) _Ảnh chụp màn hình: Claude Code 2.1.220_ Nếu cài đặt thành công, lệnh in ra số phiên bản kèm tên công cụ, dạng `2.1.220 (Claude Code)`. Tiếp theo, chạy lệnh chẩn đoán: ```bash claude doctor ``` Lệnh này in ra tình trạng cài đặt, lỗi cấu hình trong file settings và các cảnh báo kèm gợi ý sửa — tất cả ở chế độ chỉ đọc, không mở phiên làm việc. ## Bước 3 — Đăng nhập vào tài khoản Claude Chạy lệnh khởi động: ```bash claude ``` Trình duyệt mặc định sẽ mở trang xác thực; làm theo hướng dẫn trên màn hình để đăng nhập. Khi terminal hiện `Login successful`, bạn đã xong bước này. ![Ba chặng của quá trình đăng nhập: terminal chạy lệnh claude, trình duyệt mở trang xác thực, rồi mã xác thực quay ngược về terminal khi trình duyệt không tự mở](https://camnangai.com/articles/huong-dan-cai-dat-claude-code/04-vn.webp) Nếu trình duyệt không tự mở — thường gặp khi bạn làm việc qua SSH, WSL2 hoặc trong container — hãy nhấn phím `c` để chép URL đăng nhập. Dán URL đó vào trình duyệt trên máy của bạn, đăng nhập, rồi dán mã trả về vào terminal tại dòng `Paste code here if prompted`. Nếu biến môi trường `ANTHROPIC_API_KEY` đang được đặt, Claude Code bỏ qua bước mở trình duyệt và hỏi bạn có duyệt dùng key đó không. ## Bước 4 — Mở phiên làm việc đầu tiên trong dự án Chuyển vào thư mục gốc của dự án: ```bash cd /path/to/your/project ``` Khởi động phiên làm việc: ```bash claude ``` Màn hình chào sẽ hiện phiên bản, mô hình đang dùng và thư mục làm việc hiện tại. Đó là dấu hiệu Claude Code đã đọc đúng thư mục dự án của bạn. ## Bước 5 — Giao việc đầu tiên cho Claude Bắt đầu bằng một câu hỏi để Claude đọc dự án trước: ```text dự án này làm gì? ``` Sau đó thử một yêu cầu chỉnh sửa thật: ```text thêm một hàm hello world vào file chính ``` Claude Code không tự ghi đè mã nguồn: nó hiện bản so sánh (diff) và chờ bạn duyệt từng thay đổi. Nhấn `Shift+Tab` để chuyển giữa các chế độ quyền — chế độ mặc định hỏi trước mỗi lần sửa, `acceptEdits` tự duyệt các sửa đổi file, còn `plan` chỉ đề xuất chứ không đụng vào file. ![Phiên làm việc Claude Code trong terminal: người dùng gõ một yêu cầu và Claude trả lời ngay trong cửa sổ dòng lệnh, kèm thanh trạng thái hiển thị mô hình và chế độ quyền](https://camnangai.com/articles/huong-dan-cai-dat-claude-code/05.webp) _Ảnh chụp màn hình: Claude Code 2.1.220_ ## Không muốn dùng terminal? Cài ứng dụng desktop Nếu bạn thích giao diện đồ họa, ứng dụng desktop chạy cùng bộ máy với bản CLI nhưng không cần terminal. Tải bản cài cho [macOS](https://claude.ai/api/desktop/darwin/universal/dmg/latest/redirect) hoặc [Windows](https://claude.com/download); trên Linux thì cài qua apt theo hướng dẫn của Anthropic. Cài xong, bạn đăng nhập bằng tài khoản Anthropic, mở tab **Code**, chọn **Local** rồi trỏ tới thư mục dự án. Bản desktop đã có sẵn Claude Code nên không cần cài Node.js hay CLI riêng; đổi lại, nếu muốn gõ `claude` trong terminal thì bạn vẫn phải cài bản CLI. ## Các lệnh cần nhớ trong phiên đầu tiên | Lệnh | Tác dụng | | :-------- | :--------------------------------------------- | | `/help` | Xem danh sách lệnh và phím tắt | | `/clear` | Xóa lịch sử hội thoại để làm sạch ngữ cảnh | | `/model` | Đổi mô hình đang dùng | | `/init` | Tạo file `CLAUDE.md` cho dự án | | `/resume` | Mở lại một phiên làm việc trước đó | | `/exit` | Thoát Claude Code (hoặc nhấn `Ctrl+D` hai lần) | Ngoài ra: `Tab` để tự động hoàn thành, phím mũi tên lên để xem lại lệnh cũ, `Esc` để ngắt khi Claude đang chạy. Danh sách đầy đủ nằm trong [cheatsheet lệnh Claude Code](https://camnangai.com/ung-dung-ai/lap-trinh-vien/cheatsheet-lenh-claude-code). ## Xử lý sự cố khi cài đặt và đăng nhập | Dòng lỗi nguyên văn | Nguyên nhân | Cách khắc phục | | :---------------------------------------------------------------------- | :--------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------- | | `command not found: claude` | Thư mục chứa binary chưa có trong `PATH`. | Thêm `export PATH="$HOME/.local/bin:$PATH"` vào `~/.zshrc` (Zsh) hoặc `~/.bashrc` (Bash), rồi mở cửa sổ terminal mới. | | `'claude' is not recognized` | Trên Windows, thư mục cài chưa nằm trong `PATH`. | Thêm `$env:USERPROFILE\.local\bin` vào `PATH` bằng PowerShell, đóng cửa sổ và mở lại. | | `syntax error near unexpected token '<'` | URL cài đặt trả về trang HTML thay vì shell script. | Chạy lại lệnh; nếu vẫn lỗi, cài bằng Homebrew. Nếu trang báo "App unavailable in region", Claude Code chưa hỗ trợ nước bạn. | | `irm is not recognized` | Bạn đang ở CMD chứ không phải PowerShell. | Mở PowerShell, hoặc dùng lệnh cài dành riêng cho CMD. | | `Could not establish trust relationship for the SSL/TLS secure channel` | Windows 10 đời cũ chưa bật TLS 1.2. | Chạy `[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12` rồi cài lại. | | `dyld: cannot load` hoặc `built for Mac OS X 13.0` | macOS của bạn cũ hơn phiên bản tối thiểu Claude Code hỗ trợ. | Kiểm tra trong About This Mac; nếu dưới 13.0 thì cập nhật macOS. | | Đăng nhập xong vẫn lỗi quyền (`400` hoặc `403`) | Biến `ANTHROPIC_API_KEY` trong môi trường đang lấn át tài khoản bạn vừa đăng nhập. | Chạy `unset ANTHROPIC_API_KEY`, rồi gõ `/status` để xem Claude Code đang dùng thông tin đăng nhập nào. | ## Bước tiếp theo Chạy lệnh `/init` để tạo file `CLAUDE.md` cho dự án. Đây là nơi bạn ghi lại quy ước đặt tên, lệnh build và lệnh test riêng của dự án để Claude đọc lại ở mọi phiên sau; hãy commit file này vào Git để cả nhóm dùng chung. Xem thêm [cách viết CLAUDE.md hiệu quả](https://camnangai.com/ung-dung-ai/lap-trinh-vien/claude-md-best-practices). ## Tài liệu tham khảo - [Terminal guide for new users - Claude Code Docs](https://code.claude.com/docs/en/terminal-guide) - [Advanced setup - Claude Code Docs](https://code.claude.com/docs/en/setup) - [Quickstart - Claude Code Docs](https://code.claude.com/docs/en/quickstart) - [Troubleshoot installation and login - Claude Code Docs](https://code.claude.com/docs/en/troubleshoot-install) - [Authentication - Claude Code Docs](https://code.claude.com/docs/en/authentication) - [Get started with the desktop app - Claude Code Docs](https://code.claude.com/docs/en/desktop-quickstart) - [How to Use Claude Code (Beginner Guide) - Builder.io](https://www.builder.io/blog/how-to-use-claude-code) - [Troubleshoot Claude Code installation and authentication - Claude Help Center](https://support.claude.com/en/articles/14552646-troubleshoot-claude-code-installation-and-authentication)