Phần lớn vấn đề trong 1DesignTool quy về một nắm nguyên nhân — agent thiếu hoặc đã đăng xuất, lượt chạy đứng yên, preview không render, cổng FAIL, hay hạn mức đã cạn. Trang này là nơi nhìn đầu tiên cho mỗi trường hợp.
Agent không có trong picker
App tìm các CLI được hỗ trợ trên PATH của bạn — giống cách một terminal làm.
- Nó đã cài chưa? Chạy CLI bằng tên trong một terminal (
claude,codex…) — nếu shell tìm thấy, app cũng nên thấy. - Nó đã đăng nhập chưa? Picker hiển thị trạng thái đăng nhập; một đăng nhập thiếu là auth của chính CLI, không phải của app. Đăng nhập bên phía CLI rồi mở lại.
- Nó có trong danh sách không? 16 CLI được hỗ trợ nằm ở Các coding agent được hỗ trợ — một CLI không có trong danh sách thì không cắm vào được.
Một lượt chạy đứng yên hoặc thất bại
- Kiểm tra quota của agent — lượt tính vào tài khoản CLI của bạn; một tài khoản cạn hay hết hạn làm lượt thất bại rõ ràng trong transcript.
- Đọc transcript — output của chính agent nằm ở đó; một lỗi phía CLI hiện ra là chính nó, không phải một lỗi chung chung.
- Thử lại một lần — một lỗi CLI thoáng qua đôi khi chạy lại được. Một lỗi bền thì có nguyên nhân mà transcript gọi tên.
Preview không render
- Preview là default-deny — một loại file mà classifier không phục vụ sẽ render ra không có gì thay vì nguy hiểm. Đây là sàn an toàn, không phải bug.
- Worktree cũ — trên một codebase project, preview đọc worktree
1design/<slug>; nếu trạng thái branch trông lạ, review diff trên thanh branch trước khi nghi render. - Refresh panel — nút reload trên thanh preview đọc lại thư mục; một file ghi dở thường hết sự cố ở lần paint tiếp.
Cổng FAIL không sạch
- Sửa ở độ rộng này — nút sửa của một finding FAIL gửi đúng vấn đề đó trả agent dưới dạng brief một dòng; finding gọi tên độ rộng và phần tử, nên sửa thường thuần cơ khí.
- Kiểm tra ở đúng độ rộng đó — finding nói viewport nào vỡ; nhìn kết quả ở đó trước khi cho rằng luật sai.
- Vài finding là cố ý — một đánh đổi đã biết có thể chấp nhận; cổng khuyên, không chặn. Xem Cổng design kit.
Hạn mức từ chối một lượt chạy
Một từ chối 1design:limit: gọi tên hạn mức đã cạn — lượt, render, version,
biến thể hay design system trên gói free. Settings → Usage hiển thị đầy
đủ các đồng hồ đo, và archive một version giải phóng một slot không cần
license. Hạn mức là bộ đếm trọn đời; Pro xóa chúng. Xem
Free vs Pro.
Trên Windows: lỗi EISDIR (vấn đề đã biết)
Trong 1.7.0 trên Windows, các script design kit có thể thất bại với EISDIR —
làm hỏng Knowledge, kiểm tra hậu lượt, export video và chế độ Build. Đây là
bug đã biết, đã sửa ở bản kế tiếp; trên macOS các luồng đó không bị ảnh hưởng.
Một MCP client không kết nối được
- Kiểm tra panel truy cập — Settings → MCP access hiển thị endpoint, token và danh sách client được phép; một client bị từ chối thường chưa có trong danh sách.
- Kiểm tra token — token trong panel là thứ client gửi; một token cũ hay sai sẽ từ chối kết nối.
- Kiểm tra activity log — log hiển thị cái gì đã tới server và cái gì không.
Nhìn đâu trước
- Panel transcript — output của agent, nguyên văn
- Thanh branch — trên một codebase project, lượt thực sự đổi gì
- Settings → Usage — đồng hồ đo nào đã cạn
- Activity log — một MCP client thực sự đã làm gì
Mẹo: Transcript luôn là thứ đọc đầu tiên — output của chính agent là phiên bản trung thực về chuyện đã xảy ra, và phần lớn "app hỏng" thực ra là "CLI nói điều gì đó mà UI dịch quá nhẹ tay".