Xử lý mã lỗi Claude Code

Nguyên nhân thường gặp: Thư mục cài đặt chưa nằm trong PATH, hoặc shell hiện tại chưa nạp lại cấu hình.

Cách xử lý: Hãy mở terminal mới, hoặc thêm thư mục cài đặt Claude Code vào PATH rồi nạp lại cấu hình shell.

export PATH="$PATH:$HOME/.local/bin"
source ~/.zshrc

Nguyên nhân thường gặp: Phiên bản Node thấp hơn yêu cầu chính thức, hoặc WSL đang gọi Node phía Windows.

Cách xử lý: Hãy nâng cấp Node, hoặc dùng trình cài đặt gốc chính thức. Trên WSL, hãy xác nhận đường dẫn bằng which node / which npm để chắc chắn nó đến từ môi trường Linux.

node -v
which node
which npm

Nguyên nhân thường gặp: Thư mục npm toàn cục thuộc sở hữu của root, hoặc lần cài bằng sudo trước đó làm quyền bị rối.

Cách xử lý: Đừng cài Claude Code bằng sudo. Hãy đổi npm prefix sang một thư mục của người dùng, hoặc dùng trình cài đặt gốc.

npm config set prefix ~/.npm-global
export PATH="$HOME/.npm-global/bin:$PATH"

Nguyên nhân thường gặp: OAuth callback của trình duyệt không quay về được CLI cục bộ - thường gặp khi dùng remote SSH, devcontainer, tường lửa nghiêm ngặt hoặc callback localhost bị chặn.

Cách xử lý: Hãy xác nhận trình duyệt và CLI kết nối được với nhau trên cùng một máy. Nếu cần, hãy đăng xuất, khởi động lại Claude Code và hoàn tất xác thực lại.

/logout
# 关闭 Claude Code 后重新运行
claude

Nguyên nhân thường gặp: Proxy doanh nghiệp hoặc cổng bảo mật đang chèn một CA tự ký mà Node không tin cậy theo mặc định.

Cách xử lý: Hãy nhờ bộ phận IT cấp CA bundle của công ty và chỉ định nó qua NODE_EXTRA_CA_CERTS.

export NODE_EXTRA_CA_CERTS=/path/to/company-ca.pem

Nguyên nhân thường gặp: Biến proxy cấu hình sai, giao thức proxy không được hỗ trợ, NO_PROXY ghi đè lên tên miền đích, hoặc tường lửa doanh nghiệp đang chặn truy cập.

Cách xử lý: Claude Code dùng các biến môi trường proxy HTTP/HTTPS chuẩn; tài liệu nêu rõ proxy SOCKS không được hỗ trợ. Hãy thử lại với HTTPS_PROXY trước.

export HTTPS_PROXY=http://proxy.example.com:8080
echo $HTTPS_PROXY
echo $NO_PROXY

Nguyên nhân thường gặp: Tổ chức chưa bật Claude Code, allowlist doanh nghiệp không có lối ra hiện tại, bị hạn chế theo tài khoản/khu vực/chính sách, hoặc proxy bị từ chối.

Cách xử lý: Với tài khoản cá nhân, hãy xác nhận khu vực được hỗ trợ và trạng thái tài khoản trước; với tài khoản doanh nghiệp, hãy nhờ quản trị viên kiểm tra quyền Claude Code, SSO, IP allowlist và quy tắc tường lửa.

Nguyên nhân thường gặp: Yêu cầu quá dồn dập, số kết nối đồng thời quá cao, hoặc gói tài khoản hay tổ chức đã chạm giới hạn tốc độ.

Cách xử lý: Hãy giảm số kết nối đồng thời bên ngoài, dừng các vòng lặp thử lại và chờ giới hạn được đặt lại. Đừng bọc Claude Code bằng nhiều worker để ép tăng tốc.

Nguyên nhân thường gặp: API key đến từ một shell khác, key Console xung đột với phiên OAuth, hoặc tổ chức yêu cầu đăng nhập SSO.

Cách xử lý: Hãy kiểm tra ANTHROPIC_API_KEY có được đặt trong shell hiện tại không. Tài khoản doanh nghiệp nên làm theo quy trình đăng nhập Console/SSO mà quản trị viên yêu cầu.

echo $ANTHROPIC_API_KEY