Claude Code cài đặt bằng một lệnh duy nhất trên mọi nền tảng được hỗ trợ, và toàn bộ lần chạy đầu tiên là: cài đặt, nhập claude, đăng nhập. Hướng dẫn này có lệnh chính xác cho từng hệ điều hành, những điều cần kiểm tra khi không hoạt động, và cách trỏ đến endpoint khác sau khi cài xong.
Lệnh đã được xác minh 10 tháng 10, 2026 dựa trên tài liệu thiết lập Claude Code của Anthropic.
Trước khi bắt đầu
| Yêu cầu | Được hỗ trợ |
|---|---|
| Hệ điều hành | macOS 13.0+, Windows 10 1809+ / Server 2019+, Ubuntu 20.04+, Debian 10+, Alpine Linux 3.19+ |
| Phần cứng | RAM từ 4 GB, x64 hoặc ARM64 |
| Shell | Bash, Zsh, PowerShell hoặc CMD |
| Mạng | Yêu cầu kết nối internet |
| Tài khoản | Pro, Max, Team, Enterprise hoặc Console — gói Claude.ai miễn phí không bao gồm Claude Code |
Cài đặt — trình cài đặt native
Đây là phương pháp được khuyến nghị trên mọi nền tảng. Phương pháp này cài một binary độc lập và tự cập nhật trong nền.
# macOS, Linux, WSL
curl -fsSL https://claude.ai/install.sh | bash# Windows PowerShell
irm https://claude.ai/install.ps1 | iex:: Windows CMD
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmdNếu không chắc mình đang ở shell Windows nào, hãy nhìn lời nhắc: PowerShell hiển thị PS C:\, CMD hiển thị C:\ không có PS. Chạy nhầm lệnh là lỗi cài đặt phổ biến nhất trên Windows — xem bảng khắc phục sự cố bên dưới để biết lỗi chính xác trong từng trường hợp.
Trình quản lý gói
Dùng các cách này nếu bạn muốn trình quản lý gói hiện có quản lý việc cài đặt. Đánh đổi là cập nhật: không cách nào trong số này tự cập nhật theo mặc định, không giống trình cài đặt native.
# Homebrew (macOS, Linux) — stable channel
brew install --cask claude-code
# WinGet (Windows)
winget install Anthropic.ClaudeCode
# npm — requires Node.js 22+; never with sudo
npm install -g @anthropic-ai/claude-codeHomebrew phát hành hai cask: claude-code theo dõi kênh stable (thường chậm hơn khoảng một tuần, bỏ qua các bản phát hành có hồi quy nghiêm trọng) và claude-code@latest phát hành mọi phiên bản ngay lập tức. Các kho apt, dnf và apk có chữ ký tồn tại cho Debian / Ubuntu, Fedora / RHEL và Alpine, mỗi kho đều có kênh stable và latest.
Trên npm, không bao giờ dùng sudo npm install -g — lệnh này gây ra vấn đề quyền và là rủi ro bảo mật. Gói npm cài chính xác cùng binary native như trình cài đặt độc lập, nên trong cả hai trường hợp đều không có dependency Node khi chạy.
Xác minh cài đặt
claude --version # prints e.g. "2.1.211 (Claude Code)"
claude doctor # read-only install + settings diagnostics
claude # start a session in the current projectclaude doctor là lệnh cần nhớ: lệnh này in ra tình trạng cài đặt, lỗi xác thực tệp cài đặt và các cách khắc phục được đề xuất mà không bắt đầu một phiên, khiến nó trở thành cách nhanh nhất để phân biệt cài đặt hỏng với cấu hình hỏng.
Lần chạy đầu tiên và đăng nhập
Mở terminal trong dự án bạn muốn làm việc và chạy claude. Lệnh này mở một phiên tương tác và hướng dẫn bạn đăng nhập trên trình duyệt. Claude Code yêu cầu tài khoản Pro, Max, Team, Enterprise hoặc Console.
Một hành vi cần biết trước khi khiến bạn bất ngờ: nếu ANTHROPIC_API_KEY đã được đặt trong môi trường, Claude Code sẽ nhắc bạn phê duyệt khóa đó một lần thay vì mở trình duyệt. Từ chối lời nhắc này thì khóa sẽ bị bỏ qua một cách im lặng từ đó về sau và không được hỏi lại — trông chính xác như thể biến không được đọc. Bật lại tại /config → Dùng khóa API tùy chỉnh.
Windows: native hoặc WSL
| Tùy chọn | Yêu cầu | Sandbox | Chọn khi |
|---|---|---|---|
| Windows native | Không yêu cầu gì; Git for Windows là tùy chọn | Không được hỗ trợ | Dự án và công cụ của bạn chạy native trên Windows |
| WSL 2 | Đã bật WSL 2 | Được hỗ trợ | Toolchain Linux, hoặc khi bạn muốn thực thi lệnh trong sandbox |
| WSL 1 | Đã bật WSL 1 | Không được hỗ trợ | Bạn không có WSL 2 |
Trên Windows native, cài đặt Git for Windows là tùy chọn nhưng được khuyến nghị: nó cung cấp Git Bash làm nền cho Bash tool. Nếu không có, Claude Code sẽ chạy lệnh shell thông qua PowerShell tool. Trong WSL, bạn cài đặt và khởi chạy claude bên trong terminal WSL, không phải từ PowerShell.
Khắc phục sự cố
| Triệu chứng | Nguyên nhân và cách khắc phục |
|---|---|
The token '&&' is not a valid statement separator | Bạn đã chạy lệnh CMD trong PowerShell. Hãy dùng dòng irm … | iex thay thế. |
'irm' is not recognized… | Ngược lại — bạn đã chạy lệnh PowerShell trong CMD. Hãy dùng dòng curl … install.cmd. |
syntax error near unexpected token '<', một 403 hoặc lỗi curl khác | Tệp tải xuống không trả về script — thường do proxy hoặc bộ lọc mạng giữa bạn và trình cài đặt. Hãy thử lại hoặc dùng phương pháp cài đặt bằng trình quản lý gói. |
claude: command not found sau khi cài đặt sạch | Mở terminal mới để shell nhận thư mục cài đặt, sau đó chạy claude doctor. Một bản cài đặt cũ thứ hai hoặc bí danh shell lỗi thời là nguyên nhân phổ biến khác. |
| Lỗi quyền trong quá trình cài đặt npm | Bạn đã dùng sudo, hoặc thư mục toàn cục của npm không thể ghi. Hãy sửa quyền sở hữu thư mục thay vì chạy lại với sudo; thư mục toàn cục không thể ghi cũng ngăn cập nhật tự động. |
Thiếu binary native sau npm install -g | Trình quản lý gói của bạn được cấu hình để bỏ qua các dependency tùy chọn. Binary theo nền tảng được cung cấp dưới dạng một dependency như vậy, nên hãy cho phép chúng và cài đặt lại. |
| Cài đặt thất bại trên Alpine hoặc một distro musl khác | Alpine không có sẵn bash và curl. Hãy cài bash curl libgcc libstdc++ ripgrep, sau đó đặt USE_BUILTIN_RIPGREP thành "0" trong khối env của tệp cài đặt. |
| Tìm kiếm và phát hiện tệp không thành công | ripgrep thường được tích hợp sẵn. Nếu không thể chạy trên nền tảng của bạn, hãy cài đặt ripgrep hệ thống và thiết lập USE_BUILTIN_RIPGREP=0. |
| Thiếu công cụ Bash trên Windows native | Cài đặt Git for Windows. Nếu Claude Code vẫn không tìm thấy Git Bash, hãy thiết lập CLAUDE_CODE_GIT_BASH_PATH trong khối env của ~/.claude/settings.json. |
401 sau khi đã cấu hình khóa | Khóa nằm trong tiêu đề mà máy chủ không đọc — hãy chuyển đổi giữa ANTHROPIC_AUTH_TOKEN và ANTHROPIC_API_KEY. Xem chi tiết trong hướng dẫn khóa API. |
Trỏ Claude Code đến Kunavo
Sau khi chạy, Claude Code sẽ hoạt động với mọi endpoint cung cấp Anthropic Messages API — nó đọc trực tiếp ANTHROPIC_BASE_URL, nên đây là cấu hình được hỗ trợ chứ không phải giải pháp tạm thời. Không plugin, không proxy, không tệp nhị phân đã vá:
export ANTHROPIC_BASE_URL=https://api.kunavo.com
export ANTHROPIC_AUTH_TOKEN=sk-kn-...
export ANTHROPIC_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5-5
export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5Năm điều về khối đó, mỗi điều có thể khiến bạn mất một giờ nếu cấu hình sai:
ANTHROPIC_BASE_URLchỉ là origin. Claude Code tự thêm/v1/messages— thêm cả đường dẫn sẽ dẫn đến lỗi 404.- Hãy dùng
ANTHROPIC_AUTH_TOKEN, không phảiANTHROPIC_API_KEY. Chúng nằm trong các tiêu đề HTTP khác nhau. Bearer token có hiệu lực ngay lập tức, cònANTHROPIC_API_KEYcần bước phê duyệt một lần được mô tả ở trên. Kunavo đọc khóa từ cả hai tiêu đề, bao gồm cả/v1/models, nên trên Kunavo chính bước phê duyệt đó là yếu tố phân biệt chúng. - Thiết lập rõ ràng
ANTHROPIC_MODEL. Kunavo so khớp chính xác slug mô hình và không tạo bí danh cho các tên có hậu tố ngày, vì vậyclaude-sonnet-4-5-20250929trả về 404 trong khiclaude-sonnet-5hoạt động. - Hãy ghim cả
ANTHROPIC_DEFAULT_OPUS_MODELvàANTHROPIC_DEFAULT_SONNET_MODEL. Giá trị mặc định tích hợp của Claude Code và bí danhopuscủa nó đều phân giải thành Opus mới nhất; nếu Kunavo chưa cung cấp mô hình đó, yêu cầu đầu tiên sẽ trả về 404. Khối cấu hình ghimopusvào Opus 5.5 (claude-opus-5-5), yêu cầu Claude Code v2.1.280 trở lên — hãy chạyclaude updatetrên bản cài đặt cũ. Bí danhsonnetyêu cầu Sonnet 5.5, mô hình mà Kunavo không cung cấp, vì vậy nếu thiếu ghim sonnet/model sonnet, giai đoạn thực thi củaopusplanvà mọi tác nhân con được đặt thànhmodel: sonnetsẽ trả về 404. - Đồng thời cố định
ANTHROPIC_DEFAULT_HAIKU_MODEL. Bí danhhaikusẽ yêu cầu một model ID mà Kunavo không cung cấp (Haiku 5.5 từ v2.1.293; trước đó là ID Haiku 4.5 có hậu tố ngày tháng), vì vậy nếu thiếu dòng này,/model haikuvà các tác tử con được đặt dùngmodel: haiku, bao gồm cảclaude-code-guidetích hợp sẵn, đều sẽ trả về 404. Thiết lập này cũng chuyển các lệnh gọi chạy nền mà Claude Code tự thực hiện để tạo phần tóm tắt và tiêu đề khỏi mô hình chính:claude-haiku-4-5có giá $0,70 / $3,50 cho mỗi 1M, so với $1,40 / $7,00.
Đặt các giá trị này trong khối env của ~/.claude/settings.json thay vì xuất ra shell nếu bạn muốn trình soạn thảo và các agent chạy nền cũng nhìn thấy chúng — và tuyệt đối không đặt trong .claude/settings.json đã commit của dự án. Tạo khóa sk-kn- trong bảng điều khiển sau khi đăng ký; nạp thêm $10 là mức tối thiểu, không có phí hằng tháng và số dư không hết hạn. Chi phí của từng mô hình trên mỗi token, so với giá API chính thức của Anthropic, quyết định $10 đó dùng được bao lâu.
Điều gì thay đổi phía sau gateway
Lập trình, công cụ, subagent, MCP, hook và bộ nhớ đệm prompt đều không bị ảnh hưởng. Có ba điều thay đổi, và bạn nên biết trước khi cho rằng có gì đó bị hỏng:
- Remote Control và tính năng đọc chính tả bằng giọng nói không khả dụng. Cả hai đều cần danh tính claude.ai, thứ bị thông tin xác thực gateway thay thế.
/fastcó thể báo chế độ nhanh bị vô hiệu hóa. Việc kiểm tra tính khả dụng gọi trực tiếp đến Anthropic thay vì đi theo base URL của bạn. Các yêu cầu thông thường không bị ảnh hưởng.- Các giá trị
/contexttrở thành ước tính cục bộ. Đếm token là endpoint duy nhất được đặc tả gateway riêng của Anthropic đánh dấu là tùy chọn, và Claude Code sẽ ước tính cục bộ khi endpoint này vắng mặt — hiện Kunavo không cung cấp/v1/messages/count_tokens. Tự động nén và chính phiên làm việc không bị ảnh hưởng.
Danh sách đầy đủ, cùng quyết định dùng router hay không dùng router, nằm trong hướng dẫn router Claude Code.
Câu hỏi thường gặp
Làm cách nào để cài đặt Claude Code?
Trên macOS, Linux hoặc WSL, chạy `curl -fsSL https://claude.ai/install.sh | bash`. Trên Windows, chạy `irm https://claude.ai/install.ps1 | iex` trong PowerShell, hoặc `curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd` trong CMD. Trình cài đặt native là phương pháp được khuyến nghị và tự cập nhật trong nền. Homebrew (`brew install --cask claude-code`), WinGet (`winget install Anthropic.ClaudeCode`), npm và các kho apt/dnf/apk có chữ ký cũng được hỗ trợ, nhưng không phương pháp nào trong số đó tự cập nhật theo mặc định.
Tôi có cần Node.js để cài đặt Claude Code không?
Không cần với trình cài đặt native, Homebrew, WinGet hoặc các kho gói Linux — tất cả đều cài một binary native không dùng Node khi chạy. Chỉ đường dẫn cài đặt npm mới liên quan đến Node, và kể từ v2.1.198, gói đó yêu cầu Node.js 22 trở lên. Ngay cả khi đó, npm chỉ kéo cùng binary native thông qua một dependency tùy chọn theo từng nền tảng.
Yêu cầu hệ thống của Claude Code là gì?
macOS 13.0+, Windows 10 1809+ hoặc Windows Server 2019+, Ubuntu 20.04+, Debian 10+ hoặc Alpine Linux 3.19+; RAM từ 4 GB trên bộ xử lý x64 hoặc ARM64; kết nối internet; và Bash, Zsh, PowerShell hoặc CMD làm shell. Bạn cũng phải ở quốc gia được Anthropic hỗ trợ.
Làm cách nào để đăng nhập Claude Code lần đầu?
Chạy `claude` trong thư mục dự án và làm theo lời nhắc trên trình duyệt. Claude Code yêu cầu tài khoản Pro, Max, Team, Enterprise hoặc Console — gói Claude.ai miễn phí không bao gồm quyền truy cập Claude Code. Nếu biến môi trường ANTHROPIC_API_KEY được đặt, Claude Code sẽ nhắc bạn phê duyệt khóa đó một lần thay vì mở trình duyệt.
Tôi có thể cài đặt Claude Code trên Windows mà không cần WSL không?
Có. Chạy trình cài đặt PowerShell hoặc CMD và khởi chạy `claude` từ bất kỳ terminal nào; bạn không cần quyền Administrator. Git for Windows là tùy chọn nhưng được khuyến nghị vì cung cấp Git Bash làm nền cho Bash tool — nếu không có, Claude Code sẽ chạy lệnh shell thông qua PowerShell tool. WSL 2 là lựa chọn nên dùng nếu bạn muốn các toolchain Linux hoặc thực thi lệnh trong sandbox, những thứ Windows native không hỗ trợ.
Tại sao `claude` báo không tìm thấy lệnh sau khi cài đặt?
Thư mục cài đặt chưa nằm trong PATH của shell bạn đang dùng. Trước tiên hãy mở terminal mới — trình cài đặt thêm ~/.local/bin trên macOS và Linux, còn phiên hiện tại sẽ không nhận được thay đổi đó. Chạy `claude doctor` để chẩn đoán chỉ đọc cài đặt và các tệp cài đặt của bạn. Một bản cài đặt cũ thứ hai hoặc bí danh shell còn sót lại là nguyên nhân phổ biến khác.
Làm cách nào để trỏ Claude Code đến endpoint API khác?
Đặt ANTHROPIC_BASE_URL thành origin của bất kỳ endpoint nào cung cấp Anthropic Messages API — Claude Code đọc trực tiếp giá trị này và tự thêm /v1/messages, vì vậy không cần plugin hoặc proxy. Kết hợp với ANTHROPIC_AUTH_TOKEN làm thông tin xác thực và một ANTHROPIC_MODEL cụ thể, đồng thời ghim ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL và ANTHROPIC_DEFAULT_HAIKU_MODEL vào các mô hình mà endpoint cung cấp, vì nếu không, các bí danh opus và sonnet sẽ sử dụng các mô hình mới nhất của Anthropic. Trên Kunavo, cách này chạy cùng các mô hình Claude với mức giá thấp hơn 30% so với giá niêm yết của Anthropic, theo hình thức trả theo mức sử dụng.
Bước tiếp theo
- Khóa API Claude Code — lấy ở đâu, đặt ở đâu và sự không khớp tiêu đề đứng sau phần lớn lỗi 401.
- Giá Claude Code — gói thuê bao so với API, mức giá từng mô hình và chi phí một tháng.
- Claude Code có miễn phí không? — phần nào miễn phí, phần nào không và ranh giới nằm ở đâu.
- Chạy mà không cần lời nhắc cấp quyền —
--dangerously-skip-permissionsthực sự loại bỏ điều gì và ba biện pháp cô lập, mỗi biện pháp mất khoảng một phút. - Claude Code so với Codex CLI — nếu bạn vẫn đang chọn một agent trên terminal.