困ったときは

#インストールと初回の起動

Linux: Ubuntu 23.10 以降では、AppArmor が Electron のサンドボックスの使うユーザー名前空間を制限するため、AppImage が起動時にサンドボックスのエラーで止まることがあります。代わりに .deb を入れてください。

#画面やウインドウを録画できない（macOS）

メッセージ: 画面全体や別のウインドウを録画するには、macOS の「画面収録」の許可が必要です。

1. 録画の対象 のダイアログで システム設定を開く を押します。
2. プライバシーとセキュリティ → 画面とシステムオーディオ収録 で Ferret をオンにします。
3. アプリを再起動してから、確認し直す を押します。

内蔵ブラウザ を録画するだけなら、許可は要りません。

macOS でソースから動かすと、pnpm dev は名前を変えてアドホック署名した Electron のコピーを起動します。これも Ferret という名前なので（scripts/prepare-dev-electron.mjs）、上の一覧には別の Ferret として出ます。初めて動かすときは、macOS が画面収録とマイクの許可をもう一度求めます。2回目からは聞かれません。開発用のビルドはモックのキーチェーン（--use-mock-keychain）を使うので、キーチェーンの確認は出ません。そのため、開発用のビルドで保存した Cookie やキーは、本物のキーチェーンではなく固定の鍵で暗号化されます。本物のキーチェーンを使うには ADE_DEV_REAL_KEYCHAIN=1 を設定します。

#マイクが開かない

メッセージ: マイクを開けませんでした。OSの設定で許可を確認してください

• macOS: システム設定 → プライバシーとセキュリティ → マイク で Ferret をオンにします。
• Windows: 設定 → プライバシーとセキュリティ → マイク で、デスクトップアプリに許可します。

マイクが無くてもペンで囲んだところは指摘になりますが、話した依頼は付きません。

#会議の相手の声が録れない

相手の声も録る がオンなのにパソコンの音声を録れないとき、Ferret は次のどれかの警告を出し、マイク・映像・ペンの記録は続けます。

• Ferret にシステムオーディオの録音が許可されていません。（macOS）: システム設定 → プライバシーとセキュリティ → 画面収録とシステムオーディオ録音 で Ferret をオンにし、Ferret を終了して開き直してから、新しく録画を始めます。
• 相手の声を録るには macOS 14.2 以降が必要です。: macOS をアップデートします。それまではマイクだけを録ります。
• Windows がシステム音声へのアクセスを許可しませんでした。 または 音声の出力先が見つかりません。: 設定 → システム → サウンド（Windows）でスピーカーかヘッドホンを有効にするか、つないでから、新しく録画を始めます。
• システム音声を取得できません。（Linux）: PulseAudio を入れます。PipeWire を使っているなら pipewire-pulse を入れます。
• 相手の声の録音が止まりました: 音声の出力先が切り替わったか、外れました。: 録画の残りは相手の声なしで続きます。残りは 追加で録る で録ってください。

相手の言葉が自分の発言としても出るときは、マイクがスピーカーの音を拾っています。ヘッドホンを使ってください。

#端末内のモデルが無い / whisper-cli が見つからない

メッセージ: 端末内の文字起こしモデルがありません。音声は保存し、ペンの指摘だけを分解します。

設定でモデルをダウンロードするか、手元の ggml-*.bin を選びます。設定に whisper.cpp（whisper-cli）が見つかりません と出るときは、それをインストールし（手順）、PATH に入っていることを確かめてから設定を開き直します。Finder やエクスプローラーから起動したパッケージ版のアプリには、シェルの PATH が見えないことがあります。Homebrew の場所のような標準の場所に入れてください。

sha256 の確認に通らなかったモデルのダウンロードは捨てられます。もう一度試してください。

#ターミナル: node-pty を読み込めない

ソースから動かしていて、node-pty が別の Node や Electron の ABI 向けにビルドされているときに起きます。

pnpm rebuild:native

#エージェントが見つからない / Agentへ送信 で送られない

• ターミナルに command not found: claude（または codex、gemini、ほかのエージェントのコマンド）と出る: CLI がインストールされていないか、PATH に入っていません。Ferret はシェル自身のエラーを出すだけで、ヒントは足しません。ふだんのターミナルでそのコマンドが動くか確かめるか、設定 → Agent の インストール を使うか、そのエージェントの コマンド に絶対パスを入れてください。
• Agentが確認を待っています。ターミナルで応答してから送信してください。 先にエージェントの問いに答えてください。
• Agentの入力欄がまだ準備できていません。 エージェントの起動が終わるまで待ってください。
• 本文は入力しましたが送信できませんでした。ターミナルでEnterを押してください。
• ターミナルを開いてください。
• 起動引数を解釈できません: クォートが閉じていません。 エージェントの引数のクォートを直してください。

#録画が始まらない

• プロジェクトフォルダを開いてください
• レビューするURLを開いてください
• ページを開けていません。表示できるURLを開いてから録画してください 開発サーバーが動いているか確かめてください。サーバーに接続できません は、そのポートで何も待ち受けていないという意味です。

#OpenAI のキーや接続先が未設定

OpenAIのAPIキーが設定されていません。… や 文字起こしの接続先（Base URL・モデル名）が未設定です。…: 設定で入れるか、この端末（無料） に切り替えてください。その録画の音声はすでに保存されています。

#GitHub のエラー

• GitHub CLI（gh）が見つかりません。 gh をインストールしてください。
• GitHub にログインしていません。 設定 → GitHub / GitLab → ターミナルでログイン を使ってください。
• origin のリモートがありません。 や origin が GitHub のリポジトリではありません。 git remote -v を確かめてください。
• リポジトリが見つからないか、アクセスする権限がありません。 gh auth status と GH_TOKEN を確かめてください。

#不具合を報告する

github.com/JapanMarketing-Dev/ferret/issues （新しいタブで開きます） に issue を作り、OS、アプリのバージョン（フッター → アップデート）、再現の手順を書いてください。人に見せられない画面が入った .ferret/ の中身は添付しないでください。