OpenClaw로 오디오 및 음성 메시지 처리하기

사용자로부터 음성 메시지를 받았을 때, 이를 일일이 듣고 텍스트로 옮기는 작업은 정말 번거로운 일이에요. 특히 여러 개의 오디오 파일을 처리해야 하거나, 음성으로 특정 명령을 내리고 싶을 때 자동화된 도구가 없다면 개발 효율이 떨어질 수밖에 없죠.

OpenClaw를 사용하면 오디오 파일을 자동으로 감지하고 텍스트로 변환하여 워크플로우에 바로 녹여낼 수 있어요.

필요한 것

시작하기 전에 다음 조건들을 확인해 주세요.

• tools.media.audio.enabled 설정 (기본값은 true 혹은 자동 감지)
• 로컬 CLI 도구 (선택 사항: sherpa-onnx-offline, whisper-cli, whisper)
• API Provider 키 (선택 사항: OpenAI, Groq, Deepgram, Google)
• 환경 변수 설정 (CLI 사용 시 SHERPA_ONNX_MODEL_DIR 또는 WHISPER_CPP_MODEL 등)

빠른 시작

OpenClaw는 별다른 설정이 없어도 시스템에 설치된 도구를 자동으로 찾아냅니다. 로컬 CLI를 먼저 검색하고, 없으면 Gemini CLI나 등록된 Provider 키를 순서대로 시도해요.

특정 모델을 지정하고 싶다면 아래 예시처럼 config.json5 파일을 수정해 보세요. OpenAI를 우선 사용하고, 실패할 경우 로컬에 설치된 Whisper CLI를 사용하도록 설정하는 방법이에요.

{
  tools: {
    media: {
      audio: {
        enabled: true,
        maxBytes: 20971520, // 20MB 제한
        models: [
          { provider: "openai", model: "gpt-4o-mini-transcribe" },
          {
            type: "cli",
            command: "whisper",
            args: ["--model", "base", "{{MediaPath}}"],
            timeoutSeconds: 45,
          },
        ],
      },
    },
  },
}

설정이 완료되면 OpenClaw가 오디오 첨부 파일을 찾아 [Audio] 블록으로 교체하고, 변환된 텍스트를 {{Transcript}} 변수에 담아줍니다. 트랜스크립션이 성공하면 slash command도 그대로 인식해서 작동해요.

문제 해결

설정 중에 문제가 발생하면 다음 사항들을 체크해 보세요.

• 파일 크기 제한: 기본값은 20MB(maxBytes)예요. 파일이 이보다 크면 해당 모델은 건너뛰고 다음 순서의 모델을 시도하게 됩니다.
• CLI 실행 및 경로 오류: CLI 도구가 PATH에 등록되어 있는지 확인하세요. OpenClaw는 ~ 경로를 확장해서 인식하지만, 가급적 전체 경로를 적어주는 것이 안전해요.
• 타임아웃 발생: 트랜스크립션이 너무 오래 걸리면 응답 대기열이 막힐 수 있어요. timeoutSeconds(기본 60초)를 환경에 맞게 적절히 늘려보세요.
• Scope 규칙 충돌: chatType에 따라 특정 그룹이나 방에서 오디오 처리가 거부될 수 있어요. 설정한 scope 규칙이 첫 번째 매칭에서 차단되고 있지 않은지 확인해 보세요.

더 자세한 설정 방법이나 도움이 필요하다면 AI Setup Assistant를 활용해 보세요!

다음 단계

• Deepgram (audio transcription)