Cài đặt Claude Code — một dòng lệnh và hai điểm mắc kẹt sau đó

Cài đặt Claude Code chỉ là một lệnh, còn nơi thực sự dễ vướng nằm ở phía sau. Phần lớn bài viết về cài đặt kết thúc ở “Cài đặt hoàn tất”, nhưng tại Hàn Quốc còn hai cửa ải trước khi chạy được — quyền cài đặt toàn cục và đăng nhập và thanh toán. Bài viết này trình bày cả ba bước theo thứ tự, kèm cách xử lý khi từng bước gặp vấn đề.

Bước 1 — Cài đặt (một lệnh)

Điều kiện duy nhất là Node.js 18 trở lên. macOS, Windows (WSL) và Linux đều dùng cùng một lệnh.

# Node.js 18 이상이 필요합니다. 먼저 확인하세요.
node --version

# 설치
npm install -g @anthropic-ai/claude-code

# 확인 — 버전이 출력되면 설치 자체는 끝난 것입니다
claude --version

claude --versionNếu phiên bản này được in ra, việc cài đặt đã hoàn tất. Nếu dừng ở đây, bạn đang gặp một trong hai vấn đề ở các phần dưới.

Bước 2 — Lỗi quyền và đường dẫn

Đây là hai lỗi phổ biến nhất trong quá trình cài đặt.

Không khuyến nghị thêm EACCES vào sudo. Cài đặt sẽ thành công ngay lúc đó nhưng vấn đề tương tự sẽ lặp lại sau mỗi lần cập nhật, đồng thời chủ sở hữu thư mục toàn cục trở thành root khiến mọi thứ rắc rối hơn. Chuyển đường dẫn về thư mục home là cách gọn gàng hơn.

# npm 전역 설치에서 EACCES가 나면 sudo를 붙이지 말고
# 전역 경로를 홈 디렉터리로 옮기는 편이 안전합니다.
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global

# 셸 설정에 추가한 뒤 새 터미널을 엽니다
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc

Trên Windows, hãy cài đặt trong WSL. Các tệp dự án cũng phải nằm trong hệ thống tệp WSL để tính năng theo dõi tệp và xử lý đường dẫn hoạt động bình thường.

Bước 3 — Đăng nhập và thanh toán (điểm thực sự bị vướng tại Hàn Quốc)

Sau khi cài đặt xong, chạy claude sẽ yêu cầu đăng nhập. Đây là nơi nhiều người tại Hàn Quốc bị dừng nhất, và nguyên nhân không liên quan đến cài đặt.

• Thẻ bị chặn thanh toán quốc tế — sẽ thất bại khi thanh toán thuê bao. Cho phép thanh toán quốc tế trong ứng dụng hoặc trang web của công ty phát hành thẻ thường giải quyết được.
• KakaoPay·Toss — không được hỗ trợ khi thanh toán trên claude.ai (chỉ có trong các phương thức thanh toán cửa hàng của thuê bao trên ứng dụng di động). Nếu thử với kỳ vọng dùng phương thức thanh toán nội địa, bạn sẽ bị vướng ở bước này.
• Nếu không có thẻ có thể thanh toán quốc tế — bạn không thể sử dụng phương thức đăng ký trên web. Phương thức xác thực bằng khóa bên dưới nạp và sử dụng số dư Kunavo; khi trang thanh toán hiển thị won Hàn Quốc, KakaoPay, Naver Pay, PAYCO, Samsung Pay và thẻ nội địa (chưa bật thanh toán quốc tế) được cung cấp làm phương thức thanh toán, vì vậy bạn có thể nạp tiền mà không cần thẻ thanh toán quốc tế (Toss không được hỗ trợ).

Những gì có thể và không thể thực hiện với từng phương thức thanh toán được tổng hợp trong cách thanh toán Claude.

Khi thanh toán thuê bao bị chặn — chạy bằng key với bản cài đặt hiện có

Ngoài đăng nhập bằng thuê bao, Claude Code cũng hỗ trợ xác thực bằng API key. Khi hai biến môi trường dưới đây được đặt, chương trình chạy mà không qua màn hình đăng nhập; xóa các biến này sẽ đưa chương trình về trạng thái ban đầu. Không cần cài đặt lại.

# 구독 결제가 막혔을 때 설치한 클로드 코드를 그대로 쓰는 방법.
# 이 두 줄이 있으면 로그인 대신 키로 인증하고, 지우면 원래대로 돌아갑니다.
export ANTHROPIC_BASE_URL=https://api.kunavo.com
export ANTHROPIC_AUTH_TOKEN=sk-kn-...

# 클로드 코드의 기본 모델과 opus·sonnet 별칭은 Anthropic의 최신 모델을 따라가므로,
# Kunavo가 제공하는 모델로 고정해 404를 막습니다. sonnet 별칭은 Kunavo가 제공하지
# 않는 Sonnet 5.5를 요청하므로, 고정하지 않으면 /model sonnet, opusplan의 실행 단계,
# sonnet 서브에이전트가 404로 실패합니다. opus는 Opus 5.5로 고정하며,
# 클로드 코드 v2.1.280 이상이 필요합니다(이전 버전은 claude update).
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

claude

Theo cách này, bạn bị tính phí theo số token thực tế sử dụng thay vì phí cố định hằng tháng, nên không phát sinh chi phí trong những tháng không làm việc. Quy trình cấp khóa nằm ở cấp khóa API Claude; để biết thuê bao hay thanh toán theo mức sử dụng rẻ hơn, hãy xem giá Claude Code.

Lần chạy đầu tiên sau khi cài đặt — kiểm tra trong 3 phút

Sau khi chạy, hãy mở claude trong thư mục dự án và chạy /init một lần. Nó đọc kho mã và tạo CLAUDE.md, sau đó tự động được đọc trong mọi phiên. Cách vận hành từ đây — viết quy tắc, thiết lập quyền và lệnh tùy chỉnh — được trình bày tiếp trong cách sử dụng Claude Code.

Các lỗi xuất hiện sau khi chạy (401·429·529) có nguyên nhân hoàn toàn khác với lỗi cài đặt. Cách phân biệt được tổng hợp riêng trong tổng hợp lỗi Claude Code.

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