WSL2에서 Claude Code 음성 모드 사용하기

사전 요구사항

WSL2 (Windows Subsystem for Linux 2) 설치 및 실행 중
WSLg (Windows Subsystem for Linux GUI) 사용 가능 (Windows 11, 또는 Windows 10에서 Microsoft Store WSL 1.0.0+ 사용 시)
WSL2 내 Ubuntu 또는 호환 Linux 배포판
WSL2 환경에 Claude Code 설치됨
PulseAudio (리눅스 사운드 서버) 실행 중 (WSLg가 자동으로 제공)
Windows 마이크 권한 활성화: 설정 > 개인 정보 및 보안 > 마이크 > "마이크 액세스" 및 "데스크톱 앱에서 마이크에 액세스하도록 허용" 활성화

문제 설명

WSL2에서 Claude Code 음성 모드를 사용하려고 Space를 길게 누르면 ALSA (Advanced Linux Sound Architecture, 리눅스 오디오 시스템) 오류가 발생할 수 있습니다:

1ALSA lib confmisc.c:855:(parse_card) cannot find card '0'
2ALSA lib conf.c:5178:(_snd_config_evaluate) function snd_func_card_inum returned error: No such file or directory
3ALSA lib pcm.c:2664:(snd_pcm_open_noupdate) Unknown PCM default

1ALSA lib confmisc.c:855:(parse_card) cannot find card '0'
2ALSA lib conf.c:5178:(_snd_config_evaluate) function snd_func_card_inum returned error: No such file or directory
3ALSA lib pcm.c:2664:(snd_pcm_open_noupdate) Unknown PCM default

WSL2에는 오디오 하드웨어가 없어서 ALSA가 하드웨어에 직접 접근하면서 발생하는 오류입니다. WSLg가 PulseAudio를 지원하지만, ALSA가 하드웨어 대신 PulseAudio를 통해 라우팅하도록 설정해야 합니다.

해결 방법

1단계: ALSA-PulseAudio 브릿지 설치

libasound2-plugins 패키지가 ALSA와 PulseAudio를 연결하는 플러그인을 제공합니다:

1sudo apt-get update && sudo apt-get install -y libasound2-plugins

1sudo apt-get update && sudo apt-get install -y libasound2-plugins

2단계: ALSA가 PulseAudio를 사용하도록 설정

ALSA 사용자 설정 파일 ~/.asoundrc를 생성합니다. 이 파일은 ALSA가 오디오 장치를 어떻게 사용할지 정의합니다:

1cat > ~/.asoundrc << 'EOF'
2pcm.!default {
3    type pulse
4}
5
6ctl.!default {
7    type pulse
8}
9EOF

1cat > ~/.asoundrc << 'EOF'
2pcm.!default {
3    type pulse
4}
5
6ctl.!default {
7    type pulse
8}
9EOF

이 설정은 ALSA가 오디오 입출력(pcm)과 믹서 제어(ctl) 모두에서 PulseAudio를 기본 백엔드로 사용하도록 합니다. !default 형식이 ALSA 기본 장치 설정을 덮어씁니다.

zsh 주의사항: zsh를 사용하는 경우 클립보드에서 붙여넣기 시 ! 문자가 \!로 이스케이프될 수 있습니다. 파일 생성 후 cat ~/.asoundrc로 내용에 pcm.!default(백슬래시 없음)가 표시되는지 확인하세요. 백슬래시가 나타나면 텍스트 편집기로 직접 파일을 생성하세요.

3단계: Claude Code 재시작

ALSA는 프로세스 시작 시 ~/.asoundrc를 읽습니다. 변경 사항을 적용하려면 Claude Code 세션을 종료하고 다시 시작해야 합니다.

4단계: 음성 모드 테스트

Claude Code를 열고 Space를 길게 눌러 음성 모드를 활성화합니다. ALSA 오류가 더 이상 나타나지 않아야 합니다.

설정 확인

해결 방법을 적용한 후 각 구성요소가 정상인지 확인합니다.

WSLg 사용 가능 여부 확인

1ls /mnt/wslg/PulseServer

1ls /mnt/wslg/PulseServer

이 파일이 존재하면 WSLg PulseAudio를 사용할 수 있습니다.

PulseAudio 실행 확인

1pactl info

1pactl info

출력에 Server Name: pulseaudio와 Default Source: RDPSource가 포함되어야 합니다. RDP (Remote Desktop Protocol)는 WSLg가 Windows 호스트와 오디오를 주고받는 데 사용하는 프로토콜입니다.

사용 가능한 오디오 소스 확인

1pactl list sources short

1pactl list sources short

RDPSource(Windows 호스트의 마이크 입력)와 RDPSink.monitor(시스템 오디오 모니터)가 표시되어야 합니다.

ALSA 설정 확인

1cat ~/.asoundrc

1cat ~/.asoundrc

출력 내용:

1pcm.!default {
2    type pulse
3}
4
5ctl.!default {
6    type pulse
7}

1pcm.!default {
2    type pulse
3}
4
5ctl.!default {
6    type pulse
7}

브릿지 플러그인 설치 확인

1dpkg -l | grep libasound2-plugins

1dpkg -l | grep libasound2-plugins

출력 첫 열이 ii(installed, 설치됨)로 표시되어야 합니다.

문제 해결

WSLg 사용 불가

/mnt/wslg/가 존재하지 않으면:

WSL 업데이트: PowerShell에서 wsl --update
재시작: PowerShell에서 wsl --shutdown
버전 확인: wsl --version (WSLg 버전이 표시되어야 합니다)

PULSE_SERVER가 설정되지 않음

