Fehlerbehebung

#Aufnahme des Bildschirms oder eines Fensters schlägt fehl (macOS)

Meldung: Für die Aufnahme des ganzen Bildschirms oder eines anderen Fensters ist die macOS-Berechtigung „Bildschirmaufnahme“ nötig.

1. Klicken Sie im Dialog Aufnahmeziel auf Systemeinstellungen öffnen.
2. Datenschutz & Sicherheit → Bildschirm- & Systemaudioaufnahme: Aktivieren Sie Ferret.
3. Starten Sie die App neu und klicken Sie dann auf Erneut prüfen.

Für die Aufnahme mit dem Ziel Integrierter Browser ist keine Berechtigung nötig.

Wenn Sie Ferret unter macOS aus dem Quellcode starten, startet pnpm dev eine umbenannte, ad hoc signierte Kopie von Electron, die ebenfalls Ferret heißt (scripts/prepare-dev-electron.mjs). Sie erscheint daher als eigener Ferret-Eintrag in diesen Listen. Beim ersten Start fragt macOS erneut nach dem Zugriff auf Bildschirmaufnahme und Mikrofon, danach nicht mehr. Entwicklungs-Builds verwenden einen Mock-Schlüsselbund (--use-mock-keychain), daher erscheint keine Schlüsselbund-Abfrage: Cookies und Schlüssel, die in einem Dev-Build gespeichert werden, sind mit einem festen Schlüssel verschlüsselt, nicht mit dem echten Schlüsselbund. Setzen Sie ADE_DEV_REAL_KEYCHAIN=1, um den echten Schlüsselbund zu verwenden.

#Mikrofon lässt sich nicht öffnen

Meldung: Mikrofon konnte nicht geöffnet werden. Prüfen Sie die Berechtigung in den Systemeinstellungen.

• macOS: Systemeinstellungen → Datenschutz & Sicherheit → Mikrofon, dann Ferret aktivieren.
• Windows: Einstellungen → Datenschutz und Sicherheit → Mikrofon, dann Desktop-Apps den Zugriff erlauben.

Ohne Mikrofon erzeugen Stiftkreise trotzdem Befunde, sie enthalten aber keine gesprochene Anfrage.

#Kein lokales Modell / whisper-cli nicht gefunden

Meldung: Kein Transkriptionsmodell auf dem Gerät gefunden. Das Audio wird gespeichert; nur Stiftbefunde werden verarbeitet.

Laden Sie in den Einstellungen ein Modell herunter oder wählen Sie eine vorhandene ggml-*.bin. Wenn die Einstellungen whisper.cpp (whisper-cli) wurde nicht gefunden anzeigen, installieren Sie es (Anleitung), stellen Sie sicher, dass es im PATH liegt, und öffnen Sie die Einstellungen erneut. Paketierte Apps, die aus dem Finder oder Explorer gestartet werden, sehen den PATH Ihrer Shell möglicherweise nicht. Installieren Sie es daher an einem Standardort, etwa dem von Homebrew.

Ein Modell-Download, dessen sha256-Prüfung fehlschlägt, wird verworfen. Versuchen Sie es erneut.

#Terminal: node-pty konnte nicht geladen werden

Das passiert, wenn Sie Ferret aus dem Quellcode starten und node-pty für eine andere Node- oder Electron-ABI gebaut wurde.

pnpm rebuild:native

#Agent nicht gefunden / „An Agent senden“ sendet nicht

• command not found: claude (oder codex, gemini oder der Befehl eines anderen Agents) im Terminal: Die CLI ist nicht installiert oder liegt nicht im PATH. Ferret zeigt den Fehler der Shell selbst an und fügt keinen Hinweis hinzu. Prüfen Sie, ob der Befehl in Ihrem normalen Terminal funktioniert, verwenden Sie Installieren unter Einstellungen → Agents oder tragen Sie einen absoluten Pfad als Befehl dieses Agents ein.
• Der Agent wartet auf eine Bestätigung. Antworten Sie im Terminal und senden Sie dann. Beantworten Sie zuerst die Abfrage des Agents.
• Die Eingabe des Agents ist noch nicht bereit. Warten Sie, bis der Agent vollständig gestartet ist.
• Der Text wurde eingegeben, aber nicht gesendet. Drücken Sie im Terminal die Eingabetaste.
• Öffnen Sie zuerst ein Terminal.
• Startargumente können nicht geparst werden: Unclosed quote. Korrigieren Sie die Anführungszeichen in den Argumenten des Agents.

#Aufnahme startet nicht

• Öffnen Sie zuerst einen Projektordner.
• Öffnen Sie zuerst eine zu prüfende URL.
• Die Seite wurde nicht geladen. Öffnen Sie eine URL, die angezeigt wird, und nehmen Sie dann auf. Prüfen Sie, ob der Dev-Server läuft. Keine Verbindung zum Server. bedeutet, dass an diesem Port nichts lauscht.

#OpenAI-Schlüssel oder Endpoint nicht gesetzt

Kein OpenAI-API-Schlüssel gesetzt … oder Der Transkriptions-Endpoint (Base URL / Modell) ist nicht gesetzt …: Tragen Sie ihn in den Einstellungen ein oder wechseln Sie zu Auf dem Gerät (kostenlos). Das Audio dieser Aufnahme ist bereits gespeichert.

#GitHub-Fehler

• GitHub CLI (gh) nicht gefunden. Installieren Sie gh.
• Nicht bei GitHub angemeldet. Einstellungen → GitHub / GitLab → Im Terminal anmelden.
• Kein origin-Remote. oder origin ist kein GitHub-Repository. Prüfen Sie git remote -v.
• Repository nicht gefunden oder kein Zugriff. Prüfen Sie gh auth status und GH_TOKEN.

#Fehler melden

Eröffnen Sie ein Issue unter github.com/JapanMarketing-Dev/ferret/issues (öffnet in einem neuen Tab) mit Ihrem Betriebssystem, der App-Version (Fußzeile → Updates) und den Schritten zur Reproduktion. Hängen Sie keine Inhalte aus .ferret/ an, die private Bildschirme zeigen.