Sửa lỗi kết nối Claude Code trên Windows (ECONNREFUSED, Bun crash)

Hai lỗi phổ biến khi cài và dùng Claude Code trên Windows là không kết nối được API (Unable to connect to API: ECONNREFUSED khi chạy prompt) và sập trình biên dịch bản native (Bun has crashed: Internal assertion failure). Cách xử lý triệt để: gỡ bản cài qua NPM đã lỗi thời, xóa cache/cấu hình cũ, rồi cài lại bằng bản Native Stable.

Tóm tắt thao tác nhanh

Mở PowerShell và chạy các lệnh sau theo thứ tự.

1. Gỡ bản cài cũ qua NPM (nếu có):

   Sao chép

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

2. Xóa các tệp cấu hình và cache bị lỗi:

   Sao chép

   Remove-Item -Path "$env:USERPROFILE\.claude" -Recurse -Force
   Remove-Item -Path "$env:USERPROFILE\.claude.json" -Force
   Remove-Item -Path ".claude" -Recurse -Force
   Remove-Item -Path ".mcp.json" -Force

3. Cài lại bằng bản Native Stable:

   Sao chép

   & ([scriptblock]::Create((irm https://claude.ai/install.ps1))) stable

Các bước thực hiện

Bước 1: Gỡ bản NPM (đã lỗi thời)

Ban đầu, nhiều người cài Claude Code qua Node.js (npm install -g @anthropic-ai/claude-code). Tài liệu của Anthropic đã cập nhật đây là bản lỗi thời (deprecated). Chạy qua Node.js trên Windows hay gây vấn đề phân giải cổng mạng nội bộ - điển hình nhất là lỗi ECONNREFUSED giữa lúc dùng prompt do mất kết nối với local server.

Gỡ bản cũ khỏi NPM:

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

Bước 2: Xóa cache và tệp cấu hình

Khi chuyển từ NPM sang bản native (biên dịch bằng lõi Bun), định dạng file cấu hình JSON/YAML cũ có thể không tương thích. Bun khi cố đọc tệp này có thể văng lỗi: panic: Internal assertion failure - Bun has crashed... yaml_parse(500).

Để tránh tàn dư lỗi từ cài đặt cũ, xóa toàn bộ cache cấu hình (lưu ý: lịch sử chat cũ ở terminal sẽ mất, công cụ trở về trạng thái mặc định ban đầu).

Với thư mục gốc của tài khoản người dùng:

Remove-Item -Path "$env:USERPROFILE\.claude" -Recurse -Force
Remove-Item -Path "$env:USERPROFILE\.claude.json" -Force

Nếu có tệp cấu hình trong thư mục dự án đang mở PowerShell:

Remove-Item -Path ".claude" -Recurse -Force
Remove-Item -Path ".mcp.json" -Force

Bước 3: Cài bản Native Stable

Bản native (file thực thi độc lập .exe) chạy nhẹ hơn và bỏ qua dependency của hệ điều hành. Để tránh bản Latest quá mới dính bug của Bun compiler trên Windows (ví dụ bản v2.1.100), tốt nhất là cài cố định vào nhánh Stable:

& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) stable

Xử lý sự cố / Lưu ý

• Xác minh lỗi do proxy: đôi khi lỗi ECONNREFUSED đến từ việc terminal trên Windows bị cài đè một HTTP agent. Kiểm tra biến môi trường proxy ẩn bằng $env:HTTP_PROXY hoặc $env:HTTPS_PROXY, và gán rỗng như $env:HTTP_PROXY="" nếu phát hiện proxy rác.
• Yêu cầu hệ thống phụ: chạy claude với bản native không cần quyền Administrator, nhưng máy phải cài Git for Windows vì Claude dùng thư viện mô phỏng Bash từ nó.