문제 해결

증상으로 섹션을 고르세요. 각 섹션에 체크리스트와 순서 있는 수정 방법이 있습니다. 점선 프레임은 스크린샷 자리 표시자입니다(public/screenshots/ts-*.svg).

시작 전: 다음 다섯 가지를 적어 두세요

1. macOS 버전
2. VoiceHotkey 버전 (설정 → 정보)
3. 받아쓰기 엔진 이름
4. 로컬 전용 켜짐/꺼짐
5. 앱 경로 (Finder → 정보 가져오기)

개인정보

API 키, 라이선스 비밀, 민감한 전사는 절대 붙여 넣지 마세요. 문의 참고.

---

단축키가 아무 반응도 없음

오버레이 없음, 메뉴 바 상태 변화 없음, 시스템 피드백 없음.

체크리스트

• 메뉴 바 아이콘 있음 (앱 실행 중)
• 현재 앱 경로에 대해 손쉬운 사용이 켜져 있음
• /Applications 또는 ~/Applications에서 실행
• 단축키가 다른 앱과 충돌하지 않음
• 단축키 페이지에 손쉬운 사용 경고 없음

단계

1. 프로세스 — 메뉴 바 아이콘으로 메뉴가 열려야 합니다. 없으면 Applications에서 다시 실행하세요.
2. 손쉬운 사용 — 시스템 설정 → 개인정보 보호 및 보안 → 손쉬운 사용. VoiceHotkey 행 하나, 올바른 경로, 스위치 켬. 중복 제거 후 앱 종료·재실행.
3. 안정 경로 — 설치 및 권한 참고.
4. 다시 바인딩 — 설정 → 단축키 → 덜 흔한 조합을 기록.
5. 충돌 — ⌥Space를 쓰는 다른 도구를 종료하고 다시 시도.

그림 A · 손쉬운 사용 목록 (자리 표시자 · ts-01-accessibility-list.svg)

---

녹음은 되지만 텍스트가 없음

오버레이는 듣는 중인데 필드는 비어 있거나 처리가 끝나지 않음.

체크리스트

• 데모 모드 꺼짐
• 마이크 허용됨; 올바른 입력 장치
• 엔진 구성됨 (키 / Apple 준비)
• 로컬 전용이 클라우드 엔진을 막지 않음
• 네트워크 / 할당량 / 키 유효성
• 일반 텍스트 필드에 캐럿 (보안 필드는 삽입 차단 가능)

단계

1. 설정 → 일반 — 데모 모드를 끕니다.
2. 메뉴 바 상태 읽기 — 마이크 필요, 엔진 미구성, 로컬 전용 차단 등.
3. 마이크 — VoiceHotkey에 대해 켭니다. 음성 메모로 하드웨어를 확인하세요.
4. 엔진 — 대조군으로 Apple을 시도합니다. Apple은 되고 클라우드만 실패하면 → 키/네트워크/할당량.
5. 로컬 전용 — 로컬 전용이 켜져 있으면 공용 엔진이 실패합니다.
6. 출력 — 후처리 출력 동작이 캐럿 삽입이어야 합니다. Terminal이 주입을 막으면 메모에서 시도하세요.

그림 B · 메뉴 바 상태 (자리 표시자 · ts-02-menubar-status.svg)

그림 C · 로컬 전용 (자리 표시자 · ts-03-local-only.svg)

---

권한이 계속 초기화됨

어제까지 됐는데 오늘 단축키 죽음; 손쉬운 사용이 반쯤만 설정된 것처럼 보임.

흔한 원인

원인	설명
경로 변경	Downloads, 다른 폴더, 다른 빌드 경로
서명 / 교체	덮어쓰기 설치가 새 앱으로 취급됨
중복 행	잘못된 손쉬운 사용 항목에 바인딩됨

수정

1. Applications에 앱 하나만 둡니다.
2. VoiceHotkey를 완전히 종료합니다.
3. 손쉬운 사용과 마이크에서 모든 VoiceHotkey 행을 제거합니다.
4. 고정 경로에서 실행하고 권한을 다시 부여합니다.
5. 항상 같은 경로를 엽니다(디버그 vs 릴리스 패키지는 다른 경로로 취급).

---

다듬기 / 번역이 반영되지 않음

• 다듬기 켜짐 / 번역 단축키 사용
• 후처리 LLM 키 구성됨
• 로컬 전용이 API를 막지 않음
• 실패 시 원본 전사 삽입 가능 (예상 동작)

1. 설정 → 텍스트 후처리: 다듬기 켬; 번역은 자체 단축키 사용.
2. LLM 제공자 키를 구성합니다.
3. 로컬 전용을 끄거나 Base URL을 localhost로 두고 비교합니다.
4. 다듬기를 켜기 전에 기본 받아쓰기가 되는지 확인합니다.

---

셸 명령이 실행되지 않음

• Trial 또는 Pro (Free 아님)
• 설정 → 음성 명령 → 셸 명령 허용 켜짐
• 확인 대화상자를 취소하지 않음
• 위험 차단 목록에 걸리지 않음
• 의도 모델 켜짐 및 구성됨

셸 명령 및 플랜 참고.

그림 D · 라이선스 (자리 표시자 · ts-04-license.svg)

---

빠른 시나리오

새로 설치

1. 경로 + 두 권한
2. 데모 모드 끔
3. 동작하는 엔진 하나
4. 메모에서 테스트

업그레이드 후

1. Applications에서 새 빌드 실행
2. 오래된 손쉬운 사용 행 정리 후 다시 부여
3. 정보에서 버전 확인

회사 네트워크 / 개인정보

1. 클라우드 API에 도달 가능해야 함
2. 또는 Apple / localhost 사용
3. 로컬 전용은 업데이트 확인도 일시 중지

---

여전히 안 되면

1. 첫 설정 시범 실행을 다시 합니다.
2. 맨 위 다섯 가지 항목을 수집합니다.
3. 문의를 통해 이슈를 등록합니다.

설치 및 권한DMG, 경로, 손쉬운 사용, 마이크.

첫 설정데모 모드, 엔진, 단축키, 테스트.