디스코드 음성채팅을 OpenClaw로 연결하기: 개발 과정과 트러블슈팅 총정리

안녕하세요! AI Think Lab입니다!

 

오늘은 “디스코드 음성채팅에서 말한 내용을 텍스트로 바꿔(OpenClaw로 전달) → 답변을 다시 음성으로 읽어주는” 파이프라인을 실제로 구현한 과정을, 시행착오까지 포함해서 정리해볼게요.

 

🎯 목표 (한 줄 요약)

디스코드 음성 채널에서 대화하듯이, 사용자 발화를 인식(STT)하고 OpenClaw에서 답변을 만든 뒤, 음성(TTS)으로 자연스럽게 응답하는 보이스봇을 만든다.

 

🧩 전체 아키텍처 (흐름)

1) Discord Voice Receiver → Opus 디코딩 → PCM

2) PCM → 16kHz mono WAV 변환

3) STT(whisper.cpp) → 텍스트 추출

4) OpenClaw Gateway로 질문 전달

5) 답변 텍스트 → TTS(Windows SAPI) → 음성 채널 재생

 

🛠️ 구현 단계 (핵심만 딱)

① 디스코드 봇 기본 뼈대

• prefix 커맨드 기반으로 시작: !talk / !stop

• !talk: 음성 대화 루프 시작

• !stop: 대화 모드 종료 + 음성채널 퇴장

 

② TTS 무료 구성 (Windows SAPI)

• OpenAI 키 없이 돌리기 위해 로컬 TTS로 전환

• System.Speech로 WAV 생성 → data chunk(PCM) 추출 → 디스코드 보이스 플레이어에 전달

 

③ STT 무료 구성 (whisper.cpp)

• Opus 수신 → PCM 디코딩 → 16k WAV 변환 후 whisper-cli 실행

• 모델은 ggml 계열을 사용했고, 환경/버전 이슈가 있어 모델/옵션 튜닝 포인트가 생김

 

④ OpenClaw 브리지

• STT 텍스트를 OpenClaw Gateway로 전달

• 응답 텍스트를 받아서 TTS로 읽어주며, “음성 ↔ OpenClaw” 브리지 완성

 

🧯 트러블슈팅 모음 (여기서 시간 제일 씀)

1) !join / !talk 무반응

원인: “@봇 !talk”처럼 멘션이 앞에 오면 파서가 커맨드로 인식 못 하는 케이스

해결: 멘션 prefix도 제거/정규화해서 커맨드로 처리

 

2) 음성 연결이 안 되거나 바로 끊김

원인: DAVE 프로토콜 의존성 누락(@snazzah/davey), 또는 네트워크에서 IP discovery 단계 이슈

해결: 누락 패키지 설치 + 에러 핸들링/로그 강화

 

3) FFmpeg not found

원인: 재생 소스가 변환을 요구할 때 내부에서 ffmpeg를 찾으면서 터짐

해결: 변환 없이 바로 재생 가능한 PCM/WAV 기반으로 맞추거나, 사전에 WAV로 생성

 

4) 프로세스가 여러 개 떠서 “수정이 안 먹는 느낌”

원인: node 프로세스 중복 실행으로 로그/상태가 섞임

해결: 단일 프로세스 유지 + 재시작 루틴 통일

 

5) 에코 루프 (봇이 자기 목소리 다시 듣기)

해결: 봇이 말하는 동안에는 STT 처리를 무시하는 플래그(isSpeaking) 적용

 

6) !stop을 쳐도 음성 채널에 남아있음

원인: 상태만 종료되고 실제 VoiceConnection이 살아있는 경우

해결: leaveVoiceChannel + getVoiceConnection(guildId).destroy()로 강제 정리

 

💡 운영 팁 (체감 퀄리티 올리는 포인트)

• 대화 모드는 “짧게 끊어서 여러 번”보다 “한 번 켜고 또박또박 한 문장”이 인식률이 더 좋음

• 너무 짧은 오디오/노이즈는 초반에 필터링하는 게 안정적

• STT가 연속으로 비면 자동으로 “다시 말해줘” 안내를 넣으면 UX가 좋아짐

 

✅ 마무리

이번 구현은 상용 통화 품질을 목표로 하기보단, 로컬 무료 구성으로도 음성 → 에이전트 → 음성 파이프라인을 충분히 만들 수 있다는 걸 증명하는 데 초점을 뒀어요.

 

다음 확장 아이디어

• /talk /stop 같은 슬래시 커맨드

• 안정적인 프로세스 매니저(pm2) 적용

• STT 모델/옵션 튜닝 및 발화 합치기(buffering)

 

읽어줘서 고마워요!