음성 받아쓰기

Claude Code CLI에서 프롬프트를 타이핑하는 대신 푸시투토크 음성 받아쓰기를 사용하여 말로 입력할 수 있습니다.

키를 누른 채로 말하면 프롬프트를 받아쓸 수 있습니다. 음성은 프롬프트 입력란에 실시간으로 변환되므로, 같은 메시지에서 음성과 타이핑을 혼합하여 사용할 수 있습니다. /voice로 받아쓰기를 활성화하세요. 기본 푸시투토크 키는 Space이며, 짧은 홀드 대기 없이 첫 키 입력에 바로 활성화되도록 수정자 키 조합으로 재바인딩할 수 있습니다.

음성 받아쓰기는 Claude Code v2.1.69 이상이 필요합니다. claude --version으로 버전을 확인하세요.

요구사항

음성 받아쓰기는 Claude.ai 계정으로 인증할 때만 사용 가능한 스트리밍 음성-텍스트 변환 서비스를 사용합니다. Anthropic API 키 직접 사용, Amazon Bedrock, Google Vertex AI, Microsoft Foundry로 Claude Code가 구성된 경우에는 사용할 수 없습니다.

음성 받아쓰기는 로컬 마이크 접근이 필요하므로, 웹 기반 Claude Code나 SSH 세션과 같은 원격 환경에서는 작동하지 않습니다. WSL에서는 음성 받아쓰기에 오디오 접근을 위한 WSLg가 필요하며, Windows 11의 WSL2에 포함되어 있습니다. Windows 10 또는 WSL1에서는 네이티브 Windows에서 Claude Code를 실행하세요.

오디오 녹음은 macOS, Linux, Windows에서 내장 네이티브 모듈을 사용합니다. Linux에서 네이티브 모듈을 로드할 수 없는 경우, Claude Code는 ALSA utils의 arecord 또는 SoX의 rec으로 폴백합니다. 둘 다 사용할 수 없는 경우, /voice가 패키지 관리자에 맞는 설치 명령을 출력합니다.

음성 받아쓰기 활성화

/voice를 실행하여 음성 받아쓰기를 켜세요. 처음 활성화할 때 Claude Code가 마이크 확인을 수행합니다. macOS에서는 터미널에 대해 이전에 권한이 부여되지 않은 경우 시스템 마이크 권한 프롬프트가 트리거됩니다.

/voice
Voice mode enabled. Hold Space to record. Dictation language: en (/config to change).

음성 받아쓰기는 세션 간에 유지됩니다. /voice를 다시 실행하면 끌 수 있으며, 사용자 설정 파일에서 직접 설정할 수도 있습니다:

{
  "voiceEnabled": true
}

음성 받아쓰기가 활성화된 동안 프롬프트가 비어 있으면 입력 푸터에 hold Space to speak 힌트가 표시됩니다. 사용자 정의 상태 줄이 구성된 경우에는 힌트가 표시되지 않습니다.

프롬프트 녹음

Space를 누른 채로 녹음을 시작합니다. Claude Code는 터미널에서 빠른 키 반복 이벤트를 감지하여 키가 눌려 있는지 판단하므로, 녹음이 시작되기 전에 짧은 워밍업이 있습니다. 푸터에 워밍업 중에는 keep holding…이 표시되고, 녹음이 활성화되면 실시간 파형으로 전환됩니다.

워밍업 중에 처음 몇 개의 키 반복 문자가 입력란에 타이핑되지만, 녹음이 활성화되면 자동으로 제거됩니다. 단일 Space 탭은 여전히 공백을 입력하며, 홀드 감지는 빠른 반복에서만 트리거됩니다.

워밍업을 건너뛰려면 meta+k와 같은 수정자 키 조합으로 재바인딩하세요. 수정자 키 조합은 첫 키 입력에서 바로 녹음을 시작합니다.

음성은 말하는 동안 프롬프트에 표시되며, 변환이 확정되기 전까지는 흐리게 표시됩니다. Space를 놓으면 녹음이 중지되고 텍스트가 확정됩니다. 변환된 텍스트는 커서 위치에 삽입되며 커서는 삽입된 텍스트의 끝에 위치하므로, 어떤 순서로든 타이핑과 받아쓰기를 혼합할 수 있습니다. Space를 다시 누른 채로 다른 녹음을 추가하거나, 먼저 커서를 이동하여 프롬프트의 다른 위치에 음성을 삽입할 수 있습니다:

> refactor the auth middleware to ▮
  # Space를 누른 채로 "use the new token validation helper"라고 말합니다
> refactor the auth middleware to use the new token validation helper▮

