Bao quát cài đặt, khởi tạo, kết nối proxy, lỗi thường gặp và quy trình triển khai đầy đủ.

Vui lòng tham khảo tài liệu chính thức trướcdocs.claude.com

📋 Yêu cầu trước khi bắt đầu Vui lòng hoàn tất cài đặt môi trường Node.js trước, bảo đảm Node.js 18+ đã được cài đúng cách.

⚡ Bắt buộc đọc khi cài lần đầu: bỏ qua lỗi khởi tạo ban đầu

Khi dùng kênh trung chuyển, Claude Code sẽ xuất hiện lỗi sau trong lần khởi động đầu tiên:

Hình ảnh hiển thị thông báo lỗi xuất hiện khi Claude Code khởi động lần…

Welcome to Claude Code
Unable to connect to Anthropic services
Failed to connect to api.anthropic.com: ERR_BAD_REQUEST

Điều này là do Claude Code trong lần khởi động đầu tiên sẽ cố kết nối tới API chính thức để xác nhận khởi tạo, nhưng kênh trung chuyển không thể vượt qua bước này. Sau khi cài đặt xong, trước khi khởi động lần đầu, hãy dùng một trong các cách sau để bỏ qua:

Cách 1: dùng CC-Switch để bỏ qua (khuyến nghị)

Hãy tải bản cài đặt mới nhất phù hợp với macOS hoặc Windows từ trang tải CC-Switch. Mở công cụ cấu hình CC-Switch, vào Cài đặt → Chung, rồi bật tùy chọn “Bỏ qua xác nhận cài đặt Claude Code lần đầu” là được.

Hình ảnh hiển thị thẻ “General” trong trang cài đặt của công cụ cấu hình…

Cách 2: sửa tệp cấu hình thủ công

Tìm tệp ~/.claude.json trong thư mục gốc người dùng, rồi thêm trường "hasCompletedOnboarding": true ở cuối:

⚠️ Lưu ý định dạng JSON Trước khi thêm trường mới, cần thêm một dấu phẩy tiếng Anh ở cuối trường trước đó; nếu không JSON sai định dạng sẽ khiến Claude Code không thể khởi động.

{
"installMethod": "unknown",
"autoUpdates": true,
"firstStartTime": "2025-07-14T06:11:03.877Z",
"userID": "xxxx",
"projects": {
"/home/your-user": {
"allowedTools": [],
"history": [],
"mcpContextUris": [],
"mcpServers": {},
"enabledMcpjsonServers": [],
"disabledMcpjsonServers": [],
"hasTrustDialogAccepted": false,
"projectOnboardingSeenCount": 0,
"hasClaudeMdExternalIncludesApproved": false,
"hasClaudeMdExternalIncludesWarningShown": false
}
},
"hasCompletedOnboarding": true
}

Sau khi sửa và lưu, chạy lại claude là có thể sử dụng bình thường.

Nguồn tham khảo: Claude Code bỏ qua xác nhận khởi tạo

🚀 Dùng CC-Switch để cấu hình nhanh (khuyến nghị)

Nếu bạn đã cài công cụ cấu hình nhanh CC-Switch, bạn có thể dễ dàng quản lý cấu hình Claude Code qua giao diện đồ họa mà không cần tự chỉnh tệp cấu hình và biến môi trường.

Ưu điểm của CC-Switch

Giao diện trực quan, thao tác đơn giản
Chuyển nhanh giữa các cấu hình nhà cung cấp khác nhau chỉ với một cú nhấp
Tự động quản lý biến môi trường và tệp cấu hình
Hỗ trợ sao lưu và khôi phục cấu hình
Không cần khởi động lại terminal để đổi cấu hình

Các bước cấu hình

Khởi động CC-Switch và thêm cấu hình Claude Code

Hình ảnh hiển thị giao diện thêm cấu hình mới trong ứng dụng CC-Switch.…

