Xử lý sự cố ứng dụng Desktop

Chẩn đoán lỗi khởi chạy đầu, license, dữ liệu cục bộ, nền tảng và staged update mà không xoá trạng thái người dùng.

Bắt đầu từ triệu chứng bên dưới. Giữ artifact v2.12.0 đã xác minh và bảo toàn trạng thái AgentKit trong khi chẩn đoán.

Cửa sổ không mở

Triệu chứng	Ý nghĩa	Bước an toàn tiếp theo
`ak gui` in gợi ý tải Desktop và thoát `1`	Bạn đã chạy artifact CLI tiêu chuẩn không có Wails	Chạy trực tiếp artifact Desktop đã xác minh
Linux ARM64 hoặc Windows ARM64 in cảnh báo khả dụng rồi thoát `0`	v2.12.0 không có gói Desktop cho kiến trúc đó	Dùng CLI hoặc browser dashboard; đừng thay bằng binary x64
macOS chặn ứng dụng	Gatekeeper chưa cho phép bundle này	Kiểm tra lại SHA-256, rồi dùng quy trình allow-once trong Cài đặt
Linux báo permission denied	AppImage chưa có quyền executable	Chạy `chmod +x ak-gui_2.12.0_linux_amd64.AppImage` bằng user của bạn
Linux báo lỗi FUSE	Host thiếu lớp tương thích AppImage FUSE	Cài gói tương thích của distribution; đừng chạy bằng root
Windows hiển thị SmartScreen	Windows đang đánh giá executable đã tải	Kiểm tra lại SHA-256 trước khi chọn More info → Run anyway cho artifact phát hành khớp
Windows báo không tìm thấy Microsoft Edge WebView2 Runtime	Startup preflight không tìm thấy WebView2 runtime bắt buộc	Cài hoặc repair WebView2 từ trang download chính thức của Microsoft, rồi thử lại

Desktop cần graphical session. --no-interactive không ngăn cửa sổ, còn --json và --quiet không tạo lần khởi chạy có cấu trúc hoặc im lặng. Với host headless, hãy dùng lệnh CLI hoặc khởi động browser dashboard riêng mà không mở browser cục bộ:

ak config start --no-open

Chỉ expose server vượt ra ngoài loopback bind mặc định sau khi áp dụng kiểm soát xác thực và network phù hợp.

Desktop vẫn ở màn hình license

Đăng nhập CLI thành công không kích hoạt Desktop. Hãy nhập license App hợp lệ trong Desktop khi đang online. Nếu grace period offline 72 giờ đã hết, hãy kết nối lại để Desktop xác minh.

Nếu Desktop báo không thể đọc hoặc lưu session, hãy kiểm tra ownership và quyền của $AGENTKIT_HOME/auth/session.json. Đừng dán tệp đó vào yêu cầu hỗ trợ và đừng xoá toàn bộ AgentKit home. Profile → Sign out chỉ xoá slot App cục bộ; ak logout chỉ xoá slot CLI.

Kit, Activity hoặc Session trống

Refresh App session và kết nối mạng khi catalog Kit được cấp quyền không khả dụng. Kit chỉ có thể cài khi App session cấp quyền cho nó.
Chạy lại local scan khi thiếu coding assistant mới cài hoặc project đã đăng ký. Sau khi cài Kit, hãy restart assistant đó hoặc mở runtime session mới.
Activity đọc $AGENTKIT_HOME/activity/events.ndjson. Session reconcile nguồn Claude Code và Codex được hỗ trợ vào $AGENTKIT_HOME/analytics/analytics.db khi Desktop đang mở. View trống có thể nghĩa là chưa có bằng chứng cục bộ được hỗ trợ; nó không chứng minh tệp đã bị xoá.
Xoá project trong Desktop chỉ xoá mục registry AgentKit. Thao tác này không xoá thư mục project.

Desktop v2.12.0 không khởi động skill của Kit hay agent run. Hãy chạy skill trong coding assistant trước khi chờ Activity hoặc bằng chứng session mới.

Một port đang bận

Desktop không bind HTTP port. Xung đột trên 127.0.0.1:8766 thuộc browser dashboard được khởi động riêng; xung đột trên 127.0.0.1:8765 thuộc API server được khởi động riêng. Kiểm tra các process đó bằng:

ak config status
ak api status

Đóng Desktop sẽ dừng service trong process, stream và reconciler của nó, nhưng không dừng dashboard hoặc API server được khởi động riêng.

Update không hoàn tất

Windows x64 từ chối paired Desktop apply trong v2.12.0. Hãy tải và xác minh zip Desktop thay thế theo cách thủ công.
Trên macOS hoặc Linux x64, hãy giữ CLI tiêu chuẩn khớp version đã cài và bảo toàn $AGENTKIT_HOME/updater/pending-binary-update.json cùng thư mục staging được báo.
Giải phóng dung lượng, sửa ownership hoặc quyền, đóng process đang giữ executable, rồi mở lại chính ứng dụng Desktop đó để retry.
Nếu rollback cũng thất bại, hãy dừng. Giữ các đường dẫn installed, staged, pending và backup từ lỗi thay vì tự tráo file.

Đọc Cập nhật ứng dụng Desktop để hiểu ranh giới transaction và tham chiếu ak self-update để biết output cùng exit behavior của CLI.

Thu thập chẩn đoán an toàn

Thoát Desktop, mở terminal và khởi chạy đúng executable đã cài:

/Applications/agentkit.app/Contents/MacOS/ak-gui

./ak-gui_2.12.0_linux_amd64.AppImage

.\ak-gui.exe

Chẩn đoán runtime, update và launch của Desktop có thể xuất hiện dưới dạng plain text trên stderr. Trên Windows, Desktop cũng ghi launch log vào %LOCALAPPDATA%\agentkit\logs\ak-gui.log. Launch không có console khi thất bại sẽ hiển thị native dialog với error cùng vị trí log; nếu thiếu WebView2 runtime, dialog cũng gồm official repair link. Với startup failure khác, kiểm tra Event Viewer → Windows Logs → Application để tìm entry ak-gui.exe và vẫn giữ endpoint protection bật.

Ghi lại triệu chứng, hệ điều hành, kiến trúc, tên artifact, kết quả SHA-256 và chỉ các dòng stderr, log hoặc Event Viewer liên quan. Xoá license key, nội dung session, đường dẫn project riêng tư và giá trị cấu hình chưa che trước khi chia sẻ.

Cài lại cùng gói Desktop đã xác minh có thể thay ứng dụng mà không xoá dữ liệu AgentKit. Chỉ xoá mục ứng dụng đã cài được mô tả trong Cài đặt, không bao giờ xoá toàn bộ AgentKit hoặc runtime home.