Hướng dẫn cài đặt Claude Code — lệnh macOS, Windows, kết nối bằng thuê bao hoặc khóa API sau khi cài

Để cài Claude Code chỉ cần một dòng lệnh: trên macOS, Linux và 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 (trong Command Prompt CMD thì dùng dòng install.cmd bên dưới). Sau khi cài xong, mở terminal mới, dùng claude --version để xác nhận, rồi chạy claude để bắt đầu. Lần kết nối đầu tiên có hai cách: đăng nhập bằng tài khoản Pro, Max, Team, Enterprise hoặc Console (gói miễn phí Claude.ai không bao gồm Claude Code), hoặc đặt hai biến môi trường ANTHROPIC_BASE_URL và ANTHROPIC_AUTH_TOKEN để dùng API key tính phí theo mức sử dụng, hoàn toàn không cần thuê bao.

Đã đối chiếu lệnh vào ngày 11 tháng 9, 2026, dựa trên tài liệu cài đặt chính thức của Anthropic. Trang này chỉ nói về cài đặt và kết nối lần đầu; cách sử dụng hằng ngày sau khi cài xem tại Claude Code tutorial.

Kiểm tra trước khi cài đặt

Cài đặt trên macOS

Mở “Terminal” và dán dòng này:

# macOS、Linux、WSL
curl -fsSL https://claude.ai/install.sh | bash

Đây là phương thức cài đặt native được chính thức khuyến nghị: nó cài một binary độc lập và tự động cập nhật ở chế độ nền. Điểm vào của binary là ~/.local/bin/claude; các terminal đã mở sẽ không đọc PATH mới, vì vậy hãy mở một cửa sổ mới sau khi cài. Linux và WSL dùng cùng một lệnh.

Cài đặt trên Windows

Windows có hai lệnh khác nhau; khác biệt duy nhất là bạn mở loại terminal nào. Nếu dấu nhắc là PS C:\Users\你的名字> thì đó là PowerShell; nếu không có PS mà chỉ có C:\Users\你的名字> thì đó là Command Prompt (CMD). Không cần chạy với quyền quản trị viên.

# 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.cmd

Dán sai nơi là lỗi phổ biến nhất trên Windows. Chạy dòng CMD trong PowerShell sẽ thấy The token '&&' is not a valid statement separator; chạy dòng PowerShell trong CMD sẽ thấy 'irm' is not recognized as an internal or external command. Dán curl … | bash của macOS vào PowerShell sẽ xuất hiện A parameter cannot be found that matches parameter name 'fsSL'. Cả ba trường hợp đều chỉ cần đổi sang đúng dòng lệnh.

Nên cài thêm Git for Windows: Claude Code sẽ dùng Git Bash đi kèm để chạy lệnh; nếu chưa cài, nó sẽ dùng PowerShell. Nếu đã cài nhưng không tìm thấy Git Bash, thêm CLAUDE_CODE_GIT_BASH_PATH vào khối env trong tệp cấu hình, trỏ đến đường dẫn của bash.exe.

Nếu chọn WSL, hãy chạy dòng lệnh macOS/Linux ở trên trong terminal của WSL và cũng khởi động claude bên trong WSL, không phải từ PowerShell hoặc CMD.

Cài đặt bằng trình quản lý gói

Bạn cũng có thể để trình quản lý gói hiện có quản lý việc cài đặt; đổi lại, mặc định chúng đều không tự động cập nhật, nên bạn phải định kỳ nâng cấp thủ công (ví dụ brew upgrade claude-code, winget upgrade Anthropic.ClaudeCode). Debian/Ubuntu, Fedora/RHEL và Alpine còn có các kho gói apt, dnf, apk được ký chính thức.

# Homebrew（macOS、Linux）— stable 通道
brew install --cask claude-code

# WinGet（Windows）
winget install Anthropic.ClaudeCode

# npm — 需要 Node.js 22 以上；絕對不要加 sudo
npm install -g @anthropic-ai/claude-code

Phương thức cài đặt qua npm yêu cầu Node.js 22 trở lên kể từ v2.1.198; nếu phiên bản Node.js cũ hơn, npm chỉ in cảnh báo EBADENGINE nhưng quá trình cài đặt vẫn hoàn tất. Nó cài đặt cùng một tệp thực thi như trình cài đặt native và không phụ thuộc vào Node.js khi chạy. Tuyệt đối không dùng sudo npm install -g, vì sẽ gây ra vấn đề về quyền truy cập và cũng có rủi ro bảo mật.

Xác nhận cài đặt thành công

claude --version   # 正常會印出版本號，例如 2.1.211 (Claude Code)
claude doctor      # 唯讀的安裝與設定診斷，不會開啟工作階段

