메인 콘텐츠로 건너뛰기

​
오디오 / 음성 노트 — 2026-01-17

​
정상적으로 작동하는 것

  • 미디어 이해 (오디오): 오디오 이해가 활성화되어 있거나 (또는 자동 감지되는 경우), OpenClaw 는 다음을 수행합니다.
    1. 첫 번째 오디오 첨부 파일(로컬 경로 또는 URL)을 찾고 필요한 경우 다운로드합니다.
    2. 각 모델 엔트리로 전송하기 전에 maxBytes 을 적용합니다.
    3. 순서대로 첫 번째로 적격한 모델 엔트리(프로바이더 또는 CLI)를 실행합니다.
    4. 실패하거나 건너뛰는 경우(크기/타임아웃), 다음 엔트리를 시도합니다.
    5. 성공 시, Body 를 [Audio] 블록으로 교체하고 {{Transcript}} 을 설정합니다.
  • 명령 파싱: 전사가 성공하면, 슬래시 명령이 계속 동작하도록 CommandBody/RawBody 이 전사 텍스트로 설정됩니다.
  • 상세 로깅: --verbose 에서 전사가 실행될 때와 본문을 교체할 때를 로깅합니다.

​
자동 감지 (기본값)

모델을 구성하지 않았고 tools.media.audio.enabled 이 false 로 설정되지 않은 경우, OpenClaw 는 다음 순서로 자동 감지하며, 처음으로 동작하는 옵션에서 중지합니다.
  1. 로컬 CLI (설치된 경우)
    • sherpa-onnx-offline (SHERPA_ONNX_MODEL_DIR 에 인코더/디코더/조이너/토큰이 필요)
    • whisper-cli (whisper-cpp 출처; WHISPER_CPP_MODEL 또는 번들된 tiny 모델 사용)
    • whisper (Python CLI; 모델을 자동으로 다운로드)
  2. Gemini CLI (gemini) 를 read_many_files 와 함께 사용
  3. 프로바이더 키 (OpenAI → Groq → Deepgram → Google)
자동 감지를 비활성화하려면 tools.media.audio.enabled: false 을 설정하십시오. 사용자 정의하려면 tools.media.audio.models 을 설정하십시오. 참고: 바이너리 감지는 macOS/Linux/Windows 전반에서 최선의 노력을 기반으로 합니다. CLI 가 PATH 에 있는지 확인하십시오(~ 를 확장합니다). 또는 전체 명령 경로를 포함한 명시적 CLI 모델을 설정하십시오.

​
구성 예시

​
프로바이더 + CLI 대체(OpenAI + Whisper CLI)

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

​
범위 게이팅이 있는 프로바이더 전용

{
  tools: {
    media: {
      audio: {
        enabled: true,
        scope: {
          default: "allow",
          rules: [{ action: "deny", match: { chatType: "group" } }],
        },
        models: [{ provider: "openai", model: "gpt-4o-mini-transcribe" }],
      },
    },
  },
}

​
프로바이더 전용(Deepgram)

{
  tools: {
    media: {
      audio: {
        enabled: true,
        models: [{ provider: "deepgram", model: "nova-3" }],
      },
    },
  },
}

​
참고 사항 및 제한

  • 프로바이더 인증은 표준 모델 인증 순서를 따릅니다(인증 프로필, 환경 변수, models.providers.*.apiKey).
  • Deepgram 은 provider: "deepgram" 이 사용될 때 DEEPGRAM_API_KEY 를 사용합니다.
  • Deepgram 설정 세부 정보: Deepgram (오디오 전사).
  • 오디오 프로바이더는 tools.media.audio 를 통해 baseUrl, headers, providerOptions 를 재정의할 수 있습니다.
  • 기본 크기 제한은 20MB(tools.media.audio.maxBytes)입니다. 초과 크기의 오디오는 해당 모델에서 건너뛰고 다음 엔트리를 시도합니다.
  • 오디오에 대한 기본 maxChars 는 미설정(전체 전사)입니다. 출력 길이를 줄이려면 tools.media.audio.maxChars 또는 엔트리별 maxChars 를 설정하십시오.
  • OpenAI 자동 기본값은 gpt-4o-mini-transcribe 입니다. 더 높은 정확도를 위해 model: "gpt-4o-transcribe" 을 설정하십시오.
  • 여러 음성 노트를 처리하려면 tools.media.audio.attachments 을 사용하십시오(mode: "all" + maxAttachments).
  • 전사 텍스트는 템플릿에서 {{Transcript}} 으로 사용할 수 있습니다.
  • CLI stdout 은 5MB 로 제한됩니다. CLI 출력은 간결하게 유지하십시오.

​
그룹에서의 멘션 감지

그룹 채팅에 requireMention: true가 설정된 경우, OpenClaw는 이제 멘션을 확인하기 전에 오디오를 전사합니다. 이 기능을 사용하면 음성 메모에 멘션이 포함된 경우에도 처리할 수 있습니다. 작동 방식:
  1. 음성 메시지에 텍스트 본문이 없고 그룹에서 멘션이 필요한 경우, OpenClaw는 “프리플라이트” 전사를 수행합니다.
  2. 전사된 텍스트는 멘션 패턴(예: @BotName, 이모지 트리거)을 확인합니다.
  3. 멘션이 발견되면 메시지는 전체 응답 파이프라인을 거칩니다.
  4. 멘션 감지를 위해 전사 텍스트가 사용되므로 음성 메모도 멘션 게이트를 통과할 수 있습니다.
대체 동작:
  • 프리플라이트 중 전사에 실패하면(타임아웃, API 오류 등) 텍스트 전용 멘션 감지를 기준으로 메시지가 처리됩니다.
  • 이를 통해 텍스트와 오디오가 함께 포함된 메시지가 잘못 누락되는 일을 방지합니다.
예시: 사용자가 requireMention: true가 설정된 Telegram 그룹에서 “Hey @Claude, what’s the weather?”라고 말하는 음성 메모를 보냅니다. 음성 메모가 전사되고 멘션이 감지되면 에이전트가 응답합니다.

​
9. 주의 사항

  • 범위 규칙은 첫 번째 매치가 우선합니다. chatType 은 direct, group, 또는 room 로 정규화됩니다.
  • CLI 가 종료 코드 0 으로 종료되고 일반 텍스트를 출력하는지 확인하십시오. JSON 은 jq -r .text 를 통해 가공해야 합니다.
  • 응답 큐 차단을 피하려면 타임아웃을 합리적으로 유지하십시오(timeoutSeconds, 기본값 60초).
  • 프리플라이트 전사는 멘션 감지를 위해 첫 번째 오디오 첨부 파일만 처리합니다. 추가 오디오는 메인 미디어 이해 단계에서 처리됩니다.