帮助
故障排除
常见问题及解决方法。引号中的消息是应用在简体中文界面下显示的内容。
#无法录制屏幕或窗口（macOS）
消息：录制整个屏幕或其他窗口需要 macOS 屏幕录制权限。
- 在 录制对象 对话框中点击 打开系统设置。
- 在 隐私与安全性 → 屏幕与系统录音 中打开 Ferret。
- 重新启动应用，然后点击 重新检查。
录制 内置浏览器 不需要任何权限。
在 macOS 上从源码运行时，pnpm dev 会启动一个经过重命名、采用临时（ad-hoc）签名的 Electron 副本，它同样叫 Ferret（scripts/prepare-dev-electron.mjs），因此会在这些列表中显示为另一个 Ferret 条目。第一次运行时，macOS 会再次请求屏幕录制和麦克风权限，之后不会再询问。开发版本使用模拟钥匙串（--use-mock-keychain），因此不会弹出钥匙串提示：开发版本中保存的 Cookie 和密钥使用固定密钥加密，而不是真正的钥匙串。设置 ADE_DEV_REAL_KEYCHAIN=1 即可使用真正的钥匙串。
#麦克风无法打开
消息：无法打开麦克风。请在系统设置中检查权限。
- macOS：在 系统设置 → 隐私与安全性 → 麦克风 中打开 Ferret。
- Windows：在 设置 → 隐私和安全性 → 麦克风 中允许桌面应用访问。
没有麦克风时，用画笔圈出的地方仍会生成反馈，但不带口述的请求。
#没有本机模型 / 找不到 whisper-cli
消息：未找到本机转写模型。音频会被保存，仅处理画笔反馈。
在设置中下载模型，或选择已有的 ggml-*.bin。如果设置中显示 未找到 whisper.cpp（whisper-cli）。
，请安装它（安装说明），确认它在 PATH 中，然后重新打开设置。从 Finder 或资源管理器启动的打包应用可能读不到 shell 的 PATH，因此请安装到 Homebrew 等标准位置。
未通过 sha256 校验的模型下载会被丢弃。请重试。
#终端：无法加载 node-pty
从源码运行时，如果 node-pty 是针对不同的 Node 或 Electron ABI 构建的，就会出现此问题。
pnpm rebuild:native#找不到 Agent / 发送给 Agent 没有发送
- 终端中出现
command not found: claude（或codex、gemini等其他 Agent 的命令）：CLI 未安装或不在PATH中。Ferret 会直接显示 shell 自身的错误，不附加提示。请确认该命令在你平时使用的终端中可以运行，或在 设置 → Agent 中使用 安装，或将绝对路径设为该 Agent 的 命令。 Agent 正在等待确认。请在终端中回应后再发送。
请先回应 Agent 的提示。Agent 的输入尚未就绪。
请等待 Agent 启动完成。文本已输入但未发送。请在终端中按 Enter。
请先打开终端。
无法解析启动参数：引号未闭合。
请修正该 Agent 参数中的引号。
#无法开始录制
请先打开项目文件夹。
请先打开要审查的 URL。
页面未加载。请打开可显示的 URL 后再录制。
请确认开发服务器正在运行。无法连接到服务器
表示该端口上没有任何服务在监听。
#未设置 OpenAI 密钥或 endpoint
未设置 OpenAI API key。…
或 未设置转写 endpoint（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，并写明你的操作系统、应用版本（页脚 → 更新）以及复现步骤。不要附上包含私密画面的 .ferret/ 内容。