Điều đáng nhớ nhất là claude doctor: nó không mở phiên làm việc, chỉ liệt kê trạng thái cài đặt, lỗi trong tệp cấu hình và cách khắc phục đề xuất; đây là cách nhanh nhất để phân biệt “hỏng cài đặt” với “hỏng cấu hình”.

Nếu xuất hiện command not found: claude hoặc 'claude' is not recognized trên Windows, nghĩa là thư mục cài đặt không nằm trong PATH. Trên macOS/Linux, trước tiên mở terminal mới rồi thử lại; nếu vẫn không được, thêm ~/.local/bin vào PATH của ~/.zshrc hoặc ~/.bashrc. Vị trí cài đặt trên Windows là %USERPROFILE%\.local\bin; dùng PowerShell để kiểm tra và thêm vào:

# 1. 檢查安裝目錄是否已在 PATH 裡
$env:PATH -split ';' | Select-String '\.local\\bin'

# 2. 沒有任何輸出的話，把它加進「使用者」PATH，然後關掉終端機重開
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

# 3. 重開後再確認一次；若有兩份安裝，這行會列出兩個路徑
where.exe claude

Kết nối lần đầu: đăng nhập thuê bao hoặc dùng khóa tính phí theo mức sử dụng

Tuyến A: Đăng nhập bằng tài khoản thuê bao

Trong thư mục dự án, chạy claude và làm theo hướng dẫn trên trình duyệt để đăng nhập bằng tài khoản Pro, Max, Team, Enterprise hoặc Console. Lưu ý một chi tiết: nếu môi trường đã có ANTHROPIC_API_KEY, Claude Code sẽ hỏi một lần bạn có muốn sử dụng khóa này hay không; nếu chọn từ chối ở lần đó, về sau nó sẽ âm thầm bỏ qua khóa và không hỏi lại, khiến bạn tưởng biến chưa được đọc. Để bật lại, vào /config rồi chọn Use custom API key.

Tuyến B: Không cần thuê bao, dùng khóa tính phí theo mức sử dụng

Claude Code hỗ trợ sẵn ANTHROPIC_BASE_URL, vì vậy trỏ đến bất kỳ endpoint nào cung cấp Anthropic Messages API đều là cấu hình được hỗ trợ chính thức, không cần plugin, proxy hay binary đã chỉnh sửa. Các bước là: đăng ký tài khoản, nạp tiền (tối thiểu $10), tạo một khóa bắt đầu bằng sk-kn- trong trang quản lý khóa (chỉ hiển thị một lần), sau đó đặt các biến bên dưới. macOS/Linux:

export ANTHROPIC_BASE_URL=https://api.kunavo.com   # 只寫到網域，不要加 /v1
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-5

Nếu muốn thử trước trong một cửa sổ PowerShell trên Windows:

# 只對這個 PowerShell 視窗有效，關掉就沒了
$env:ANTHROPIC_BASE_URL = "https://api.kunavo.com"
$env:ANTHROPIC_AUTH_TOKEN = "sk-kn-..."
$env:ANTHROPIC_MODEL = "claude-sonnet-5"
$env:ANTHROPIC_DEFAULT_OPUS_MODEL = "claude-opus-5-5"
$env:ANTHROPIC_DEFAULT_SONNET_MODEL = "claude-sonnet-5"
$env:ANTHROPIC_DEFAULT_HAIKU_MODEL = "claude-haiku-4-5"
claude

Để sử dụng lâu dài, nên ghi vào khối env trong tệp cấu hình người dùng ~/.claude/settings.json (trên Windows là %USERPROFILE%\.claude\settings.json). Viết ở đây giúp mọi terminal, tiện ích mở rộng editor và tiến trình nền đều đọc được; nếu tệp đã có cấu hình khác, chỉ cần hợp nhất env vào đó:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.kunavo.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-kn-...",
    "ANTHROPIC_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-5-5",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5"
  }
}

Mỗi trong sáu dòng này đều có một điểm nếu cấu hình sai thì bạn có thể bị mắc kẹt rất lâu:

