Khắc phục sự cố

#Không ghi được màn hình hoặc cửa sổ (macOS)

Thông báo: Ghi toàn màn hình hoặc cửa sổ khác cần quyền Ghi màn hình của macOS.

1. Trong hộp thoại Mục tiêu ghi, nhấn Mở System Settings.
2. Privacy & Security → Screen & System Audio Recording: bật Ferret.
3. Khởi động lại ứng dụng, rồi nhấn Kiểm tra lại.

Ghi Trình duyệt tích hợp không cần quyền nào.

Khi chạy từ mã nguồn trên macOS, pnpm dev khởi chạy một bản sao Electron đã đổi tên, ký ad-hoc, cũng có tên Ferret (scripts/prepare-dev-electron.mjs), nên nó xuất hiện như một mục Ferret riêng trong các danh sách này. Lần đầu chạy, macOS sẽ hỏi lại quyền Ghi màn hình và Microphone. Sau đó sẽ không hỏi lại nữa. Bản build phát triển dùng keychain giả (--use-mock-keychain), nên không có hộp thoại Keychain: cookie và key được lưu trong bản build dev được mã hóa bằng một key cố định, không phải bằng Keychain thật. Đặt ADE_DEV_REAL_KEYCHAIN=1 để dùng Keychain thật.

#Không mở được microphone

Thông báo: Không mở được microphone. Kiểm tra quyền trong cài đặt hệ điều hành.

• macOS: System Settings → Privacy & Security → Microphone, rồi bật Ferret.
• Windows: Cài đặt → Quyền riêng tư và bảo mật → Micrô, rồi cho phép ứng dụng desktop.

Khi không có mic, các vòng tròn vẽ bằng bút vẫn tạo ra góp ý, nhưng không kèm yêu cầu bằng lời nói.

#Không có model trên máy / không tìm thấy whisper-cli

Thông báo: Không tìm thấy model chuyển văn bản trên máy. Âm thanh sẽ được lưu, và chỉ góp ý bằng bút được xử lý.

Tải model trong Cài đặt, hoặc chọn một tệp ggml-*.bin có sẵn. Nếu Cài đặt báo Không tìm thấy whisper.cpp (whisper-cli), hãy cài nó (hướng dẫn), đảm bảo nó nằm trong PATH, rồi mở lại Cài đặt. Ứng dụng đóng gói được mở từ Finder hoặc Explorer có thể không thấy PATH của shell, nên hãy cài vào vị trí tiêu chuẩn, chẳng hạn vị trí của Homebrew.

Model tải về không qua được kiểm tra sha256 sẽ bị loại bỏ. Hãy tải lại.

#Terminal: không tải được node-pty

Lỗi này xảy ra khi chạy từ mã nguồn và node-pty được build cho một ABI Node hoặc Electron khác.

pnpm rebuild:native

#Không tìm thấy agent / Gửi cho Agent không gửi được

• command not found: claude (hoặc codex, gemini, hay lệnh của agent khác) trong terminal: CLI chưa được cài hoặc không nằm trong PATH. Ferret hiển thị nguyên lỗi của shell và không thêm gợi ý nào. Hãy kiểm tra lệnh đó chạy được trong terminal thông thường của bạn, dùng Cài đặt trong Cài đặt → Agent, hoặc đặt đường dẫn tuyệt đối làm Lệnh của agent đó.
• Agent đang chờ xác nhận. Hãy phản hồi trong terminal, rồi gửi. Hãy trả lời yêu cầu của agent trước.
• Ô nhập của agent chưa sẵn sàng. Đợi agent khởi động xong.
• Văn bản đã được nhập nhưng chưa gửi. Hãy nhấn Enter trong terminal.
• Hãy mở terminal trước.
• Không phân tích được tham số khởi chạy: Unclosed quote. Sửa lại dấu ngoặc kép trong tham số của agent.

#Không bắt đầu ghi được

• Hãy mở thư mục dự án trước.
• Hãy mở URL cần review trước.
• Trang không tải được. Hãy mở một URL hiển thị được, rồi ghi. Kiểm tra dev server có đang chạy không. Không kết nối được server nghĩa là không có gì đang lắng nghe ở port đó.

#Chưa đặt OpenAI key hoặc endpoint

Chưa đặt OpenAI API key… hoặc Chưa đặt endpoint chuyển văn bản (Base URL / model)…: thêm trong Cài đặt, hoặc chuyển sang Trên máy (miễn phí). Âm thanh của bản ghi đó đã được lưu.

#Lỗi GitHub

• Không tìm thấy GitHub CLI (gh). Cài gh.
• Chưa đăng nhập GitHub. Cài đặt → GitHub / GitLab → Đăng nhập trong terminal.
• Không có remote origin. hoặc origin không phải repository GitHub. Kiểm tra git remote -v.
• Không tìm thấy repository, hoặc bạn không có quyền truy cập. Kiểm tra gh auth status và GH_TOKEN.

#Báo lỗi

Mở một issue tại github.com/JapanMarketing-Dev/ferret/issues (mở trong tab mới) kèm hệ điều hành, phiên bản ứng dụng (footer → Cập nhật) và các bước để tái hiện lỗi. Đừng đính kèm nội dung .ferret/ có chứa màn hình riêng tư.