Khắc phục sự cố cài đặt và xác thực Claude Code (Troubleshoot Claude Code installation and authentication)

Mười vấn đề này chiếm phần lớn các phiếu hỗ trợ cài đặt và xác thực liên quan đến Claude Code. Mỗi mục bao gồm giải pháp đáng tin cậy nhất.

Trình cài đặt đã thêmClaudevào PATH của bạn, nhưng shell hiện tại của bạn vẫn chưa nhận ra nó. Mở một terminal mới, hoặc chạysource ~/.zshrc(hoặc~/.bashrc). Trên Windows, đóng và mở lại PowerShell.

Điều này thường có nghĩa là việc cài đặt đã được chạy vớisudo, hoặc thư mục npm toàn cầu của bạn thuộc sở hữu root. Đừng sử dụng sudo. Thay vào đó, hãy sử dụng trình cài đặt gốc (curl -fsSL https://claude.ai/install.sh | bash), hoặc sửa tiền tố của npm bằngnpm config set prefix ~/.npm-globalvà thêm điều đóthùngthư mục vào PATH của bạn.

Yêu cầu mã ClaudeNode 18 hoặc cao hơn. Kiểm tra phiên bản của bạn vớinode -v. Nếu nó cũ hơn, hãy cài đặt phiên bản hiện tại thông quanvm cài đặt --lts, hoặc sử dụng trình cài đặt gốc, đi kèm với runtime riêng của nó và hoàn toàn tránh được vấn đề này.

Đường dẫn Windows PATH rò rỉ vào WSL và ghi đè nvm. Thêm node Linux của bạn lên đầu PATH trong~/.bashrc:export PATH="$HOME/.nvm/versions/node/$(nvm current)/bin:$PATH"

Máy chủ tải xuống (storage.googleapis.com) có khả năng bị chặn. Trước tiên hãy cài đặt proxy của bạn vớixuất HTTPS_PROXY=http://proxy.example.com:port, sau đó chạy lại trình cài đặt. Nếu điều đó không thể, hãy hỏi nhóm IT của bạn về gói cài đặt ngoại tuyến.

Công ty của bạn chèn chứng chỉ của riêng mình. Chỉ định Node đến gói CA của công ty:export NODE_EXTRA_CA_CERTS=/path/to/company-ca.pemThêm nó vào hồ sơ shell của bạn để nó được giữ lại.

Điều này thường có nghĩa là callback localhost bị chặn, điều này phổ biến khi sử dụng SSH từ xa, trong devcontainers hoặc sau tường lửa nghiêm ngặt. Thay vào đó, hãy sử dụng quy trình thủ công: sao chép URL hiển thị trong terminal, hoàn tất đăng nhập trong bất kỳ trình duyệt nào, sau đó dán mã trả về trở lại terminal.

Có ba nguyên nhân phổ biến: khóa đã được xuất ra trong một shell khác (chạyvang vọng$ANTHROPIC_API_KEYđể kiểm tra), Claude Code vẫn chưa được thông báo để tin tưởng khóa này (nó sẽ nhắc một lần khi sử dụng lần đầu; cho đến khi bạn phê duyệt,KHÓA_API_AN_THIỆNưu tiên hơn bất kỳ phiên OAuth nào chỉ sau khi được phê duyệt), hoặc khóa là khóa Console nhưng tổ chức của bạn yêu cầu đăng nhập SSO thay vào đó.

Claude Code sử dụng các SDK nhà cung cấp tiêu chuẩn, vì vậy cách khắc phục giống như với bất kỳ công cụ CLI AWS/GCP nào. Đối với Bedrock, hãy xác nhậnaws sts get-caller-identitycông việc vàVÙNG_AWSđược đặt ở khu vực nơi mô hình của bạn được kích hoạt. Đối với Vertex, xác nhậngcloud xác thực đăng nhập ứng dụng mặc địnhđã được chạy và rằngID_DỰ_ÁN_ĐỈNH_NGƯỜIvàVÙNG_ML_ĐÁM_MÂYđược đặt.

Tài khoản của bạn tồn tại nhưng không có quyền truy cập vào mô hình mà Claude Code đang yêu cầu. Đối với các tài khoản Enterprise, hãy xác nhận rằng ghế của bạn đang hoạt động trong cài đặt quản trị của tổ chức bạn. Trên Bedrock hoặc Vertex, hãy xác nhận rằng mô hình Claude cụ thể đã được bật trong khu vực hoặc dự án đó. Như một giải pháp tạm thời, hãy chạy/mô hìnhvà chọn một mô hình mà bạn biết rằng bạn có quyền truy cập.

Chạybác sĩ Claudetừ shell thông thường của bạn (không phải từ bên trong phiên Claude). Nó in ra một báo cáo chẩn đoán mà bạn có thể đính kèm vào phiếu hỗ trợ. Để xem danh sách đầy đủ các sự cố đã biết, hãy xemhướng dẫn khắc phục sự cố.