• ANTHROPIC_BASE_URL chỉ được ghi đến domain.Claude Code sẽ tự nối /v1/messages; nếu ghi thêm /v1 sẽ thành /v1/v1/messages và trả về 404.
• Dùng ANTHROPIC_AUTH_TOKEN, không dùng ANTHROPIC_API_KEY.Hai biến này nằm trong các HTTP header khác nhau: biến trước gửi Authorization: Bearer và có hiệu lực ngay; biến sau gửi x-api-key và còn phải qua bước xác nhận một lần được nói ở trên.
• ANTHROPIC_MODEL phải ghi tên model đầy đủ và chính xác.Kunavo chỉ nhận tên khớp hoàn toàn, không tự ánh xạ tên cũ có hậu tố ngày tháng.
• ANTHROPIC_DEFAULT_OPUS_MODEL phụ trách bí danh opus. Mô hình mặc định của Claude Code và bí danh opus đều trỏ đến Opus mới nhất; nếu Kunavo chưa cung cấp mô hình đó thì sẽ trả về 404, vì vậy dòng này và ANTHROPIC_MODEL đều phải được cố định. Ở đây, bí danh opus được cố định ở Opus 5.5 (claude-opus-5-5), yêu cầu Claude Code v2.1.280 hoặc mới hơn; với phiên bản cũ, hãy chạy claude update trước.
• ANTHROPIC_DEFAULT_SONNET_MODEL quản lý bí danh sonnet. Trên Anthropic API, bí danh sonnet trỏ đến Sonnet 5.5, nhưng Kunavo không cung cấp mô hình này. Nếu không cố định mô hình, /model sonnet, giai đoạn thực thi của opusplan và các tác nhân con được cấu hình thành model: sonnet đều sẽ trả về lỗi 404, nên ở đây cũng cố định mô hình thành Claude Sonnet 5 (claude-sonnet-5).
• ANTHROPIC_DEFAULT_HAIKU_MODEL phụ trách bí danh haiku.Từ Claude Code v2.1.293, bí danh haiku trỏ đến Haiku 5.5; ở các phiên bản cũ hơn, bí danh này trỏ đến tên Haiku 4.5 có hậu tố ngày tháng. Kunavo không nhận cả hai tên này. Nếu không chỉ định cố định, /model haiku và các tác tử con được đặt dùng model: haiku (bao gồm cả claude-code-guide do Claude Code tự khởi chạy) đều sẽ trả về 404, vì vậy hãy cố định thành claude-haiku-4-5 ở đây.
• ANTHROPIC_DEFAULT_HAIKU_MODEL phụ trách các lệnh gọi nền.Phần tóm tắt và tiêu đề do Claude Code tự thực hiện đều dùng model này: Claude Haiku 4.5 có giá $0,70 / $3,50 cho mỗi 1M token, còn model chính Claude Sonnet 5 có giá $1,40 / $7,00 (bằng giá chính thức của Anthropic).

Không ghi khóa vào .claude/settings.json trong dự án — tệp đó sẽ được commit và chia sẻ cho mọi người clone dự án. Nếu dùng tiện ích mở rộng VS Code, đặt biến trong claudeCode.environmentVariables thuộc cài đặt người dùng VS Code, vì tiện ích mở rộng sẽ kiểm tra thông tin xác thực trước khi khởi động.

Xác nhận đang dùng tuyến nào

Sau khi vào Claude Code, chạy /status. Nếu thấy dòng Auth token, nghĩa là khóa đang có hiệu lực; nếu thấy Login method và liệt kê tài khoản claude.ai, nghĩa là biến chưa được đọc. Hai cơ chế này không cộng dồn: chỉ cần biến khóa còn tồn tại thì thuê bao đã đăng nhập sẽ bị tạm gác; xóa biến là quay lại thuê bao, không cần cài lại.

Khi đi qua gateway, có ba điểm khác biệt: Remote Control và nhập liệu bằng giọng nói cần danh tính claude.ai nên không thể sử dụng; kiểm tra khả dụng của /fast sẽ hỏi trực tiếp Anthropic và có thể hiển thị không khả dụng, nhưng yêu cầu thông thường không bị ảnh hưởng; các con số của /context trở thành ước tính cục bộ. Viết code, công cụ, subagent, MCP, hooks và bộ nhớ đệm prompt vẫn hoạt động bình thường. Hướng dẫn đầy đủ có tại Claude Code integration docs và Claude Code API key guide (đều bằng tiếng Anh).

Đối chiếu lỗi thường gặp

Sau khi cài đặt

Lần đầu vào dự án, hãy chạy /init để nó đọc toàn bộ dự án và tạo CLAUDE.md. Cách chuyển Opus, Sonnet, Haiku theo nhiệm vụ, chi phí thực tế của một phiên làm việc và cách dùng /clear, /compact để giảm chi phí đều có trong Claude Code tutorial.

Việc chọn tuyến nào cũng đáng được nói thẳng: người tương tác nhiều giờ mỗi ngày và có mức sử dụng lớn thường thấy thuê bao cố định hằng tháng có lợi hơn; tính phí theo mức sử dụng phù hợp với người có nhu cầu dao động lớn hoặc không muốn bị giới hạn bởi cửa sổ sử dụng 5 giờ, và tháng không làm việc sẽ có chi phí $0. Dùng Kunavo là dùng dung lượng dùng chung, không có hạn mức riêng và không có SLA hợp đồng; các đội cần những bảo đảm này nên mua trực tiếp từ Anthropic. Chi phí hằng tháng và điểm hòa vốn của hai tuyến có tại Claude Code costs.

Câu hỏi thường gặp