문제 해결

#화면이나 창을 녹화할 수 없음(macOS)

메시지: 전체 화면이나 다른 창을 녹화하려면 macOS 화면 기록 권한이 필요합니다.

1. 녹화 대상 대화 상자에서 시스템 설정 열기를 클릭합니다.
2. 개인정보 보호 및 보안 → 화면 및 시스템 오디오 기록에서 Ferret을 켭니다.
3. 앱을 다시 시작한 다음 다시 확인을 클릭합니다.

내장 브라우저 녹화에는 권한이 필요 없습니다.

macOS에서 소스로 실행할 때 pnpm dev는 이름을 바꾸고 ad-hoc 서명한 Electron 사본을 실행하며, 이 사본의 이름도 Ferret입니다(scripts/prepare-dev-electron.mjs). 그래서 위 목록에 별도의 Ferret 항목으로 나타납니다. 처음 실행할 때 macOS가 화면 기록과 마이크 접근 권한을 다시 묻습니다. 그 뒤로는 다시 묻지 않습니다. 개발 빌드는 모의 키체인(--use-mock-keychain)을 사용하므로 키체인 확인 창이 나타나지 않습니다. 개발 빌드에서 저장한 쿠키와 키는 실제 키체인이 아니라 고정된 키로 암호화됩니다. 실제 키체인을 사용하려면 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

#에이전트를 찾을 수 없음 / 에이전트에게 보내기가 전송되지 않음

• 터미널에 command not found: claude(또는 codex, gemini, 다른 에이전트의 명령)가 표시됨: CLI가 설치되어 있지 않거나 PATH에 없습니다. Ferret은 셸의 오류를 그대로 보여 주며 힌트를 덧붙이지 않습니다. 평소 쓰는 터미널에서 명령이 동작하는지 확인하거나, 설정 → 에이전트의 설치를 사용하거나, 해당 에이전트의 명령에 절대 경로를 지정하세요.
• 에이전트가 확인을 기다리고 있습니다. 터미널에서 응답한 후 보내세요. 먼저 에이전트의 확인 요청에 답하세요.
• 에이전트의 입력이 아직 준비되지 않았습니다. 에이전트가 시작을 마칠 때까지 기다리세요.
• 텍스트는 입력되었지만 전송되지 않았습니다. 터미널에서 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 (새 탭에서 열림)에 OS, 앱 버전(푸터 → 업데이트), 재현 절차를 적어 issue를 등록하세요. 비공개 화면이 담긴 .ferret/의 내용은 첨부하지 마세요.