Mở ứng dụng CC-Switch
Nhấp vào thẻ “Claude” ở phía trên
Nhấp nút màu cam “+” ở góc trên bên phải để thêm cấu hình mới

Hình ảnh hiển thị giao diện thêm cấu hình mới trong ứng dụng CC-Switch.…

Điền thông tin cấu hình nhà cung cấp

Tên nhà cung cấp: tên tùy chỉnh (ví dụ "guizhou")
API Base URL: nhập https://api.llm-token.cn
API Key: dán key token chuyên dụng của Claude mà bạn lấy từ nền tảng
Chọn model: chọn model Claude khả dụng theo nhu cầu
Nhấp nút “Lưu”

💡 Mẹo

Có thể thêm nhiều cấu hình nhà cung cấp khác nhau (ví dụ chính thức, Guishu Cloud, v.v.)
CC-Switch sẽ tự động sửa tệp cấu hình ~/.claude/settings.json
Sau khi chuyển cấu hình, chỉ cần đóng và mở lại Claude Code là có hiệu lực

Bật cấu hình và sử dụng

Tìm cấu hình gptagent vừa tạo trong danh sách cấu hình
Nhấp nút “Đang sử dụng” ở bên phải cấu hình đó (hoặc nhấp trực tiếp vào thẻ cấu hình)
Cấu hình sẽ được đánh dấu ở trạng thái “Đang sử dụng” (nhãn màu xanh lá)
Khởi động lại Claude Code để cấu hình mới có hiệu lực

Chuyển nhanh qua khay hệ thống

CC-Switch hỗ trợ chuyển cấu hình nhanh qua khay hệ thống:

Nhấp chuột phải vào biểu tượng CC-Switch trong khay hệ thống
Chọn phân loại Claude trong menu
Chọn trực tiếp cấu hình muốn chuyển sang
Cấu hình có hiệu lực ngay, không cần mở giao diện chính

⚠️ Lưu ý

Sau khi chuyển cấu hình, cần khởi động lại Claude Code thì mới có hiệu lực
Có thể kiểm tra tốc độ endpoint API trong CC-Switch để chọn cấu hình tối ưu

Cấu hình xong nhưng vẫn không chat được?

Hãy thử cách này, nếu vẫn không được thì liên hệ bộ phận hỗ trợ

Hình ảnh hiển thị giao diện CC Switch, phía trên có tiêu đề “CC Switch”…

Hình ảnh hiển thị trang cài đặt của CC Switch ở thẻ “Proxy”. Trong giao…

Hình ảnh hiển thị nội dung thẻ “Mã” trong trang cài đặt của hướng dẫn tr…

⌨️ Cấu hình thủ công bằng dòng lệnh

Nếu bạn không dùng CC-Switch, cũng có thể cấu hình Claude Code thủ công qua dòng lệnh.

🖥️ Nền tảng Windows

Yêu cầu hệ thống

Windows 10, 11

Các bước cài đặt

Cách 1: Native Install (khuyến nghị)

Dùng PowerShell:

irm https://claude.ai/install.ps1 | iex

Dùng CMD:

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Cách 2: Cài bằng NPM (không khuyến nghị)

⚠️ Không khuyến nghị dùng npm để cài Kênh npm cập nhật chậm, phiên bản được cài thường cũ hơn; nên ưu tiên cách Native ở trên.

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

Kiểm tra cài đặt:

claude --version

Cấu hình biến môi trường

Nếu dùng PowerShell:

