Khi Claude Code connection timeout hiện ra, phản xạ đầu tiên của nhiều người là nghi máy mình. Nhưng CLI vẫn chạy, API key vẫn đúng, mô hình vẫn online. Cái treo lại là một yêu cầu đơn lẻ: nó chờ, chờ thêm, rồi bỏ cuộc. Luồng HTTP bên dưới không truyền xong kịp trong cửa sổ thời gian mặc định, thế thôi.
Có một dấu hiệu rất dễ kiểm chứng: nếu cùng một lệnh chạy trơn ở quán cà phê nhưng lại timeout ở văn phòng, thì khác biệt không nằm trong câu lệnh của bạn. Nó nằm ở quãng đường mà các gói tin phải băng qua để tới được máy chủ API. Đó là tầng mà gần như mọi hướng dẫn online bỏ qua, và cũng là tầng bài này sẽ mổ xẻ.
Ba kiểu người hay dính timeout nhất
Kiểu thứ nhất, và đông nhất, là lập trình viên có lưu lượng phải đi một tuyến quốc tế dài rồi mới chạm tới API. Bạn gõ claude để nhờ nó tái cấu trúc một module lớn, con trỏ đứng im, và rồi "Request timed out" trong khi mấy câu hỏi ngắn lúc nãy vẫn trả lời ngay. Mô hình thật ra đang nói, chỉ là dòng token quay về không bò nổi qua một chặng nghẽn.
Kiểu thứ hai gặp ở mạng công ty hoặc trường học, và biểu hiện khác hẳn: "Partial response received". Câu trả lời tới được nửa chừng thì kết nối bị cắt. Thường là một proxy hay tường lửa đệm luồng dữ liệu lại, hoặc đóng phắt một kết nối mà nó tưởng đã nhàn rỗi trong lúc mô hình đang suy nghĩ.
Kiểu thứ ba ít ai để ý: chạy headless trong CI. Một agent có thể gọi công cụ hàng chục lượt liên tiếp, và chỉ cần một khứ hồi kẹt giữa chừng là cả pipeline đổ. Ba tình huống nghe rất khác nhau nhưng chung một gốc rễ — yêu cầu không bao giờ kết thúc gọn gàng, nên client đành ngắt.
Chẩn đoán: tìm cho ra tầng đang hỏng
Đây là timeout thật hay chỉ là chậm?
Phân biệt hai thứ này trước đã, vì cách xử lý ngược nhau. Claude Code để sẵn một cửa sổ khá rộng cho mỗi yêu cầu, cỡ mười phút. Nếu chạm tới giới hạn đó nghĩa là luồng không sinh ra được gì dùng được trong suốt khoảng thời gian dài như vậy, chứ không đơn thuần là mô hình trả lời chậm.
Vài lệnh kiểm tra nhanh: claude --version để chắc CLI không phải bản cũ, rồi /doctor gom phần lớn lỗi cấu hình vào một lượt. Sau đó gửi một prompt thật ngắn. Nếu yêu cầu nhỏ bật về tức thì mà tác vụ agent lớn lại treo, tuyến của bạn vẫn thông — nó chỉ không gánh nổi lưu lượng lớn kéo dài.
Đo độ trễ và mất gói
Bước này mới là cái cốt lõi. ping cho bạn thời gian khứ hồi cơ sở tới máy chủ API. traceroute hoặc mtr cho bạn thấy mất gói nhảy ra ở chặng nào.
Một vài con số đáng nhớ: lập trình tương tác chạy mượt khi khứ hồi ổn định dưới 150ms và gần như không rớt gói. Vượt 250ms mà lại kèm mất gói rải rác ở một chặng trung gian thì luồng phản hồi sẽ giật, và các lượt gọi dài bắt đầu chết. Một thứ ít người nghĩ tới: jitter nguy hiểm ngang ngửa độ trễ thuần. Một tuyến cứ nhảy qua lại giữa 80ms và 400ms làm luồng đứt thất thường, dù trung bình nhìn vẫn "đẹp".
"Partial response received" nói lên điều gì
Đừng đọc nó như một lỗi của mô hình. Nó là báo cáo từ tầng kết nối: phiên TLS đang chở câu trả lời theo dạng luồng bị cắt trước khi token cuối kịp về. Thủ phạm hay gặp là một proxy ở giữa, keep-alive bị ai đó gỡ, hoặc một chính sách đóng kết nối ngay khi thấy nó im một nhịp. Cách kiểm chứng đơn giản nhất là chạy lại đúng lệnh đó trên một mạng khác và xem nó có đi trọn không.
Lỗi ở máy, ở tuyến, hay ở nhà cung cấp?
Loại trừ theo thứ tự, từng tầng một. Mở trang trạng thái chính thức của API trước — nếu nó báo xanh thì vấn đề nằm dưới tầng ứng dụng, tức là ở mạng. Bật điểm phát sóng từ điện thoại rồi thử lại; nếu timeout biến mất, tuyến internet chính của bạn chính là chỗ cần sửa. Cả quy trình này mất chưa tới một phút mà khoanh vùng được gần hết.
Khi đã biết chắc lỗi nằm ở tuyến, NasaCode vào đúng tầng đó: thay vì để gói tin tự lần mò trên đường mặc định hay nghẽn, nó ghim lưu lượng vào một tuyến có độ trễ ổn định và tỉ lệ mất gói thấp, đủ để luồng sống tới lúc tác vụ chạy xong.
Vài cách kết nối, chúng khác nhau ở đâu
Không phải mọi cách đưa lưu lượng tới API đều ngang nhau khi nói về luồng dữ liệu dài. Bảng dưới so sánh chúng theo đúng tiêu chí mà công việc lập trình AI thực sự cần.
| Cách kết nối | Giữ luồng cho tác vụ dài | Chọn tuyến | Hỗ trợ client | Riêng tư |
|---|---|---|---|---|
| Kết nối trực tiếp mặc định | Khó đoán trên chặng quốc tế dài | Tùy nhà mạng quyết | Mọi terminal | Tiêu chuẩn |
| Proxy công cộng miễn phí | Reset giữa chừng thường xuyên | Ít, dùng chung và quá tải | Cấu hình thủ công, dễ hỏng | Mờ ám, rủi ro lộ key |
| Đường hầm tiêu dùng phổ thông | Tạm ổn, không tối ưu cho luồng | Node khu vực dùng chung | Chủ yếu ứng dụng desktop | Thất thường |
| Tuyến của NasaCode | Độ trễ ổn định cho luồng liên tục | Node độ trễ thấp cho lập trình viên | Hợp cả desktop lẫn CLI | Ưu tiên riêng tư, không ghi log |
Điểm cần nhìn không phải cột nào "thắng", mà là một tác vụ agent dài cần độ trễ ổn định suốt nhiều phút liền. Một tuyến nhanh nhưng hay đứt còn tệ hơn một tuyến chậm hơn chút mà bền.
Mấy câu hay được hỏi
Nới giới hạn timeout lên thì có hết không?
Hầu như không. Cửa sổ dài hơn chỉ cứu được khi luồng đã sắp xong. Còn nếu đang rớt gói hoặc kết nối bị reset, timeout to hơn chỉ làm bạn chờ lâu hơn để nhận đúng cái thất bại cũ. Sửa tuyến trước đã.
Máy mạnh hơn có giúp gì không?
Không. Timeout là chuyện của mạng — byte đang bay giữa terminal của bạn và API. CPU với RAM ảnh hưởng tốc độ chạy công cụ ở máy, chứ không quyết định nổi việc dòng phản hồi có vượt qua một chặng mất gói hay không.
Làm sao biết lỗi từ phía nhà cung cấp hay từ mạng của mình?
Xem trang trạng thái chính thức trước tiên. Nếu nó báo khỏe mà một prompt tối giản vẫn treo hoặc lỗi, gần như chắc chắn vấn đề ở tuyến của bạn. Thử lại trên một mạng khác để xác nhận, nhanh thôi.
Có cách nào giữ phiên agent dài khỏi đứt giữa chừng?
Đừng dồn quá nhiều vào mỗi bước là một phần. Nhưng yếu tố quyết định hơn là chạy trên một tuyến có độ trễ ổn định và ít mất gói. Một tác vụ nhiều bước chỉ giữ được luồng từ đầu đến cuối khi đường đi của nó không gãy ở khúc giữa.
Nói cho cùng, timeout của Claude Code thường là một vấn đề tuyến đường mặc bộ đồ của lỗi ứng dụng. Một khi bạn đo độ trễ và mất gói thay vì đoán mò, hướng sửa hiện ra khá rõ. Nếu tuyến mặc định của bạn cứ làm khó những phiên tái cấu trúc dài, thử cho lưu lượng đi qua một node độ trễ thấp của NasaCode rồi xem các lượt gọi dài có còn rụng giữa chừng nữa không.
