ヘルプ
困ったときは
よくある問題と直し方です。引用したメッセージは、アプリが日本語で出す文言です。
#画面やウインドウを録画できない（macOS）
メッセージ: 画面全体や別のウインドウを録画するには、macOS の「画面収録」の許可が必要です。
- 録画の対象 のダイアログで システム設定を開く を押します。
- プライバシーとセキュリティ → 画面とシステムオーディオ収録 で Ferret をオンにします。
- アプリを再起動してから、確認し直す を押します。
内蔵ブラウザ を録画するだけなら、許可は要りません。
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: 設定 → プライバシーとセキュリティ → マイク で、デスクトップアプリに許可します。
マイクが無くてもペンで囲んだところは指摘になりますが、話した依頼は付きません。
#端末内のモデルが無い / 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/ の中身は添付しないでください。