[Environment]::SetEnvironmentVariable("ANTHROPIC_AUTH_TOKEN", "sk-xxx", "User")
[Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://api.llm-token.cn", "User")

Nếu dùng CMD:

setx ANTHROPIC_AUTH_TOKEN "sk-xxx"
setx ANTHROPIC_BASE_URL "https://api.llm-token.cn"

💡 Mẹo Hãy nhớ thay sk-xxx bằng key riêng của bạn! Sau khi cấu hình xong, hãy khởi động lại terminal để biến môi trường có hiệu lực.

Khởi động Claude

Trong terminal, chuyển vào thư mục dự án (dùng cd) hoặc ở bất kỳ thư mục nào, nhập lệnh claude là có thể khởi động để sử dụng.

🍏 Nền tảng macOS

Yêu cầu hệ thống

MacOS 10.15 (Catalina) hoặc cao hơn

Các bước cài đặt

Cách 1: Homebrew (khuyến nghị)

brew install --cask claude-code

Cách 2: Curl Script

curl -fsSL https://claude.ai/install.sh | bash

Cách 3: Cài bằng NPM (không khuyến nghị)

⚠️ Không khuyến nghị dùng npm để cài Kênh npm cập nhật chậm, phiên bản được cài thường cũ hơn; nên ưu tiên cách Native ở trên.

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

Kiểm tra cài đặt

claude -v

Trong trường hợp bình thường, đầu ra sẽ tương tự: 1.0.108 (Claude Code)

Cấu hình biến môi trường

echo 'export ANTHROPIC_AUTH_TOKEN="sk-xxx"' >> ~/.zshrc
echo 'export ANTHROPIC_BASE_URL="https://api.llm-token.cn"' >> ~/.zshrc
source ~/.zshrc

💡 Mẹo Hãy nhớ thay sk-xxx bằng key riêng của bạn!

curl -fsSL https://claude.ai/install.sh | bash

Cách 2: Cài bằng NPM (không khuyến nghị)

⚠️ Không khuyến nghị dùng npm để cài Kênh npm cập nhật chậm, phiên bản được cài thường cũ hơn; nên ưu tiên cách Native ở trên.

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

Kiểm tra cài đặt

claude -v

Cấu hình biến môi trường

Ubuntu/Debian (Bash)

echo 'export ANTHROPIC_AUTH_TOKEN="sk-xxx"' >> ~/.bashrc
echo 'export ANTHROPIC_BASE_URL="https://api.llm-token.cn"' >> ~/.bashrc
source ~/.bashrc

Fedora/CentOS (Zsh)

echo 'export ANTHROPIC_AUTH_TOKEN="sk-xxx"' >> ~/.zshrc
echo 'export ANTHROPIC_BASE_URL="https://api.llm-token.cn"' >> ~/.zshrc
source ~/.zshrc

💡 Mẹo Hãy nhớ thay sk-xxx bằng key riêng của bạn!

Xác nhận Claude Code đã được cài đúng cách
Kiểm tra biến môi trường PATH
Khởi động lại cửa sổ terminal

Kết nối thất bại?

Kiểm tra kết nối mạng
Xác nhận API Key là chính xác
Kiểm tra số dư còn đủ hay không

Your privacy choices

Hướng dẫn triển khai Claude Code

⚡ Bắt buộc đọc khi cài lần đầu: bỏ qua lỗi khởi tạo ban đầu

Cách 1: dùng CC-Switch để bỏ qua (khuyến nghị)

Cách 2: sửa tệp cấu hình thủ công

🚀 Dùng CC-Switch để cấu hình nhanh (khuyến nghị)

Ưu điểm của CC-Switch

Các bước cấu hình

Cấu hình xong nhưng vẫn không chat được?

⌨️ Cấu hình thủ công bằng dòng lệnh

🖥️ Nền tảng Windows

Yêu cầu hệ thống

Các bước cài đặt

Cấu hình biến môi trường

🍏 Nền tảng macOS

Yêu cầu hệ thống

Các bước cài đặt

Kiểm tra cài đặt

Cấu hình biến môi trường

Khởi động lại terminal và mở Claude

🐧 Nền tảng Linux

Yêu cầu hệ thống

Các bước cài đặt

Kiểm tra cài đặt

Cấu hình biến môi trường

Khởi động lại terminal và mở Claude

Các vấn đề thường gặp

Báo không tìm thấy lệnh?

Kết nối thất bại?

Các mục trên trang này