문제 해결

증상으로 섹션을 고르세요. 각 섹션에 체크리스트와 순서 있는 수정 방법이 있습니다. 그림은 자동 생성 UI 미리보기 PNG입니다(public/screenshots/ts-*.webp).

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

macOS 버전
VoiceHotkey 버전 (설정 → 정보)
인식 엔진 이름
로컬 전용 켜짐/꺼짐
앱 경로 (Finder → 정보 가져오기)

단축키가 아무 반응도 없음

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

체크리스트

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

단계

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

UI 미리보기: 정리된 손쉬운 사용 목록 — 그림 A · 손쉬운 사용 목록 (UI 미리보기 · ts-01-accessibility-list.webp)

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

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

체크리스트

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

단계

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

UI 미리보기: 메뉴 바 상태 — 그림 B · 메뉴 바 상태 (UI 미리보기 · ts-02-menubar-status.webp)

UI 미리보기: 로컬 전용 토글 — 그림 C · 로컬 전용 (UI 미리보기 · ts-03-local-only.webp)

권한이 계속 초기화됨

어제까지 됐는데 오늘 단축키가 죽음; 손쉬운 사용에 기록이 있는 것처럼 보이지만 실제로는 작동하지 않음.

흔한 원인

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

수정

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

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

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

설정 → 텍스트 처리: 다듬기가 꺼져 있지 않은지 확인; 번역은 일반 음성 입력 단축키가 아니라 번역 단축키를 사용.
음성 입력과 별개인 LLM 제공자 키를 구성합니다(의도 모델과 같은 제공자 키체인을 공유할 수 있음).
로컬 전용을 끄고 한 번 비교해 보거나, Base URL을 로컬 게이트웨이로 지정합니다.
그래도 실패하면: 먼저 순수 음성 입력으로 텍스트가 나오는지 확인한 뒤 다듬기를 켜서, 문제 범위를 좁혀 나갑니다.

음성 명령이 아무 반응도 없음

설정 → 음성 명령 상단의 「음성 명령 사용」이 켜져 있는지
명령 단축키가 음성 입력/번역 단축키와 충돌하지 않고, 손쉬운 사용이 승인되어 있는지
「단축키 허용」이 꺼져 있지 않은지(꺼져 있으면 사전 기반 단축키만 실패함)
사용자 사전 항목이 활성화되어 있고 구문이 일치하는지(정확 일치를 먼저, 그다음 퍼지 일치)

음성 명령 참고.

셸 명령이 실행되지 않음

「음성 명령 사용」 총개폐 스위치가 켜져 있는지
체험 또는 Pro인지 (Free에는 셸 명령이 없음)
설정 → 음성 명령에서 「셸 명령 허용」이 켜져 있는지(「일반」 페이지가 아님)
확인 대화상자를 취소하지 않았는지
명령이 위험 패턴 차단 목록에 걸리지 않는지
의도 모델로 생성하는 경우: 의도 모델이 켜져 있고 구성되어 있는지. 사용자 사전에 의존하는 경우: 항목이 셸 유형이고 활성화되어 있는지

셸 명령 및 플랜 참고.

UI 미리보기: 라이선스 페이지 — 그림 D · 라이선스 (UI 미리보기 · ts-04-license.webp)

빠른 시나리오

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

여전히 안 되면

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

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

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