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 v3.0.0-beta.15 đã 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`	Không có gói Desktop v3.0.0-beta.15 nào được phát hành 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_3.0.0-beta.15_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
Linux báo không tìm thấy WebKitGTK runtime cho bản build này rồi thoát	Startup preflight không tìm thấy các tiến trình helper của WebKit mà cửa sổ cần	Cài runtime WebKitGTK 4.1 (`libwebkit2gtk-4.1-0` trên Debian và Ubuntu, `webkit2gtk4.1` trên Fedora, `webkit2gtk-4.1` trên Arch), rồi thử lại
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

Trên Linux, AppImage hiện được xác minh trên Debian và Ubuntu. Trên Fedora, Arch và các distribution khác đặt tiến trình helper của WebKit ở vị trí khác, cửa sổ vẫn có thể không mở được dù đã cài runtime 4.1; xem Cài đặt. Nếu runtime của bạn được cài theo một bố cục vẫn hoạt động nhưng preflight không nhận ra, hãy đặt AK_GUI_SKIP_WEBKIT_PREFLIGHT=1 để vẫn khởi chạy. Bỏ qua bước kiểm tra không khắc phục được runtime bị thiếu; lần khởi chạy vẫn có thể bị dừng đột ngột.

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 Desktop báo Quyền dùng ngoại tuyến đã hết hạn (Offline access expired), grace period offline 72 giờ kể từ lần kiểm tra thành công gần nhất đã hết; hãy kết nối lại và kích hoạt lại để Desktop xác minh license. Thông báo rằng thiết bị này đã bị đăng xuất khỏi license, hoặc license không còn hoạt động, là quyết định từ registry; hãy kích hoạt lại bằng license key hoặc liên hệ hỗ trợ.

Nếu quá trình kích hoạt báo đã đạt giới hạn thiết bị, license một seat sẽ tự động chuyển sang thiết bị này, còn license nhiều seat đã đầy sẽ đề xuất Move the license to this device. ak login --license-key không chuyển seat, nên hãy dùng Desktop cho lựa chọn đó. Mỗi lần chuyển sẽ đăng xuất thiết bị trước đó và gửi email cho chủ license. Nếu Desktop báo license đã chuyển giữa các thiết bị 3 lần trong 24 giờ qua, hãy gỡ một thiết bị tại agentkit.best/account/licenses hoặc thử lại sau.

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á.
Desktop tự thiết lập local analytics index và dựng lại index không còn mở được, trừ khi bạn đã tắt hoặc xoá index. Sau khi tắt hoặc xoá, hãy bật lại Use local index trong tab Database của Settings hoặc chạy ak analytics enable. Dùng Sync now trong tab đó để làm mới index.
Xoá project trong Desktop chỉ xoá mục registry AgentKit. Thao tác này không xoá thư mục project.

Nếu onboarding báo thiếu Node.js, hãy dùng thao tác cài Node.js LTS tường minh hoặc gợi ý cài thủ công được hiển thị. Chờ bước kiểm tra lại phiên bản, rồi chạy lại thao tác cài hoặc refresh Kit bị ảnh hưởng để cấu hình Hook và status line dựa trên Node.

Desktop v3.0.0-beta.15 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 stage artifact CLI và Desktop khớp nhau, rồi trusted helper hoàn tất swap sau khi process cha nhả executable. Nếu thao tác đó không hoàn tất, 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_3.0.0-beta.15_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.