Audio / Voice Notes — 2026-01-17

작동 방식

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

자동 감지 (기본값)

모델을 설정하지 않고 tools.media.audio.enabled가 false로 설정되지 않은 경우, OpenClaw는 다음 순서로 자동 감지하며 첫 번째로 작동하는 옵션에서 멈춥니다:

  1. 로컬 CLI (설치된 경우)
    • sherpa-onnx-offline (encoder/decoder/joiner/tokens가 포함된 SHERPA_ONNX_MODEL_DIR 필요)
    • whisper-cli (whisper-cpp에서 제공; WHISPER_CPP_MODEL 또는 번들 tiny 모델 사용)
    • whisper (Python CLI; 모델 자동 다운로드)
  2. Gemini CLI (gemini) read_many_files 사용
  3. Provider 키 (OpenAI → Groq → Deepgram → Google)

자동 감지를 비활성화하려면 tools.media.audio.enabled: false로 설정하세요. 사용자 지정하려면 tools.media.audio.models를 설정하세요. 참고: 바이너리 감지는 macOS/Linux/Windows에서 최선을 다하며, CLI가 PATH에 있는지 확인하거나(~ 확장), 전체 명령 경로로 명시적인 CLI 모델을 설정하세요.

설정 예시

Provider + 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
          }
        ]
      }
    }
  }
}

범위 게이팅을 포함한 Provider 전용

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

Provider 전용 (Deepgram)

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

참고 사항 및 제한

  • Provider 인증은 표준 모델 인증 순서를 따릅니다(auth profiles, 환경 변수, models.providers.*.apiKey).
  • Deepgram은 provider: "deepgram" 사용 시 DEEPGRAM_API_KEY를 가져옵니다.
  • Deepgram 설정 세부 정보: Deepgram (audio transcription).
  • 오디오 provider는 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 출력을 간결하게 유지하세요.

주의 사항

  • 범위 규칙은 첫 번째 매칭 우선입니다. chatType은 direct, group, 또는 room으로 정규화됩니다.
  • CLI가 종료 코드 0으로 종료되고 일반 텍스트를 출력하는지 확인하세요; JSON은 jq -r .text로 처리해야 합니다.
  • 답장 큐를 차단하지 않도록 합리적인 시간 제한(timeoutSeconds, 기본 60초)을 유지하세요.
← 문서로 돌아가기