WSLg가 정상 동작하면 PULSE_SERVER 환경 변수가 자동으로 설정됩니다. echo $PULSE_SERVER가 빈 값을 반환하는 경우는 드물지만, SSH로 WSL에 접속했거나 커스텀 init 스크립트가 환경변수를 덮어쓴 경우에 발생할 수 있습니다:

1export PULSE_SERVER="${PULSE_SERVER:-unix:/mnt/wslg/PulseServer}"

1export PULSE_SERVER="${PULSE_SERVER:-unix:/mnt/wslg/PulseServer}"

문제가 지속되면 위 줄을 ~/.bashrc 또는 ~/.zshrc에 추가하세요. 이미 설정된 값이 있으면 덮어쓰지 않는 조건부 형식입니다.

오디오 소스 없음

pactl list sources에 아무것도 표시되지 않으면:

모든 WSL 터미널을 닫습니다
PowerShell에서 wsl --shutdown 실행
WSL 터미널을 다시 열면 WSLg가 자동으로 재시작됩니다
pactl list sources short로 확인

PipeWire 충돌

WSL용 Ubuntu 이미지에는 기본적으로 PipeWire (차세대 리눅스 오디오 서버)가 설치되어 있지 않습니다. 하지만 수동으로 PipeWire를 설치했거나 데스크톱 패키지를 추가한 경우, WSLg PulseAudio 소켓과 충돌할 수 있습니다. 오디오가 작동하지 않으면:

사용자 세션에서 해당 서비스가 자동 시작되지 않도록 비활성화합니다:

1systemctl --user disable pulseaudio.service pulseaudio.socket 2>/dev/null
2systemctl --user disable pipewire.service pipewire.socket 2>/dev/null

1systemctl --user disable pulseaudio.service pulseaudio.socket 2>/dev/null
2systemctl --user disable pipewire.service pipewire.socket 2>/dev/null

PULSE_SERVER가 WSLg의 소켓을 가리키는지 확인:

1echo $PULSE_SERVER  # unix:/mnt/wslg/PulseServer이어야 합니다

1echo $PULSE_SERVER  # unix:/mnt/wslg/PulseServer이어야 합니다

음성 입력은 되지만 소리가 캡처되지 않음

음성 모드가 오류 없이 열리지만 입력이 캡처되지 않는 경우:

1pactl set-default-source RDPSource

1pactl set-default-source RDPSource

독립적으로 녹음 테스트

위 해결 방법(특히 2단계 .asoundrc 설정)을 완료한 후에 실행하세요. alsa-utils는 Claude Code 음성 모드의 필수 의존성이 아닌 디버깅 도구입니다:

1sudo apt-get install -y alsa-utils
2arecord -d 3 /tmp/test.wav && aplay /tmp/test.wav

1sudo apt-get install -y alsa-utils
2arecord -d 3 /tmp/test.wav && aplay /tmp/test.wav

3초간 녹음(-d 3) 후 재생합니다. 녹음된 소리가 들리면 오디오 입력이 정상적으로 작동하고 있습니다.

참고: 음성 모드 현황 (2026년 3월 기준)

롤아웃 현황: 점진적 롤아웃 중, 약 5% 사용자부터 시작. 접근 권한이 있으면 welcome 화면에 안내가 표시됩니다.
활성화: /voice 명령으로 토글하거나, settings.json에서 voiceEnabled: true로 영구 활성화 가능.
Push-to-talk (누르고 있는 동안만 녹음): Space를 길게 눌러 녹음, 놓으면 텍스트 변환. v2.1.71부터 keybindings.json의 voice:pushToTalk으로 키 변경 가능.
지원 언어: v2.1.71 (2026년 3월 7일) 기준 20개 언어 지원. 한국어는 포함되지 않으며, 영어(또는 기타 지원 언어)로 말해야 합니다. 언어 자동 감지 기능 없음.
음성 변환 비용: STT (Speech-to-Text, 음성→텍스트 변환) 변환은 요금 한도에 포함되지 않음 (Pro, Max, Team, Enterprise).
공식 문서 없음: code.claude.com/docs/en/voice-mode는 404 반환. changelog에서만 정보 확인 가능.
Push-to-talk 전용: 항상 듣기 모드나 wake word (호출어, 예: "Hey Siri") 모드는 없음 (터미널 환경에 맞춘 의도적 설계).

테스트 환경

WSL 버전: 2.6.1.0
WSLg 버전: 1.0.66
Windows: 10.0.26200
배포판: Ubuntu 22.04 LTS (WSL2)
PulseAudio: 16.1 (WSLg 제공)

참고문헌

WSLg Architecture - WSLg가 RDP를 통해 오디오를 전달하는 구조
ALSA Project - .asoundrc - .asoundrc 설정 파일 문법 및 플러그인 구성
PulseAudio - ALSA Plugin - ALSA-PulseAudio 브릿지 설정
Microsoft WSL Release Notes - WSL/WSLg 버전별 변경사항
Claude Code Changelog v2.1.71 - 음성 모드 롤아웃, 지원 언어, push-to-talk 키 변경 기능

#사전 요구사항

#문제 설명

#해결 방법

#1단계: ALSA-PulseAudio 브릿지 설치

#2단계: ALSA가 PulseAudio를 사용하도록 설정

#3단계: Claude Code 재시작

#4단계: 음성 모드 테스트

#설정 확인

#WSLg 사용 가능 여부 확인

#PulseAudio 실행 확인

#사용 가능한 오디오 소스 확인

#ALSA 설정 확인

#브릿지 플러그인 설치 확인

#문제 해결

#WSLg 사용 불가

#PULSE_SERVER가 설정되지 않음

#오디오 소스 없음

#PipeWire 충돌

#음성 입력은 되지만 소리가 캡처되지 않음

#독립적으로 녹음 테스트

#참고: 음성 모드 현황 (2026년 3월 기준)

#테스트 환경

#참고문헌