변환은 코딩 어휘에 맞게 조정되어 있습니다. regex, OAuth, JSON, localhost와 같은 일반적인 개발 용어가 올바르게 인식되며, 현재 프로젝트 이름과 git 브랜치 이름이 자동으로 인식 힌트로 추가됩니다.

받아쓰기 언어 변경

음성 받아쓰기는 Claude의 응답 언어를 제어하는 것과 동일한 language 설정을 사용합니다. 해당 설정이 비어 있으면 받아쓰기는 영어로 기본 설정됩니다.

지원되는 받아쓰기 언어

언어	코드
체코어	cs
덴마크어	da
네덜란드어	nl
영어	en
프랑스어	fr
독일어	de
그리스어	el
힌디어	hi
인도네시아어	id
이탈리아어	it
일본어	ja
한국어	ko
노르웨이어	no
폴란드어	pl
포르투갈어	pt
러시아어	ru
스페인어	es
스웨덴어	sv
터키어	tr
우크라이나어	uk

/config에서 또는 설정에서 직접 언어를 설정하세요. BCP 47 언어 코드 또는 언어 이름을 사용할 수 있습니다:

{
  "language": "japanese"
}

language 설정이 지원 목록에 없는 경우, /voice는 활성화 시 경고를 표시하고 받아쓰기에 영어로 폴백합니다. Claude의 텍스트 응답은 이 폴백의 영향을 받지 않습니다.

푸시투토크 키 재바인딩

푸시투토크 키는 Chat 컨텍스트에서 voice:pushToTalk에 바인딩되어 있으며 기본값은 Space입니다. ~/.claude/keybindings.json에서 재바인딩하세요:

{
  "bindings": [
    {
      "context": "Chat",
      "bindings": {
        "meta+k": "voice:pushToTalk",
        "space": null
      }
    }
  ]
}

"space": null을 설정하면 기본 바인딩이 제거됩니다. 두 키 모두 활성화하려면 이 줄을 생략하세요.

홀드 감지가 키 반복에 의존하므로, v와 같은 단일 문자 키에 바인딩하면 워밍업 중에 프롬프트에 입력되므로 피하세요. Space를 사용하거나, meta+k와 같은 수정자 키 조합을 사용하면 워밍업 없이 첫 키 입력에서 바로 녹음을 시작할 수 있습니다. 전체 키바인딩 구문은 키보드 단축키 사용자 정의를 참고하세요.

문제 해결

음성 받아쓰기가 활성화되지 않거나 녹음되지 않을 때 흔히 발생하는 문제:

• Voice mode requires a Claude.ai account: API 키 또는 서드파티 프로바이더로 인증되어 있습니다. /login을 실행하여 Claude.ai 계정으로 로그인하세요.
• Microphone access is denied: 시스템 설정에서 터미널에 마이크 권한을 부여하세요. macOS에서는 시스템 설정 → 개인정보 보호 및 보안 → 마이크로 이동하세요. Windows에서는 설정 → 개인 정보 → 마이크로 이동하세요. 그런 다음 /voice를 다시 실행하세요.
• No audio recording tool found (Linux): 네이티브 오디오 모듈을 로드할 수 없고 폴백이 설치되어 있지 않습니다. 오류 메시지에 표시된 명령으로 SoX를 설치하세요 (예: sudo apt-get install sox).
• Space를 누르고 있어도 아무 일도 일어나지 않음: 누르고 있는 동안 프롬프트 입력란을 확인하세요. 공백이 계속 쌓이면 음성 받아쓰기가 꺼져 있는 것이므로 /voice를 실행하여 활성화하세요. 한두 개의 공백만 나타나고 그 후 아무 일도 없으면 음성 받아쓰기는 켜져 있지만 홀드 감지가 트리거되지 않는 것입니다. 홀드 감지는 터미널이 키 반복 이벤트를 보내야 하므로, OS 수준에서 키 반복이 비활성화된 경우 눌린 키를 감지할 수 없습니다.
• 변환이 깨지거나 잘못된 언어로 나옴: 받아쓰기는 기본적으로 영어입니다. 다른 언어로 받아쓰기하는 경우 먼저 /config에서 설정하세요. 받아쓰기 언어 변경을 참고하세요.

참고 자료

• 키보드 단축키 사용자 정의: voice:pushToTalk 및 기타 CLI 키보드 액션 재바인딩
• 설정 구성: voiceEnabled, language 및 기타 설정 키에 대한 전체 레퍼런스
• 대화형 모드: 키보드 단축키, 입력 모드, 세션 제어
• 내장 명령어: /voice, /config 및 모든 명령어에 대한 레퍼런스