Khắc phục sự cố Terminal

Giải quyết các vấn đề thường gặp với terminal và AI agent.

Trang này hướng dẫn xử lý các sự cố phổ biến nhất với terminal và AI agent trong 1DevTool. Tìm triệu chứng phù hợp với bạn và làm theo các bước khắc phục.

Terminal không hiển thị output (màn hình trắng)

Triệu chứng: Terminal mở ra nhưng màn hình trắng hoàn toàn, không có gì hiển thị dù bạn đã gõ lệnh.

Nguyên nhân thường gặp và cách xử lý:

  1. Renderer bị treo — Nhấn Cmd+R (Mac) hoặc Ctrl+R (Windows/Linux) để làm mới terminal panel. Thao tác này tải lại lớp hiển thị mà không kết thúc phiên.
  2. Font không hỗ trợ — Vào Settings → Terminal → Font và chuyển sang font mặc định (thường là monospace hoặc Menlo). Một số font tùy chỉnh có thể khiến terminal không render được.
  3. Terminal chưa được focus — Nhấn vào bên trong vùng terminal để đảm bảo nó đang nhận input. Đôi khi chỉ cần nhấn Enter một lần để kích hoạt hiển thị.
  4. Phiên tmux bị tách — Xem mục "Thông báo phiên bị tách" bên dưới.

Agent không phản hồi

Triệu chứng: Bạn đã gõ prompt và nhấn Enter, nhưng agent không làm gì cả. Không có output, không có dấu hiệu xử lý.

Cách xử lý:

  1. Kiểm tra xem agent đang chờ input không — Cuộn lên trong lịch sử terminal. Agent có thể đã hỏi một câu và đang chờ bạn trả lời. Gõ câu trả lời và nhấn Enter.
  2. Kiểm tra kết nối mạng — Claude Code, Codex và Gemini CLI đều cần internet để hoạt động. Mở trình duyệt tích hợp và kiểm tra xem mạng có ổn định không.
  3. Kiểm tra API key — Nếu agent in ra lỗi xác thực (authentication error), API key của bạn có thể đã hết hạn hoặc không đúng. Chạy agent trực tiếp trong terminal Bash để xem thông báo lỗi đầy đủ.
  4. Khởi động lại agent — Nhấn Ctrl+C trong terminal để dừng tiến trình hiện tại, rồi gõ lại lệnh khởi động agent (ví dụ claude). Bạn không mất phiên tmux, chỉ cần khởi động lại agent.
  5. Kiểm tra giới hạn rate — Nếu bạn đã gửi nhiều prompt liên tiếp, nhà cung cấp API có thể đang giới hạn tốc độ của bạn. Đợi vài phút rồi thử lại.

Lịch sử cuộn bị cắt bớt

Triệu chứng: Bạn cuộn lên nhưng không thể xem output từ sớm hơn trong phiên — lịch sử dừng lại đột ngột.

Giải thích: Mặc định tmux giới hạn scrollback buffer ở một số dòng nhất định để tránh dùng quá nhiều RAM.

Cách khắc phục: Tăng giới hạn scrollback trong cấu hình tmux. Mở hoặc tạo file ~/.tmux.conf và thêm:

set-option -g history-limit 50000

Sau đó khởi động lại tmux bằng cách thoát 1DevTool hoàn toàn và mở lại. Giá trị 50,000 dòng thường là đủ cho hầu hết các phiên agent.

Thông báo "phiên bị tách" (detached)

Triệu chứng: Terminal hiển thị thông báo kiểu "session detached" hoặc "[exited]" thay vì kết nối lại với agent.

Điều này có nghĩa là: tmux đã mất kết nối với phiên — thường xảy ra sau khi ngủ đông (hibernate) hoặc sau khi máy ngủ sâu trong thời gian dài.

Cách xử lý:

  1. Mở Session Manager (nhấn biểu tượng phiên ở thanh trạng thái dưới cùng).
  2. Tìm phiên tương ứng trong danh sách.
  3. Nhấn Reconnect. 1DevTool sẽ đính kèm lại terminal panel với phiên đang chạy.
  4. Nếu phiên không còn trong danh sách (agent đã thoát), hãy mở terminal mới và khởi động lại agent từ đầu.

Terminal mới bắt đầu từ thư mục sai

Triệu chứng: Bạn mở terminal mới nhưng nó bắt đầu ở thư mục home (~) thay vì thư mục dự án.

Cách khắc phục:

  1. Đảm bảo bạn đang ở trong context đúng của dự án — nhìn vào thanh bên trái xem đúng dự án đang được chọn chưa.
  2. Nếu dự án của bạn là SSH remote, kiểm tra xem kết nối SSH có còn active không. Nếu kết nối bị ngắt, 1DevTool có thể mở terminal local thay thế.
  3. Xóa và tạo lại terminal: nhấn nút X để đóng terminal hiện tại, sau đó nhấn + để tạo mới. Terminal mới sẽ bắt đầu đúng thư mục dự án.

CPU cao bất thường

Triệu chứng: Quạt máy tính quay nhanh hoặc máy nóng dù agent không làm gì đặc biệt.

Nguyên nhân thường gặp:

  • Nhiều agent chạy cùng lúc — Mỗi AI agent dùng tài nguyên CPU và mạng. Nếu bạn có 4-5 agent chạy song song, đó là bình thường. Đóng bớt các agent không cần thiết.
  • Agent bị kẹt trong vòng lặp — Đôi khi agent tự lặp lại một tác vụ. Nhìn vào output trong terminal. Nếu thấy cùng một thứ lặp đi lặp lại, nhấn Ctrl+C để dừng.
  • tmux server — Trong trường hợp hiếm, tmux server có thể sử dụng nhiều CPU bất thường. Thoát 1DevTool hoàn toàn và mở lại thường giải quyết được vấn đề này.

Vẫn gặp sự cố?

Nếu bạn đã thử tất cả các bước trên mà vẫn chưa giải quyết được, hãy:

  1. Mở một terminal Bash trong 1DevTool và chạy agent trực tiếp từ command line để xem thông báo lỗi đầy đủ không bị lọc bởi giao diện.
  2. Kiểm tra phần Câu hỏi thường gặp để tìm vấn đề tương tự.
  3. Liên hệ hỗ trợ qua trang 1devtool.com kèm theo mô tả chi tiết và ảnh chụp màn hình nếu có thể.